Documentation: Showcase template system and usage patterns

[miohansen]

Overview

The repository includes a comprehensive template system with 32 templates across 5 categories. These templates power AI generation, Claude Code integration, and documentation workflows. This issue tracks the creation of documentation to showcase template usage and patterns.

Current Template System

Template Categories (5)

Category	Templates	Install Command	Destination
AI	7 templates	r2r templates install ai	.r2r/eac/templates/ai/
Claude	14 templates	r2r templates install claude	.claude/
Docs	7 templates	r2r templates install docs	docs/reference/
Reports	4 templates	r2r templates install reports	.r2r/templates/reports/
Specs	1 template	r2r templates install specs	specs/risk-controls/

Template Usage Status

✅ Actively Used (100% Integration)

AI Templates (7/7 used):

• commit-message/module.md → create-commit-message command
• commit-message/squash.md → create-squash-message command
• commit-message/top-level.md → create-commit-message command
• design/design.md → create-design command
• risk-assess/risk-assess.md → create-risk-assess command
• risk-profile/risk-profile.md → create-risk-profile command
• specs/specs.md → create-spec command

Claude Templates (14/14 used):

• Agents: architect.md, debugger.md, test-engineer.md
• Commands: boot.md, implement.md, plan.md, review.md, test.md
• Skills: comprehensive-review.md, feature-workflow.md, refactor-safe.md
• Setup: mcp-setup.md, .mcp.json.template
• Schemas: agent-result.json

Specs Templates (1/1 used):

• risk-catalog/controls.catalog.json → validate-control-tags command

Reports Templates (3/4 used):

• test-results.md → show-test-results command
• risk-assess.md → create-risk-assess command
• release-notes-template.md → get-release-notes command
• ⚠️ implementation-report.md → Manual use

⚠️ Reference Templates (Manual Use)

Docs Templates (7 templates):

• design/dr.md - Design record template
• implementation-plan.md - Implementation planning
• intended-use.md - Module documentation
• Operations: blameless-post-mortem.md, defect.md, incident.md, operation-maintenance.md

These are reference templates for manual copying and customization (not auto-generated by commands).

Problems Identified

1. Missing Documentation

Problem: No comprehensive guide showing:

• How templates power the AI generation workflow
• How to customize installed templates
• Template placeholder syntax and usage
• Real-world examples of filled templates

Impact: Users don't understand the template system's power and flexibility.

2. Missing from Help Text

Problem: The r2r templates help text lists 4 template types but 5 are available:

Current Help:
  docs      Install documentation templates
  ai        Install AI prompt templates
  reports   Install report templates
  specs     Install specification templates

Missing:
  claude    Install Claude Code configuration templates ❌

Location: go/eac/commands/impl/templates/templates.go:50-71

3. Limited Discoverability

Problem: No commands to explore templates:

• Can't list available templates
• Can't preview template content
• Can't validate installed templates

Desired commands:

r2r templates list              # Show all available templates
r2r templates describe ai       # Show details for AI templates
r2r templates validate          # Check installed templates

4. No Showcase Examples

Problem: No examples showing:

• Before/after of AI-generated content
• Customization patterns
• Integration workflows
• Best practices

Proposed Solution

1. Create Template Usage Guide

Location: docs/how-to-guides/eac/template-system.md

Content:

# Template System Guide

## Overview
- Template categories and purposes
- Installation destinations
- Integration with commands

## AI Templates
- How AI generation uses templates
- Customizing AI prompts
- Adding custom instructions
- Example: Customizing commit message style

## Claude Templates
- Setting up Claude Code integration
- Agent customization
- Command customization
- Skill workflows

## Docs Templates
- Using reference templates
- Customization workflow
- Team documentation patterns

## Reports Templates
- Automated report generation
- Template customization
- Integration with CI/CD

## Specs Templates
- OSCAL compliance integration
- Security control mapping
- Custom control catalogs

2. Fix Help Text

File: go/eac/commands/impl/templates/templates.go

Change:

  log.Info("Template Types:")
  log.Info("  docs      Install documentation templates to docs/reference/")
  log.Info("  ai        Install AI prompt templates to .r2r/eac/templates/ai/")
+ log.Info("  claude    Install Claude Code templates to .claude/")
  log.Info("  reports   Install report templates to .r2r/templates/reports/")
  log.Info("  specs     Install specification templates to specs/risk-controls/")

3. Create Showcase Examples

Location: docs/reference/templates/examples/

Examples to create:

• ai-commit-message-example.md - Before/after commit message generation
• ai-spec-generation-example.md - Natural language → Gherkin
• claude-agent-customization.md - Customizing architect agent
• report-customization.md - Customizing test results report

4. Add Template Discovery (Future Enhancement)

New commands (low priority):

r2r templates list              # List all templates
r2r templates describe <type>   # Show template details
r2r templates validate          # Validate installed templates

Success Criteria

• Template usage guide created in docs/how-to-guides/eac/template-system.md
• Help text updated to include claude template type
• At least 3 showcase examples created
• Examples demonstrate real-world usage patterns
• Documentation includes customization workflows
• Template system is easy to discover and understand

Additional Context

Analysis Document: See out/template-usage-analysis.md for detailed analysis

Key Insights:

• Templates are well-organized and actively used
• Strong integration with AI generation and Claude Code
• Missing user-facing documentation
• Template system is a core differentiator but hidden from users

Priority: Medium-High

• Essential for showcasing the repository's AI-powered capabilities
• Helps users understand and customize the development workflow
• Required for external users to adopt the tooling

Related Issues

• Claude Code integration improvements
• AI prompt engineering best practices
• Documentation enhancement initiatives