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, test-first structure, and cycle validation	--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
• Quantification-Enforced: All test cases, coverage requirements, and implementation scope MUST include explicit counts and enumerations (e.g., "15 test cases: [test1, test2, ...]" not "comprehensive tests")

Quantification Requirements for TDD (MANDATORY)

Purpose: Eliminate ambiguity by enforcing explicit test case counts, coverage metrics, and implementation scope.

Core Rules:

1. Explicit Test Case Counts: Red phase specifies exact number with enumerated list
2. Quantified Coverage: Acceptance includes measurable percentage (e.g., ">=85%")
3. Detailed Implementation Scope: Green phase enumerates files, functions, line counts
4. Enumerated Refactoring Targets: Refactor phase lists specific improvements with counts

TDD Phase Formats:

• Red Phase: "Write N test cases: [test1, test2, ...]"
• Green Phase: "Implement N functions in file lines X-Y: [func1() X1-Y1, func2() X2-Y2, ...]"
• Refactor Phase: "Apply N refactorings: [improvement1 (details), improvement2 (details), ...]"
• Acceptance: "All N tests pass with >=X% coverage: verify by [test command]"

TDD Cycles Array: Each cycle must include test_count, test_cases array, implementation_scope, and expected_coverage

Validation Checklist:

• Every Red phase specifies exact test case count with enumerated list
• Every Green phase enumerates files, functions, and estimated line counts
• Every Refactor phase lists specific improvements with counts
• Every acceptance criterion includes measurable coverage percentage
• tdd_cycles array contains test_count and test_cases for each cycle
• No vague language ("comprehensive", "complete", "thorough")

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

Each TDD task JSON contains complete Red-Green-Refactor cycle with these key fields:

Top-Level Fields:

• id: Task identifier (IMPL-N or IMPL-N.M for subtasks)
• title: Feature description with TDD
• status: pending | in_progress | completed | container
• context_package_path: Path to context package
• meta: TDD-specific metadata
• context: Requirements, cycles, paths, acceptance
• flow_control: Pre-analysis, 3 TDD phases, post-completion, error handling

Meta Object (TDD-Specific):

• type: "feature"
• agent: "@code-developer"
• tdd_workflow: true (REQUIRED - enables TDD flow)
• max_iterations: Green phase test-fix cycle limit (default: 3)
• use_codex: false (manual fixes) or true (Codex automated fixes)

Context Object:

• requirements: Quantified feature requirements with TDD phase details
• tdd_cycles: Array of test cycles (each with test_count, test_cases, implementation_scope, expected_coverage)
• focus_paths: Target directories (absolute or relative from project root)
• acceptance: Measurable success criteria with verification commands
• depends_on: Task dependencies
• parent: Parent task ID (for subtasks only)

Flow Control Object:

• pre_analysis: Optional pre-execution checks
• implementation_approach: Exactly 3 steps with tdd_phase field:
  1. Red Phase (tdd_phase: "red"): Write failing tests
  2. Green Phase (tdd_phase: "green"): Implement to pass tests (includes test-fix cycle)
  3. Refactor Phase (tdd_phase: "refactor"): Improve code quality
• post_completion: Optional final verification
• error_handling: Error recovery strategies (e.g., auto-revert on max iterations)

Implementation Approach Step Structure: Each step includes:

• step: Step number
• title: Phase description
• tdd_phase: Phase identifier ("red" | "green" | "refactor")
• description: Detailed phase description
• modification_points: Quantified changes to make
• logic_flow: Step-by-step execution logic
• acceptance: Phase-specific acceptance criteria
• command: Test/verification command (optional)
• depends_on: Previous step dependencies
• output: Step output identifier

IMPL_PLAN.md Structure

Frontmatter (TDD-specific fields):

• workflow_type: "tdd"
• tdd_workflow: true
• feature_count, task_count (≤10 total)
• task_breakdown: simple_features, complex_features, total_subtasks
• test_context: Path to test-context-package.json (if exists)
• conflict_resolution: Path to CONFLICT_RESOLUTION.md (if exists)
• verification_history, phase_progression

8 Sections:

1. Summary: Core requirements, TDD-specific approach
2. Context Analysis: CCW workflow context, project profile, module structure, dependencies
3. Brainstorming Artifacts Reference: Artifact usage strategy, priority order
4. Implementation Strategy: TDD cycles (Red-Green-Refactor), architectural approach, testing strategy
5. TDD Implementation Tasks: Feature-by-feature tasks with internal TDD cycles, dependencies
6. Implementation Plan: Phased breakdown, resource requirements
7. Risk Assessment & Mitigation: Risk table, TDD-specific risks, monitoring
8. Success Criteria: Functional completeness, technical quality (≥80% coverage), TDD compliance

Phase 4: TODO_LIST.md Generation

Generate task list with internal TDD phase indicators:

Structure:

• Simple features: - [ ] **IMPL-N**: Feature with TDD (Internal phases: Red → Green → Refactor)
• Complex features: ▸ **IMPL-N**: Container with subtasks - [ ] **IMPL-N.M**: Sub-feature

Status Legend:

• ▸ = Container task (has subtasks)
• [ ] = Pending | [x] = Completed
• Red → Green → Refactor = TDD phases

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

Output:

• Task JSON files in .task/ directory (IMPL-N.json format)
• IMPL_PLAN.md with TDD Implementation Tasks section
• TODO_LIST.md with internal TDD phase indicators
• Session state updated with task count and TDD metadata

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