Claude-Code-Workflow/.claude/commands/workflow/tools/task-generate-tdd.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
task-generate-tdd	Generate TDD task chains with Red-Green-Refactor dependencies	--session WFS-session-id [--agent]	Read(*), Write(*), Bash(gemini:*), TodoWrite(*)

TDD Task Generation Command

Overview

Generate TDD-specific tasks from analysis results with complete Red-Green-Refactor cycles contained within each task.

Task Strategy & Philosophy

Optimized Task Structure (Current)

• 1 feature = 1 task containing complete TDD cycle internally
• Each task executes Red-Green-Refactor phases sequentially
• Task count = Feature count (typically 5 features = 5 tasks)
• Benefits:
  • 70% reduction in task management overhead
  • Continuous context per feature (no switching between TEST/IMPL/REFACTOR)
  • Simpler dependency management
  • Maintains TDD rigor through internal phase structure

Previous Approach (Deprecated):

• 1 feature = 3 separate tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
• 5 features = 15 tasks with complex dependency chains
• High context switching cost between phases

When to Use Subtasks

• Feature complexity >2500 lines or >6 files per TDD cycle
• Multiple independent sub-features needing parallel execution
• Strong technical dependency blocking (e.g., API before UI)
• Different tech stacks or domains within feature

Task Limits

• Maximum 10 tasks (hard limit for TDD workflows)
• Feature-based: Complete functional units with internal TDD cycles
• Hierarchy: Flat (≤5 simple features) | Two-level (6-10 for complex features with sub-features)
• Re-scope: If >10 tasks needed, break project into multiple TDD workflow sessions

TDD Cycle Mapping

• Old approach: 1 feature = 3 tasks (TEST-N.M, IMPL-N.M, REFACTOR-N.M)
• Current approach: 1 feature = 1 task (IMPL-N with internal Red-Green-Refactor phases)
• Complex features: 1 container (IMPL-N) + subtasks (IMPL-N.M) when necessary

Core Principles

• TDD-First: Every feature starts with a failing test (Red phase)
• Feature-Complete Tasks: Each task contains complete Red-Green-Refactor cycle
• Phase-Explicit: Internal phases clearly marked in flow_control.implementation_approach
• Task Merging: Prefer single task per feature over decomposition
• Path Clarity: All focus_paths prefer absolute paths (e.g., D:\\project\\src\\module), or clear relative paths from project root (e.g., ./src/module)
• Artifact-Aware: Integrates brainstorming outputs
• Memory-First: Reuse loaded documents from memory
• Context-Aware: Analyzes existing codebase and test patterns
• Iterative Green Phase: Auto-diagnose and fix test failures with Gemini + optional Codex
• Safety-First: Auto-revert on max iterations to prevent broken state

Core Responsibilities

• Parse analysis results and identify testable features
• Generate feature-complete tasks with internal TDD cycles (1 task per simple feature)
• Apply task merging strategy by default, create subtasks only when complexity requires
• Generate IMPL_PLAN.md with TDD Implementation Tasks section
• Generate TODO_LIST.md with internal TDD phase indicators
• Update session state for TDD execution with task count compliance

Execution Lifecycle

Phase 1: Input Validation & Discovery

Memory-First Rule: Skip file loading if documents already in conversation memory

1. Session Validation

   • If session metadata in memory → Skip loading
   • Else: Load .workflow/{session_id}/workflow-session.json

2. Conflict Resolution Check (NEW - Priority Input)

   • If CONFLICT_RESOLUTION.md exists → Load selected strategies
   • Else: Skip to brainstorming artifacts
   • Path: .workflow/{session_id}/.process/CONFLICT_RESOLUTION.md

3. Artifact Discovery

   • If artifact inventory in memory → Skip scanning
   • Else: Scan .workflow/{session_id}/.brainstorming/ directory
   • Detect: role analysis documents, guidance-specification.md, role analyses

4. Context Package Loading

   • Load .workflow/{session_id}/.process/context-package.json
   • Load .workflow/{session_id}/.process/test-context-package.json (if exists)

Phase 2: TDD Task JSON Generation

Input Sources (priority order):

1. Conflict Resolution (if exists): .process/CONFLICT_RESOLUTION.md - Selected resolution strategies
2. Brainstorming Artifacts: Role analysis documents (system-architect, product-owner, etc.)
3. Context Package: .process/context-package.json - Project structure and requirements
4. Test Context: .process/test-context-package.json - Existing test patterns

