Claude-Code-Workflow/.claude/docs/tdd-implementation-roadmap.md

TDD Workflow Implementation Roadmap

Overview

This roadmap outlines the implementation steps for the TDD workflow system, organized by priority and dependencies.

Phase 1: Core TDD Task Generation (Foundation)

Priority: HIGH

Dependencies: None

Estimated Effort: Medium

1.1 Create task-generate-tdd Command

File: .claude/commands/workflow/tools/task-generate-tdd.md

Implementation Steps:

1. Copy structure from task-generate.md
2. Add TDD-specific Gemini prompt for task breakdown
3. Implement Red-Green-Refactor task chain generation logic
4. Add meta.tdd_phase field to task JSONs
5. Implement dependency enforcement (TEST → IMPL → REFACTOR)
6. Generate TDD_PLAN.md alongside IMPL_PLAN.md

Key Features:

• Gemini-based TDD task analysis
• Automatic chain creation for each feature
• Validation of TDD structure
• Support for both manual and agent modes

Testing:

• Test with single feature
• Test with multiple features
• Verify dependency chains
• Validate JSON schema compliance

---

Phase 2: TDD Planning Orchestrator

Priority: HIGH

Dependencies: Phase 1

Estimated Effort: Medium

2.1 Create tdd-plan Command

File: .claude/commands/workflow/tdd-plan.md

Implementation Steps:

1. Copy orchestrator pattern from plan.md
2. Modify Phase 4 to call task-generate-tdd instead of task-generate
3. Add Phase 5 for TDD structure validation
4. Update structured input format to include TEST_FOCUS
5. Customize TodoWrite pattern for TDD phases
6. Design TDD-specific output summary

Key Features:

• 5-phase orchestration (adds validation phase)
• Reuses existing session:start, context-gather, concept-enhanced
• TDD-specific task generation in Phase 4
• Structure validation in Phase 5
• Clear TDD chain summary in output

Testing:

• End-to-end TDD workflow creation
• Verify all phases execute correctly
• Validate generated task structure
• Test with different input formats

---

Phase 3: TDD Coverage Analysis Tool

Priority: MEDIUM

Dependencies: Phase 1

Estimated Effort: Small

3.1 Create tdd-coverage-analysis Command

File: .claude/commands/workflow/tools/tdd-coverage-analysis.md

Implementation Steps:

1. Create command specification
2. Implement test task extraction logic
3. Add test execution wrapper
4. Implement coverage data parsing
5. Add TDD cycle verification logic
6. Generate analysis report

Key Features:

• Extract test files from TEST tasks
• Run test suite with coverage
• Verify Red-Green-Refactor cycle
• Generate coverage metrics
• Identify gaps in TDD process

Testing:

• Test with completed TDD workflow
• Verify coverage data accuracy
• Test cycle verification logic
• Validate report generation

---

Phase 4: TDD Verification Orchestrator

Priority: MEDIUM

Dependencies: Phase 1, Phase 3

Estimated Effort: Medium

4.1 Create tdd-verify Command

File: .claude/commands/workflow/tdd-verify.md

Implementation Steps:

1. Create 4-phase orchestrator structure
2. Implement session discovery logic
3. Add task chain validation
4. Integrate tdd-coverage-analysis
5. Add Gemini compliance report generation
6. Design verification output summary

Key Features:

• Automatic session detection
• Task chain structure validation
• Test execution analysis
• Compliance scoring
• Detailed quality recommendations
• Clear verification summary

Testing:

• Test with complete TDD workflow
• Test with incomplete workflow
• Verify compliance scoring
• Test report generation

---

Phase 5: TDD Templates and Documentation

Priority: MEDIUM

Dependencies: Phases 1-4

Estimated Effort: Small

5.1 Create TDD Prompt Templates

Files:

• .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

Implementation Steps:

1. Design test-writing template (Red phase)
2. Design implementation template (Green phase)
3. Design refactoring template (Refactor phase)
4. Include TDD best practices
5. Add specific acceptance criteria

Key Features:

• Phase-specific guidance
• TDD best practices embedded
• Clear acceptance criteria
• Agent-friendly format

5.2 Update Core Documentation

Files to Update:

• .claude/workflows/workflow-architecture.md
• .claude/workflows/task-core.md
• README.md

Updates Required:

1. Add TDD workflow section to architecture
2. Document meta.tdd_phase field in task-core
3. Add TDD usage examples to README
4. Create TDD workflow diagram
5. Add troubleshooting guide

---

Phase 6: Integration and Polish

Priority: LOW

Dependencies: Phases 1-5

Estimated Effort: Small

6.1 Command Registry Updates

Files:

• .claude/commands.json (if exists)
• Slash command documentation

Updates:

1. Register new commands
2. Update command help text
3. Add command shortcuts
4. Update command examples

6.2 Testing and Validation

Activities:

1. End-to-end integration testing
2. Performance testing
3. Error handling validation
4. Documentation review
5. User acceptance testing

