# Roadcrew Templates

**Roadcrew is template-driven** - all documents use structured templates with `{{VARIABLE}}` substitution for consistency and quality.

---

## Core Product Templates

### Strategic Documents (WHAT/WHY/WHO/WHEN)
- **`vision.template.md`** - Product vision and PRD (translates ideas into actionable epics)
- **`memory-bank/requirements/brds/brd.template.md`** - Business Requirements Document (market, pricing, revenue, segments - referenced by PRD/Spec)
- **`brd-example.template.md`** - Example BRD showing optimal structure with word limits
- **`memory-bank/requirements/prds/prd.template.md`** - Product Requirements Document (what/why only, maps 1:1 to spec, strict length limits)
- **`prd-example.template.md`** - Example PRD showing optimal structure with word limits
- **`memory-bank/requirements/specs/spec.template.md`** - Technical specifications (ruthlessly concise, AI-parseable, maps 1:1 to enhancement issues)
- **`spec-example.template.md`** - Example spec showing optimal structure with word limits

### Release Planning
- **`memory-bank/releases/current-release.template.md`** - Release tracking (for current releases)
- **`memory-bank/releases/future-releases.template.md`** - Planned releases and roadmap
- **`memory-bank/releases/past-releases.template.md`** - Historical releases and retrospectives

### GitHub Issue Templates
- **`epic.template.md`** - Epic issues (Features with 2+ child tasks)
- **`enhancement.template.md`** - Enhancement issues (Tasks for new features)
- **`bug.template.md`** - Bug issues (Tasks for fixes)

**Note:** All issue templates include a **Type** field with enum values: `Epic | Enhancement | Bug | PRD | Spec | Process`. This replaces GitHub labels for issue categorization.

### Testing & Feedback
- **`epic-test-plan.template.md`** - Comprehensive epic testing documentation
- **`feedback.template.md`** - Structured feedback from meetings/interviews

### Configuration Templates
- **`roadcrew.template.yml`** - Project config, resource capacity, and TOC-based allocation
- **`assignment-rules.template.yml`** - GitHub project + developer assignment rules by risk level
- **`tech-stack.template.md`** - Technology stack overview (auto-generated by `/analyze-repo`)
- **`google-drive.template.json`** - Google Drive API configuration
- **`google-drive-service-account.template.json`** - Service account credentials

**Note:** `assignment-rules.yml` replaces the older separate `github-config.yml` file (consolidated for simplicity).

### Onboarding
- **`RELEASEME.template.md`** - Generated onboarding guide for new projects
- **`.cursorrules.template.md`** - Workflow rules for instance repositories

---

## Template Philosophy

### Separation of Concerns

**Templates enforce clear boundaries:**
- **PRD (memory-bank/activeContext.md or legacy vision.md)** defines product strategy → guides epics
- **Specs (memory-bank/requirements/specs/)** define technical implementation → guides issues
- **Epics** organize features → contain 2-8 related tasks
- **Issues** define specific work → reference specs for details

### Prevent Duplication

**Each document has one purpose:**
- Issues contain brief summaries, not full designs
- Full technical details live in specs
- Business context lives in PRD
- Each document has a clear, singular purpose

**Benefits:**
- Single source of truth for each type of information
- Easy to update (change once, applies everywhere)
- Clear navigation (know where to look for what)
- AI can reference correct context

### BRD Template Design (v2.0)

**The updated `brd.template.md` is ruthlessly optimized for:**
1. **Business Context Only** - Market, segments, pricing, revenue, goals (not features)
2. **Reference Not Duplicate** - PRDs/Specs reference BRD sections, never copy content
3. **Strict Length Limits** - Every field has max words/bullets for consistency
4. **Table/Bullet Driven** - Pricing, GTM, metrics, risks all in structured tables

**Key Design Principles:**

**Strict Length Limits:**
- Executive Summary: ≤40 words (only paragraph in entire doc)
- Business Goals: ≤5 bullets, each ≤15 words
- Non-Goals: ≤3 bullets, each ≤12 words
- Market Segments: ≤4 bullets, each ≤15 words
- Revenue Streams: ≤3 bullets, each ≤15 words
- Differentiators: ≤3 bullets, each ≤15 words
- Pricing Table: ≤3 tiers, features column ≤6 words
- GTM Roadmap: ≤3 phases, each ≤20 words
- Metrics: ≤6 total (2 per category), each ≤15 words

