sf-agent-framework

# Template Format Utility This utility defines the standard format and processing rules for SF-Agent templates across all expansion packs. ## Purpose Standardize template creation and processing: - Consistent template structure - Variable substitution rules - Conditional logic handling - LLM instruction embedding - Multi-format support ## Template Structure ### Basic Template Format ```yaml name: template-name version: 1.0 description: Brief description of the template category: [document|code|config|checklist] output_format: [markdown|yaml|json|apex|lwc] # Variables that can be substituted variables: project_name: type: string required: true description: Name of the project include_sections: type: array required: false default: ['overview', 'requirements', 'design'] # Template content with variable substitution content: | # {{project_name}} Documentation Generated on: {{current_date}} Author: {{author_name}} ## Overview {{overview_content}} ^^CONDITION: include_requirements^^ ## Requirements {{requirements_content}} ^^/CONDITION: include_requirements^^ # Instructions for LLM processing processing_instructions: | When using this template: 1. Gather all required variables through elicitation 2. Process conditional sections based on context 3. Ensure all placeholders are replaced 4. Validate output format ``` ## Variable Types ### Supported Variable Types ```yaml variableTypes: string: description: Simple text value example: '{{project_name}}' number: description: Numeric value example: '{{max_users}}' boolean: description: True/false value example: '{{include_security}}' date: description: Date value example: '{{go_live_date}}' format: 'YYYY-MM-DD' array: description: List of values example: '{{team_members[]}}' object: description: Nested structure example: '{{config.database.host}}' enum: description: Predefined options example: '{{environment}}' options: ['dev', 'test', 'prod'] ``` ### Variable Syntax ``` Basic: {{variable_name}} Nested: {{object.property}} Array: {{items[0]}} or {{items[]}} Default: {{variable|default_value}} Transform: {{variable|uppercase}} Computed: {{=current_date()}} ``` ## Conditional Logic ### Condition Syntax ``` ^^CONDITION: condition_name^^ Content shown when condition is true ^^/CONDITION: condition_name^^ ^^IF: expression^^ Content for true condition ^^ELSE^^ Content for false condition ^^/IF^^ ^^FOREACH: item in items^^ Repeated content for {{item.name}} ^^/FOREACH^^ ``` ### Condition Examples ```yaml # Boolean condition ^^CONDITION: include_testing^^ ## Testing Strategy - Unit tests required - Integration tests for APIs - UAT scenarios documented ^^/CONDITION: include_testing^^ # Expression condition ^^IF: priority == "high"^^ ⚠️ HIGH PRIORITY PROJECT ^^/IF^^ # Loop condition ^^FOREACH: requirement in requirements^^ - {{requirement.id}}: {{requirement.description}} Priority: {{requirement.priority}} ^^/FOREACH^^ ``` ## LLM Instructions ### Embedding Instructions ```yaml processing_instructions: | [[SYSTEM: This section contains instructions for the LLM]] ELICITATION STRATEGY: 1. Start by asking for {{project_name}} and {{project_type}} 2. Based on project_type, determine which optional sections to include 3. For each included section, gather specific details [[USER_INTERACTION: Progressive disclosure]] - Present template sections one at a time - Allow user to review and modify each section - Confirm before proceeding to next section [[VALIDATION: Ensure completeness]] - All required variables must be provided - Dates must be in correct format - Enum values must be from allowed options ``` ### Interactive Elements ```yaml interactive_sections: requirements_gathering: prompt: | Let's define the requirements for {{project_name}}. I'll ask you about: 1. Functional requirements 2. Non-functional requirements 3. Constraints and assumptions Shall we start with functional requirements? collect: - functional_requirements[] - nonfunctional_requirements[] - constraints[] ``` ## Template Processing ### Processing Pipeline ```javascript // Template processing flow processTemplate({ template: 'prd-template.yaml', context: { project_name: 'Customer Portal', include_testing: true, priority: 'high', }, steps: [ 'loadTemplate', 'validateVariables', 'substituteVariables', 'processConditions', 'processLoops', 'formatOutput', 'validateOutput', ], }); ``` ### Variable Resolution ```javascript // Resolve variables in order resolveVariables({ order: [ 'environmentVariables', // System vars 'contextVariables', // Passed context 'computedVariables', // Calculated values 'defaultValues', // Fallback defaults ], transforms: { uppercase: (val) => val.toUpperCase(), date: (val) => new Date(val).toISOString(), sanitize: (val) => val.replace(/[^\w\s]/gi, ''), }, }); ``` ## Multi-Format Support ### Format Handlers ```yaml formatHandlers: markdown: extension: .md processor: markdownProcessor features: - headers - lists - tables - code blocks yaml: extension: .yaml processor: yamlProcessor features: - nested structures - arrays - multiline strings apex: extension: .cls processor: apexProcessor features: - class generation - method stubs - test classes lwc: extension: .js processor: lwcProcessor features: - component structure - wire adapters - event handlers ``` ## Validation Rules ### Template Validation ```yaml validation: template: required_fields: - name - content - category naming_convention: kebab-case max_size: 100KB variables: naming: camelCase no_reserved_words: true unique_names: true output: must_replace_all_variables: true no_undefined_conditions: true valid_syntax: true ``` ## Best Practices ### Template Design 1. **Clear Structure** - Use consistent formatting - Organize sections logically - Include helpful comments - Provide examples 2. **Variable Naming** - Use descriptive names - Follow naming conventions - Group related variables - Document purpose 3. **Conditional Logic** - Keep conditions simple - Avoid deep nesting - Use meaningful names - Test all paths 4. **LLM Instructions** - Be specific and clear - Guide the interaction - Include validation steps - Handle edge cases ### Template Maintenance 1. **Version Control** - Track template versions - Document changes - Maintain compatibility - Archive old versions 2. **Testing** - Test with sample data - Verify all conditions - Check output formats - Validate edge cases 3. **Documentation** - Document all variables - Explain conditions - Provide usage examples - Include troubleshooting This utility ensures consistent, powerful template processing across all SF-Agent implementations.