# Template File Structure for Synkra AIOX
# This YAML defines output templates that agents use to generate consistent documents
# Version: 1.0 (Story 6.1.2 - Personalized Agents)

template:
  name: {TemplateName}
  id: {template-id}
  description: {Brief description of what this template generates}
  version: "1.0"

  # When to use this template
  usage:
    when: {When to use this template}
    agents: [{agent1}, {agent2}]  # Which agents typically use this

  # Personality configuration
  personality:
    supports_personalization: true  # Can agents inject personality?
    personality_slots:              # Where personality can be injected
      - section: {section_name}
        field: {field_name}
        type: {text|emoji|vocabulary}

    fixed_structure: true           # Structure must not change
    fixed_sections:                 # Sections that are always the same
      - {section1}
      - {section2}

# Document metadata (standardized across all outputs)
metadata:
  agent: "{agent.name} ({agent.persona_profile.archetype})"
  generated_at: "{timestamp}"
  duration: "{duration}"
  tokens_used: "{tokens.total} total"
  template_version: "{template.version}"

# Document structure (FIXED POSITIONS for familiaridade)
structure:
  # Section 1: Header (ALWAYS FIRST)
  header:
    format: markdown
    required: true
    content: |
      # {DocumentTitle}

      **Generated by:** {agent.name} ({agent.persona_profile.archetype})
      **Date:** {timestamp}
      **Version:** {document.version}

  # Section 2: Executive Summary (ALWAYS SECOND)
  summary:
    format: markdown
    required: true
    personality_slot: greeting  # Agent can personalize this
    content: |
      ## Executive Summary

      {PERSONALITY_SLOT: Agent introduces document in their voice}

      **Examples by archetype:**
      - **Builder (Dex):** "Construí este documento para mapear a arquitetura. Vamos direto ao ponto."
      - **Guardian (Quinn):** "Validei todos os requisitos antes de gerar este documento. Tudo verificado."
      - **Balancer (Pax):** "Este documento equilibra visão técnica e necessidades de negócio."

      {summary_content}

  # Section 3: Main Content (VARIES BY TEMPLATE TYPE)
  content:
    format: markdown
    required: true
    subsections:
      - name: {subsection1_name}
        required: {true|false}
        content: |
          {subsection1_content}

      - name: {subsection2_name}
        required: {true|false}
        personality_slot: {slot_name}  # Optional personality injection
        content: |
          {subsection2_content}

  # Section 4: Metrics & Validation (ALWAYS BEFORE FOOTER)
  metrics:
    format: markdown
    required: true
    content: |
      ## Validation Metrics

      - **Duration:** {duration}
      - **Tokens Used:** {tokens.total} total
      - **Sections:** {sections.completed}/{sections.total}
      - **Completeness:** {completeness}%

  # Section 5: Footer (ALWAYS LAST)
  footer:
    format: markdown
    required: true
    personality_slot: signature  # Agent signature
    content: |
      ---

      **Generated by:** {agent.name} ({agent.persona_profile.archetype})
      **Template:** {template.name} v{template.version}

      {PERSONALITY_SLOT: agent.signature_closing}

# Field definitions (data structure for template)
fields:
  # Required fields (must be provided)
  required:
    - name: {field1_name}
      type: {string|number|boolean|array|object}
      description: {Field description}
      validation:
        min_length: {number}      # For strings
        max_length: {number}      # For strings
        pattern: {regex}          # For validation

    - name: {field2_name}
      type: {type}
      description: {Description}

  # Optional fields (have defaults)
  optional:
    - name: {field3_name}
      type: {type}
      default: {default_value}
      description: {Description}

# Personality configuration for this template
personality_configuration:
  # Vocabulary guidance for this document type
  recommended_vocabulary:
    Builder: [construir, implementar, arquitetar, estruturar]
    Guardian: [validar, proteger, garantir, verificar]
    Balancer: [equilibrar, harmonizar, alinhar, integrar]
    Visionary: [planejar, estrategizar, projetar, antecipar]

  # Tone guidance for this document type
  recommended_tone:
    formal_document: analytical    # PRDs, architecture docs
    user_facing: empathetic       # User guides, onboarding
    technical: pragmatic          # Technical specs, API docs
    strategic: collaborative      # Roadmaps, planning docs

  # Emoji usage guidance
  emoji_usage:
    frequency: {minimal|low|medium|high}
    allowed_contexts: [{header}, {status}, {celebration}]
    archetype_palettes: true  # Use archetype-specific emoji palettes

