Template Processing System in aios-core: How It Works With template-format.md

The Template Processing System is a lightweight engine that parses, validates, and renders template strings according to the unified markup specification defined in template-format.md, enabling deterministic output generation across all aios-core components.

The Template Processing System powers every templated operation inside the aios-core repository, from code scaffolding to agent prompt generation. At its foundation lies template-format.md, a canonical specification living in aios-core/utils/ that defines the exact syntax for variable placeholders, AI directives, and conditional logic. By enforcing this single source of truth, aios-core guarantees that any template—whether used by the CLI, the task runner, or the LLM layer—undergoes the same predictable parsing and validation pipeline.

Core Components of the Template Processing System

The engine is modular by design, separating concerns into three primary modules that collaborate to transform raw template strings into finished output.

TemplateEngine Class

Located at .aios-core/infrastructure/scripts/template-engine.js, the TemplateEngine class serves as the primary entry point. It exposes the process() method, which orchestrates the full lifecycle: parsing the template, validating against the spec, injecting variables, and handling AI-specific directives.

const TemplateEngine = require('./.aios-core/infrastructure/scripts/template-engine');
const engine = new TemplateEngine();

const result = engine.process(templateString, variables);

TemplateValidator

The .aios-core/infrastructure/scripts/template-validator.js module performs pre-flight checks before rendering occurs. Its isValid() method ensures that every required placeholder declared in the template has a corresponding value in the supplied variables object and that the file contains valid YAML front-matter as mandated by template-format.md.

const TemplateValidator = require('./.aios-core/infrastructure/scripts/template-validator');
const validator = new TemplateValidator();

if (!validator.isValid(templateContent)) {
  throw new Error('Template does not conform to template-format.md');
}

Template Loader

Found at .aios-core/product/templates/engine/loader.js, the loader handles file system operations and initial parsing. It reads template files from disk, strips the mandatory YAML front-matter, and passes the remaining content to the TemplateEngine. If a file lacks the required front-matter, the loader throws an Invalid template format error immediately.

How template-format.md Defines the Markup Language

The template-format.md specification in aios-core/utils/ establishes three distinct markup constructs that the Template Processing System recognizes and handles differently during the rendering pipeline.

Variable Placeholders

The engine scans for double-curly syntax: {{variable}}. When the process() method receives a variables object, it performs a global replacement of every placeholder key with its corresponding value. If a placeholder exists in the template but not in the variables object, the TemplateValidator flags it as an error before rendering begins.

AI-Only Directives

Enclosed in double brackets, [[LLM: …]] blocks contain instructions intended exclusively for the large-language-model layer. The Template Processing System handles these directives based on the execution mode:

• Incremental mode: Preserves the directive for downstream LLM processing.
• Rapid mode: Strips the directive entirely before returning the final string.

This dual-mode behavior allows the same template to serve both interactive AI workflows and fast, deterministic code generation.

Conditional Blocks

The specification supports logic-based rendering through constructs like {{#if condition}} … {{/if}}. The engine evaluates the condition against the supplied variables object and includes or excludes the enclosed content accordingly. This enables dynamic template behavior without requiring external preprocessing.

Processing Workflow

The Template Processing System executes a deterministic five-step pipeline every time it renders output:

1. Load: The loader.js module reads the template file and extracts YAML front-matter.
2. Parse: TemplateEngine.parse() tokenizes the content, identifying placeholders, AI directives, and conditional blocks.
3. Validate: template-validator.js confirms that all required variables are present and that the markup conforms to template-format.md.
4. Render: The engine injects variables, evaluates conditionals, and processes AI directives according to the current execution mode.
5. Return: The final resolved string is passed back to the caller, ready for file writing, LLM consumption, or CLI output.

Practical Implementation Examples

Basic Script Usage

The following pattern from docs/guides/template-engine-v2.md demonstrates the standard API for processing a template with variables and an AI directive:

const TemplateEngine = require('./.aios-core/infrastructure/scripts/template-engine');
const engine = new TemplateEngine();

// A minimal template with a placeholder and an LLM directive
const tmpl = `
Hello {{name}}!

[[LLM: Summarise the greeting in one sentence.]]
`;

const result = engine.process(tmpl, { name: 'Alice' });
console.log(result);

Output:

Hello Alice!

Summarise the greeting in one sentence.

CLI Command Integration

The generate command in .aios-core/cli/commands/generate/index.js lazy-loads the engine to avoid unnecessary overhead:

// Lines 17-30 of the command file
let TemplateEngine = null;

function getTemplateEngine() {
  if (!TemplateEngine) {
    TemplateEngine = engine.TemplateEngine;
  }
  return TemplateEngine;
}

// When a user runs `aios generate …`
const Engine = getTemplateEngine();
const rendered = Engine.process(templateFileContent, userVariables);
writeFile(targetPath, rendered);

Validation Before Rendering

To prevent runtime errors, validate templates against the specification before processing:

const TemplateValidator = require('./.aios-core/infrastructure/scripts/template-validator');
const validator = new TemplateValidator();

if (!validator.isValid(templateContent)) {
  throw new Error('Template does not conform to template-format.md');
}

Summary

• The Template Processing System is a purpose-built engine in aios-core that enforces a unified template syntax defined by template-format.md.
• It consists of three core modules: the TemplateEngine class for orchestration, the TemplateValidator for compliance checking, and the loader.js module for file handling.
• The system recognizes three markup types: variable placeholders ({{var}}), AI directives ([[LLM: …]]), and conditional blocks ({{#if}}).
• Execution modes (incremental vs. rapid) determine whether AI directives are preserved for LLM processing or stripped for fast generation.
• All templates must include YAML front-matter, which the loader extracts before parsing begins.

Frequently Asked Questions

What happens if a template is missing a required variable placeholder?

The TemplateValidator detects the mismatch before rendering occurs and emits a clear warning indicating which placeholders are missing. According to the implementation in .aios-core/infrastructure/scripts/template-validator.js, the engine will throw an error or warning message such as "Template contains X placeholders: …" to prevent incomplete output.

How does the Template Processing System handle AI directives differently in rapid mode versus incremental mode?

In incremental mode, the engine preserves [[LLM: …]] blocks so that downstream large-language-model layers can process the instructions. In rapid mode, the engine strips these directives entirely before returning the final string, optimizing for speed when LLM processing is not required. This dual-mode behavior allows the same template to serve both interactive AI workflows and deterministic code generation.

Where is the template-format.md specification located and why is it important?

The template-format.md file resides in aios-core/utils/ and acts as the single source of truth for all template syntax rules. It is important because it ensures consistency across every component that uses the Template Engine—including CLI commands, document generators, and agent prompts—by standardizing how variable placeholders, AI directives, and conditional logic must be written.

Can I use conditional logic inside templates without external preprocessing?

Yes. The Template Processing System natively supports conditional blocks using syntax such as {{#if condition}} … {{/if}}. The engine evaluates these conditions against the supplied variables object during the rendering phase, allowing you to include or exclude content dynamically without requiring external tools or manual preprocessing steps.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}