---

Implementation Priority Matrix

Priority | Phase | Component                    | Effort | Dependencies
---------|-------|------------------------------|--------|-------------
HIGH     | 1     | task-generate-tdd            | Medium | None
HIGH     | 2     | tdd-plan                     | Medium | Phase 1
MEDIUM   | 3     | tdd-coverage-analysis        | Small  | Phase 1
MEDIUM   | 4     | tdd-verify                   | Medium | Phase 1, 3
MEDIUM   | 5     | Templates & Documentation    | Small  | Phase 1-4
LOW      | 6     | Integration & Polish         | Small  | Phase 1-5

---

Detailed Component Specifications

Component 1: task-generate-tdd

Inputs:

• --session <sessionId>: Required session identifier
• --agent: Optional flag for agent mode
• ANALYSIS_RESULTS.md from session

Outputs:

• TDD_PLAN.md: TDD-specific implementation plan
• IMPL_PLAN.md: Standard implementation plan
• TODO_LIST.md: Task list with TDD phases
• .task/TEST-*.json: Test task files
• .task/IMPL-*.json: Implementation task files
• .task/REFACTOR-*.json: Refactoring task files

Core Logic:

1. Load ANALYSIS_RESULTS.md
2. Call Gemini to identify features and create TDD breakdown
3. For each feature:
   a. Create TEST task (Red phase)
   b. Create IMPL task with depends_on TEST (Green phase)
   c. Create REFACTOR task with depends_on IMPL (Refactor phase)
4. Validate chain structure
5. Generate TDD_PLAN.md
6. Generate IMPL_PLAN.md
7. Generate TODO_LIST.md
8. Return task count and chain summary

Gemini Prompt Structure:

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.

Validation Rules:

• Each TEST task must have ID format TEST-N.M
• Each IMPL task must have depends_on: ["TEST-N.M"]
• Each REFACTOR task must have depends_on: ["IMPL-N.M"]
• All tasks must have meta.tdd_phase field
• Agent must be appropriate for phase

---

Component 2: tdd-plan

Inputs:

• <input>: Feature description, file path, or issue ID
• --agent: Optional flag for agent mode

Outputs:

• Session summary with TDD chain information
• All standard workflow outputs
• TDD_PLAN.md

Phase Breakdown:

Phase 1: Session Discovery (Reused)

• Command: /workflow:session:start --auto "TDD: ..."
• Extract: sessionId

Phase 2: Context Gathering (Reused)

• Command: /workflow:tools:context-gather --session sessionId ...
• Extract: contextPath

Phase 3: TDD Analysis (Reused)

• Command: /workflow:tools:concept-enhanced --session sessionId --context contextPath
• Extract: ANALYSIS_RESULTS.md

Phase 4: TDD Task Generation (New)

• Command: /workflow:tools:task-generate-tdd --session sessionId [--agent]
• Extract: Task count, chain count

Phase 5: Structure Validation (New)

• Internal validation
• Verify chain completeness
• Verify dependencies
• Extract: Validation status

TodoWrite Pattern:

