Team Lifecycle V4

Team Lifecycle v4

Orchestrate multi-agent software development: specification → planning → implementation → testing → review.

Architecture

Skill(skill="team-lifecycle-v4", args="task description")
                    |
         SKILL.md (this file) = Router
                    |
     +--------------+--------------+
     |                             |
  no --role flag              --role <name>
     |                             |
  Coordinator                  Worker
  roles/coordinator/role.md    roles/<name>/role.md
     |
     +-- analyze → dispatch → spawn → STOP
                                 |
                    +--------+---+--------+
                    v        v            v
             [team-worker]  ...    [team-supervisor]
              per-task               resident agent
              lifecycle              message-driven
                                     (woken via SendMessage)

Role Registry

Role Router

Parse $ARGUMENTS:

• Has --role <name> → Read roles/<name>/role.md, execute Phase 2-4
• No --role → @roles/coordinator/role.md, execute entry router

Shared Constants

• Session prefix: TLV4
• Session path: .workflow/.team/TLV4-<slug>-<date>/
• CLI tools: ccw cli --mode analysis (read-only), ccw cli --mode write (modifications)
• Message bus: mcp__ccw-tools__team_msg(session_id=<session-id>, ...)

Worker Spawn Template

Coordinator spawns workers using this template:

Agent({
  subagent_type: "team-worker",
  description: "Spawn <role> worker",
  team_name: <team-name>,
  name: "<role>",
  run_in_background: true,
  prompt: `## Role Assignment
role: <role>
role_spec: <skill_root>/roles/<role>/role.md
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
requirement: <task-description>
inner_loop: <true|false>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file (@<skill_root>/roles/<role>/role.md) to load Phase 2-4 domain instructions.
Execute built-in Phase 1 (task discovery) -> role Phase 2-4 -> built-in Phase 5 (report).`
})

Supervisor Spawn Template

Supervisor is a resident agent (independent from team-worker). Spawned once during session init, woken via SendMessage for each CHECKPOINT task.

Spawn (Phase 2 — once per session)

Agent({
  subagent_type: "team-supervisor",
  description: "Spawn resident supervisor",
  team_name: <team-name>,
  name: "supervisor",
  run_in_background: true,
  prompt: `## Role Assignment
role: supervisor
role_spec: <skill_root>/roles/supervisor/role.md
session: <session-folder>
session_id: <session-id>
team_name: <team-name>
requirement: <task-description>

## Progress Milestones
session_id: <session-id>
Report progress via team_msg at natural phase boundaries (context loaded -> core work done -> verification).
Report blockers immediately via team_msg type="blocker".
Report completion via team_msg type="task_complete" after final SendMessage.

Read role_spec file (@<skill_root>/roles/supervisor/role.md) to load checkpoint definitions.
Init: load baseline context, report ready, go idle.
Wake cycle: coordinator sends checkpoint requests via SendMessage.`
})

Wake (handleSpawnNext — per CHECKPOINT task)

SendMessage({
  type: "message",
  recipient: "supervisor",
  content: `## Checkpoint Request
task_id: <CHECKPOINT-NNN>
scope: [<upstream-task-ids>]
pipeline_progress: <done>/<total> tasks completed`,
  summary: "Checkpoint request: <CHECKPOINT-NNN>"
})

Shutdown (handleComplete)

SendMessage({
  type: "shutdown_request",
  recipient: "supervisor",
  content: "Pipeline complete, shutting down supervisor"
})

User Commands

Completion Action

When pipeline completes, coordinator presents:

AskUserQuestion({
  questions: [{
    question: "Pipeline complete. What would you like to do?",
    header: "Completion",
    multiSelect: false,
    options: [
      { label: "Archive & Clean (Recommended)", description: "Archive session, clean up team" },
      { label: "Keep Active", description: "Keep session for follow-up work" },
      { label: "Export Results", description: "Export deliverables to target directory" }
    ]
  }]
})

Specs Reference

• specs/pipelines.md — Pipeline definitions and task registry
• specs/quality-gates.md — Quality gate criteria and scoring
• specs/knowledge-transfer.md — Artifact and state transfer protocols

Session Directory

.workflow/.team/TLV4-<slug>-<date>/
├── team-session.json           # Session state + role registry
├── spec/                       # Spec phase outputs
├── plan/                       # Implementation plan + TASK-*.json
├── artifacts/                  # All deliverables
├── wisdom/                     # Cross-task knowledge
├── explorations/               # Shared explore cache
├── discussions/                # Discuss round records
└── .msg/                       # Team message bus

Error Handling

Analyst

Research and codebase exploration for context gathering.

Identity

• Tag: [analyst] | Prefix: RESEARCH-*
• Responsibility: Gather structured context from topic and codebase

Boundaries

MUST

• Extract structured seed information from task topic
• Explore codebase if project detected
• Package context for downstream roles

MUST NOT

• Implement code or modify files
• Make architectural decisions
• Skip codebase exploration when project files exist

Phase 2: Seed Analysis

1. Read upstream artifacts via team_msg(operation="get_state") 2. Extract session folder from task description 3. Parse topic from task description 4. If topic references file (@path or .md/.txt) → read it 5. CLI seed analysis:

   Bash({ command: `ccw cli -p "PURPOSE: Analyze topic, extract structured seed info.
   TASK: • Extract problem statement • Identify target users • Determine domain
   • List constraints • Identify 3-5 exploration dimensions
   TOPIC: <topic-content>
   MODE: analysis
   EXPECTED: JSON with: problem_statement, target_users[], domain, constraints[], exploration_dimensions[]" --tool gemini --mode analysis`, run_in_background: false })

6. Parse result JSON

Phase 3: Codebase Exploration

When project detected:

Bash({ command: `ccw cli -p "PURPOSE: Explore codebase for context
TASK: • Identify tech stack • Map architecture patterns • Document conventions • List integration points
MODE: analysis
CONTEXT: @**/*
EXPECTED: JSON with: tech_stack[], architecture_patterns[], conventions[], integration_points[]" --tool gemini --mode analysis`, run_in_background: false })

Tech Profile Scan

After codebase exploration, scan results for context-aware trigger signals (based on detected codebase characteristics):

1. Check imports/dependencies → framework signals (sql_detected, auth_detected, ml_detected, frontend_framework) 2. Check file patterns → infrastructure signals (devops_detected, data_migration, realtime_detected) 3. Check code patterns → risk signals (perf_sensitive, crypto_usage, legacy_patterns, test_gap) 4. Include tech_profile in Phase 5 state_update data:

   "tech_profile": {
     "signals": ["<detected signals>"],
     "evidence": { "<signal>": ["<file paths>"] },
     "confidence": "high|medium|low"
   }

Phase 4: Context Packaging

1. Write spec-config.json → <session>/spec/ 2. Write discovery-context.json → <session>/spec/ 3. Inline Discuss (DISCUSS-001):

• Artifact: <session>/spec/discovery-context.json
• Perspectives: product, risk, coverage

4. Handle verdict per consensus protocol 5. Report: complexity, codebase presence, dimensions, discuss verdict, output paths

Error Handling

Analyze Task

Parse user task -> detect capabilities -> build dependency graph -> design roles.

CONSTRAINT: Text-level analysis only. NO source code reading, NO codebase exploration.

Signal Detection

Dependency Graph

Natural ordering tiers:

• Tier 0: analyst, planner (knowledge gathering)
• Tier 1: writer (creation requires context)
• Tier 2: executor (implementation requires plan/design)
• Tier 3: tester, reviewer (validation requires artifacts)

