agent-rules-kit/.trae/rules/05-template-processing.md

Bootstrap of **Cursor** rules (`.mdc`) and mirror documentation (`.md`) for AI agent-guided projects.

---
description:
globs: cli/**/*,templates/**/*
alwaysApply: false
---

# Template Processing & Variables

This document explains how templates are processed and variables are substituted in Agent Rules Kit.

## Template Variables

The following variables are available for use in template files:

| Variable            | Description                       | Example            |
| ------------------- | --------------------------------- | ------------------ |
| `{projectPath}`     | Path to the project               | `/path/to/project` |
| `{detectedVersion}` | Detected version of the framework | `10`               |
| `{versionRange}`    | Compatible version range          | `v10-11`           |
| `{stack}`           | Selected stack                    | `laravel`          |

## Processing Flow

1. **Read Template**: Templates are read from `templates/` directory
2. **Process Variables**: All variables in `{placeholder}` format are replaced
3. **Add Front Matter**: Metadata is added as front matter to MDC files
4. **Output Generation**: Processed content is written to destination

## Implementation

The main processing happens in `cli/utils/file-helpers.js`:

```javascript
// Process template variables (simplified example)
const processTemplateVariables = (content, meta = {}) => {
	let processedContent = content;

	// Replace all template variables with their values
	const templateVariables = [
		{ value: meta.detectedVersion, replace: 'detectedVersion' },
		{ value: meta.versionRange, replace: 'versionRange' },
		{ value: meta.projectPath, replace: 'projectPath' },
		{ value: meta.stack, replace: 'stack' },
	];

	templateVariables.forEach(({ value, replace }) => {
		if (value) {
			const regex = new RegExp(`\\{${replace}\\}`, 'g');
			processedContent = processedContent.replace(regex, value);
		}
	});

	return processedContent;
};
```

## Example

Template file:

```markdown
# {stack} Documentation

This project is using {stack} version {detectedVersion}.
It is located at {projectPath}.
```

After processing (if stack=laravel, detectedVersion=10, projectPath=/app):

```markdown
# laravel Documentation

This project is using laravel version 10.
It is located at /app.
```

# Template Structure Guidelines

This document explains the organization pattern for all stack documentation in Agent Rules Kit.

## Core Organization Pattern

All documentation for stacks follows this three-tier structure:

### 1. Base Documentation (Conceptual)

Files in `templates/stacks/<stack>/base/` contain **ONLY** conceptual information with no implementation-specific code. These files:

-   Explain general concepts
-   Provide architectural guidelines
-   Outline best practices
-   Avoid version-specific implementation details

Example: `templates/stacks/<stack>/base/architecture-concepts.md`

### 2. Version-Specific Implementation

Files in `templates/stacks/<stack>/v<number>/` contain concrete implementation examples specific to that version:

-   Code examples showing actual implementation
-   Version-specific APIs and patterns
-   Testing implementations with exact syntax
-   Configuration examples

Example: `templates/stacks/<stack>/v3/testing-best-practices.md`

### 3. Shared Version Implementations

When implementations are identical across adjacent versions, use a shared folder:

-   `templates/stacks/<stack>/v2-3/` for code shared between versions 2 and 3
-   Avoids duplication while maintaining version specificity
-   Should still be implementation-focused

## Naming Conventions

1. Use consistent file names across versions
2. Same base filename should refer to the same concept
3. Keep extensions as `.md` (they will be converted to `.mdc` by the CLI)

## When Editing Templates

-   If adding new concepts: add to `/base` without implementation details
-   If adding version-specific code: add to the appropriate `/v<number>` folder
-   If updating shared code: ensure it's compatible with all versions in the range

This structure maintains clear separation between concepts and implementation, preventing future maintenance issues and ensuring clear guidance for all supported versions.