// Initialize
[
  {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"}
]

// After each phase, update one to "completed", next to "in_progress"

Output Template:

TDD Planning complete for session: {sessionId}

Features analyzed: {count}
TDD chains generated: {count}
Total tasks: {count}

Structure:
- {Feature 1}: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
- {Feature 2}: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1

Plans:
- Implementation: .workflow/{sessionId}/IMPL_PLAN.md
- TDD Structure: .workflow/{sessionId}/TDD_PLAN.md

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

---

Component 3: tdd-coverage-analysis

Inputs:

• --session <sessionId>: Required session identifier

Outputs:

• .process/test-results.json: Test execution results
• .process/coverage-report.json: Coverage metrics
• .process/tdd-cycle-report.md: TDD cycle verification

Core Logic:

1. Extract all TEST tasks from session
2. Identify test files from focus_paths
3. Run test suite with coverage
4. Parse coverage data
5. For each TDD chain:
   a. Verify TEST task created tests
   b. Verify IMPL task made tests pass
   c. Verify REFACTOR task maintained green tests
6. Generate cycle verification report
7. Return coverage metrics and cycle status

Test Execution:

npm test -- --coverage --json > .process/test-results.json
# or
pytest --cov --json-report > .process/test-results.json

Cycle Verification Algorithm:

For each chain (TEST-N.M, IMPL-N.M, REFACTOR-N.M):
  1. Read TEST-N.M-summary.md
     - Check: Tests were created
     - Check: Tests failed initially

  2. Read IMPL-N.M-summary.md
     - Check: Implementation was completed
     - Check: Tests now pass

  3. Read REFACTOR-N.M-summary.md
     - Check: Refactoring was completed
     - Check: Tests still pass

  If all checks pass: Chain is valid
  Else: Report missing steps

---

Component 4: tdd-verify

Inputs:

• [session-id]: Optional session ID (auto-detect if not provided)

Outputs:

• Verification summary
• TDD_COMPLIANCE_REPORT.md

Phase Breakdown:

Phase 1: Session Discovery

# If session-id provided
sessionId = argument

# Else auto-detect
sessionId = $(find .workflow/ -name '.active-*' | head -1 | sed 's/.*active-//')

Phase 2: Task Chain Validation

# Load all task JSONs
tasks=$(find .workflow/${sessionId}/.task/ -name '*.json')

# For each TDD chain
for feature in features:
  verify_chain_exists(TEST-N.M, IMPL-N.M, REFACTOR-N.M)
  verify_dependencies(IMPL depends_on TEST, REFACTOR depends_on IMPL)
  verify_meta_fields(tdd_phase, agent)

Phase 3: Test Execution Analysis

/workflow:tools:tdd-coverage-analysis --session ${sessionId}

Phase 4: Compliance Report

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

Output Template:

TDD Verification Report - Session: {sessionId}

## Chain Validation
{status} Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1 ({status})
{status} Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1 ({status})

## Test Execution
{status} All TEST tasks produced failing tests
{status} All IMPL tasks made tests pass
{status} All REFACTOR tasks maintained green tests

## Compliance Score: {score}/100

Detailed report: .workflow/{sessionId}/TDD_COMPLIANCE_REPORT.md

Recommendations:
{recommendations}

---

File Structure Reference

.workflow/
└── WFS-{session-id}/
    ├── ANALYSIS_RESULTS.md          # From concept-enhanced
    ├── IMPL_PLAN.md                 # Standard plan
    ├── TDD_PLAN.md                  # TDD-specific plan ⭐ NEW
    ├── TODO_LIST.md                 # With TDD phase markers
    ├── TDD_COMPLIANCE_REPORT.md     # From tdd-verify ⭐ NEW
    │
    ├── .task/
    │   ├── TEST-1.1.json            # Red phase ⭐ NEW
    │   ├── IMPL-1.1.json            # Green phase (enhanced)
    │   ├── REFACTOR-1.1.json        # Refactor phase ⭐ NEW
    │   └── ...
    │
    ├── .summaries/
    │   ├── TEST-1.1-summary.md      # Test task summary
    │   ├── IMPL-1.1-summary.md      # Implementation summary
    │   ├── REFACTOR-1.1-summary.md  # Refactor summary
    │   └── ...
    │
    └── .process/
        ├── TDD_TASK_BREAKDOWN.md    # Gemini breakdown ⭐ NEW
        ├── test-results.json         # Test execution ⭐ NEW
        ├── coverage-report.json      # Coverage data ⭐ NEW
        └── tdd-cycle-report.md       # Cycle verification ⭐ NEW

---

Implementation Order

Week 1: Foundation

1. Create task-generate-tdd.md specification
2. Implement Gemini TDD breakdown logic
3. Implement task JSON generation with TDD chains
4. Test with simple single-feature workflow

Week 2: Orchestration

1. Create tdd-plan.md specification
2. Implement 5-phase orchestrator
3. Integrate with task-generate-tdd
4. End-to-end testing

Week 3: Verification

1. Create tdd-coverage-analysis.md specification
2. Implement test execution and cycle verification
3. Create tdd-verify.md specification
4. Implement verification orchestrator
5. Integration testing

Week 4: Polish

1. Create TDD prompt templates
2. Update documentation
3. Create usage examples
4. Final integration testing
5. User acceptance testing

---

Success Criteria

Functional Requirements

• TDD workflows can be created from feature descriptions
• Task chains enforce Red-Green-Refactor order
• Dependencies prevent out-of-order execution
• Verification detects non-compliance
• Coverage analysis integrates with test tools
• Reports provide actionable insights

Quality Requirements

• Commands follow existing architectural patterns
• Error handling is robust
• Documentation is complete
• Examples demonstrate common use cases
• Integration with existing workflow is seamless

Performance Requirements

• TDD planning completes within 2 minutes
• Verification completes within 1 minute
• Gemini analysis stays within token limits
• Test execution doesn't timeout

---

Risk Mitigation

Risk 1: Test Framework Integration

Mitigation: Support multiple test frameworks (npm test, pytest, etc.) with configurable commands

Risk 2: Gemini Token Limits

Mitigation: Use focused context in prompts, paginate large analysis

Risk 3: Complex Dependencies

Mitigation: Thorough validation logic, clear error messages

Risk 4: User Adoption

Mitigation: Clear documentation, simple examples, gradual rollout

---

Next Steps

1. Review Design: Get feedback on architecture and specifications
2. Create Prototype: Implement Phase 1 (task-generate-tdd) as proof of concept
3. Test Prototype: Validate with real-world TDD workflow
4. Iterate: Refine based on testing feedback
5. Full Implementation: Complete remaining phases
6. Documentation: Create user guides and examples
7. Release: Roll out to users with migration guide