sf-agent-framework

# SF-Agent Template Format Specification v2.0 ## Overview The Enhanced Template Format provides a powerful, self-contained template system with embedded LLM instructions, variable substitution, conditional logic, and structured content generation. Based on modern template engineering principles. ## Core Principles 1. **Self-Contained**: Templates include all processing logic 2. **LLM-Native**: Instructions embedded directly in templates 3. **Clean Output**: Processing directives never appear in final output 4. **Flexible**: Supports variables, conditions, and repetition 5. **Validated**: Structure and variables can be validated before processing ## Template Structure ```yaml # Required: Template metadata template: id: unique-template-id name: Human Readable Template Name version: 1.0.0 description: >- Detailed description of what this template generates # Output configuration output: format: markdown # markdown, yaml, json, xml location: docs/generated/ # Output directory naming: '{{type}}-{{id}}.md' # Output file naming pattern # Template metadata metadata: phase: planning # planning, development, deployment context_mode: rich # rich, lean, minimal max_tokens: 15000 # Maximum output size validation_required: true # Require validation before use # Optional: Variable definitions variables: - name: project_name description: Name of the Salesforce project required: true default: null type: string - name: sprint_number description: Current sprint number required: false default: 1 type: number - name: components description: List of components to generate required: true type: array # Optional: Validation rules validation: required_sections: - business_context - technical_specifications completeness_checks: - all_variables_defined - no_empty_sections - llm_instructions_valid # Required: Content sections sections: - id: header title: Document Header required: true # LLM instruction for this section instruction: | [[LLM: Generate a professional document header including: - Document title with project name - Version and date - Author information - Executive summary (2-3 sentences) Keep tone formal and concise]] # Static content (optional) content: | # {{project_name}} Documentation Version: {{version}} Date: {{date}} # Subsections (optional) subsections: - id: metadata title: Document Metadata instruction: '[[LLM: Add relevant metadata]]' - id: requirements title: Requirements required: true condition: 'phase == planning' # Only include in planning phase instruction: | [[LLM: Based on the provided context, generate: 1. Functional requirements (numbered list) 2. Non-functional requirements 3. Constraints and assumptions Ensure requirements are SMART (Specific, Measurable, Achievable, Relevant, Time-bound)]] # Context required for LLM context_required: | - User stories from backlog - Stakeholder interviews - Business objectives subsections: - id: functional title: Functional Requirements repeatable: true repeat_for: requirements_list loop_var: requirement repeat_template: | ### FR-{{requirement.id}}: {{requirement.title}} {{requirement.description}} **Acceptance Criteria:** {{requirement.criteria}} - id: technical title: Technical Specifications required: true # Complex instruction with conditions instruction: | [[LLM: Generate technical specifications including: [[IF: includes_apex]] - Apex class structures with method signatures - Trigger framework implementation - Test class specifications (90% coverage minimum) [[ENDIF]] [[IF: includes_lwc]] - LWC component architecture - Wire service configuration - Event handling specifications [[ENDIF]] [[IF: includes_integration]] - API endpoint definitions - Authentication methods - Error handling strategies - Retry logic and circuit breakers [[ENDIF]] Ensure all specifications follow Salesforce best practices]] # Conditional subsections subsections: - id: apex_specs title: Apex Specifications condition: 'includes_apex == true' instruction: | [[LLM: For each Apex class needed: 1. Define class purpose and responsibility 2. List all public methods with signatures 3. Specify error handling approach 4. Define test scenarios Include actual code snippets where helpful]] - id: lwc_specs title: Lightning Web Component Specifications condition: 'includes_lwc == true' instruction: | [[LLM: For each LWC component: 1. Component file structure 2. Properties and their decorators 3. Lifecycle hooks used 4. Event definitions 5. Wire service usage]] - id: implementation title: Implementation Guide required: true instruction: | [[LLM: Create step-by-step implementation guide: 1. Environment setup steps 2. Development sequence (what to build first) 3. Configuration requirements 4. Testing approach 5. Deployment steps Number all steps and include specific commands where applicable]] # Examples for LLM guidance (never included in output) examples: - '1. Clone repository: `git clone <repo-url>`' - '2. Install dependencies: `npm install`' - '3. Create feature branch: `git checkout -b feature/{{feature_name}}`' ``` ## Markup Syntax ### Variable Substitution ``` {{variable_name}} # Simple variable {{user.name}} # Nested object property {{array[0]}} # Array index {{variable || 'default'}} # Default value ``` ### LLM Instructions ``` [[LLM: Instruction text]] # Never appears in output [[LLM: Multi-line instruction with detailed guidance ]] ``` ### Conditional Blocks ``` [[IF: condition]] Content to include if condition is true [[ENDIF]] [[IF: condition]] If content [[ELSE]] Else content [[ENDIF]] [[IF: var1 == 'value1']] Content for value1 [[ELSEIF: var1 == 'value2']] Content for value2 [[ELSE]] Default content [[ENDIF]] ``` ### Repetition ```yaml sections: - id: components repeatable: true repeat_for: component_list # Variable containing array loop_var: component # Variable name in loop repeat_template: | ## {{component.name}} Type: {{component.type}} Description: {{component.description}} ``` ## Advanced Features ### 1. Dynamic Section Inclusion ```yaml sections: - id: advanced_features title: Advanced Features include_if_any: - has_complex_logic - requires_optimization - performance_critical ``` ### 2. Cross-Section References ```yaml sections: - id: summary title: Summary instruction: | [[LLM: Summarize the key points from sections: - {{ref:requirements}} - {{ref:technical}} Create executive summary in 3-5 bullet points]] ``` ### 3. External Data Loading ```yaml sections: - id: data_model title: Data Model load_external: data/salesforce-objects.yaml instruction: | [[LLM: Using the loaded Salesforce object definitions, create a comprehensive data model diagram]] ``` ### 4. Validation Rules ```yaml validation: rules: - type: required_variable variable: project_name message: 'Project name is required' - type: section_length section: requirements min_length: 500 message: 'Requirements section too short' - type: llm_instruction_present sections: [technical, implementation] message: 'Technical sections must have LLM instructions' ``` ### 5. Output Formats #### Markdown (Default) ```yaml output: format: markdown options: heading_style: atx # or setext code_style: fenced # or indented line_width: 80 ``` #### YAML Output ```yaml output: format: yaml options: indent: 2 array_style: block # or flow quote_strings: true ``` #### JSON Output ```yaml output: format: json options: indent: 2 sort_keys: true ``` ## Template Processing Workflow ### 1. Load Template ```javascript const processor = new TemplateProcessor(); const template = await processor.loadTemplate('template.yaml'); ``` ### 2. Validate Structure ```javascript const validation = processor.validateTemplate(template); if (!validation.valid) { console.error(validation.errors); } ``` ### 3. Set Variables ```javascript const variables = { project_name: 'Customer Portal', sprint_number: 5, includes_apex: true, includes_lwc: true, }; ``` ### 4. Process Template ```javascript const result = await processor.processTemplate('template.yaml', variables, context); ``` ### 5. Review LLM Instructions ```javascript console.log('LLM Instructions to process:'); result.llmInstructions.forEach((inst) => { console.log(`- ${inst.section}: ${inst.instruction}`); }); ``` ## Best Practices ### DO: - ✅ Keep LLM instructions clear and specific - ✅ Use variables for all dynamic content - ✅ Validate templates before processing - ✅ Include examples for complex sections - ✅ Use conditions to control output - ✅ Test templates with various inputs ### DON'T: - ❌ Mix content and instructions - ❌ Use complex logic in conditions - ❌ Hardcode values that should be variables - ❌ Create deeply nested structures - ❌ Forget to escape special characters ## Template Library Organization ``` sf-core/templates/ ├── planning/ │ ├── requirements-template.yaml │ ├── architecture-template.yaml │ └── design-doc-template.yaml ├── development/ │ ├── story-template.yaml │ ├── test-plan-template.yaml │ └── code-review-template.yaml ├── deployment/ │ ├── release-notes-template.yaml │ ├── deployment-guide-template.yaml │ └── rollback-plan-template.yaml └── reporting/ ├── status-report-template.yaml ├── metrics-dashboard-template.yaml └── retrospective-template.yaml ``` ## Integration with Agents Agents can use templates directly: ```yaml # In agent definition dependencies: templates: - requirements-template.yaml - architecture-template.yaml commands: *generate-requirements: template: requirements-template.yaml variables: source: user_input context: project_context ``` ## Examples ### Simple Template ```yaml template: id: simple-story name: User Story Template sections: - id: story title: User Story instruction: | [[LLM: Generate user story in format: As a [persona], I want [feature], so that [benefit]]] ``` ### Complex Template with Everything ```yaml template: id: complex-architecture name: Architecture Document version: 2.0.0 variables: - name: system_name required: true - name: components type: array required: true - name: include_security type: boolean default: true sections: - id: overview title: System Overview instruction: '[[LLM: Generate system overview]]' - id: components title: Component Architecture repeatable: true repeat_for: components loop_var: comp subsections: - id: comp_detail title: '{{comp.name}} Component' instruction: | [[LLM: Describe {{comp.name}} including: - Purpose and responsibilities - Interfaces and APIs - Data flow - Dependencies]] - id: security title: Security Architecture condition: 'include_security == true' instruction: | [[LLM: Define security architecture: - Authentication methods - Authorization model - Data encryption - Audit logging]] ``` ## Conclusion The Enhanced Template Format v2.0 provides a powerful, flexible system for generating consistent, high-quality documentation with embedded intelligence. Templates are self-contained, reusable, and can adapt to various contexts while maintaining clean output.