Claude-Code-Workflow/.claude/docs/tdd-workflow-design.md

TDD Workflow Design Specification

Architecture Overview

The TDD workflow introduces a specialized planning and verification system that enforces Test-Driven Development principles through the existing workflow architecture. It follows the same orchestrator pattern as /workflow:plan but generates TDD-specific task chains.

Command Structure

Primary Commands (Orchestrators)

• /workflow:tdd-plan - TDD workflow planning orchestrator
• /workflow:tdd-verify - TDD compliance verification orchestrator

Tool Commands (Executors)

• /workflow:tools:task-generate-tdd - TDD-specific task generator
• /workflow:tools:tdd-coverage-analysis - Test coverage analyzer

---

1. /workflow:tdd-plan Command

Purpose

Orchestrate TDD-specific workflow planning that generates Red-Green-Refactor task chains with enforced dependencies.

Command Specification

name: tdd-plan
description: Orchestrate TDD workflow planning with Red-Green-Refactor task chains
usage: /workflow:tdd-plan [--agent] <input>
argument-hint: "[--agent] \"feature description\"|file.md|ISS-001"
examples:
  - /workflow:tdd-plan "Implement user authentication"
  - /workflow:tdd-plan --agent requirements.md
  - /workflow:tdd-plan ISS-001
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)

Execution Flow (5 Phases)

Phase 1: Session Discovery

/workflow:session:start --auto "TDD: [structured-description]"

• Extract: sessionId (WFS-xxx)
• Validation: Session directory created

Phase 2: Context Gathering

/workflow:tools:context-gather --session [sessionId] "TDD: [structured-description]"

• Extract: contextPath (context-package.json)
• Validation: Context package exists

Phase 3: TDD Analysis

/workflow:tools:concept-enhanced --session [sessionId] --context [contextPath]

• Extract: ANALYSIS_RESULTS.md
• Validation: Contains TDD-specific recommendations

Phase 4: TDD Task Generation

# Manual mode (default)
/workflow:tools:task-generate-tdd --session [sessionId]

# Agent mode
/workflow:tools:task-generate-tdd --session [sessionId] --agent

• Extract: Task count, TDD chain count
• Validation:
  • IMPL_PLAN.md exists
  • TDD_PLAN.md exists (TDD-specific plan)
  • Task JSONs follow Red-Green-Refactor pattern
  • Dependencies correctly enforced

Phase 5: TDD Structure Validation

# Internal validation step (no separate command call)
# Verify task chain structure:
# - Each feature has TEST → IMPL → REFACTOR sequence
# - Dependencies are correctly set
# - Meta.type fields are appropriate

• Extract: Validation report
• Validation: All TDD chains valid

Structured Input Format

TDD: [feature-name]
GOAL: [Clear objective]
SCOPE: [What to test and implement]
CONTEXT: [Relevant background]
TEST_FOCUS: [Critical test scenarios]

TDD-Specific TodoWrite Pattern

