cmte/src/templates/README.md

Design by Committee™ except it's just you and LLMs

# Template Engine for Committee

This module implements the template engine for the Committee project, providing context management, file collection handling, and template rendering.

## Components

### Context Management (`context.ts`)

The context management system provides a structured way to pass data between processing phases:

- `TemplateContext` interface defines the structure for context objects
- `createContext()` creates new context objects
- `enhanceContext()` merges new context data into existing context
- `enhanceContextWithPhaseOutput()` intelligently adds phase outputs to context
- `createServiceContext()` creates service-specific context

### File Collection Management (`collections.ts`)

The file collection management system extracts and manages collections of files from configuration:

- `FileCollectionManager` class handles registration and retrieval of file collections
- Automatically extracts collections from configuration objects
- Supports filtering collections with glob-like patterns
- Caches file content for performance

### Template Rendering (`renderer.ts`)

The template renderer provides a comprehensive system for rendering templates with context and file collections:

- `TemplateRenderer` class handles all aspects of template rendering
- Built on Mustache for template variable substitution
- Supports file collections with XML-based rendering
- Supports filtering collections with patterns like `{{collection:*.ts}}`
- Caches template and file content for performance

## Usage

### Basic Template Rendering

```typescript
import { createContext, TemplateRenderer } from './templates/index.js';

// Create context
const context = createContext();
context.directiveName = 'embed';
context.serviceName = 'ParserService';

// Create renderer
const renderer = new TemplateRenderer(context);

// Render a template file
const result = await renderer.renderTemplate('templates/requirements-thinking.md');
```

### Using File Collections

```typescript
import { createContext, TemplateRenderer, FileCollectionManager } from './templates/index.js';

// Create context
const context = createContext();

// Create file collection manager and extract collections from config
const collectionManager = new FileCollectionManager();
collectionManager.extractCollectionsFromConfig(config);

// Create renderer and register collections
const renderer = new TemplateRenderer(context);
renderer.registerCollections(collectionManager.getAllCollections());

// Render template with file collections
const result = await renderer.renderTemplate('templates/draft-spec-thinking.md');
```

## File Collection Syntax

Templates can reference file collections using the standard Mustache syntax:

```
Here are all code files:
{{code}}

Here are only TypeScript files:
{{code:*.ts}}
```

When rendered, file collections are wrapped in XML tags:

```
<code>
  <path/to/file1.ts>
  file content
  </path/to/file1.ts>
  
  <path/to/file2.ts>
  file content
  </path/to/file2.ts>
</code>
```

This XML format works well with LLM-based processing, allowing the model to understand the structure of the files.

## Testing

You can run the template test script to see the template engine in action:

```
npm run test:templates
```

This creates a sample template and renders it with test context and file collections.