TDD Task Structure includes:

• Feature list with testable requirements
• Test cases for Red phase
• Implementation requirements for Green phase (with test-fix cycle)
• Refactoring opportunities
• Task dependencies and execution order
• Conflict resolution decisions (if applicable)

Phase 3: Task JSON & IMPL_PLAN.md Generation

Task Structure (Feature-Complete with Internal TDD)

For each feature, generate task(s) with ID format:

• IMPL-N - Single task containing complete TDD cycle (Red-Green-Refactor)
• IMPL-N.M - Sub-tasks only when feature is complex (>2500 lines or technical blocking)

Task Dependency Rules:

• Sequential features: IMPL-2 depends_on ["IMPL-1"] if Feature 2 needs Feature 1
• Independent features: No dependencies, can execute in parallel
• Complex features: IMPL-N.2 depends_on ["IMPL-N.1"] for subtask ordering

Agent Assignment:

• All IMPL tasks → @code-developer (handles full TDD cycle)
• Agent executes Red, Green, Refactor phases sequentially within task

Meta Fields:

• meta.type: "feature" (TDD-driven feature implementation)
• meta.agent: "@code-developer"
• meta.tdd_workflow: true (enables TDD-specific flow)
• meta.tdd_phase: Not used (phases are in flow_control.implementation_approach)
• meta.max_iterations: 3 (for Green phase test-fix cycle)
• meta.use_codex: false (manual fixes by default)

Task JSON Structure Reference

Simple Feature Task (IMPL-N.json) - Recommended for most features:

{
  "id": "IMPL-N",                                  // Task identifier
  "title": "Feature description with TDD",         // Human-readable title
  "status": "pending",                             // pending | in_progress | completed | container
  "context_package_path": ".workflow/{session-id}/.process/context-package.json", // Path to smart context package
  "meta": {
    "type": "feature",                             // Task type
    "agent": "@code-developer",                    // Assigned agent
    "tdd_workflow": true,                          // REQUIRED: Enables TDD flow
    "max_iterations": 3,                           // Green phase test-fix cycle limit
    "use_codex": false                             // false=manual fixes, true=Codex automated fixes
  },
  "context": {
    "requirements": [                              // Feature requirements with TDD phases
      "Feature description",
      "Red: Test scenarios to write",
      "Green: Implementation approach with test-fix cycle",
      "Refactor: Code quality improvements"
    ],
    "tdd_cycles": [                                // OPTIONAL: Detailed test cycles
      {
        "cycle": 1,
        "feature": "Specific functionality",
        "test_focus": "What to test",
        "expected_failure": "Why test should fail initially"
      }
    ],
    "focus_paths": ["D:\\project\\src\\path", "./tests/path"],  // Absolute or clear relative paths from project root
    "acceptance": [                                // Success criteria
      "All tests pass (Red → Green)",
      "Code refactored (Refactor complete)",
      "Test coverage ≥80%"
    ],
    "depends_on": []                               // Task dependencies
  },
  "flow_control": {
    "pre_analysis": [                              // OPTIONAL: Pre-execution checks
      {
        "step": "check_test_framework",
        "action": "Verify test framework",
        "command": "bash(npm list jest)",
        "output_to": "test_framework_info",
        "on_error": "warn"
      }
    ],
    "implementation_approach": [                   // REQUIRED: 3 TDD phases
      {
        "step": 1,
        "title": "RED Phase: Write failing tests",
        "tdd_phase": "red",                        // REQUIRED: Phase identifier
        "description": "Write comprehensive failing tests",
        "modification_points": ["Files/changes to make"],
        "logic_flow": ["Step-by-step process"],
        "acceptance": ["Phase success criteria"],
        "depends_on": [],
        "output": "failing_tests"
      },
      {
        "step": 2,
        "title": "GREEN Phase: Implement to pass tests",
        "tdd_phase": "green",                      // REQUIRED: Phase identifier
        "description": "Minimal implementation with test-fix cycle",
        "modification_points": ["Implementation files"],
        "logic_flow": [
          "Implement minimal code",
          "Run tests",
          "If fail → Enter iteration loop (max 3):",
          "  1. Extract failure messages",
          "  2. Gemini bug-fix diagnosis",
          "  3. Apply fixes",
          "  4. Rerun tests",
          "If max_iterations → Auto-revert"
        ],
        "acceptance": ["All tests pass"],
        "command": "bash(npm test -- tests/path/)",
        "depends_on": [1],
        "output": "passing_implementation"
      },
      {
        "step": 3,
        "title": "REFACTOR Phase: Improve code quality",
        "tdd_phase": "refactor",                   // REQUIRED: Phase identifier
        "description": "Refactor while keeping tests green",
        "modification_points": ["Quality improvements"],
        "logic_flow": ["Incremental refactoring with test verification"],
        "acceptance": ["Tests still pass", "Code quality improved"],
        "command": "bash(npm run lint && npm test)",
        "depends_on": [2],
        "output": "refactored_implementation"
      }
    ],
    "post_completion": [                           // OPTIONAL: Final verification
      {
        "step": "verify_full_tdd_cycle",
        "action": "Confirm complete TDD cycle",
        "command": "bash(npm test && echo 'TDD complete')",
        "output_to": "final_validation",
        "on_error": "fail"
      }
    ],
    "error_handling": {                            // OPTIONAL: Error recovery
      "green_phase_max_iterations": {
        "action": "revert_all_changes",
        "commands": ["bash(git reset --hard HEAD)"],
        "report": "Generate failure report"
      }
    }
  }
}

