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

> Discover the aios-core Template Processing System. Learn how this engine parses, validates, and renders templates for deterministic output. Understand its role with template-format.md.

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: internals
- Published: 2026-02-16

---

**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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/.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.

```javascript
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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/template-format.md).

```javascript
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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/template-validator.js) confirms that all required variables are present and that the markup conforms to [`template-format.md`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/docs/guides/template-engine-v2.md) demonstrates the standard API for processing a template with variables and an AI directive:

```javascript
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`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/cli/commands/generate/index.js) lazy-loads the engine to avoid unnecessary overhead:

```javascript
// 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:

```javascript
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`](https://github.com/SynkraAI/aios-core/blob/main/template-format.md).
- It consists of three core modules: the **`TemplateEngine`** class for orchestration, the **`TemplateValidator`** for compliance checking, and the **[`loader.js`](https://github.com/SynkraAI/aios-core/blob/main/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`](https://github.com/SynkraAI/aios-core/blob/main/.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`](https://github.com/SynkraAI/aios-core/blob/main/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.