Claude-Code-Workflow/.claude/skills/command-guide/reference/commands/workflow/tdd-plan.md

name, description, argument-hint, allowed-tools

name	description	argument-hint	allowed-tools
tdd-plan	TDD workflow planning with Red-Green-Refactor task chain generation, test-first development structure, and cycle tracking	[--cli-execute] "feature description"|file.md	SlashCommand(*), TodoWrite(*), Read(*), Bash(*)

TDD Workflow Plan Command (/workflow:tdd-plan)

Coordinator Role

This command is a pure orchestrator: Execute 6 slash commands in sequence, parse outputs, pass context, and ensure complete TDD workflow creation with Red-Green-Refactor task generation.

Execution Modes:

• Agent Mode (default): Use /workflow:tools:task-generate-tdd (autonomous agent-driven)
• CLI Mode (--cli-execute): Use /workflow:tools:task-generate-tdd --cli-execute (Gemini/Qwen)

Task Attachment Model:

• SlashCommand invocation expands workflow by attaching sub-tasks to current TodoWrite
• When a sub-command is invoked (e.g., /workflow:tools:test-context-gather), its internal tasks are attached to the orchestrator's TodoWrite
• Orchestrator executes these attached tasks sequentially
• After completion, attached tasks are collapsed back to high-level phase summary
• This is task expansion, not external delegation

Auto-Continue Mechanism:

• TodoList tracks current phase status and dynamically manages task attachment/collapse
• When each phase finishes executing, automatically execute next pending phase
• All phases run autonomously without user interaction
• ⚠️ CONTINUOUS EXECUTION - Do not stop until all phases complete

Core Rules

1. Start Immediately: First action is TodoWrite initialization, second action is Phase 1 execution
2. No Preliminary Analysis: Do not read files before Phase 1
3. Parse Every Output: Extract required data for next phase
4. Auto-Continue via TodoList: Check TodoList status to execute next pending phase automatically
5. Track Progress: Update TodoWrite dynamically with task attachment/collapse pattern
6. TDD Context: All descriptions include "TDD:" prefix
7. Task Attachment Model: SlashCommand invocation attaches sub-tasks to current workflow. Orchestrator executes these attached tasks itself, then collapses them after completion
8. ⚠️ CRITICAL: DO NOT STOP: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase

6-Phase Execution (with Conflict Resolution)

Phase 1: Session Discovery

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

TDD Structured Format:

TDD: [Feature Name]
GOAL: [Objective]
SCOPE: [Included/excluded]
CONTEXT: [Background]
TEST_FOCUS: [Test scenarios]

Parse: Extract sessionId

TodoWrite: Mark phase 1 completed, phase 2 in_progress

After Phase 1: Return to user showing Phase 1 results, then auto-continue to Phase 2

---

Phase 2: Context Gathering

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

Use Same Structured Description: Pass the same structured format from Phase 1

Input: sessionId from Phase 1

Parse Output:

• Extract: context-package.json path (store as contextPath)
• Typical pattern: .workflow/active/[sessionId]/.process/context-package.json

Validation:

• Context package path extracted
• File exists and is valid JSON

TodoWrite: Mark phase 2 completed, phase 3 in_progress

After Phase 2: Return to user showing Phase 2 results, then auto-continue to Phase 3

---

Phase 3: Test Coverage Analysis

Command: /workflow:tools:test-context-gather --session [sessionId]

Purpose: Analyze existing codebase for:

• Existing test patterns and conventions
• Current test coverage
• Related components and integration points
• Test framework detection

Parse: Extract testContextPath (.workflow/active/[sessionId]/.process/test-context-package.json)

Benefits:

• Makes TDD aware of existing environment
• Identifies reusable test patterns
• Prevents duplicate test creation
• Enables integration with existing tests

TodoWrite Update (Phase 3 SlashCommand invoked - tasks attached):

[
  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
  {"content": "Phase 3.1: Detect test framework and conventions (test-context-gather)", "status": "in_progress", "activeForm": "Detecting test framework"},
  {"content": "Phase 3.2: Analyze existing test coverage (test-context-gather)", "status": "pending", "activeForm": "Analyzing test coverage"},
  {"content": "Phase 3.3: Identify coverage gaps (test-context-gather)", "status": "pending", "activeForm": "Identifying coverage gaps"},
  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
]