Key JSON Fields Summary:

• meta.tdd_workflow: Must be true
• meta.max_iterations: Green phase fix cycle limit (default: 3)
• meta.use_codex: Automated fixes (false=manual, true=Codex)
• flow_control.implementation_approach: Exactly 3 steps with tdd_phase: "red", "green", "refactor"
• context.tdd_cycles: Optional detailed test cycle specifications
• context.parent: Required for subtasks (IMPL-N.M)

IMPL_PLAN.md Structure

Generate IMPL_PLAN.md with 8-section structure:

Frontmatter (required fields):

---
identifier: WFS-{session-id}
source: "User requirements" | "File: path"
conflict_resolution: .workflow/{session-id}/.process/CONFLICT_RESOLUTION.md  # if exists
context_package: .workflow/{session-id}/.process/context-package.json
context_package_path: .workflow/{session-id}/.process/context-package.json
test_context: .workflow/{session-id}/.process/test-context-package.json  # if exists
workflow_type: "tdd"
verification_history:
  conflict_resolution: "executed | skipped" # based on conflict_risk
  action_plan_verify: "pending"
phase_progression: "brainstorm → context → test_context → conflict_resolution → tdd_planning"
feature_count: N
task_count: N  # ≤10 total
task_breakdown:
  simple_features: K
  complex_features: L
  total_subtasks: M
tdd_workflow: true
---

8 Sections Structure:

# Implementation Plan: {Project Title}

## 1. Summary
- Core requirements and objectives (2-3 paragraphs)
- TDD-specific technical approach

## 2. Context Analysis
- CCW Workflow Context (Phase progression, Quality gates)
- Context Package Summary (Focus paths, Test context)
- Project Profile (Type, Scale, Tech Stack, Timeline)
- Module Structure (Directory tree)
- Dependencies (Primary, Testing, Development)
- Patterns & Conventions

## 3. Brainstorming Artifacts Reference
- Artifact Usage Strategy
  - CONFLICT_RESOLUTION.md (if exists - selected resolution strategies)
  - role analysis documents (primary reference)
  - test-context-package.json (test patterns)
  - context-package.json (smart context)
- Artifact Priority in Development

## 4. Implementation Strategy
- Execution Strategy (TDD Cycles: Red-Green-Refactor)
- Architectural Approach
- Key Dependencies (Task dependency graph)
- Testing Strategy (Coverage targets, Quality gates)

## 5. TDD Implementation Tasks
- Feature-by-Feature TDD Tasks
  - Each task: IMPL-N with internal Red → Green → Refactor
  - Dependencies and complexity metrics
- Complex Feature Examples (when subtasks needed)
- TDD Task Breakdown Summary

## 6. Implementation Plan (Detailed Phased Breakdown)
- Execution Strategy (feature-by-feature sequential)
- Phase breakdown (Phase 1, Phase 2, etc.)
- Resource Requirements (Team, Dependencies, Infrastructure)

## 7. Risk Assessment & Mitigation
- Risk table (Risk, Impact, Probability, Mitigation, Owner)
- Critical Risks (TDD-specific)
- Monitoring Strategy

