markitect-tool/docs/template-generation.md

Templates and Generation Hooks

markitect-tool keeps generation deterministic in core. LLM-assisted generation is represented as an external hook boundary, not as a provider dependency.

Template Variables

Templates use simple double-brace variables:

# {{title}}

Owner: {{owner.name}}

{{body}}

Variables can use dot paths into JSON/YAML data.

mkt template inspect template.md
mkt template render template.md --data data.yaml --output rendered.md
mkt template render template.md --set title="Draft" --set owner.name=Ada

Strict rendering is the default. Use --lenient to keep unresolved placeholders in place.

Contract Stubs

Contracts can generate first-draft Markdown stubs:

mkt generate stub --contract examples/contracts/adr.contract.md --set status=proposed

The stub generator creates frontmatter from contract fields and emits required and recommended sections. Forbidden sections are skipped.

Rule-Based Generation

A generation plan is a Markdown file with a fenced YAML block:

# Letter Generation

```yaml generation
template: templates/letter.md
data_file: data/letter.yaml
output: out/letter.md
```

Run it with:

mkt generate rules rules.md --output-dir .

The documents key can render multiple outputs:

documents:
  - template: templates/letter.md
    data:
      title: First
    output: out/first.md
  - template: templates/letter.md
    data_file: data/second.yaml
    output: out/second.md

Assisted Generation Hook

FR-042 is supported as a protocol boundary. External packages can implement a hook with:

from markitect_tool.generation import GenerationHookRequest, GenerationHookResult

class MyHook:
    def generate(self, request: GenerationHookRequest) -> GenerationHookResult:
        ...

Core does not call an LLM provider by itself. Higher layers can pass a hook into generate_with_hook(...) after handling credentials, policy, and provider selection.