Note: SlashCommand invocation attaches test-context-gather's 3 tasks. Orchestrator executes these tasks.

Next Action: Tasks attached → Execute Phase 3.1-3.3 sequentially

TodoWrite Update (Phase 3 completed - tasks collapsed):

[
  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
]

Note: Phase 3 tasks completed and collapsed to summary.

After Phase 3: Return to user showing test coverage results, then auto-continue to Phase 4/5 (depending on conflict_risk)

---

Phase 4: Conflict Resolution (Optional - auto-triggered by conflict risk)

Trigger: Only execute when context-package.json indicates conflict_risk is "medium" or "high"

Command: SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId] --context [contextPath]")

Input:

• sessionId from Phase 1
• contextPath from Phase 2
• conflict_risk from context-package.json

Parse Output:

• Extract: Execution status (success/skipped/failed)
• Verify: CONFLICT_RESOLUTION.md file path (if executed)

Validation:

• File .workflow/active/[sessionId]/.process/CONFLICT_RESOLUTION.md exists (if executed)

Skip Behavior:

• If conflict_risk is "none" or "low", skip directly to Phase 5
• Display: "No significant conflicts detected, proceeding to TDD task generation"

TodoWrite Update (Phase 4 SlashCommand invoked - tasks attached, if conflict_risk ≥ medium):

[
  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
  {"content": "Phase 4.1: Detect conflicts with CLI analysis (conflict-resolution)", "status": "in_progress", "activeForm": "Detecting conflicts"},
  {"content": "Phase 4.2: Present conflicts to user (conflict-resolution)", "status": "pending", "activeForm": "Presenting conflicts"},
  {"content": "Phase 4.3: Apply resolution strategies (conflict-resolution)", "status": "pending", "activeForm": "Applying resolution strategies"},
  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
]

Note: SlashCommand invocation attaches conflict-resolution's 3 tasks. Orchestrator executes these tasks.

Next Action: Tasks attached → Execute Phase 4.1-4.3 sequentially

TodoWrite Update (Phase 4 completed - tasks collapsed):

[
  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
  {"content": "Execute conflict resolution", "status": "completed", "activeForm": "Executing conflict resolution"},
  {"content": "Execute TDD task generation", "status": "pending", "activeForm": "Executing TDD task generation"},
  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
]

Note: Phase 4 tasks completed and collapsed to summary.

After Phase 4: Return to user showing conflict resolution results (if executed) and selected strategies, then auto-continue to Phase 5

Memory State Check:

• Evaluate current context window usage and memory state
• If memory usage is high (>110K tokens or approaching context limits):
  • Command: SlashCommand(command="/compact")
  • This optimizes memory before proceeding to Phase 5
• Memory compaction is particularly important after analysis phase which may generate extensive documentation
• Ensures optimal performance and prevents context overflow

---

Phase 5: TDD Task Generation

Command:

• Agent Mode (default): /workflow:tools:task-generate-tdd --session [sessionId]
• CLI Mode (--cli-execute): /workflow:tools:task-generate-tdd --session [sessionId] --cli-execute

Parse: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles)

Validate:

• IMPL_PLAN.md exists (unified plan with TDD Implementation Tasks section)
• IMPL-*.json files exist (one per feature, or container + subtasks for complex features)
• TODO_LIST.md exists with internal TDD phase indicators
• Each IMPL task includes:
  • meta.tdd_workflow: true
  • flow_control.implementation_approach with 3 steps (red/green/refactor)
  • Green phase includes test-fix-cycle configuration
• IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
• Task count ≤10 (compliance with task limit)

TodoWrite Update (Phase 5 SlashCommand invoked - tasks attached):