## 8. Success Criteria
- Functional Completeness
- Technical Quality (Test coverage ≥80%)
- Operational Readiness
- TDD Compliance

Phase 4: TODO_LIST.md Generation

Generate task list with internal TDD phase indicators:

For Simple Features (1 task per feature):

## TDD Implementation Tasks

### Feature 1: {Feature Name}
- [ ] **IMPL-1**: Implement {feature} with TDD → [Task](./.task/IMPL-1.json)
  - Internal phases: Red → Green → Refactor
  - Dependencies: None

### Feature 2: {Feature Name}
- [ ] **IMPL-2**: Implement {feature} with TDD → [Task](./.task/IMPL-2.json)
  - Internal phases: Red → Green → Refactor
  - Dependencies: IMPL-1

For Complex Features (with subtasks):

### Feature 3: {Complex Feature Name}
▸ **IMPL-3**: Implement {complex feature} with TDD → [Task](./.task/IMPL-3.json)
  - [ ] **IMPL-3.1**: {Sub-feature A} with TDD → [Task](./.task/IMPL-3.1.json)
    - Internal phases: Red → Green → Refactor
  - [ ] **IMPL-3.2**: {Sub-feature B} with TDD → [Task](./.task/IMPL-3.2.json)
    - Internal phases: Red → Green → Refactor
    - Dependencies: IMPL-3.1

Status Legend:

## Status Legend
- ▸ = Container task (has subtasks)
- [ ] = Pending task
- [x] = Completed task
- Red = Write failing tests
- Green = Implement to pass tests (with test-fix cycle)
- Refactor = Improve code quality

Phase 5: Session State Update

Update workflow-session.json with TDD metadata:

{
  "workflow_type": "tdd",
  "feature_count": 5,
  "task_count": 5,
  "task_breakdown": {
    "simple_features": 4,
    "complex_features": 1,
    "total_subtasks": 2
  },
  "tdd_workflow": true,
  "task_limit_compliance": true
}

Task Count Calculation:

• Simple features: 1 task each (IMPL-N with internal TDD cycle)
• Complex features: 1 container + M subtasks (IMPL-N + IMPL-N.M)
• Total: Simple feature count + Complex feature subtask count
• Example: 4 simple + 1 complex (with 2 subtasks) = 6 total tasks (not 15)

Output Files Structure

.workflow/{session-id}/
├── IMPL_PLAN.md                     # Unified plan with TDD Implementation Tasks section
├── TODO_LIST.md                     # Progress tracking with internal TDD phase indicators
├── .task/
│   ├── IMPL-1.json                  # Complete TDD task (Red-Green-Refactor internally)
│   ├── IMPL-2.json                  # Complete TDD task
│   ├── IMPL-3.json                  # Complex feature container (if needed)
│   ├── IMPL-3.1.json                # Complex feature subtask (if needed)
│   ├── IMPL-3.2.json                # Complex feature subtask (if needed)
│   └── ...
└── .process/
    ├── CONFLICT_RESOLUTION.md       # Conflict resolution strategies (if conflict_risk ≥ medium)
    ├── test-context-package.json    # Test coverage analysis
    ├── context-package.json         # Input from context-gather
    ├── context_package_path         # Path to smart context package
    └── green-fix-iteration-*.md     # Fix logs from Green phase test-fix cycles

File Count:

• Old approach: 5 features = 15 task JSON files (TEST/IMPL/REFACTOR × 5)
• New approach: 5 features = 5 task JSON files (IMPL-N × 5)
• Complex feature: 1 feature = 1 container + M subtasks (IMPL-N + IMPL-N.M)

Validation Rules

Task Completeness

• Every IMPL-N must contain complete TDD workflow in flow_control.implementation_approach
• Each task must have 3 steps with tdd_phase: "red", "green", "refactor"
• Every task must have meta.tdd_workflow: true

Dependency Enforcement

• Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
• Complex feature subtasks: IMPL-N.M depends_on ["IMPL-N.(M-1)"] or parent dependencies
• No circular dependencies allowed

Task Limits

• Maximum 10 total tasks (simple + subtasks)
• Flat hierarchy (≤5 tasks) or two-level (6-10 tasks with containers)
• Re-scope requirements if >10 tasks needed

TDD Workflow Validation