**Critical Sections:**

**Section 5 - Pricing Model Table:**
```markdown
| Tier        | Price     | Key Features            | Audience         |
|-------------|-----------|-------------------------|------------------|
| Free        | $0        | Manual commands, 1 repo | Solo developers  |
| Starter     | $49/mo    | AI agent, 100k tokens   | Fast founders    |
| Enterprise  | $999+/mo  | Multi-repo, unlimited   | Large companies  |
```
- Max 3 tiers for clarity
- Enables PRD/Spec to reference pricing constraints
- Features column: ≤6 words per tier

**Section 7 - Metrics (split across 3 categories):**
- Product/Customer: MAU, conversion, retention
- Financial: ARR, gross margin, CAC
- Usage/Technical: Token usage, automation rate
- Max 2 per category (6 total)

**Downstream Template Alignment:**
```
brd.template.md → prd.template.md
- Business Goals (3) → PRD Business Objectives (1.1)
- Metrics (7) → PRD Success Metrics (3)
- Target Segments (2.1) → PRD User Goals context
- Differentiators (2.3) → PRD Problem Statement context

brd.template.md → spec.template.md
- Pricing Model (5) → Spec NFRs (pricing/licensing constraints)
- Metrics (7) → Spec Acceptance Criteria (performance targets)
- GTM Roadmap (6) → Spec Implementation Plan (phasing)

brd.template.md → release.template.md
- Business Goals (3) → Release overview (business impact)
- GTM Roadmap phases → Release sequencing

See also: memory-bank/releases/current-release.template.md, future-releases.template.md, past-releases.template.md
```

**Reference Pattern (prevents duplication):**
```markdown
# In PRD
**Business Context:** See [BRD § 3 Business Goals](../brds/monetization-brd.md#3-business-goals)

# In Spec
**Pricing Constraints:** See [BRD § 5 Pricing Model](../brds/monetization-brd.md#5-pricing-model)
```

**Business vs Product Boundary:**
- **BRD Contains:** Market, segments, pricing, revenue, business goals, GTM roadmap
- **BRD MUST NOT Contain:** Product features, user stories, acceptance criteria, technical details
- **PRD Contains:** Product requirements, features, user stories (references BRD for business context)

**Creating BRDs:**
Use `/create-brd` command to transform strategy docs/business plans into structured template format:
```bash
/create-brd memory-bank/requirements/brds/monetization-strategy.md
# Outputs: memory-bank/requirements/brds/monetization-brd.md
```

### PRD Template Design (v2.0)

**The updated `prd.template.md` is ruthlessly optimized for:**
1. **What/Why Focus** - Zero implementation details, pure product requirements
2. **Tight Spec Coupling** - Section 9 maps every requirement 1:1 to spec sections
3. **Strict Length Limits** - Every field has max words/bullets for consistency
4. **Table-Driven** - User stories, journeys, mappings all in tables for AI parsing

**Key Design Principles:**

**Strict Length Limits:**
- Problem Statement: ≤50 words (only paragraph in entire doc)
- Business Objectives: ≤3 bullets, each ≤15 words
- User Goals: ≤4 bullets, each ≤15 words
- Functional Requirements: ≤6 bullets (R1-R6), each ≤15 words
- Acceptance Criteria: ≤5 bullets, each ≤12 words
- User Stories: Table format, each column ≤10 words
- User Journey: ≤5 steps, each ≤15 words

**Critical Section 9 - Mapping to Spec:**
```markdown
| Functional Requirement | Spec Section |
|-----------------------|--------------|
| R1: Install script    | 2.1.1        |
| R2: Mode detection    | 3.1          |
```
- Every R1-R6 requirement maps to spec section
- Enables bidirectional traceability (PRD ↔ Spec)
- Used by `/create-spec` to generate inverse mapping

**Downstream Template Alignment:**
```
prd.template.md → spec.template.md
- Functional Requirements (4.1) → Spec Requirements (2.1)
- Non-Functional Constraints (4.2) → Spec NFRs (2.2)
- User Stories (5) → Spec Issue Breakdown context (8)
- Acceptance Criteria (4.3) → Spec Acceptance Criteria (6.1)

prd.template.md → epic.template.md
- User Goals (1.2) → Epic Overview and Key Goals
- User Journey (6) → Epic Child Issue sequencing

prd.template.md → release.template.md
- Business Objectives (1.1) → Release Target State
- Success Metrics (3) → Release Criteria
```