[
  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
  {"content": "Phase 5.1: Discovery - analyze TDD requirements (task-generate-tdd)", "status": "in_progress", "activeForm": "Analyzing TDD requirements"},
  {"content": "Phase 5.2: Planning - design Red-Green-Refactor cycles (task-generate-tdd)", "status": "pending", "activeForm": "Designing TDD cycles"},
  {"content": "Phase 5.3: Output - generate IMPL tasks with internal TDD phases (task-generate-tdd)", "status": "pending", "activeForm": "Generating TDD tasks"},
  {"content": "Validate TDD structure", "status": "pending", "activeForm": "Validating TDD structure"}
]

Note: SlashCommand invocation attaches task-generate-tdd's 3 tasks. Orchestrator executes these tasks. Each generated IMPL task will contain internal Red-Green-Refactor cycle.

Next Action: Tasks attached → Execute Phase 5.1-5.3 sequentially

TodoWrite Update (Phase 5 completed - tasks collapsed):

[
  {"content": "Execute session discovery", "status": "completed", "activeForm": "Executing session discovery"},
  {"content": "Execute context gathering", "status": "completed", "activeForm": "Executing context gathering"},
  {"content": "Execute test coverage analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
  {"content": "Execute TDD task generation", "status": "completed", "activeForm": "Executing TDD task generation"},
  {"content": "Validate TDD structure", "status": "in_progress", "activeForm": "Validating TDD structure"}
]

Note: Phase 5 tasks completed and collapsed to summary. Each generated IMPL task contains complete Red-Green-Refactor cycle internally.

Phase 6: TDD Structure Validation & Action Plan Verification (RECOMMENDED)

Internal validation first, then recommend external verification

Internal Validation:

1. Each task contains complete TDD workflow (Red-Green-Refactor internally)
2. Task structure validation:
   • meta.tdd_workflow: true in all IMPL tasks
   • flow_control.implementation_approach has exactly 3 steps
   • Each step has correct tdd_phase: "red", "green", "refactor"
3. Dependency validation:
   • Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
   • Complex features: IMPL-N.M depends_on ["IMPL-N.(M-1)"] for subtasks
4. Agent assignment: All IMPL tasks use @code-developer
5. Test-fix cycle: Green phase step includes test-fix-cycle logic with max_iterations
6. Task count: Total tasks ≤10 (simple + subtasks)

Return Summary:

TDD Planning complete for session: [sessionId]

Features analyzed: [N]
Total tasks: [M] (1 task per simple feature + subtasks for complex features)

Task breakdown:
- Simple features: [K] tasks (IMPL-1 to IMPL-K)
- Complex features: [L] features with [P] subtasks
- Total task count: [M] (within 10-task limit)

Structure:
- IMPL-1: {Feature 1 Name} (Internal: Red → Green → Refactor)
- IMPL-2: {Feature 2 Name} (Internal: Red → Green → Refactor)
- IMPL-3: {Complex Feature} (Container)
  - IMPL-3.1: {Sub-feature A} (Internal: Red → Green → Refactor)
  - IMPL-3.2: {Sub-feature B} (Internal: Red → Green → Refactor)
[...]

Plans generated:
- Unified Implementation Plan: .workflow/active/[sessionId]/IMPL_PLAN.md
  (includes TDD Implementation Tasks section with workflow_type: "tdd")
- Task List: .workflow/active/[sessionId]/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

Recommended Next Steps:
1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality and dependencies
2. /workflow:execute --session [sessionId]  # Start TDD execution
3. /workflow:tdd-verify [sessionId]  # Post-execution TDD compliance check

Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies

TodoWrite Pattern

Core Concept: Dynamic task attachment and collapse for TDD workflow with test coverage analysis and Red-Green-Refactor cycle generation.

Key Principles

1. Task Attachment (when SlashCommand invoked):

   • Sub-command's internal tasks are attached to orchestrator's TodoWrite
   • Example: /workflow:tools:test-context-gather attaches 3 sub-tasks (Phase 3.1, 3.2, 3.3)
   • First attached task marked as in_progress, others as pending
   • Orchestrator executes these attached tasks sequentially

2. Task Collapse (after sub-tasks complete):

   • Remove detailed sub-tasks from TodoWrite
   • Collapse to high-level phase summary
   • Example: Phase 3.1-3.3 collapse to "Execute test coverage analysis: completed"
   • Maintains clean orchestrator-level view

3. Continuous Execution:

   • After collapse, automatically proceed to next pending phase
   • No user intervention required between phases
   • TodoWrite dynamically reflects current execution state

Lifecycle Summary: Initial pending tasks → Phase invoked (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED to summary) → Next phase begins (conditional Phase 4 if conflict_risk ≥ medium) → Repeat until all phases complete.

TDD-Specific Features

• Phase 3: Test coverage analysis detects existing patterns and gaps
• Phase 5: Generated IMPL tasks contain internal Red-Green-Refactor cycles
• Conditional Phase 4: Conflict resolution only if conflict_risk ≥ medium

Benefits

• ✓ Real-time visibility into TDD workflow execution
• ✓ Clear mental model: SlashCommand = attach → execute → collapse
• ✓ Test-aware planning with coverage analysis
• ✓ Self-contained TDD cycles within each IMPL task

Note: See individual Phase descriptions (Phase 3, 4, 5) for detailed TodoWrite Update examples with full JSON structures.

Execution Flow Diagram

TDD Workflow Orchestrator
│
├─ Phase 1: Session Discovery
│  └─ /workflow:session:start --auto
│     └─ Returns: sessionId
│
├─ Phase 2: Context Gathering
│  └─ /workflow:tools:context-gather
│     └─ Returns: context-package.json path
│
├─ Phase 3: Test Coverage Analysis                    ← ATTACHED (3 tasks)
│  └─ /workflow:tools:test-context-gather
│     ├─ Phase 3.1: Detect test framework
│     ├─ Phase 3.2: Analyze existing test coverage
│     └─ Phase 3.3: Identify coverage gaps
│     └─ Returns: test-context-package.json           ← COLLAPSED
│
├─ Phase 4: Conflict Resolution (conditional)
│  IF conflict_risk ≥ medium:
│  └─ /workflow:tools:conflict-resolution             ← ATTACHED (3 tasks)
│     ├─ Phase 4.1: Detect conflicts with CLI
│     ├─ Phase 4.2: Present conflicts to user
│     └─ Phase 4.3: Apply resolution strategies
│     └─ Returns: CONFLICT_RESOLUTION.md              ← COLLAPSED
│  ELSE:
│  └─ Skip to Phase 5
│
├─ Phase 5: TDD Task Generation                       ← ATTACHED (3 tasks)
│  └─ /workflow:tools:task-generate-tdd
│     ├─ Phase 5.1: Discovery - analyze TDD requirements
│     ├─ Phase 5.2: Planning - design Red-Green-Refactor cycles
│     └─ Phase 5.3: Output - generate IMPL tasks with internal TDD phases
│     └─ Returns: IMPL-*.json, IMPL_PLAN.md           ← COLLAPSED
│        (Each IMPL task contains internal Red-Green-Refactor cycle)
│
└─ Phase 6: TDD Structure Validation
   └─ Internal validation + summary returned
   └─ Recommend: /workflow:action-plan-verify

Key Points:
• ← ATTACHED: SlashCommand attaches sub-tasks to orchestrator TodoWrite
• ← COLLAPSED: Sub-tasks executed and collapsed to phase summary
• TDD-specific: Each generated IMPL task contains complete Red-Green-Refactor cycle

Input Processing

Convert user input to TDD-structured format:

Simple text → Add TDD context Detailed text → Extract components with TEST_FOCUS File/Issue → Read and structure with TDD

Error Handling

• Parsing failure: Retry once, then report
• Validation failure: Report missing/invalid data
• Command failure: Keep phase in_progress, report error
• TDD validation failure: Report incomplete chains or wrong dependencies

TDD Workflow Enhancements

Overview

The TDD workflow has been significantly enhanced by integrating best practices from both traditional plan --agent and test-gen workflows, creating a hybrid approach that bridges the gap between idealized TDD and real-world development complexity.

Key Improvements

1. Test Coverage Analysis (Phase 3)

Adopted from test-gen workflow

Before planning TDD tasks, the workflow now analyzes the existing codebase:

• Detects existing test patterns and conventions
• Identifies current test coverage
• Discovers related components and integration points
• Detects test framework automatically

Benefits:

• Context-aware TDD planning
• Avoids duplicate test creation
• Enables integration with existing tests
• No longer assumes greenfield scenarios

2. Iterative Green Phase with Test-Fix Cycle

Adopted from test-gen workflow

IMPL (Green phase) tasks now include automatic test-fix cycle for resilient implementation:

Enhanced IMPL Task Flow:

1. Write minimal implementation code
2. Execute test suite
3. IF tests pass → Complete task
4. IF tests fail → Enter fix cycle:
   a. Gemini diagnoses with bug-fix template
   b. Apply fix (manual or Codex)
   c. Retest
   d. Repeat (max 3 iterations)
5. IF max iterations → Auto-revert changes 🔄

Benefits:

• Faster feedback within Green phase
• Autonomous recovery from implementation errors
• Systematic debugging with Gemini
• Safe rollback prevents broken state

3. Agent-Driven Planning

From plan --agent workflow

Supports action-planning-agent for more autonomous TDD planning with:

• MCP tool integration (code-index, exa)
• Memory-first principles
• Brainstorming artifact integration
• Task merging over decomposition

Workflow Comparison

Aspect	Previous	Current (Optimized)
Phases	6 (with test coverage)	7 (added concept verification)
Context	Greenfield assumption	Existing codebase aware
Task Structure	1 feature = 3 tasks (TEST/IMPL/REFACTOR)	1 feature = 1 task (internal TDD cycle)
Task Count	5 features = 15 tasks	5 features = 5 tasks (70% reduction)
Green Phase	Single implementation	Iterative with fix cycle
Failure Handling	Manual intervention	Auto-diagnose + fix + revert
Test Analysis	None	Deep coverage analysis
Feedback Loop	Post-execution	During Green phase
Task Management	High overhead (15 tasks)	Low overhead (5 tasks)
Execution Efficiency	Frequent context switching	Continuous context per feature

Migration Notes

Backward Compatibility: Fully compatible

• Existing TDD workflows continue to work
• New features are additive, not breaking
• Phase 3 can be skipped if test-context-gather not available

Session Structure:

.workflow/active/WFS-xxx/
├── IMPL_PLAN.md (unified plan with TDD Implementation Tasks section)
├── TODO_LIST.md (with internal TDD phase indicators)
├── .process/
│   ├── context-package.json
│   ├── test-context-package.json
│   ├── ANALYSIS_RESULTS.md (enhanced with TDD breakdown)
│   └── green-fix-iteration-*.md (fix logs from Green phase cycles)
└── .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)