Complexity Scoring

Results: 1-3 Low, 4-6 Medium, 7+ High

Role Minimization

• Cap at 5 roles
• Merge overlapping capabilities
• Absorb trivial single-step roles

Output

Write <session>/task-analysis.json:

{
  "task_description": "<original>",
  "pipeline_type": "<spec-only|impl-only|full-lifecycle|...>",
  "capabilities": [{ "name": "<cap>", "prefix": "<PREFIX>", "keywords": ["..."] }],
  "dependency_graph": { "<TASK-ID>": { "role": "<role>", "blockedBy": ["..."], "priority": "P0|P1|P2" } },
  "roles": [{ "name": "<role>", "prefix": "<PREFIX>", "inner_loop": false }],
  "complexity": { "score": 0, "level": "Low|Medium|High" },
  "needs_research": true
}

Dispatch Tasks

Create task chains from dependency graph with proper blockedBy relationships.

Workflow

1. Read task-analysis.json -> extract dependency_graph 2. Read specs/pipelines.md -> get task registry for selected pipeline 3. Topological sort tasks (respect blockedBy) 4. Validate all owners exist in role registry (SKILL.md) 5. For each task (in order):

• TaskCreate with structured description (see template below)
• TaskUpdate with blockedBy + owner assignment

6. Update team-session.json with pipeline.tasks_total 7. Validate chain (no orphans, no cycles, all refs valid)

Task Description Template

PURPOSE: <goal> | Success: <criteria>
TASK:
  - <step 1>
  - <step 2>
CONTEXT:
  - Session: <session-folder>
  - Upstream artifacts: <list>
  - Key files: <list>
EXPECTED: <artifact path> + <quality criteria>
CONSTRAINTS: <scope limits>
---
InnerLoop: <true|false>
RoleSpec: ~  or <project>/.claude/skills/team-lifecycle-v4/roles/<role>/role.md

InnerLoop Flag Rules

• true: Role has 2+ serial same-prefix tasks (writer: DRAFT-001->004) where each blockedBy the previous
• false: Role has 1 task, or tasks are parallel (no mutual blockedBy)

Parallel Detection for IMPL Tasks

When creating IMPL-{1..N} tasks from PLAN-001 output:

1. Read plan.json → extract tasks[] with their depends_on fields 2. Build dependency graph among IMPL tasks only 3. Classify:

• Serial chain: IMPL-002 blockedBy IMPL-001 → both get InnerLoop: true, single worker
• Parallel set: IMPL-001..N all blockedBy PLAN-001 only (no mutual deps) → each gets InnerLoop: false, separate workers
• Mixed DAG: Some parallel, some serial → group into independent chains, each chain gets one worker with InnerLoop: true; independent chains spawn in parallel

4. Set InnerLoop in each task description accordingly

CHECKPOINT Task Rules

CHECKPOINT tasks are dispatched like regular tasks but handled differently at spawn time:

• Created via TaskCreate with proper blockedBy (upstream tasks that must complete first)
• Owner: supervisor
• NOT spawned as team-worker — coordinator wakes the resident supervisor via SendMessage
• If supervision: false in team-session.json, skip creating CHECKPOINT tasks entirely
• RoleSpec in description: ~ or <project>/.claude/skills/team-lifecycle-v4/roles/supervisor/role.md

Dependency Validation

• No orphan tasks (all tasks have valid owner)
• No circular dependencies
• All blockedBy references exist
• Session reference in every task description
• RoleSpec reference in every task description

Monitor Pipeline

Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.

Constants

• SPAWN_MODE: background
• ONE_STEP_PER_INVOCATION: true
• FAST_ADVANCE_AWARE: true
• WORKER_AGENT: team-worker
• SUPERVISOR_AGENT: team-supervisor (resident, woken via SendMessage)

Handler Router

handleCallback

Worker completed. Process and advance.

1. Find matching worker by role in message 2. Check if progress update (inner loop) or final completion 3. Progress -> update session state, STOP 4. Completion -> mark task done

• Resident agent (supervisor) -> keep in active_workers (stays alive for future checkpoints)
• Standard worker -> remove from active_workers

4.5. evaluateSpecialistInjection (based on detected codebase characteristics):

• If callback from analyst, planner, or executor role:

a. get_state(role=<callback_role>) → extract tech_profile.signals b. Merge with previously collected signals from other roles c. Evaluate against trigger matrix (§4) d. P0 matches → TaskCreate with blockedBy on current stage, blocks downstream e. P1 matches → TaskCreate parallel with REVIEW/TEST stage f. Log: team_msg(type="specialist_injection", data={ specialist, signals, priority, evidence }) g. Dedup: skip if same specialist already injected this session 5. Check for checkpoints:

• CHECKPOINT-* with verdict "block" -> AskUserQuestion: Override / Revise upstream / Abort
• CHECKPOINT-* with verdict "warn" -> log risks to wisdom, proceed normally
• CHECKPOINT-* with verdict "pass" -> proceed normally
• QUALITY-001 -> display quality gate, pause for user commands
• PLAN-001 -> dynamicImplDispatch (see below)

6. -> handleSpawnNext

dynamicImplDispatch (PLAN-001 callback)

When PLAN-001 completes, coordinator creates IMPL tasks based on complexity:

1. Read <session>/plan/plan.json → extract complexity, tasks[] 2. Route by complexity (per specs/pipelines.md §6):

3. For each IMPL task: TaskCreate with structured description (dispatch.md template) 4. Set blockedBy:

• Parallel tasks: blockedBy: [PLAN-001] (or [CHECKPOINT-003] if supervision enabled)
• Serial chain within DAG: blockedBy includes upstream IMPL task IDs

5. Update team-session.json: pipeline.tasks_total, pipeline.impl_topology: "single"|"parallel"|"dag" 6. Log via team_msg: { type: "state_update", data: { impl_count: N, topology: "..." } }

handleCheck

Read-only status report, then STOP.

Worker Progress (from message bus):

Before generating status output, read worker milestones:

const progressMsgs = mcp__ccw-tools__team_msg({
  operation: "list", session_id: sessionId, type: "progress", last: 50
})
const blockerMsgs = mcp__ccw-tools__team_msg({
  operation: "list", session_id: sessionId, type: "blocker", last: 10
})

// Aggregate latest milestone per task
const taskProgress = {}
for (const msg of (progressMsgs.result?.messages || [])) {
  const tid = msg.data?.task_id
  if (tid && (!taskProgress[tid] || msg.ts > taskProgress[tid].ts)) {
    taskProgress[tid] = { phase: msg.data.phase, pct: msg.data.progress_pct, ts: msg.ts }
  }
}

Include in status output:

• Per-worker latest milestone (phase + progress_pct) next to task status
• Active blockers section (if any blockerMsgs found)

Output:

[coordinator] Pipeline Status
[coordinator] Progress: <done>/<total> (<pct>%)
[coordinator] Active: <workers with elapsed time>
[coordinator] Ready: <pending tasks with resolved deps>
[coordinator] Commands: 'resume' to advance | 'check' to refresh

handleResume

1. No active workers -> handleSpawnNext 2. Has active -> check each status

• completed -> mark done
• in_progress -> still running
• Resident agent (supervisor) with resident: true + no CHECKPOINT in_progress + pending CHECKPOINT exists

-> supervisor may have crashed. Respawn with recovery: true 3. Some completed -> handleSpawnNext 4. All running -> report status, STOP