**What/Why vs How Boundary:**
- **PRD Contains:** Business goals, user needs, requirements, success metrics
- **PRD MUST NOT Contain:** File names, functions, architecture, implementation
- **Spec Contains:** All technical "how" details

**Creating PRDs:**
Use `/create-prd` command to transform BRDs/narrative PRDs/strategy docs into structured template format:
```bash
/create-prd memory-bank/requirements/brds/monetization-strategy.md
# Outputs: memory-bank/requirements/prds/monetization-prd.md
```

### Spec Template Design (v2.0)

**The updated `spec.template.md` is ruthlessly optimized for:**
1. **AI Parsing** - Atomic bullets/tables, strict word limits, predictable structure
2. **Developer Velocity** - No narrative, all actionable, deep linkable sections
3. **Zero Duplication** - References PRD/BRD, doesn't repeat "what/why"
4. **Downstream Mapping** - Issue sections map 1:1 to `enhancement.template.md`

**Key Design Principles:**

**Strict Length Limits:**
- Overview: ≤50 words (maps to enhancement.template.md)
- Acceptance Criteria: ≤5 bullets, ≤12 words each
- Technical Implementation: ≤6 bullets
- NFRs: ≤20 words each
- Out of Scope: ≤3 bullets, ≤12 words each

**Downstream Template Alignment:**
```
spec.template.md Issue Section → enhancement.template.md
- Overview (≤50 words) → Overview & User Story
- Accepts (≤5 bullets) → Acceptance Criteria
- Tech Approach (≤6 bullets) → Technical Implementation
- Classification (1-10) → Used by scope-release for TOC routing
- Size/Complexity (S/M/L) → Appears in issue title
```

**PRD → Spec Mapping Table:**
- First section explicitly maps PRD requirements to spec sections
- Prevents duplication by referencing, not repeating
- Validates spec completeness (all PRD requirements covered)

**Deep Linkability:**
- Every epic/issue has anchor: `{#issue-{{EPIC}}-N}`
- Enables precise linking: `[Spec § Issue 2.1](../specs/auth-spec.md#issue-2-1)`
- Used by `/implement-epic` to reference specific issue details

**Creating Specs:**
Use `/create-spec` command to transform BRDs/PRDs/narrative specs into structured template format:
```bash
/create-spec memory-bank/requirements/prds/feature-prd.md
# Outputs: memory-bank/requirements/specs/feature-spec.md
```

---

## Template Variables

All templates use `{{VARIABLE_NAME}}` syntax for substitution.

### Common Variables

- `{{PROJECT_NAME}}` - Project name
- `{{CURRENT_VERSION}}` - Current version
- `{{FEATURE_NAME}}` - Feature or epic name
- `{{TYPE}}` - Issue type (Epic, Enhancement, Bug, PRD, Spec, Process)
- `{{CLASSIFICATION}}` - Classification level (1-10 scale)
- `{{ZONE}}` - Classification zone (ai-solo, ai-led, ai-assisted, ai-limited)
- `{{ISSUE_SIZE}}` - Small, Medium, Large
- `{{ASSIGNEES}}` - Developer assignments

### Release Variables

**For past-releases.md:**
- `{{VERSION}}` - Release version (e.g., "v1.1.0")
- `{{RELEASE_NAME}}` - Meaningful release identifier (e.g., "R1 MVP", "Phase 2 Auth")
- `{{RELEASE_DATE}}` - Release completion date
- `{{DURATION}}` - Release duration (e.g., "2 weeks")
- `{{KEY_ACHIEVEMENTS}}` - Major accomplishments
- `{{SUCCESS_METRICS}}` - Measurable outcomes
- `{{LESSONS_LEARNED}}` - Retrospective insights

**Example:** `## v1.1.0 - R1 MVP (2025-10-20)`

**Type Field Values:**
- **Epic**: Feature with 2+ child issues
- **Enhancement**: New feature or improvement
- **Bug**: Bug fix or issue resolution
- **PRD**: Product requirements document
- **Spec**: Technical specification
- **Process**: Workflow or DevOps improvement

