sf-agent-framework

# Template Format Utility - Agent Instructions ## Purpose This utility provides instructions for AI agents on the advanced template markup conventions used throughout the SF-Agent framework for intelligent document generation. ## Agent Instructions ### When to Use Template Formatting Apply template formatting when: - Generating dynamic documents - Creating reusable content templates - Building interactive user experiences - Implementing conditional logic - Processing variable substitution - Creating structured outputs - Building complex documentation This utility defines the advanced template markup conventions used throughout the SF-Agent framework for intelligent document generation. ## Template Markup Conventions ### 1. Variable Replacement **Basic Variables**: ``` {{variable_name}} {{user.name}} {{project.title}} ``` **Nested Objects**: ``` {{company.address.city}} {{team.members[0].name}} ``` **Default Values**: ``` {{variable_name|default_value}} {{project.budget|"Not Specified"}} ``` ### 2. LLM Instructions **Presentation Guidance**: ``` [[LLM: Present this section first and wait for user confirmation before proceeding]] [[LLM: Use professional tone, avoid technical jargon when explaining to business users]] [[LLM: If user seems confused, offer to provide examples]] ``` **Elicitation Triggers**: ``` [[LLM: After presenting this section, offer advanced elicitation options for refinement]] [[LLM: This is a critical section - ensure user fully understands implications]] ``` **Dynamic Behavior**: ``` [[LLM: If project_type == "complex", include additional risk sections]] [[LLM: Adapt language based on user's expertise level]] ``` ### 3. Conditional Content **Basic Conditions**: ``` ^^CONDITION: has_integration^^ ## Integration Requirements This section details the integration points... ^^/CONDITION: has_integration^^ ``` **Complex Conditions**: ``` ^^CONDITION: project_size == "enterprise" AND compliance_required == true^^ ## Compliance and Governance Extended compliance requirements for enterprise projects... ^^/CONDITION: project_size^^ ``` **Nested Conditions**: ``` ^^CONDITION: include_testing^^ ## Testing Strategy ^^CONDITION: automated_testing^^ ### Automated Testing Approach ^^/CONDITION: automated_testing^^ ^^/CONDITION: include_testing^^ ``` ### 4. Repeatable Sections **Basic Repetition**: ``` <<REPEAT section="requirement" count="{{requirement_count}}">> ### Requirement {{requirement.number}}: {{requirement.title}} **Description**: {{requirement.description}} **Priority**: {{requirement.priority}} <</REPEAT>> ``` **Dynamic Lists**: ``` <<REPEAT section="stakeholder" list="{{project.stakeholders}}">> - **{{stakeholder.name}}** ({{stakeholder.role}}): {{stakeholder.interest}} <</REPEAT>> ``` ### 5. Computed Values **Simple Calculations**: ``` {{COMPUTE: total_hours = estimated_hours * 1.2}} **Buffer Included**: {{total_hours}} hours ``` **Conditional Calculations**: ``` {{COMPUTE: risk_factor = IF(project_size == "large", 1.5, 1.2)}} **Risk Multiplier**: {{risk_factor}} ``` ### 6. Formatting Instructions **Text Formatting**: ``` {{FORMAT: uppercase}}{{project.code}}{{/FORMAT}} {{FORMAT: date="MMM DD, YYYY"}}{{project.start_date}}{{/FORMAT}} {{FORMAT: currency}}{{budget.total}}{{/FORMAT}} ``` ### 7. Include External Content **Include Other Templates**: ``` {{INCLUDE: templates/common-header.md}} {{INCLUDE: templates/legal-disclaimer.md}} ``` **Conditional Includes**: ``` ^^CONDITION: needs_security^^ {{INCLUDE: templates/security-requirements.md}} ^^/CONDITION: needs_security^^ ``` ### 8. Validation Markers **Required Sections**: ```  ## Executive Summary {{executive_summary}} ``` **Quality Checkpoints**: ```  ## Technical Architecture ``` ### 9. Meta Instructions **Template Metadata**: ``` --- template: user-story version: 2.0 requires: [project_name, user_role, acceptance_criteria] optional: [technical_notes, dependencies] --- ``` **Section Properties**: ```  ## System Design ``` ## Template Processing Guidelines ### Processing Order 1. Parse template metadata 2. Validate required variables present 3. Process includes recursively 4. Evaluate conditions 5. Expand repeatable sections 6. Replace variables 7. Apply formatting 8. Execute computations 9. Follow LLM instructions ### Error Handling - Missing required variables: Prompt user - Invalid conditions: Skip section with warning - Circular includes: Detect and prevent - Malformed markup: Highlight and request fix ### Best Practices 1. **Clear Variable Names**: Use descriptive names like `{{project.estimated_completion_date}}` not `{{date2}}` 2. **Logical Conditions**: Name conditions based on meaning: `has_external_api` not `condition_1` 3. **Progressive Disclosure**: Use LLM instructions to guide users through complex templates 4. **Validation Points**: Mark critical sections that need review 5. **Reusable Components**: Extract common sections into includable templates ## Integration with Agents Agents using templates should: 1. **Pre-validate**: Check all required variables before processing 2. **Interactive Mode**: Use LLM instructions for user guidance 3. **Quality Checks**: Validate output against checklists 4. **Iterative Refinement**: Allow users to refine sections 5. **Context Awareness**: Pass appropriate context for conditions ## Example Template ```markdown --- template: salesforce-user-story version: 1.0 requires: [story_title, user_role, business_value] --- # User Story: {{story_title}} [[LLM: Present this user story and ask if the user wants to refine any section]] ## Story As a {{user_role}}, I want {{user_need}}, So that {{business_value}}. ^^CONDITION: has_acceptance_criteria^^ ## Acceptance Criteria <<REPEAT section="criterion" list="{{acceptance_criteria}}">> - {{criterion.description}} <</REPEAT>> ^^/CONDITION: has_acceptance_criteria^^ ^^CONDITION: is_technical^^ ## Technical Notes [[LLM: This section is for technical team members only]] {{technical_implementation_notes}} ^^/CONDITION: is_technical^^  ```