handleSpawnNext

Find ready tasks, spawn workers, STOP.

1. Collect: completedSubjects, inProgressSubjects, readySubjects 2. No ready + work in progress -> report waiting, STOP 3. No ready + nothing in progress -> handleComplete 4. Has ready -> for each: a. Check inner_loop: parse task description InnerLoop: field (NOT role.md default)

• InnerLoop: true AND same-role worker already active -> skip (worker picks up next task)
• InnerLoop: false OR no active same-role worker -> spawn new worker

b. *CHECKPOINT- task** -> wake resident supervisor (see below) c. Other tasks -> standard spawn:

• TaskUpdate -> in_progress
• team_msg log -> task_unblocked
• Spawn team-worker (see SKILL.md Worker Spawn Template)
• Add to active_workers

5. Update session, output summary, STOP

Wake Supervisor for CHECKPOINT

When a ready task has prefix CHECKPOINT-*:

1. Verify supervisor is in active_workers with resident: true

• Not found -> spawn supervisor using SKILL.md Supervisor Spawn Template, wait for ready callback, then wake

2. Determine scope: list task IDs that this checkpoint depends on (its blockedBy tasks) 3. SendMessage to supervisor (see SKILL.md Supervisor Wake Template):

   SendMessage({
     type: "message",
     recipient: "supervisor",
     content: "## Checkpoint Request\ntask_id: <CHECKPOINT-NNN>\nscope: [<upstream-task-ids>]\npipeline_progress: <done>/<total> tasks completed",
     summary: "Checkpoint request: <CHECKPOINT-NNN>"
   })

4. Do NOT TaskUpdate in_progress — supervisor claims the task itself 5. Do NOT add duplicate entry to active_workers (supervisor already tracked)

handleComplete

Pipeline done. Generate report and completion action.

1. Shutdown resident supervisor (if active):

   SendMessage({ to: "supervisor", message: { type: "shutdown_request", reason: "Pipeline complete" } })

2. Generate summary (deliverables, stats, discussions) 3. Read session.completion_action:

• interactive -> AskUserQuestion (Archive/Keep/Export)
• auto_archive -> Archive & Clean (status=completed, TeamDelete)
• auto_keep -> Keep Active (status=paused)

handleAdapt

Capability gap reported mid-pipeline.

1. Parse gap description 2. Check if existing role covers it -> redirect 3. Role count < 5 -> generate dynamic role-spec in <session>/role-specs/ 4. Create new task, spawn worker 5. Role count >= 5 -> merge or pause

Fast-Advance Reconciliation

On every coordinator wake: 1. Read team_msg entries with type="fast_advance" 2. Sync active_workers with spawned successors 3. No duplicate spawns

Coordinator Role

Orchestrate team-lifecycle-v4: analyze -> dispatch -> spawn -> monitor -> report.

Identity

• Name: coordinator | Tag: [coordinator]
• Responsibility: Analyze task -> Create team -> Dispatch tasks -> Monitor progress -> Report results

Boundaries

MUST

• Parse task description (text-level only, no codebase reading)
• Create team and spawn team-worker agents in background
• Dispatch tasks with proper dependency chains
• Monitor progress via callbacks and route messages
• Maintain session state (team-session.json)
• Handle capability_gap reports
• Execute completion action when pipeline finishes

MUST NOT

• Read source code or explore codebase (delegate to workers)
• Execute task work directly
• Modify task output artifacts
• Spawn workers with general-purpose agent (MUST use team-worker)
• Generate more than 5 worker roles

Command Execution Protocol

When coordinator needs to execute a specific phase: 1. Read commands/<command>.md 2. Follow the workflow defined in the command 3. Commands are inline execution guides, NOT separate agents 4. Execute synchronously, complete before proceeding

Entry Router

For callback/check/resume/adapt/complete: load @commands/monitor.md, execute handler, STOP.

Phase 0: Session Resume Check

1. Scan .workflow/.team/TLV4-*/team-session.json for active/paused sessions 2. No sessions -> Phase 1 3. Single session -> reconcile: a. Audit TaskList, reset in_progress->pending b. Rebuild team workers c. If pipeline has CHECKPOINT tasks AND supervision !== false:

• Respawn supervisor with recovery: true (see SKILL.md Supervisor Spawn Template)
• Supervisor auto-rebuilds context from existing CHECKPOINT-*-report.md files

d. Kick first ready task 4. Multiple -> AskUserQuestion for selection

Phase 1: Requirement Clarification

TEXT-LEVEL ONLY. No source code reading.

1. Parse task description 2. Clarify if ambiguous (AskUserQuestion: scope, deliverables, constraints) 3. Delegate to @commands/analyze.md 4. Output: task-analysis.json 5. CRITICAL: Always proceed to Phase 2, never skip team workflow

Phase 2: Create Team + Initialize Session

1. Resolve workspace paths (MUST do first):

• project_root = result of Bash({ command: "pwd" })
• skill_root = <project_root>/.claude/skills/team-lifecycle-v4

