> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/SynkraAI/aiox-core/llms.txt
> Use this file to discover all available pages before exploring further.

# Templates

> Reference for AIOX template system and file generation patterns

## Overview

AIOX uses **Handlebars templates** to generate consistent files across the framework. Templates are stored in `.aiox-core/development/templates/` and used by agents to create documentation, code, and configuration files.

<ParamField path="Location" type="string">
  `.aiox-core/development/templates/`
</ParamField>

<ParamField path="Template Engine" type="string">
  Handlebars.js with custom helpers
</ParamField>

<ParamField path="File Extension" type="string">
  `.md`, `.yaml`, `.js`, `.json` (various)
</ParamField>

## Template Categories

### Documentation Templates

<ResponseField name="aiox-doc-template.md" type="template">
  Standard AIOX documentation template

  **Purpose:** Create consistent documentation structure

  **Variables:**

  * `{{TITLE}}` - Document title
  * `{{VERSION}}` - Document version
  * `{{DATE}}` - Last updated date
  * `{{STATUS}}` - Document status (Active, Draft, Deprecated)

  **Usage:**

  ```bash theme={null}
  *create-doc --type=guide --title="Agent Guide"
  ```
</ResponseField>

<ResponseField name="research-prompt-tmpl.md" type="template">
  Deep research prompt generator for agent creation

  **Purpose:** Generate structured research prompts for specialist-based agents

  **Variables:**

  * `{{specialist_name}}` - Human expert name
  * `{{specialist_slug}}` - Slug format identifier
  * `{{activity}}` - Specific activity area
  * `{{domain}}` - Domain expertise
  * `{{agent_purpose}}` - Agent's primary purpose
  * `{{scope_items}}` - Research scope areas (array)
  * `{{sources}}` - Recommended sources (array)
  * `{{deliverables}}` - Expected outputs (array)

  **Template Structure:**

  ```markdown theme={null}
  # Deep Research Prompt: {{specialist_name}} {{activity_expanded}}

  ## REFINED TOPIC
  "The {{activity_expanded}} Engineering of {{specialist_name}}"

  ## CONTEXT
  {{context_paragraph}}

  ## SCOPE
  {{#each scope_items}}
  ### {{this.number}}. {{this.title}}
  {{#each this.sub_points}}
  - {{this}}
  {{/each}}
  {{/each}}

  ## EXPECTED RESULTS
  {{#each deliverables}}
  - {{this}}
  {{/each}}
  ```
</ResponseField>

### Workflow Templates

<ResponseField name="agent-handoff-tmpl.yaml" type="template">
  Agent handoff workflow template

  **Purpose:** Structure handoff between agents in workflow chains

  **Schema:**

  ```yaml theme={null}
  from_agent: {{from_agent_id}}
  to_agent: {{to_agent_id}}
  last_command: {{command_executed}}
  context:
    story: {{story_id}}
    branch: {{git_branch}}
    files_modified: {{files_list}}
  handoff_reason: {{reason}}
  next_suggested_command: {{next_command}}
  consumed: false
  timestamp: {{iso_8601_timestamp}}
  ```

  **Used by:** Workflow chain system for agent coordination
</ResponseField>

<ResponseField name="subagent-step-prompt.md" type="template">
  Subagent execution step template

  **Purpose:** Structure prompts for multi-step agent workflows

  **Variables:**

  * `{{step_number}}` - Current step number
  * `{{total_steps}}` - Total workflow steps
  * `{{step_description}}` - Step description
  * `{{inputs}}` - Required inputs
  * `{{outputs}}` - Expected outputs
  * `{{validation}}` - Validation criteria
</ResponseField>

### Service Templates

<ResponseField name="service-template/" type="directory">
  Complete service scaffolding template

  **Purpose:** Generate new service modules with consistent structure

  **Structure:**

  ```
  service-template/
  ├── src/
  │   ├── {{service-name}}.service.ts
  │   ├── {{service-name}}.interface.ts
  │   └── {{service-name}}.config.ts
  ├── tests/
  │   └── {{service-name}}.test.ts
  ├── README.md
  └── package.json
  ```

  **Service Types:**

  * `api-integration` - External API client service
  * `utility` - Utility/helper service
  * `agent-tool` - MCP tool integration service

  **Usage:**

  ```bash theme={null}
  *create-service api-integration github-api
  ```
</ResponseField>

### Pattern Templates

<ResponseField name="code-intel-integration-pattern.md" type="template">
  Code intelligence integration pattern

  **Purpose:** Document pattern for integrating code analysis tools

  **Sections:**

  * Pattern overview
  * Integration points
  * Configuration requirements
  * Usage examples
  * Error handling
</ResponseField>

### Quality Gate Templates

<ResponseField name="ptc-entity-validation.md" type="template">
  PTC (Pre-Task Check) entity validation template

  **Purpose:** Validate entity definitions before task execution

  **Validates:**

  * Schema compliance
  * Required fields
  * Relationship integrity
  * Naming conventions
</ResponseField>

<ResponseField name="ptc-qa-gate.md" type="template">
  Quality gate checkpoint template

  **Purpose:** Define quality gates for workflow stages

  **Structure:**

  ```markdown theme={null}
  # Quality Gate: {{gate_name}}

  ## Criteria
  {{#each criteria}}
  - [ ] {{this.description}}
  {{/each}}

  ## Validation
  {{validation_steps}}

  ## Exit Criteria
  {{exit_criteria}}
  ```
</ResponseField>