• meta.tdd_workflow must be true
• flow_control.implementation_approach must have exactly 3 steps
• Each step must have tdd_phase field ("red", "green", or "refactor")
• Green phase step must include test-fix cycle logic
• meta.max_iterations must be present (default: 3)

Error Handling

Input Validation Errors

Error	Cause	Resolution
Session not found	Invalid session ID	Verify session exists
Context missing	Incomplete planning	Run context-gather first

TDD Generation Errors

Error	Cause	Resolution
Task count exceeds 10	Too many features or subtasks	Re-scope requirements or merge features
Missing test framework	No test config	Configure testing first
Invalid TDD workflow	Missing tdd_phase or incomplete flow_control	Fix TDD structure in ANALYSIS_RESULTS.md
Missing tdd_workflow flag	Task doesn't have meta.tdd_workflow: true	Add TDD workflow metadata

Integration & Usage

Command Chain

• Called By: /workflow:tdd-plan (Phase 4)
• Calls: Gemini CLI for TDD breakdown
• Followed By: /workflow:execute, /workflow:tdd-verify

Basic Usage

# Manual mode (default)
/workflow:tools:task-generate-tdd --session WFS-auth

# Agent mode (autonomous task generation)
/workflow:tools:task-generate-tdd --session WFS-auth --agent

Expected Output

TDD task generation complete for session: WFS-auth

Features analyzed: 5
Total tasks: 5 (1 task per feature with internal TDD cycles)

Task breakdown:
- Simple features: 4 tasks (IMPL-1 to IMPL-4)
- Complex features: 1 task with 2 subtasks (IMPL-5, IMPL-5.1, IMPL-5.2)
- Total task count: 6 (within 10-task limit)

Structure:
- IMPL-1: User Authentication (Internal: Red → Green → Refactor)
- IMPL-2: Password Reset (Internal: Red → Green → Refactor)
- IMPL-3: Email Verification (Internal: Red → Green → Refactor)
- IMPL-4: Role Management (Internal: Red → Green → Refactor)
- IMPL-5: Payment System (Container)
  - IMPL-5.1: Gateway Integration (Internal: Red → Green → Refactor)
  - IMPL-5.2: Transaction Management (Internal: Red → Green → Refactor)

Plans generated:
- Unified Plan: .workflow/WFS-auth/IMPL_PLAN.md (includes TDD Implementation Tasks section)
- Task List: .workflow/WFS-auth/TODO_LIST.md (with internal TDD phase indicators)

TDD Configuration:
- Each task contains complete Red-Green-Refactor cycle
- Green phase includes test-fix cycle (max 3 iterations)
- Auto-revert on max iterations reached

Next: /workflow:action-plan-verify --session WFS-auth (recommended) or /workflow:execute --session WFS-auth

Test Coverage Analysis Integration

The TDD workflow includes test coverage analysis (via /workflow:tools:test-context-gather) to:

• Detect existing test patterns and conventions
• Identify current test coverage gaps
• Discover test framework and configuration
• Enable integration with existing tests

This makes TDD workflow context-aware instead of assuming greenfield scenarios.

Iterative Green Phase with Test-Fix Cycle

IMPL (Green phase) tasks include automatic test-fix cycle:

Process Flow:

1. Initial Implementation: Write minimal code to pass tests
2. Test Execution: Run test suite
3. Success Path: Tests pass → Complete task
4. Failure Path: Tests fail → Enter iterative fix cycle:
   • Gemini Diagnosis: Analyze failures with bug-fix template
   • Fix Application: Manual (default) or Codex (if meta.use_codex=true)
   • Retest: Verify fix resolves failures
   • Repeat: Up to max_iterations (default: 3)
5. Safety Net: Auto-revert all changes if max iterations reached

Key Benefits:

• Faster feedback loop within Green phase
• Autonomous recovery from initial implementation errors
• Systematic debugging with Gemini's bug-fix template
• Safe rollback prevents broken TDD state

Configuration Options

• meta.max_iterations: Number of fix attempts (default: 3 for TDD, 5 for test-gen)
• meta.use_codex: Enable Codex automated fixes (default: false, manual)

Related Commands

• /workflow:tdd-plan - Orchestrates TDD workflow planning (6 phases)
• /workflow:tools:test-context-gather - Analyzes test coverage
• /workflow:execute - Executes TDD tasks in order
• /workflow:tdd-verify - Verifies TDD compliance
• /workflow:test-gen - Post-implementation test generation