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.

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 template

Purpose: Create consistent documentation structure

Variables:

• {{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 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:

# 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 template

Purpose: Structure handoff between agents in workflow chains

Schema:

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 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

Service Templates

service-template/ · 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:

*create-service api-integration github-api

Pattern Templates

code-intel-integration-pattern.md · template

Code intelligence integration pattern

Purpose: Document pattern for integrating code analysis tools

Sections:

• Pattern overview
• Integration points
• Configuration requirements
• Usage examples
• Error handling

Quality Gate Templates

ptc-entity-validation.md · template

PTC (Pre-Task Check) entity validation template

Purpose: Validate entity definitions before task execution

Validates:

• Schema compliance
• Required fields
• Relationship integrity
• Naming conventions

ptc-qa-gate.md · template

Quality gate checkpoint template

Purpose: Define quality gates for workflow stages

Structure:

# Quality Gate: {{gate_name}}

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

## Validation
{{validation_steps}}

## Exit Criteria
{{exit_criteria}}

ptc-research-aggregation.md · template

Research aggregation template

Purpose: Aggregate research findings into structured format

Sections:

• Research summary
• Key findings
• Patterns identified
• Recommendations
• Source attribution

Template Variables

Templates use Handlebars syntax for variable substitution:

Basic Variables

{{variable}} · string

Simple string substitution

Example: {{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 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

squad-template/ · directory

Full squad scaffolding with examples

Includes:

• Agent definitions
• Workflow chains
• Task definitions
• Integration patterns
• Documentation templates

Template Best Practices

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

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

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

Documentation

• 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.js

Validates:

• 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"
   

Related Documentation

• Tasks Reference
• Agent Definition Files
• Checklists
• Template System Guide

---

Reference: .aiox-core/development/templates/