TodoWrite({todos: [
  {"content": "Execute session discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
  {"content": "Execute context gathering", "status": "pending", "activeForm": "Executing context gathering"},
  {"content": "Execute TDD analysis", "status": "pending", "activeForm": "Executing TDD analysis"},
  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
]})

Output Structure

TDD Planning complete for session: [sessionId]

Features analyzed: [count]
TDD chains generated: [count]
Total tasks: [count]

Structure:
- [Feature 1]: TEST-1 → IMPL-1 → REFACTOR-1
- [Feature 2]: TEST-2 → IMPL-2 → REFACTOR-2

Plans:
- Implementation: .workflow/[sessionId]/IMPL_PLAN.md
- TDD Structure: .workflow/[sessionId]/TDD_PLAN.md

Next: /workflow:execute or /workflow:tdd-verify

---

2. /workflow:tools:task-generate-tdd Command

Purpose

Generate TDD-specific task chains from ANALYSIS_RESULTS.md with enforced Red-Green-Refactor structure.

Command Specification

name: task-generate-tdd
description: Generate TDD task chains with Red-Green-Refactor dependencies
usage: /workflow:tools:task-generate-tdd --session <session-id> [--agent]
argument-hint: "--session WFS-xxx [--agent]"
examples:
  - /workflow:tools:task-generate-tdd --session WFS-auth
  - /workflow:tools:task-generate-tdd --session WFS-auth --agent
allowed-tools: Read(*), Write(*), Bash(gemini-wrapper:*)

Implementation Flow

Step 1: Load Analysis

cat .workflow/[sessionId]/ANALYSIS_RESULTS.md

Step 2: Gemini TDD Task Planning

cd project-root && ~/.claude/scripts/gemini-wrapper -p "
PURPOSE: Generate TDD task breakdown with Red-Green-Refactor chains
TASK: Analyze ANALYSIS_RESULTS.md and create TDD-structured task breakdown
CONTEXT: @{.workflow/[sessionId]/ANALYSIS_RESULTS.md}
EXPECTED:
- Feature list with testable requirements
- Test cases for each feature (Red phase)
- Implementation requirements (Green phase)
- Refactoring opportunities (Refactor phase)
- Task dependencies and execution order
RULES: Each feature must have TEST → IMPL → REFACTOR chain. Output structured markdown for task generation.
" > .workflow/[sessionId]/.process/TDD_TASK_BREAKDOWN.md

Step 3: Generate Task JSONs

For each feature identified:

// TEST Phase (Red)
{
  "id": "TEST-1.1",
  "title": "Write failing test for [feature]",
  "status": "pending",
  "meta": {
    "type": "test",
    "agent": "@code-review-test-agent",
    "tdd_phase": "red"
  },
  "context": {
    "requirements": ["Write test case that fails", "Test should define expected behavior"],
    "focus_paths": ["tests/[feature]"],
    "acceptance": ["Test written and fails with clear error message"],
    "depends_on": []
  }
}

// IMPL Phase (Green)
{
  "id": "IMPL-1.1",
  "title": "Implement [feature] to pass tests",
  "status": "pending",
  "meta": {
    "type": "feature",
    "agent": "@code-developer",
    "tdd_phase": "green"
  },
  "context": {
    "requirements": ["Implement minimal code to pass TEST-1.1"],
    "focus_paths": ["src/[feature]", "tests/[feature]"],
    "acceptance": ["All tests in TEST-1.1 pass"],
    "depends_on": ["TEST-1.1"]
  },
  "flow_control": {
    "pre_analysis": [
      {
        "step": "load_test_requirements",
        "action": "Read test specifications from TEST phase",
        "command": "bash(cat .workflow/[sessionId]/.summaries/TEST-1.1-summary.md)",
        "output_to": "test_requirements",
        "on_error": "fail"
      }
    ]
  }
}

// REFACTOR Phase
{
  "id": "REFACTOR-1.1",
  "title": "Refactor [feature] implementation",
  "status": "pending",
  "meta": {
    "type": "refactor",
    "agent": "@code-developer",
    "tdd_phase": "refactor"
  },
  "context": {
    "requirements": ["Improve code quality while keeping tests green", "Remove duplication", "Improve readability"],
    "focus_paths": ["src/[feature]", "tests/[feature]"],
    "acceptance": ["Code improved", "All tests still pass"],
    "depends_on": ["IMPL-1.1"]
  },
  "flow_control": {
    "pre_analysis": [
      {
        "step": "verify_tests_passing",
        "action": "Run tests to confirm green state before refactoring",
        "command": "bash(npm test -- tests/[feature])",
        "output_to": "test_status",
        "on_error": "fail"
      }
    ]
  }
}

Step 4: Generate TDD_PLAN.md

# TDD Implementation Plan - [Session ID]

## Features and Test Chains

### Feature 1: [Feature Name]
**TDD Chain**: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1

**Red Phase (TEST-1.1)**
- Write failing test for [specific behavior]
- Test assertions: [list]

**Green Phase (IMPL-1.1)**
- Implement minimal solution
- Dependencies: TEST-1.1 must fail first

**Refactor Phase (REFACTOR-1.1)**
- Improve: [specific improvements]
- Constraint: All tests must remain green

[Repeat for each feature]

## Execution Order
1. TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
2. TEST-2.1 → IMPL-2.1 → REFACTOR-2.1
...

## TDD Compliance Checkpoints
- [ ] Each feature starts with failing test
- [ ] Implementation passes all tests
- [ ] Refactoring maintains green tests
- [ ] No implementation before tests

Step 5: Generate TODO_LIST.md

Standard todo list with TDD phase indicators:

## Pending Tasks
- [ ] TEST-1.1: Write failing test for [feature] (RED)
- [ ] IMPL-1.1: Implement [feature] to pass tests (GREEN) [depends: TEST-1.1]
- [ ] REFACTOR-1.1: Refactor [feature] implementation (REFACTOR) [depends: IMPL-1.1]

Validation Rules

1. Chain Completeness: Every TEST task must have corresponding IMPL and REFACTOR tasks
2. Dependency Enforcement:
   • IMPL depends_on TEST
   • REFACTOR depends_on IMPL
3. Agent Assignment:
   • TEST tasks → @code-review-test-agent
   • IMPL/REFACTOR tasks → @code-developer
4. Meta Fields:
   • meta.tdd_phase must be "red", "green", or "refactor"
   • meta.type must align with phase

---

3. /workflow:tdd-verify Command

Purpose

Verify TDD workflow compliance, test coverage, and Red-Green-Refactor cycle execution.

Command Specification

name: tdd-verify
description: Verify TDD workflow compliance and generate quality report
usage: /workflow:tdd-verify [session-id]
argument-hint: "[WFS-session-id]"
examples:
  - /workflow:tdd-verify
  - /workflow:tdd-verify WFS-auth
allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)