File Count Comparison:

• Old structure: 5 features = 15 task files (TEST/IMPL/REFACTOR × 5)
• New structure: 5 features = 5 task files (IMPL-N × 5)
• Complex features: Add container + subtasks only when necessary

Configuration Options (in IMPL tasks):

• meta.max_iterations: Fix attempts (default: 3)
• meta.use_codex: Auto-fix mode (default: false)

Related Commands

Prerequisite Commands:

• None - TDD planning is self-contained (can optionally run brainstorm commands before)

Called by This Command (6 phases):

• /workflow:session:start - Phase 1: Create or discover TDD workflow session
• /workflow:tools:context-gather - Phase 2: Gather project context and analyze codebase
• /workflow:tools:test-context-gather - Phase 3: Analyze existing test patterns and coverage
• /workflow:tools:conflict-resolution - Phase 4: Detect and resolve conflicts (auto-triggered if conflict_risk ≥ medium)
• /compact - Phase 4: Memory optimization (if context approaching limits)
• /workflow:tools:task-generate-tdd - Phase 5: Generate TDD tasks with agent-driven approach (default, autonomous)
• /workflow:tools:task-generate-tdd --cli-execute - Phase 5: Generate TDD tasks with CLI tools (Gemini/Qwen, when --cli-execute flag used)

Follow-up Commands:

• /workflow:action-plan-verify - Recommended: Verify TDD plan quality and structure before execution
• /workflow:status - Review TDD task breakdown
• /workflow:execute - Begin TDD implementation
• /workflow:tdd-verify - Post-execution: Verify TDD compliance and generate quality report