Skip to main content

​
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.
​
Location
string
.aiox-core/development/templates/
​
Template Engine
string
Handlebars.js with custom helpers
​
File Extension
string
.md, .yaml, .js, .json (various)

​
Template Categories

​
Documentation Templates

​
aiox-doc-template.md
template
Standard AIOX documentation templatePurpose: Create consistent documentation structureVariables:
  • {{TITLE}} - Document title
  • {{VERSION}} - Document version
  • {{DATE}} - Last updated date
  • {{STATUS}} - Document status (Active, Draft, Deprecated)
Usage:
*create-doc --type=guide --title="Agent Guide"
​
research-prompt-tmpl.md
template
Deep research prompt generator for agent creationPurpose: Generate structured research prompts for specialist-based agentsVariables:
  • {{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:
# 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}}

​
Workflow Templates

​
agent-handoff-tmpl.yaml
template
Agent handoff workflow templatePurpose: Structure handoff between agents in workflow chainsSchema:
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
​
subagent-step-prompt.md
template
Subagent execution step templatePurpose: Structure prompts for multi-step agent workflowsVariables:
  • {{step_number}} - Current step number
  • {{total_steps}} - Total workflow steps
  • {{step_description}} - Step description
  • {{inputs}} - Required inputs
  • {{outputs}} - Expected outputs
  • {{validation}} - Validation criteria

​
Service Templates

​
service-template/
directory
Complete service scaffolding templatePurpose: Generate new service modules with consistent structureStructure:
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:
*create-service api-integration github-api

​
Pattern Templates

​
code-intel-integration-pattern.md
template
Code intelligence integration patternPurpose: Document pattern for integrating code analysis toolsSections:
  • Pattern overview
  • Integration points
  • Configuration requirements
  • Usage examples
  • Error handling

​
Quality Gate Templates

​
ptc-entity-validation.md
template
PTC (Pre-Task Check) entity validation templatePurpose: Validate entity definitions before task executionValidates:
  • Schema compliance
  • Required fields
  • Relationship integrity
  • Naming conventions
​
ptc-qa-gate.md
template
Quality gate checkpoint templatePurpose: Define quality gates for workflow stagesStructure:
# Quality Gate: {{gate_name}}

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

## Validation
{{validation_steps}}

## Exit Criteria
{{exit_criteria}}
​
ptc-research-aggregation.md
template
Research aggregation templatePurpose: Aggregate research findings into structured formatSections:
  • Research summary
  • Key findings
  • Patterns identified
  • Recommendations
  • Source attribution

​
Template Variables

Templates use Handlebars syntax for variable substitution:

​
Basic Variables

​
{{variable}}
string
Simple string substitutionExample: {{agent_name}} → "Dex"
​
{{#if condition}}...{{/if}}
conditional
Conditional rendering
{{#if has_frontend}}
## Frontend Architecture
...
{{/if}}
​
{{#each items}}...{{/each}}
loop
Array iteration
{{#each commands}}
- {{this.name}}: {{this.description}}
{{/each}}

​
Custom Helpers

AIOX extends Handlebars with custom helpers:
​
timestamp
helper
Generate ISO 8601 timestamp
{{timestamp}}  # 2026-03-05T17:00:00Z
​
slugify
helper
Convert string to slug format
{{slugify agent_name}}  # "dex-the-builder" → "dex-the-builder"
​
uppercase
helper
Convert to uppercase
{{uppercase agent_id}}  # "dev" → "DEV"
​
markdown-table
helper
Generate markdown table from array
{{markdown-table columns data}}

​
Template Usage Patterns

​
Creating from Template

Agents use templates via commands: 
# 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

​
template_overrides
object
Override default template behavior in project-config.yaml
template_overrides:
  story:
    sections_order: null  # Use template default
    optional_sections: [] # No optional sections

​
Squad Templates

​
squad/
directory
Agent squad template directoryPurpose: Create multi-agent squads for complex workflowsStructure:
squad/
├── squad-definition.yaml
├── agents/
│   ├── leader.md
│   ├── specialist-1.md
│   └── specialist-2.md
├── workflows/
│   └── main-workflow.md
└── README.md
​
squad-template/
directory
Full squad scaffolding with examplesIncludes:
  • Agent definitions
  • Workflow chains
  • Task definitions
  • Integration patterns
  • Documentation templates

​
Template Best Practices

  • 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
  • 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
  • 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
  • Document all template variables
  • Provide usage examples
  • Explain when to use each template
  • Include sample output
  • Note any dependencies or requirements

​
Template Validation

​
template-validator
script
Location: .aiox-core/utils/template-validator.jsValidates:
  • Handlebars syntax correctness
  • Required variables present
  • Helper function availability
  • Output format correctness
Usage:
node .aiox-core/utils/template-validator.js <template-file>

​
Creating Custom Templates

Create project-specific templates:
  1. Create template file: 
    touch .aiox-core/development/templates/my-template.md
  2. Define template structure: 
    # {{title}}

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

## Content
{{content}}
  3. Register with agent: 
    dependencies:
  templates:
    - my-template.md
  4. Use in command: 
    *generate --template=my-template --title="Example"
Reference: .aiox-core/development/templates/

Build docs developers (and LLMs) love

Get started for freeTalk to us