Execution Flow (4 Phases)

Phase 1: Session Discovery

# Auto-detect or use provided session
find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//'

• Extract: sessionId

Phase 2: Task Chain Validation

# Bash script to validate TDD structure
find .workflow/[sessionId]/.task/ -name '*.json' -exec jq -r '.meta.tdd_phase' {} \;

• Verify: TEST → IMPL → REFACTOR chains exist
• Verify: Dependencies are correct
• Extract: Chain validation report

Phase 3: Test Execution Analysis

/workflow:tools:tdd-coverage-analysis --session [sessionId]

• Run tests from TEST tasks
• Verify IMPL tasks made tests pass
• Check REFACTOR tasks maintained green tests
• Extract: Test execution report

Phase 4: Compliance Report Generation

# Gemini analysis
cd project-root && ~/.claude/scripts/gemini-wrapper -p "
PURPOSE: Generate TDD compliance report
TASK: Analyze TDD workflow execution and generate quality report
CONTEXT: @{.workflow/[sessionId]/.task/*.json,.workflow/[sessionId]/.summaries/*}
EXPECTED:
- TDD compliance score
- Chain completeness verification
- Test coverage analysis
- Quality recommendations
- Red-Green-Refactor cycle validation
RULES: Focus on TDD best practices and workflow adherence
" > .workflow/[sessionId]/TDD_COMPLIANCE_REPORT.md

TodoWrite Pattern

TodoWrite({todos: [
  {"content": "Identify target session", "status": "in_progress", "activeForm": "Identifying target session"},
  {"content": "Validate task chain structure", "status": "pending", "activeForm": "Validating task chain structure"},
  {"content": "Analyze test execution", "status": "pending", "activeForm": "Analyzing test execution"},
  {"content": "Generate compliance report", "status": "pending", "activeForm": "Generating compliance report"}
]})

Output Structure

TDD Verification Report - Session: [sessionId]

## Chain Validation
✅ Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1 (Complete)
✅ Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1 (Complete)
⚠️  Feature 3: TEST-3.1 → IMPL-3.1 (Missing REFACTOR phase)

## Test Execution
✅ All TEST tasks produced failing tests
✅ All IMPL tasks made tests pass
✅ All REFACTOR tasks maintained green tests

## Compliance Score: 95/100

Detailed report: .workflow/[sessionId]/TDD_COMPLIANCE_REPORT.md

Recommendations:
- Complete missing REFACTOR-3.1 task
- Consider additional edge case tests for Feature 2

---

4. /workflow:tools:tdd-coverage-analysis Command

Purpose

Analyze test coverage and execution results for TDD workflow validation.

Command Specification

name: tdd-coverage-analysis
description: Analyze test coverage and TDD cycle execution
usage: /workflow:tools:tdd-coverage-analysis --session <session-id>
argument-hint: "--session WFS-xxx"
examples:
  - /workflow:tools:tdd-coverage-analysis --session WFS-auth
allowed-tools: Read(*), Write(*), Bash(*)

Implementation Flow

Step 1: Extract Test Tasks

find .workflow/[sessionId]/.task/ -name 'TEST-*.json' -exec jq -r '.context.focus_paths[]' {} \;

Step 2: Run Test Suite

npm test -- --coverage --json > .workflow/[sessionId]/.process/test-results.json

Step 3: Analyze Coverage

jq '.coverage' .workflow/[sessionId]/.process/test-results.json > .workflow/[sessionId]/.process/coverage-report.json

Step 4: Verify TDD Cycle For each chain:

• Check TEST task created test files
• Check IMPL task made tests pass
• Check REFACTOR task didn't break tests

Step 5: Generate Analysis Report

# Test Coverage Analysis

## Coverage Metrics
- Line Coverage: X%
- Branch Coverage: Y%
- Function Coverage: Z%

## TDD Cycle Verification
- Red Phase: X tests written and failed initially
- Green Phase: Y implementations made tests pass
- Refactor Phase: Z refactorings maintained green tests

## Gaps Identified
- [List any missing test coverage]
- [List any incomplete TDD cycles]

---

Integration with Existing System

Data Flow Diagram

User Input
    ↓
/workflow:tdd-plan "feature description"
    ↓
Phase 1: /workflow:session:start --auto "TDD: ..."
    ↓ sessionId
Phase 2: /workflow:tools:context-gather --session sessionId
    ↓ contextPath
Phase 3: /workflow:tools:concept-enhanced --session sessionId --context contextPath
    ↓ ANALYSIS_RESULTS.md
Phase 4: /workflow:tools:task-generate-tdd --session sessionId
    ↓ TEST-*.json, IMPL-*.json, REFACTOR-*.json
    ↓ TDD_PLAN.md, IMPL_PLAN.md, TODO_LIST.md
Phase 5: Internal validation
    ↓
Return summary
    ↓
/workflow:execute (user executes tasks)
    ↓
/workflow:tdd-verify (user verifies compliance)
    ↓
Phase 1: Session discovery
    ↓ sessionId
Phase 2: Task chain validation
    ↓ validation report
Phase 3: /workflow:tools:tdd-coverage-analysis
    ↓ coverage report
Phase 4: Gemini compliance report
    ↓ TDD_COMPLIANCE_REPORT.md
Return verification summary

File Structure

.workflow/
└── WFS-[session-id]/
    ├── ANALYSIS_RESULTS.md          # From concept-enhanced
    ├── IMPL_PLAN.md                 # Standard implementation plan
    ├── TDD_PLAN.md                  # TDD-specific plan (new)
    ├── TODO_LIST.md                 # Task list with TDD phases
    ├── TDD_COMPLIANCE_REPORT.md     # Verification report (new)
    ├── .task/
    │   ├── TEST-1.1.json
    │   ├── IMPL-1.1.json
    │   ├── REFACTOR-1.1.json
    │   └── ...
    ├── .summaries/
    │   ├── TEST-1.1-summary.md
    │   ├── IMPL-1.1-summary.md
    │   └── ...
    └── .process/
        ├── TDD_TASK_BREAKDOWN.md    # Gemini TDD breakdown
        ├── test-results.json         # Test execution results
        └── coverage-report.json      # Coverage data

Relationship with Existing Commands

• Reuses: /workflow:session:start, /workflow:tools:context-gather, /workflow:tools:concept-enhanced
• Extends: Adds TDD-specific task generation and verification
• Compatible with: /workflow:execute, /workflow:status, /workflow:resume
• Complements: /workflow:test-gen (TDD is proactive, test-gen is reactive)

---

Implementation Checklist

Command Files to Create

• .claude/commands/workflow/tdd-plan.md
• .claude/commands/workflow/tdd-verify.md
• .claude/commands/workflow/tools/task-generate-tdd.md
• .claude/commands/workflow/tools/tdd-coverage-analysis.md

Template Files to Create

• .claude/workflows/cli-templates/prompts/development/tdd-test.txt
• .claude/workflows/cli-templates/prompts/development/tdd-impl.txt
• .claude/workflows/cli-templates/prompts/development/tdd-refactor.txt

Documentation to Update

• .claude/workflows/workflow-architecture.md - Add TDD workflow section
• .claude/workflows/task-core.md - Document meta.tdd_phase field
• README.md - Add TDD workflow usage examples

Testing Requirements

• Test tdd-plan with simple feature
• Verify task chain dependencies
• Test tdd-verify compliance checking
• Validate integration with workflow:execute
• Test error handling and validation

---

Usage Examples

Example 1: Create TDD Workflow

# Plan TDD workflow
/workflow:tdd-plan "Implement user registration with email validation"

# Execute tasks in order
/workflow:execute

# Verify TDD compliance
/workflow:tdd-verify

Example 2: Agent Mode

# Use agent for autonomous TDD planning
/workflow:tdd-plan --agent requirements.md

# Execute with automatic task execution
/workflow:execute

Example 3: Issue-Based TDD

# Create TDD workflow from issue
/workflow:tdd-plan ISS-042

# Execute and verify
/workflow:execute
/workflow:tdd-verify WFS-issue-042

---

Benefits

1. Enforced TDD Discipline: Dependencies ensure tests come before implementation
2. Clear Structure: Red-Green-Refactor phases are explicit
3. Quality Verification: Built-in compliance checking
4. Existing Architecture: Reuses proven workflow patterns
5. Agent Support: Can be fully automated or manually controlled
6. Comprehensive Reporting: Clear visibility into TDD adherence
7. Flexible: Works with existing workflow commands