<ResponseField name="ptc-research-aggregation.md" type="template">
  Research aggregation template

  **Purpose:** Aggregate research findings into structured format

  **Sections:**

  * Research summary
  * Key findings
  * Patterns identified
  * Recommendations
  * Source attribution
</ResponseField>

## Template Variables

Templates use **Handlebars syntax** for variable substitution:

### Basic Variables

<ParamField path="{{variable}}" type="string">
  Simple string substitution

  Example: `{{agent_name}}` → `"Dex"`
</ParamField>

<ParamField path="{{#if condition}}...{{/if}}" type="conditional">
  Conditional rendering

  ```handlebars theme={null}
  {{#if has_frontend}}
  ## Frontend Architecture
  ...
  {{/if}}
  ```
</ParamField>

<ParamField path="{{#each items}}...{{/each}}" type="loop">
  Array iteration

  ```handlebars theme={null}
  {{#each commands}}
  - {{this.name}}: {{this.description}}
  {{/each}}
  ```
</ParamField>

### Custom Helpers

AIOX extends Handlebars with custom helpers:

<ResponseField name="timestamp" type="helper">
  Generate ISO 8601 timestamp

  ```handlebars theme={null}
  {{timestamp}}  # 2026-03-05T17:00:00Z
  ```
</ResponseField>

<ResponseField name="slugify" type="helper">
  Convert string to slug format

  ```handlebars theme={null}
  {{slugify agent_name}}  # "dex-the-builder" → "dex-the-builder"
  ```
</ResponseField>

<ResponseField name="uppercase" type="helper">
  Convert to uppercase

  ```handlebars theme={null}
  {{uppercase agent_id}}  # "dev" → "DEV"
  ```
</ResponseField>

<ResponseField name="markdown-table" type="helper">
  Generate markdown table from array

  ```handlebars theme={null}
  {{markdown-table columns data}}
  ```
</ResponseField>

## Template Usage Patterns

### Creating from Template

Agents use templates via commands:

```bash theme={null}
# Create documentation from template
*create-doc --template=aiox-doc-template --title="My Guide"

# Generate service from template
*create-service api-integration github-client

# Create research prompt
*create-deep-research-prompt --specialist="Gary Halbert" --domain="copywriting"
```

### Template Resolution

Templates are resolved from multiple locations:

1. **Project templates** - `.aiox-core/development/templates/`
2. **Framework templates** - Core template library
3. **Custom templates** - User-defined in `templates/`

### Template Overrides

<ParamField path="template_overrides" type="object">
  Override default template behavior in `project-config.yaml`

  ```yaml theme={null}
  template_overrides:
    story:
      sections_order: null  # Use template default
      optional_sections: [] # No optional sections
  ```
</ParamField>

## Squad Templates

<ResponseField name="squad/" type="directory">
  Agent squad template directory

  **Purpose:** Create multi-agent squads for complex workflows

  **Structure:**

  ```
  squad/
  ├── squad-definition.yaml
  ├── agents/
  │   ├── leader.md
  │   ├── specialist-1.md
  │   └── specialist-2.md
  ├── workflows/
  │   └── main-workflow.md
  └── README.md
  ```
</ResponseField>

<ResponseField name="squad-template/" type="directory">
  Full squad scaffolding with examples

  **Includes:**

  * Agent definitions
  * Workflow chains
  * Task definitions
  * Integration patterns
  * Documentation templates
</ResponseField>

## Template Best Practices

<AccordionGroup>
  <Accordion title="Template Design">
    * Use clear, descriptive variable names
    * Provide default values where appropriate
    * Document required vs. optional variables
    * Include usage examples in template comments
    * Use consistent formatting and structure
  </Accordion>

  <Accordion title="Variable Naming">
    * Use `snake_case` for template variables
    * Prefix boolean variables with `has_`, `is_`, `should_`
    * Use plural names for arrays (`items`, `commands`, `agents`)
    * Be explicit about data types in documentation
  </Accordion>

  <Accordion title="Template Organization">
    * Group related templates in subdirectories
    * Use clear, descriptive file names
    * Include README.md for complex template sets
    * Version templates when making breaking changes
    * Maintain backward compatibility when possible
  </Accordion>

  <Accordion title="Documentation">
    * Document all template variables
    * Provide usage examples
    * Explain when to use each template
    * Include sample output
    * Note any dependencies or requirements
  </Accordion>
</AccordionGroup>

## Template Validation

<ResponseField name="template-validator" type="script">
  Location: `.aiox-core/utils/template-validator.js`

  **Validates:**

  * Handlebars syntax correctness
  * Required variables present
  * Helper function availability
  * Output format correctness

  **Usage:**

  ```bash theme={null}
  node .aiox-core/utils/template-validator.js <template-file>
  ```
</ResponseField>

## Creating Custom Templates

Create project-specific templates:

1. **Create template file:**
   ```bash theme={null}
   touch .aiox-core/development/templates/my-template.md
   ```

2. **Define template structure:**
   ```handlebars theme={null}
   # {{title}}

   {{#if description}}
   ## Description
   {{description}}
   {{/if}}

   ## Content
   {{content}}
   ```

3. **Register with agent:**
   ```yaml theme={null}
   dependencies:
     templates:
       - my-template.md
   ```

4. **Use in command:**
   ```bash theme={null}
   *generate --template=my-template --title="Example"
   ```

## Related Documentation

* [Tasks Reference](/api/tasks)
* [Agent Definition Files](/api/agent-definition)
* [Checklists](/api/checklists)
* [Template System Guide](/guides/templates)

***

*Reference: `.aiox-core/development/templates/`*