# Output formatting (standardization rules)
formatting:
  # Markdown style
  markdown:
    heading_style: atx           # # Heading (not underline style)
    list_style: dash             # - Item (not * or +)
    code_fence: backticks        # ``` (not ~~~)
    emphasis: asterisk           # *italic* **bold**

  # Structure consistency
  consistency:
    section_spacing: 2           # Blank lines between sections
    subsection_spacing: 1        # Blank lines between subsections
    list_spacing: 0              # No blank lines in lists

  # Fixed positions (familiaridade requirement)
  fixed_positions:
    metadata: "lines 1-5"        # Always at top
    summary: "after metadata"    # Always second
    metrics: "before footer"     # Always second-to-last
    signature: "last line"       # Always last

# Validation rules
validation:
  # Structure validation
  structure:
    - rule: header_present
      message: "Header section required"

    - rule: sections_ordered
      message: "Sections must follow template order"

    - rule: metrics_before_footer
      message: "Metrics section must be before footer"

  # Content validation
  content:
    - rule: all_required_fields_present
      message: "All required fields must be provided"

    - rule: personality_slots_filled
      message: "All personality slots must be populated"

  # Personality validation
  personality:
    - rule: uses_agent_vocabulary
      message: "Should use words from agent's vocabulary list"

    - rule: matches_agent_tone
      message: "Tone should match agent's persona_profile.communication.tone"

    - rule: signature_present
      message: "Agent signature_closing required in footer"

# Examples (for documentation)
examples:
  - name: {Example 1 Name}
    agent: dev
    description: {What this example demonstrates}
    input:
      {field1}: {value1}
      {field2}: {value2}
    output: |
      {Generated document content}

  - name: {Example 2 Name}
    agent: qa
    description: {What this example demonstrates}
    input:
      {field1}: {value1}
    output: |
      {Generated document content}

# Change log
changelog:
  - version: "1.0"
    date: "2025-01-14"
    changes:
      - Added persona_profile support
      - Standardized metrics section
      - Added personality slots
      - Fixed section positions for familiaridade

# Related documents
related:
  standard: docs/standards/AGENT-PERSONALIZATION-STANDARD-V1.md
  agents:
    - .aiox-core/agents/{agent1}.md
    - .aiox-core/agents/{agent2}.md
  tasks:
    - .aiox-core/tasks/{task1}.md
  templates:
    - .aiox-core/product/templates/{related-template}.yaml

---

# USAGE GUIDE

## How Agents Use This Template

1. **Load Template:**
   ```javascript
   const template = loadTemplate('{template-id}');
   ```

2. **Populate Fields:**
   ```javascript
   const data = {
     {field1}: value1,
     {field2}: value2,
     agent: currentAgent,
     timestamp: new Date().toISOString()
   };
   ```

3. **Inject Personality:**
   ```javascript
   const personalizedContent = injectPersonality(
     template,
     currentAgent.persona_profile,
     data
   );
   ```

4. **Validate Output:**
   ```javascript
   const validation = validateTemplate(personalizedContent, template);
   if (!validation.valid) {
     throw new Error(validation.errors);
   }
   ```

5. **Generate Document:**
   ```javascript
   const document = renderTemplate(personalizedContent);
   saveDocument(document);
   ```

## Personality Injection

**Where personality shows:**
- Greeting/introduction in summary
- Recommendations and guidance
- Status messages
- Signature closing

**Where personality NEVER shows:**
- Section order
- Metric positions
- Required field labels
- Validation rules

## Validation Checklist

Before committing template file:

- [ ] All required fields defined
- [ ] Section order matches standard
- [ ] Metrics section before footer
- [ ] Personality slots identified
- [ ] Formatting rules specified
- [ ] Examples provided
- [ ] Validation rules complete
- [ ] Related documents linked

---

**Template File Version:** 1.0
**Last Updated:** 2025-01-14
**Applies to:** Story 6.1.2+ (Personalized Agents)