**Classification Zones:**
- **1-3 (ai-solo)**: AI-autonomous, human reactive only
- **4-6 (ai-led)**: AI-led, human validates
- **7-8 (ai-assisted)**: Human-led, AI assists
- **9-10 (ai-limited)**: Human-owned

### Tech Stack Variables

**Auto-filled from `/analyze-repo` command:**
- `{{DEPLOYMENT_METHOD}}` - GitHub Actions, Vercel, Docker, etc.
- `{{TEST_FRAMEWORK}}` - Jest, Playwright, pytest, etc.
- `{{DATABASE}}` - PostgreSQL, MySQL, Prisma, etc.
- `{{TECH_STACK}}` - Full technology stack description

### Strategic Variables

**From memory-bank/activeContext.md (or legacy vision.md):**
- `{{VISION_STATEMENT}}` - Product vision statement
- `{{BUSINESS_OUTCOMES}}` - Measurable business results
- `{{TARGET_PERSONAS}}` - Primary users
- `{{PHASE_NAME}}` - Current product phase

### Issue Variables

**For GitHub issue creation:**
- `{{EPIC_TITLE}}` - Epic name
- `{{ISSUE_TITLE}}` - Issue name
- `{{TYPE}}` - Issue type (Epic, Enhancement, Bug, PRD, Spec, Process)
- `{{ACCEPTANCE_CRITERIA}}` - Definition of done
- `{{TECHNICAL_APPROACH}}` - Implementation plan
- `{{DEPENDENCIES}}` - Prerequisite issues
- `{{BLOCKS}}` - Issues blocked by this one

---

## Template Enforcement

**Mandatory Usage:**
- Commands like `/scope-release` MUST use templates when creating GitHub issues
- Never create issues with inline bodies - always use templates
- Ensures consistency across all project documentation

**Validation:**
- `/scope-release` validates for unpopulated `{{VARIABLES}}`
- Checks for `[Placeholders]` and `#TBD` markers
- Fails if template variables found (must be filled first)

**Auto-Fill:**
- Tech stack variables auto-filled from `memory-bank/techContext.md`
- Assignment rules auto-filled from `config/assignment-rules.yml`
- Classification (1-10) and zone auto-parsed from markdown
- Legacy risk levels (🟢🟡🔴) automatically converted to classification

**Assignment Rules Configuration:**

The `assignment-rules.yml` file controls auto-assignment:

```yaml
# GitHub Configuration
github:
  default_project: "My Project"  # Default GitHub Project (optional)

# Developer Assignments (supports both new classification and legacy risk-level)
assignments:
  # Classification zones (recommended)
  ai-limited: "senior-dev"     # Classification 9-10 (complex/risky work)
  ai-assisted: "mid-senior-dev" # Classification 7-8 (moderate complexity)
  ai-led: "mid-dev"            # Classification 4-6 (moderate complexity)
  ai-solo: "junior-dev"        # Classification 1-3 (simple tasks)
  
  # Legacy risk levels (deprecated, but still supported)
  high-risk: "senior-dev"      # Mapped to classification 8
  medium-risk: "mid-dev"       # Mapped to classification 5
  low-risk: "junior-dev"       # Mapped to classification 2

  # Optional: Override by issue type
  bug: "qa-lead"               # All bugs → QA lead
  process: "devops-lead"       # All process → DevOps lead

  # Optional: Default fallback
  default: "team-lead"         # If no classification detected
```

**How it works:**
1. `/scope-release` parses classification (1-10) and zone from markdown
2. Falls back to legacy risk indicators (🟢 LOW, 🟡 MEDIUM, 🔴 HIGH) if present
3. Looks up assignee in `assignment-rules.yml` based on zone or risk level
4. Creates GitHub issue with `--assignee` flag
5. If classification not detected, uses `default` (or leaves unassigned)

**See also:** [docs/classification-guide.md](../docs/classification-guide.md) for full classification system documentation.

---

## Resource Configuration (TOC-based Capacity Planning)

The `roadcrew.yml` file includes resource configuration for Theory of Constraints (TOC) optimization:

```yaml
resources:
  experts:
    - name: "Senior Engineer"
      capacity: 20  # hours/week available for development
      classification_min: 7    # ai-assisted zone minimum
      classification_max: 10   # ai-limited zone maximum
      
  juniors:
    - name: "Junior Engineer"
      capacity: 40  # hours/week available for development
      classification_min: 4    # ai-led zone minimum
      classification_max: 6    # ai-led zone maximum
      
  ai:
    - name: "AI Assistant"
      classification_min: 1    # ai-solo zone minimum
      classification_max: 3    # ai-solo zone maximum
```

**TOC Optimization Principles:**

1. **Identify the Constraint**: Expert capacity is limited (typically 20 hrs/week)
2. **Exploit the Constraint**: Assign only classification 7-10 work to experts
3. **Subordinate Everything Else**: Junior and AI resources handle preparatory work
4. **Elevate the Constraint**: Maximize expert throughput by eliminating wait time

**Configuration Fields:**

- **`name`**: Resource identifier (person name or role)
- **`capacity`**: Hours per week available for development (optional for AI)
- **`classification_min`**: Minimum classification level this resource handles (1-10)
- **`classification_max`**: Maximum classification level this resource handles (1-10)

**Classification-to-Resource Mapping:**

- **Classification 1-3 (ai-solo)**: AI handles autonomously
- **Classification 4-6 (ai-led)**: Junior engineers with AI assistance
- **Classification 7-8 (ai-assisted)**: Expert engineers with AI assistance
- **Classification 9-10 (ai-limited)**: Expert engineers (human-led)

**Validation Rules:**

- Expert resources must have `classification_min >= 7` (protects constraint)
- Junior resources recommended for `classification_min: 4, classification_max: 6`
- AI resources recommended for `classification_min: 1, classification_max: 3`
- Classification ranges should not overlap across resource types
- All resources must have capacity defined (except AI - unlimited)

**Usage in Commands:**

- `/scope-release` uses resource config for capacity validation
- `/analyze-epic` checks if assignments match resource classification ranges
- Capacity tracking prevents over-allocation before issue creation

---

## Template Versioning

Templates include version tracking in frontmatter:

```yaml
---
template_version: "2.0.0"
last_updated: "2025-10-17"
---
```

### Document Migration

When templates are updated, use `/update-my-documents` to migrate:

```bash
# Update all documents to latest templates
/update-my-documents all

# Update specific document type
/update-my-documents vision
```

**Migration features:**
- Non-destructive (creates backups)
- Shows diff before saving
- Preserves all your content
- Adds new sections with `{{PLACEHOLDERS}}`
- Updates version metadata

---

## Using Templates

### 1. Copy Template

```bash
# Copy template to create new document
cp templates/vision.template.md memory-bank/activeContext.md (or legacy context/vision.md)
```

### 2. Fill Variables

Replace all `{{VARIABLES}}` with actual values:

```markdown
# Before (template)
**Vision Statement:** {{VISION_STATEMENT}}

# After (populated)
**Vision Statement:** Roadcrew enables semi-technical founders to build SaaS products 100× faster
```

### 3. Validate

```bash
# Check for unpopulated variables
grep -r "{{" context/
grep -r "{{" memory-bank/releases/

# Should return no results
```

### 4. Use in Commands

```bash
# Templates automatically used by commands
/scope-release --current  # Uses epic.template.md and issue-*.template.md
/sync-roadmap            # Uses vision.template.md structure
```

---

**See also:**
- [memory-bank/releases/current-release.template.md](roadcrew/memory-bank/releases/current-release.template.md) - Current release template
- [memory-bank/releases/future-releases.template.md](roadcrew/memory-bank/releases/future-releases.template.md) - Future releases template
- [memory-bank/releases/past-releases.template.md](roadcrew/memory-bank/releases/past-releases.template.md) - Past releases archive
- [memory-bank/requirements/brds/brd.template.md](roadcrew/memory-bank/requirements/brds/brd.template.md) - BRD template
- [memory-bank/requirements/prds/prd.template.md](roadcrew/memory-bank/requirements/prds/prd.template.md) - PRD template
- [memory-bank/requirements/specs/spec.template.md](roadcrew/memory-bank/requirements/specs/spec.template.md) - Spec template
- [epic.template.md](roadcrew/epic.template.md) - Epic issue template  
- [../docs/workflow-examples.md](../docs/workflow-examples.md) - Template usage examples
- [../docs/DEVELOPMENT.md](../docs/DEVELOPMENT.md) - Development guide