2. Generate session ID: TLV4-<slug>-<date> 3. Create session folder structure 4. TeamCreate with team name 5. Read specs/pipelines.md -> select pipeline 6. Register roles in team-session.json 7. Initialize shared infrastructure (wisdom/*.md, explorations/cache-index.json) 8. Initialize pipeline via team_msg state_update:

   mcp__ccw-tools__team_msg({
     operation: "log", session_id: "<id>", from: "coordinator",
     type: "state_update", summary: "Session initialized",
     data: { pipeline_mode: "<mode>", pipeline_stages: [...], team_name: "<name>" }
   })

9. Write team-session.json 10. Spawn resident supervisor (if pipeline has CHECKPOINT tasks AND supervision !== false):

• Use SKILL.md Supervisor Spawn Template (subagent_type: "team-supervisor")
• Wait for "[supervisor] Ready" callback before proceeding to Phase 3
• Record supervisor in active_workers with resident: true flag

Phase 3: Create Task Chain

Delegate to @commands/dispatch.md: 1. Read dependency graph from task-analysis.json 2. Read specs/pipelines.md for selected pipeline's task registry 3. Topological sort tasks 4. Create tasks via TaskCreate with blockedBy 5. Update team-session.json

Phase 4: Spawn-and-Stop

Delegate to @commands/monitor.md#handleSpawnNext: 1. Find ready tasks (pending + blockedBy resolved) 2. Spawn team-worker agents (see SKILL.md Spawn Template) 3. Output status summary 4. STOP

Phase 5: Report + Completion Action

1. Generate summary (deliverables, pipeline stats, discussions) 2. Execute completion action per session.completion_action:

• interactive -> AskUserQuestion (Archive/Keep/Export)
• auto_archive -> Archive & Clean
• auto_keep -> Keep Active

Error Handling

Fix

Revision workflow for bug fixes and feedback-driven changes.

Workflow

1. Read original task + feedback/revision notes from task description 2. Load original implementation context (files modified, approach taken) 3. Analyze feedback to identify specific changes needed 4. Apply fixes:

• Agent mode: Edit tool for targeted changes
• CLI mode: Resume previous session with fix prompt

5. Re-validate convergence criteria 6. Report: original task, changes applied, validation result

Fix Prompt Template (CLI mode)

PURPOSE: Fix issues in <task.title> based on feedback
TASK:
  - Review original implementation
  - Apply feedback: <feedback text>
  - Verify fixes address all feedback points
MODE: write
CONTEXT: @<modified files>
EXPECTED: All feedback points addressed, convergence criteria met
CONSTRAINTS: Minimal changes | No scope creep

Quality Rules

• Fix ONLY what feedback requests
• No refactoring beyond fix scope
• Verify original convergence criteria still pass
• Report partial_completion if some feedback unclear

Implement

Execute implementation from task JSON via agent or CLI delegation.

Agent Mode

Direct implementation using Edit/Write/Bash tools:

1. Read task.files[] as target files 2. Read task.implementation[] as step-by-step instructions 3. For each step:

• Substitute [variable] placeholders with pre_analysis results
• New file → Write tool; Modify file → Edit tool
• Follow task.reference patterns

4. Apply task.rationale.chosen_approach 5. Mitigate task.risks[] during implementation

Quality rules:

• Verify module existence before referencing
• Incremental progress — small working changes
• Follow existing patterns from task.reference
• ASCII-only, no premature abstractions

CLI Delegation Mode

Build prompt from task JSON, delegate to CLI:

Prompt structure:

PURPOSE: <task.title>
<task.description>

TARGET FILES:
<task.files[] with paths and changes>

IMPLEMENTATION STEPS:
<task.implementation[] numbered>

PRE-ANALYSIS CONTEXT:
<pre_analysis results>

REFERENCE:
<task.reference pattern and files>

DONE WHEN:
<task.convergence.criteria[]>

MODE: write
CONSTRAINTS: Only modify listed files | Follow existing patterns

CLI call:

Bash({ command: `ccw cli -p "<prompt>" --tool <tool> --mode write --rule development-implement-feature`,
  run_in_background: false, timeout: 3600000 })

Resume strategy:

Executor

Code implementation worker with dual execution modes.

inner_loop: dynamic — Dispatch sets per-task: true for serial IMPL chains (IMPL-001→002→003 with inter-dependencies), false for parallel IMPL sets (independent modules). When false, each IMPL task gets its own worker.

Identity

• Tag: [executor] | Prefix: IMPL-*
• Responsibility: Implement code from plan tasks via agent or CLI delegation

Boundaries

MUST

• Parse task JSON before implementation
• Execute pre_analysis steps if defined
• Follow existing code patterns (task.reference)
• Run convergence check after implementation

MUST NOT

• Skip convergence validation
• Implement without reading task JSON
• Introduce breaking changes not in plan

Phase 2: Parse Task + Resolve Mode

1. Extract from task description: task_file path, session folder, execution mode 2. Read task JSON (id, title, files[], implementation[], convergence.criteria[]) 3. Resolve execution mode:

4. Execute pre_analysis[] if exists (Read, Bash, Grep, Glob tools)

Phase 3: Execute Implementation

Route by mode → read commands/<command>.md:

• agent / gemini / codex / qwen → commands/implement.md
• Revision task → commands/fix.md

Phase 4: Self-Validation

Report: task ID, status, mode used, files modified, convergence results.

Error Handling

Planner

Codebase-informed implementation planning with complexity assessment.

Identity

• Tag: [planner] | Prefix: PLAN-*
• Responsibility: Explore codebase → generate structured plan → assess complexity

Boundaries

MUST

• Check shared exploration cache before re-exploring
• Generate plan.json + TASK-*.json files
• Assess complexity (Low/Medium/High) for routing
• Load spec context if available (full-lifecycle)

MUST NOT

• Implement code
• Skip codebase exploration
• Create more than 7 tasks

Phase 2: Context + Exploration

1. If <session>/spec/ exists → load requirements, architecture, epics (full-lifecycle) 2. Check <session>/explorations/cache-index.json for cached explorations 3. Explore codebase (cache-aware):

   Bash({ command: `ccw cli -p "PURPOSE: Explore codebase to inform planning
   TASK: • Search for relevant patterns • Identify files to modify • Document integration points
   MODE: analysis
   CONTEXT: @**/*
   EXPECTED: JSON with: relevant_files[], patterns[], integration_points[], recommendations[]" --tool gemini --mode analysis`, run_in_background: false })

4. Store results in <session>/explorations/

Secondary Signal Scan

After exploration, supplement upstream tech_profile with planning-phase signals (based on detected codebase characteristics):

1. Check plan complexity → scaling_concern if O(n^2)+ patterns found 2. Check scope → breaking_change if public API modifications planned 3. Check data → data_migration if schema changes identified 4. Include tech_profile in Phase 5 state_update (merge with any upstream signals)

Phase 3: Plan Generation

Generate plan.json + .task/TASK-*.json:

Bash({ command: `ccw cli -p "PURPOSE: Generate implementation plan from exploration results
TASK: • Create plan.json overview • Generate TASK-*.json files (2-7 tasks) • Define dependencies • Set convergence criteria
MODE: write
CONTEXT: @<session>/explorations/*.json
EXPECTED: Files: plan.json + .task/TASK-*.json
CONSTRAINTS: 2-7 tasks, include id/title/files[]/convergence.criteria/depends_on" --tool gemini --mode write`, run_in_background: false })

Output files:

<session>/plan/
├── plan.json              # Overview + complexity assessment
└── .task/TASK-*.json      # Individual task definitions

Phase 4: Submit for Approval

1. Read plan.json and TASK-*.json 2. Report to coordinator: complexity, task count, approach, plan location 3. Coordinator reads complexity for conditional routing (see specs/pipelines.md)

Error Handling

Code Review

4-dimension code review for implementation quality.

Inputs

• Plan file (plan.json)
• Git diff or modified files list
• Test results (if available)

Dimensions

Review Process

1. Gather modified files from executor's state (team_msg get_state) 2. Read each modified file 3. Score per dimension (0-100%) 4. Classify issues by severity (Critical/High/Medium/Low) 5. Generate verdict (BLOCK/CONDITIONAL/APPROVE)

Output

Write review report to <session>/artifacts/review-report.md:

• Per-dimension scores
• Issue list with file:line references
• Verdict with justification
• Recommendations (if CONDITIONAL)

Spec Quality Review

5-dimension spec quality gate with discuss protocol.

Inputs

• All spec docs in <session>/spec/
• Quality gate config from specs/quality-gates.md

Dimensions

Review Process

1. Read all spec documents from <session>/spec/ 2. Load quality gate thresholds from specs/quality-gates.md 3. Score each dimension 4. Run cross-document validation 5. Generate readiness-report.md + spec-summary.md 6. Run DISCUSS-003:

• Artifact: <session>/spec/readiness-report.md
• Perspectives: product, technical, quality, risk, coverage
• Handle verdict per consensus protocol
• DISCUSS-003 HIGH always triggers user pause

Quality Gate

Output

Write to <session>/artifacts/:

• readiness-report.md: Dimension scores, issue list, traceability matrix
• spec-summary.md: Executive summary of all spec docs

Reviewer

Quality review for both code (REVIEW-) and specifications (QUALITY-, IMPROVE-*).

Identity

• Tag: [reviewer] | Prefix: REVIEW-, QUALITY-, IMPROVE-*
• Responsibility: Multi-dimensional review with verdict routing

Boundaries

MUST

• Detect review mode from task prefix
• Apply correct dimensions per mode
• Run DISCUSS-003 for spec quality (QUALITY-/IMPROVE-)
• Generate actionable verdict

MUST NOT

• Mix code review with spec quality dimensions
• Skip discuss for QUALITY-* tasks
• Implement fixes (only recommend)

Phase 2: Mode Detection

Phase 3: Review Execution

Route to command based on detected mode.

Phase 4: Verdict

Code Review Verdict

Spec Quality Gate

Report: mode, verdict/gate, dimension scores, discuss verdict (quality only), output paths.

Error Handling

Supervisor

Process and execution supervision at pipeline phase transition points.

Identity

• Tag: [supervisor] | Prefix: CHECKPOINT-*
• Responsibility: Verify cross-artifact consistency, process compliance, and execution health between pipeline phases

Boundaries

MUST

• Read all upstream state_update messages from message bus
• Read upstream artifacts referenced in state data
• Check terminology consistency across produced documents
• Verify process compliance (upstream consumed, artifacts exist, wisdom contributed)
• Analyze error/retry patterns in message bus
• Output supervision_report with clear verdict (pass/warn/block)
• Write checkpoint report to <session>/artifacts/CHECKPOINT-NNN-report.md

MUST NOT

• Perform deep quality scoring (reviewer's job — 4 dimensions × 25% weight)
• Evaluate AC testability or ADR justification (reviewer's job)
• Modify any artifacts (read-only observer)
• Skip reading message bus history (essential for pattern detection)
• Block pipeline without justification (every block needs specific evidence)
• Run discussion rounds (no consensus needed for checkpoints)

Phase 2: Context Gathering

Load ALL available context for comprehensive supervision:

Step 1: Message Bus Analysis

team_msg(operation="list", session_id=<session_id>)

• Collect all messages since session start
• Group by: type, from, error count
• Build timeline of task completions and their quality_self_scores

Step 2: Upstream State Loading

team_msg(operation="get_state")  // all roles

• Load state for every completed upstream role
• Extract: key_findings, decisions, terminology_keys, open_questions
• Note: upstream_refs_consumed for reference chain verification

Step 3: Artifact Reading

• Read each artifact referenced in upstream states' ref paths
• Extract document structure, key terms, design decisions
• DO NOT deep-read entire documents — scan headings + key sections only

Step 4: Wisdom Loading

• Read <session>/wisdom/*.md for accumulated team knowledge
• Check for contradictions between wisdom entries and current artifacts

Phase 3: Supervision Checks

Execute checks based on CHECKPOINT type. Each checkpoint has a predefined scope.

CHECKPOINT-001: Brief ↔ PRD Consistency (after DRAFT-002)

CHECKPOINT-002: Full Spec Consistency (after DRAFT-004)

CHECKPOINT-003: Plan ↔ Input Alignment (after PLAN-001)

Execution Health Checks (all checkpoints)

Phase 4: Verdict Generation

Scoring

Each check produces: pass (1.0) | warn (0.5) | fail (0.0)

checkpoint_score = sum(check_scores) / num_checks

Report Generation

Write to <session>/artifacts/CHECKPOINT-NNN-report.md:

# Checkpoint Report: CHECKPOINT-NNN

## Scope
Tasks checked: [DRAFT-001, DRAFT-002]

## Results

### Consistency
| Check | Result | Details |
|-------|--------|---------|
| Terminology | pass | Unified across 2 docs |
| Decision chain | warn | Minor: "auth" term undefined in PRD |

### Process Compliance
| Check | Result | Details |
|-------|--------|---------|
| Upstream consumed | pass | All refs loaded |
| Artifacts exist | pass | 2/2 files present |

### Execution Health
| Check | Result | Details |
|-------|--------|---------|
| Error patterns | pass | 0 errors |
| Retries | pass | No retries |

## Verdict: PASS (score: 0.90)

## Recommendations
- Define "auth" explicitly in PRD glossary section

## Risks Logged
- None

State Update

{
  "status": "task_complete",
  "task_id": "CHECKPOINT-001",
  "ref": "<session>/artifacts/CHECKPOINT-001-report.md",
  "key_findings": ["Terminology aligned", "Decision chain consistent"],
  "decisions": ["Proceed to architecture phase"],
  "verification": "self-validated",
  "supervision_verdict": "pass",
  "supervision_score": 0.90,
  "risks_logged": 0,
  "blocks_detected": 0
}

Error Handling

Tester

Test execution with iterative fix cycle.

Identity

• Tag: [tester] | Prefix: TEST-*
• Responsibility: Detect framework → run tests → fix failures → report results

Boundaries

MUST

• Auto-detect test framework before running
• Run affected tests first, then full suite
• Classify failures by severity
• Iterate fix cycle up to MAX_ITERATIONS

MUST NOT

• Skip framework detection
• Run full suite before affected tests
• Exceed MAX_ITERATIONS without reporting

Phase 2: Framework Detection + Test Discovery

Framework detection (priority order):

Affected test discovery from executor's modified files:

• Search: <name>.test.ts, <name>.spec.ts, tests/<name>.test.ts, __tests__/<name>.test.ts

Phase 3: Test Execution + Fix Cycle

Config: MAX_ITERATIONS=10, PASS_RATE_TARGET=95%, AFFECTED_TESTS_FIRST=true

Loop: 1. Run affected tests → parse results 2. Pass rate met → run full suite 3. Failures → select strategy → fix → re-run

Strategy selection:

Test commands:

Phase 4: Result Analysis

Failure classification:

Report routing:

Error Handling

Writer

Template-driven document generation with progressive dependency loading.

Identity

• Tag: [writer] | Prefix: DRAFT-*
• Responsibility: Generate spec documents (product brief, requirements, architecture, epics)

Boundaries

MUST

• Load upstream context progressively (each doc builds on previous)
• Use templates from templates/ directory
• Self-validate every document
• Run DISCUSS-002 for Requirements PRD

MUST NOT

• Generate code
• Skip validation
• Modify upstream artifacts

Phase 2: Context Loading

Document Type Routing

Progressive Dependencies

Inputs

• Template from routing table
• spec-config.json from <session>/spec/
• discovery-context.json from <session>/spec/
• Prior decisions from context_accumulator (inner loop)
• Discussion feedback from <session>/discussions/ (if exists)

Phase 3: Document Generation

CLI generation:

Bash({ command: `ccw cli -p "PURPOSE: Generate <doc-type> document following template
TASK: • Load template • Apply spec config and discovery context • Integrate prior feedback • Generate all sections
MODE: write
CONTEXT: @<session>/spec/*.json @<template-path>
EXPECTED: Document at <output-path> with YAML frontmatter, all sections, cross-references
CONSTRAINTS: Follow document standards" --tool gemini --mode write --cd <session>`, run_in_background: false })

Phase 4: Validation

Self-Validation (all doc types)

Validation Routing

Report: doc type, validation status, discuss verdict (PRD only), output path.

Error Handling

Knowledge Transfer Protocols

1. Transfer Channels

2. Context Loading Protocol (Before Task Execution)

Every role MUST load context in this order before starting work.

Loading rules:

• Never skip step 1 -- state contains key decisions and findings
• If ref path in state does not exist, log warning and continue
• Wisdom files are append-only -- read all entries, newest last

3. Context Publishing Protocol (After Task Completion)

4. State Update Schema

Sent via team_msg(type="state_update") on task completion.

{
  "status": "task_complete",
  "task_id": "<TASK-NNN>",
  "ref": "<session>/artifacts/<filename>",
  "key_findings": [
    "Finding 1",
    "Finding 2"
  ],
  "decisions": [
    "Decision with rationale"
  ],
  "files_modified": [
    "path/to/file.ts"
  ],
  "verification": "self-validated | peer-reviewed | tested",
  "tech_profile": {
    "signals": [],
    "evidence": {},
    "confidence": "medium"
  }
}

Field rules:

• ref: Always an artifact path, never inline content
• key_findings: Max 5 items, each under 100 chars
• decisions: Include rationale, not just the choice
• files_modified: Only for implementation tasks
• verification: One of self-validated, peer-reviewed, tested
• tech_profile: Optional. Codebase signals for context-aware specialist injection. See skills_lib/specs/detected codebase signals

Supervisor-specific extensions (CHECKPOINT tasks only):

{
  "supervision_verdict": "pass | warn | block",
  "supervision_score": 0.85,
  "risks_logged": 0,
  "blocks_detected": 0
}

• supervision_verdict: Required for CHECKPOINT tasks. Determines pipeline progression.
• supervision_score: Float 0.0-1.0. Aggregate of individual check scores.
• risks_logged: Count of risks written to wisdom/issues.md.
• blocks_detected: Count of blocking issues found. >0 implies verdict=block.

5. Exploration Cache Protocol

Prevents redundant research across tasks and discussion rounds.

cache-index.json format:

{
  "entries": [
    {
      "angle": "competitor-analysis",
      "file": "explore-competitor-analysis.json",
      "created_by": "RESEARCH-001",
      "timestamp": "2026-01-15T10:30:00Z"
    }
  ]
}

Rules:

• Cache key is the exploration angle (normalized to kebab-case)
• Cache entries never expire within a session
• Any role can read cached explorations; only the creator updates them

Pipeline Definitions

1. Pipeline Selection Criteria

2. Spec-Only Pipeline

6 tasks + 2 optional checkpoints, 3 discussion rounds

RESEARCH-001(+D1) -> DRAFT-001 -> DRAFT-002(+D2) -> [CHECKPOINT-001] -> DRAFT-003 -> DRAFT-004 -> [CHECKPOINT-002] -> QUALITY-001(+D3)

Checkpoint: After QUALITY-001 -- pause for user approval before any implementation.

Supervision opt-out: Set supervision: false in team-session.json to skip CHECKPOINT tasks.

3. Impl-Only Pipeline

4 tasks + 1 optional checkpoint, 0 discussion rounds

PLAN-001 -> [CHECKPOINT-003] -> IMPL-001 -> TEST-001 + REVIEW-001

TEST-001 and REVIEW-001 run in parallel after IMPL-001 completes.

Supervision opt-out: Set supervision: false in team-session.json to skip CHECKPOINT tasks.

4. Full-Lifecycle Pipeline

10 tasks + 3 optional checkpoints = spec-only (6+2) + impl (4+1)

[Spec pipeline with CHECKPOINT-001/002] -> PLAN-001(blockedBy: QUALITY-001) -> [CHECKPOINT-003] -> IMPL-001 -> TEST-001 + REVIEW-001

PLAN-001 is blocked until QUALITY-001 passes and user approves the checkpoint.

Supervision opt-out: Set supervision: false in team-session.json to skip all CHECKPOINT tasks.

5. Frontend Pipelines

6. Conditional Routing

PLAN-001 outputs a complexity assessment that determines the impl topology.

• ORCH-001 (orchestrator): Coordinates parallel IMPL tasks, manages dependencies
• ARCH-001 (architect): Detailed architecture decisions before orchestration

7. Task Metadata Registry

8. Context-Aware Specialist Injection

Specialists are injected based on codebase signals detected by explorer/analyst/planner workers, not keyword matching. The coordinator evaluates signals emitted in worker state updates against a trigger matrix to determine when specialist roles are needed.

Signal Flow

analyst (RESEARCH-001) emits tech_profile in state_update
  → coordinator evaluateSpecialistInjection (in handleCallback)
  → signal combination matches trigger matrix
  → P0: TaskCreate blocking downstream | P1: TaskCreate parallel with REVIEW/TEST

Common Trigger Examples

Injection Rules

• Specialist tasks inherit session context and wisdom
• They publish state_update on completion like any other task
• P0 specialists block downstream tasks; P1 run in parallel
• Same specialist is only injected once per session (dedup)

Quality Gates

1. Quality Thresholds

2. Scoring Dimensions

Score = weighted average of all dimensions (0-100 per dimension).

3. Per-Phase Quality Gates

Phase 2: Product Brief

Phase 3: Requirements PRD

Phase 4: Architecture

Phase 5: Epics & Stories

Phase 6: Readiness Gate

4. Cross-Document Validation

5. Code Review Dimensions

For REVIEW-* tasks during implementation phases.

Quality

Security

Architecture

Requirements Coverage

6. Issue Classification

Architecture Document Template (Directory Structure)

Template for generating architecture decision documents as a directory of individual ADR files in Phase 4.

Usage Context

Output Structure

{workDir}/architecture/
├── _index.md                      # Overview, components, tech stack, data model, security
├── ADR-001-{slug}.md              # Individual Architecture Decision Record
├── ADR-002-{slug}.md
└── ...

---

Template: _index.md

---
session_id: {session_id}
phase: 4
document_type: architecture-index
status: draft
generated_at: {timestamp}
version: 1
dependencies:
  - ../spec-config.json
  - ../product-brief.md
  - ../requirements/_index.md
---

# Architecture: {product_name}

{executive_summary - high-level architecture approach and key decisions}

## System Overview

### Architecture Style
{description of chosen architecture style: microservices, monolith, serverless, etc.}

### System Context Diagram

C4Context title System Context Diagram Person(user, "User", "Primary user") System(system, "{product_name}", "Core system") System_Ext(ext1, "{external_system}", "{description}") Rel(user, system, "Uses") Rel(system, ext1, "Integrates with")

## Component Architecture

### Component Diagram

graph TD subgraph "{product_name}" A[Component A] --> B[Component B] B --> C[Component C] A --> D[Component D] end B --> E[External Service]

### Component Descriptions

| Component | Responsibility | Technology | Dependencies |
|-----------|---------------|------------|--------------|
| {component_name} | {what it does} | {tech stack} | {depends on} |

## Technology Stack

### Core Technologies

| Layer | Technology | Version | Rationale |
|-------|-----------|---------|-----------|
| Frontend | {technology} | {version} | {why chosen} |
| Backend | {technology} | {version} | {why chosen} |
| Database | {technology} | {version} | {why chosen} |
| Infrastructure | {technology} | {version} | {why chosen} |

### Key Libraries & Frameworks

| Library | Purpose | License |
|---------|---------|---------|
| {library_name} | {purpose} | {license} |

## Architecture Decision Records

| ADR | Title | Status | Key Choice |
|-----|-------|--------|------------|
| [ADR-001](ADR-001-{slug}.md) | {title} | Accepted | {one-line summary} |
| [ADR-002](ADR-002-{slug}.md) | {title} | Accepted | {one-line summary} |
| [ADR-003](ADR-003-{slug}.md) | {title} | Proposed | {one-line summary} |

## Data Architecture

### Data Model

erDiagram ENTITY_A ||--o{ ENTITY_B : "has many" ENTITY_A { string id PK string name datetime created_at } ENTITY_B { string id PK string entity_a_id FK string value }

### Data Storage Strategy

| Data Type | Storage | Retention | Backup |
|-----------|---------|-----------|--------|
| {type} | {storage solution} | {retention policy} | {backup strategy} |

## API Design

### API Overview

| Endpoint | Method | Purpose | Auth |
|----------|--------|---------|------|
| {/api/resource} | {GET/POST/etc} | {purpose} | {auth type} |

## Security Architecture

### Security Controls

| Control | Implementation | Requirement |
|---------|---------------|-------------|
| Authentication | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) |
| Authorization | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) |
| Data Protection | {approach} | [NFR-S-{NNN}](../requirements/NFR-S-{NNN}-{slug}.md) |

## Infrastructure & Deployment

### Deployment Architecture

{description of deployment model: containers, serverless, VMs, etc.}

### Environment Strategy

| Environment | Purpose | Configuration |
|-------------|---------|---------------|
| Development | Local development | {config} |
| Staging | Pre-production testing | {config} |
| Production | Live system | {config} |

## Codebase Integration

{if has_codebase is true:}

### Existing Code Mapping

| New Component | Existing Module | Integration Type | Notes |
|--------------|----------------|------------------|-------|
| {component} | {existing module path} | Extend/Replace/New | {notes} |

### Migration Notes
{any migration considerations for existing code}

## Quality Attributes

| Attribute | Target | Measurement | ADR Reference |
|-----------|--------|-------------|---------------|
| Performance | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) |
| Scalability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) |
| Reliability | {target} | {how measured} | [ADR-{NNN}](ADR-{NNN}-{slug}.md) |

## Risks & Mitigations

| Risk | Impact | Probability | Mitigation |
|------|--------|-------------|------------|
| {risk} | High/Medium/Low | High/Medium/Low | {mitigation approach} |

## Open Questions

- [ ] {architectural question 1}
- [ ] {architectural question 2}

## References

- Derived from: [Requirements](../requirements/_index.md), [Product Brief](../product-brief.md)
- Next: [Epics & Stories](../epics/_index.md)

---

Template: ADR-NNN-{slug}.md (Individual Architecture Decision Record)

---
id: ADR-{NNN}
status: Accepted
traces_to: [{REQ-NNN}, {NFR-X-NNN}]
date: {timestamp}
---

# ADR-{NNN}: {decision_title}

## Context

{what is the situation that motivates this decision}

## Decision

{what is the chosen approach}

## Alternatives Considered

| Option | Pros | Cons |
|--------|------|------|
| {option_1 - chosen} | {pros} | {cons} |
| {option_2} | {pros} | {cons} |
| {option_3} | {pros} | {cons} |

## Consequences

- **Positive**: {positive outcomes}
- **Negative**: {tradeoffs accepted}
- **Risks**: {risks to monitor}

## Traces

- **Requirements**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md), [NFR-X-{NNN}](../requirements/NFR-X-{NNN}-{slug}.md)
- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5)

---

Variable Descriptions

Epics & Stories Template (Directory Structure)

Template for generating epic/story breakdown as a directory of individual Epic files in Phase 5.

Usage Context

Output Structure

{workDir}/epics/
├── _index.md                      # Overview table + dependency map + MVP scope + execution order
├── EPIC-001-{slug}.md             # Individual Epic with its Stories
├── EPIC-002-{slug}.md
└── ...

---

Template: _index.md

---
session_id: {session_id}
phase: 5
document_type: epics-index
status: draft
generated_at: {timestamp}
version: 1
dependencies:
  - ../spec-config.json
  - ../product-brief.md
  - ../requirements/_index.md
  - ../architecture/_index.md
---

# Epics & Stories: {product_name}

{executive_summary - overview of epic structure and MVP scope}

## Epic Overview

| Epic ID | Title | Priority | MVP | Stories | Est. Size |
|---------|-------|----------|-----|---------|-----------|
| [EPIC-001](EPIC-001-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} |
| [EPIC-002](EPIC-002-{slug}.md) | {title} | Must | Yes | {n} | {S/M/L/XL} |
| [EPIC-003](EPIC-003-{slug}.md) | {title} | Should | No | {n} | {S/M/L/XL} |

## Dependency Map

graph LR EPIC-001 --> EPIC-002 EPIC-001 --> EPIC-003 EPIC-002 --> EPIC-004 EPIC-003 --> EPIC-005

### Dependency Notes
{explanation of why these dependencies exist and suggested execution order}

### Recommended Execution Order
1. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - foundational}
2. [EPIC-{NNN}](EPIC-{NNN}-{slug}.md): {reason - depends on #1}
3. ...

## MVP Scope

### MVP Epics
{list of epics included in MVP with justification, linking to each}

### MVP Definition of Done
- [ ] {MVP completion criterion 1}
- [ ] {MVP completion criterion 2}
- [ ] {MVP completion criterion 3}

## Traceability Matrix

| Requirement | Epic | Stories | Architecture |
|-------------|------|---------|--------------|
| [REQ-001](../requirements/REQ-001-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-001, STORY-001-002 | [ADR-001](../architecture/ADR-001-{slug}.md) |
| [REQ-002](../requirements/REQ-002-{slug}.md) | [EPIC-001](EPIC-001-{slug}.md) | STORY-001-003 | Component B |
| [REQ-003](../requirements/REQ-003-{slug}.md) | [EPIC-002](EPIC-002-{slug}.md) | STORY-002-001 | [ADR-002](../architecture/ADR-002-{slug}.md) |

## Estimation Summary

| Size | Meaning | Count |
|------|---------|-------|
| S | Small - well-understood, minimal risk | {n} |
| M | Medium - some complexity, moderate risk | {n} |
| L | Large - significant complexity, should consider splitting | {n} |
| XL | Extra Large - high complexity, must split before implementation | {n} |

## Risks & Considerations

| Risk | Affected Epics | Mitigation |
|------|---------------|------------|
| {risk description} | [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) | {mitigation} |

## Open Questions

- [ ] {question about scope or implementation 1}
- [ ] {question about scope or implementation 2}

## References

- Derived from: [Requirements](../requirements/_index.md), [Architecture](../architecture/_index.md)
- Handoff to: execution workflows (lite-plan, plan, req-plan)

---

Template: EPIC-NNN-{slug}.md (Individual Epic)

---
id: EPIC-{NNN}
priority: {Must|Should|Could}
mvp: {true|false}
size: {S|M|L|XL}
requirements: [REQ-{NNN}]
architecture: [ADR-{NNN}]
dependencies: [EPIC-{NNN}]
status: draft
---

# EPIC-{NNN}: {epic_title}

**Priority**: {Must|Should|Could}
**MVP**: {Yes|No}
**Estimated Size**: {S|M|L|XL}

## Description

{detailed epic description}

## Requirements

- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title}
- [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md): {title}

## Architecture

- [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md): {title}
- Component: {component_name}

## Dependencies

- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (blocking): {reason}
- [EPIC-{NNN}](EPIC-{NNN}-{slug}.md) (soft): {reason}

## Stories

### STORY-{EPIC}-001: {story_title}

**User Story**: As a {persona}, I want to {action} so that {benefit}.

**Acceptance Criteria**:
- [ ] {criterion 1}
- [ ] {criterion 2}
- [ ] {criterion 3}

**Size**: {S|M|L|XL}
**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md)

---

### STORY-{EPIC}-002: {story_title}

**User Story**: As a {persona}, I want to {action} so that {benefit}.

**Acceptance Criteria**:
- [ ] {criterion 1}
- [ ] {criterion 2}

**Size**: {S|M|L|XL}
**Traces to**: [REQ-{NNN}](../requirements/REQ-{NNN}-{slug}.md)

---

Variable Descriptions

Product Brief Template

Template for generating product brief documents in Phase 2.

Usage Context

---

Template

---
session_id: {session_id}
phase: 2
document_type: product-brief
status: draft
generated_at: {timestamp}
stepsCompleted: []
version: 1
dependencies:
  - spec-config.json
---

# Product Brief: {product_name}

{executive_summary - 2-3 sentences capturing the essence of the product/feature}

## Vision

{vision_statement - clear, aspirational 1-3 sentence statement of what success looks like}

## Problem Statement

### Current Situation
{description of the current state and pain points}

### Impact
{quantified impact of the problem - who is affected, how much, how often}

## Target Users

{for each user persona:}

### {Persona Name}
- **Role**: {user's role/context}
- **Needs**: {primary needs related to this product}
- **Pain Points**: {current frustrations}
- **Success Criteria**: {what success looks like for this user}

## Goals & Success Metrics

| Goal ID | Goal | Success Metric | Target |
|---------|------|----------------|--------|
| G-001 | {goal description} | {measurable metric} | {specific target} |
| G-002 | {goal description} | {measurable metric} | {specific target} |

## Scope

### In Scope
- {feature/capability 1}
- {feature/capability 2}
- {feature/capability 3}

### Out of Scope
- {explicitly excluded item 1}
- {explicitly excluded item 2}

### Assumptions
- {key assumption 1}
- {key assumption 2}

## Competitive Landscape

| Aspect | Current State | Proposed Solution | Advantage |
|--------|--------------|-------------------|-----------|
| {aspect} | {how it's done now} | {our approach} | {differentiator} |

## Constraints & Dependencies

### Technical Constraints
- {constraint 1}
- {constraint 2}

### Business Constraints
- {constraint 1}

### Dependencies
- {external dependency 1}
- {external dependency 2}

## Multi-Perspective Synthesis

### Product Perspective
{summary of product/market analysis findings}

### Technical Perspective
{summary of technical feasibility and constraints}

### User Perspective
{summary of user journey and UX considerations}

### Convergent Themes
{themes where all perspectives agree}

### Conflicting Views
{areas where perspectives differ, with notes on resolution approach}

## Open Questions

- [ ] {unresolved question 1}
- [ ] {unresolved question 2}

## References

- Derived from: [spec-config.json](spec-config.json)
- Next: [Requirements PRD](requirements.md)

Variable Descriptions

Requirements PRD Template (Directory Structure)

Template for generating Product Requirements Document as a directory of individual requirement files in Phase 3.

Usage Context

Output Structure

{workDir}/requirements/
├── _index.md                      # Summary + MoSCoW table + traceability matrix + links
├── REQ-001-{slug}.md              # Individual functional requirement
├── REQ-002-{slug}.md
├── NFR-P-001-{slug}.md            # Non-functional: Performance
├── NFR-S-001-{slug}.md            # Non-functional: Security
├── NFR-SC-001-{slug}.md           # Non-functional: Scalability
├── NFR-U-001-{slug}.md            # Non-functional: Usability
└── ...

---

Template: _index.md

---
session_id: {session_id}
phase: 3
document_type: requirements-index
status: draft
generated_at: {timestamp}
version: 1
dependencies:
  - ../spec-config.json
  - ../product-brief.md
---

# Requirements: {product_name}

{executive_summary - brief overview of what this PRD covers and key decisions}

## Requirement Summary

| Priority | Count | Coverage |
|----------|-------|----------|
| Must Have | {n} | {description of must-have scope} |
| Should Have | {n} | {description of should-have scope} |
| Could Have | {n} | {description of could-have scope} |
| Won't Have | {n} | {description of explicitly excluded} |

## Functional Requirements

| ID | Title | Priority | Traces To |
|----|-------|----------|-----------|
| [REQ-001](REQ-001-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) |
| [REQ-002](REQ-002-{slug}.md) | {title} | Must | [G-001](../product-brief.md#goals--success-metrics) |
| [REQ-003](REQ-003-{slug}.md) | {title} | Should | [G-002](../product-brief.md#goals--success-metrics) |

## Non-Functional Requirements

### Performance

| ID | Title | Target |
|----|-------|--------|
| [NFR-P-001](NFR-P-001-{slug}.md) | {title} | {target value} |

### Security

| ID | Title | Standard |
|----|-------|----------|
| [NFR-S-001](NFR-S-001-{slug}.md) | {title} | {standard/framework} |

### Scalability

| ID | Title | Target |
|----|-------|--------|
| [NFR-SC-001](NFR-SC-001-{slug}.md) | {title} | {target value} |

### Usability

| ID | Title | Target |
|----|-------|--------|
| [NFR-U-001](NFR-U-001-{slug}.md) | {title} | {target value} |

## Data Requirements

### Data Entities

| Entity | Description | Key Attributes |
|--------|-------------|----------------|
| {entity_name} | {description} | {attr1, attr2, attr3} |

### Data Flows

{description of key data flows, optionally with Mermaid diagram}

## Integration Requirements

| System | Direction | Protocol | Data Format | Notes |
|--------|-----------|----------|-------------|-------|
| {system_name} | Inbound/Outbound/Both | {REST/gRPC/etc} | {JSON/XML/etc} | {notes} |

## Constraints & Assumptions

### Constraints
- {technical or business constraint 1}
- {technical or business constraint 2}

### Assumptions
- {assumption 1 - must be validated}
- {assumption 2 - must be validated}

## Priority Rationale

{explanation of MoSCoW prioritization decisions, especially for Should/Could boundaries}

## Traceability Matrix

| Goal | Requirements |
|------|-------------|
| G-001 | [REQ-001](REQ-001-{slug}.md), [REQ-002](REQ-002-{slug}.md), [NFR-P-001](NFR-P-001-{slug}.md) |
| G-002 | [REQ-003](REQ-003-{slug}.md), [NFR-S-001](NFR-S-001-{slug}.md) |

## Open Questions

- [ ] {unresolved question 1}
- [ ] {unresolved question 2}

## References

- Derived from: [Product Brief](../product-brief.md)
- Next: [Architecture](../architecture/_index.md)

---

Template: REQ-NNN-{slug}.md (Individual Functional Requirement)

---
id: REQ-{NNN}
type: functional
priority: {Must|Should|Could|Won't}
traces_to: [G-{NNN}]
status: draft
---

# REQ-{NNN}: {requirement_title}

**Priority**: {Must|Should|Could|Won't}

## Description

{detailed requirement description}

## User Story

As a {persona}, I want to {action} so that {benefit}.

## Acceptance Criteria

- [ ] {specific, testable criterion 1}
- [ ] {specific, testable criterion 2}
- [ ] {specific, testable criterion 3}

## Traces

- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics)
- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable)
- **Implemented by**: [EPIC-{NNN}](../epics/EPIC-{NNN}-{slug}.md) (added in Phase 5)

---

Template: NFR-{type}-NNN-{slug}.md (Individual Non-Functional Requirement)

---
id: NFR-{type}-{NNN}
type: non-functional
category: {Performance|Security|Scalability|Usability}
priority: {Must|Should|Could}
status: draft
---

# NFR-{type}-{NNN}: {requirement_title}

**Category**: {Performance|Security|Scalability|Usability}
**Priority**: {Must|Should|Could}

## Requirement

{detailed requirement description}

## Metric & Target

| Metric | Target | Measurement Method |
|--------|--------|--------------------|
| {metric} | {target value} | {how measured} |

## Traces

- **Goal**: [G-{NNN}](../product-brief.md#goals--success-metrics)
- **Architecture**: [ADR-{NNN}](../architecture/ADR-{NNN}-{slug}.md) (if applicable)

---

Variable Descriptions