Claude-Code-Workflow/.claude/skills/workflow-tdd/phases/05-tdd-task-generation.md

Phase 5: TDD Task Generation

Generate TDD tasks with Red-Green-Refactor cycles via action-planning-agent.

Objective

• Generate IMPL_PLAN.md, task JSONs, and TODO_LIST.md with TDD structure
• Each task contains internal Red-Green-Refactor cycle
• Include Phase 0 user configuration (execution method, CLI tool preference)

Core Philosophy

• Agent-Driven: Delegate execution to action-planning-agent for autonomous operation
• Two-Phase Flow: Discovery (context gathering) -> Output (document generation)
• Memory-First: Reuse loaded documents from conversation memory
• MCP-Enhanced: Use MCP tools for advanced code analysis and research
• Semantic CLI Selection: CLI tool usage determined from user's task description, not flags
• Path Clarity: All focus_paths prefer absolute paths or clear relative paths from project root
• TDD-First: Every feature starts with a failing test (Red phase)
• Feature-Complete Tasks: Each task contains complete Red-Green-Refactor cycle
• Quantification-Enforced: All test cases, coverage requirements, and implementation scope MUST include explicit counts and enumerations

Task Strategy

Optimized Task Structure

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

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 18 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 >18 tasks needed, break project into multiple TDD workflow sessions

Execution

Phase 0: User Configuration (Interactive)

Purpose: Collect user preferences before TDD task generation.

AskUserQuestion({
  questions: [
    {
      question: "Do you have supplementary materials or guidelines to include?",
      header: "Materials",
      multiSelect: false,
      options: [
        { label: "No additional materials", description: "Use existing context only" },
        { label: "Provide file paths", description: "I'll specify paths to include" },
        { label: "Provide inline content", description: "I'll paste content directly" }
      ]
    },
    {
      question: "Select execution method for generated TDD tasks:",
      header: "Execution",
      multiSelect: false,
      options: [
        { label: "Agent (Recommended)", description: "Claude agent executes Red-Green-Refactor cycles directly" },
        { label: "Hybrid", description: "Agent orchestrates, calls CLI for complex steps (Red/Green phases)" },
        { label: "CLI Only", description: "All TDD cycles via CLI tools (codex/gemini/qwen)" }
      ]
    },
    {
      question: "If using CLI, which tool do you prefer?",
      header: "CLI Tool",
      multiSelect: false,
      options: [
        { label: "Codex (Recommended)", description: "Best for TDD Red-Green-Refactor cycles" },
        { label: "Gemini", description: "Best for analysis and large context" },
        { label: "Qwen", description: "Alternative analysis tool" },
        { label: "Auto", description: "Let agent decide per-task" }
      ]
    }
  ]
})

Handle Materials Response:

if (userConfig.materials === "Provide file paths") {
  const pathsResponse = AskUserQuestion({
    questions: [{
      question: "Enter file paths to include (comma-separated or one per line):",
      header: "Paths",
      multiSelect: false,
      options: [
        { label: "Enter paths", description: "Provide paths in text input" }
      ]
    }]
  })
  userConfig.supplementaryPaths = parseUserPaths(pathsResponse)
}

Build userConfig:

const userConfig = {
  supplementaryMaterials: {
    type: "none|paths|inline",
    content: [...],
  },
  executionMethod: "agent|hybrid|cli",
  preferredCliTool: "codex|gemini|qwen|auto",
  enableResume: true  // Always enable resume for CLI executions
}

Auto Mode: When --yes or -y: Skip user questions, use defaults (no materials, Agent executor).

---

Phase 1: Context Preparation & Discovery

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

Progressive Loading Strategy: Load context incrementally:

• Core: session metadata + context-package.json (always load)
• Selective: synthesis_output OR (guidance + relevant role analyses) - NOT all role analyses
• On-Demand: conflict resolution (if conflict_risk >= medium), test context

Session Path Structure (provided to agent):

.workflow/active/WFS-{session-id}/
├── workflow-session.json          # Session metadata
├── .process/
│   ├── context-package.json       # Context package with artifact catalog
│   ├── test-context-package.json  # Test coverage analysis
│   └── conflict-resolution.json   # Conflict resolution (if exists)
├── .task/                         # Output: Task JSON files
│   ├── IMPL-1.json
│   ├── IMPL-2.json
│   └── ...
├── plan.json                      # Output: Structured plan overview (TDD variant)
├── IMPL_PLAN.md                   # Output: TDD implementation plan
└── TODO_LIST.md                   # Output: TODO list with TDD phases

Discovery Actions:

1. Load Session Context (if not in memory)

   if (!memory.has("workflow-session.json")) {
     Read(`.workflow/active/${sessionId}/workflow-session.json`)
   }
   

2. Load Context Package (if not in memory)

   if (!memory.has("context-package.json")) {
     Read(`.workflow/active/${sessionId}/.process/context-package.json`)
   }
   

3. Load Test Context Package (if not in memory)

   if (!memory.has("test-context-package.json")) {
     Read(`.workflow/active/${sessionId}/.process/test-context-package.json`)
   }
   

4. Extract & Load Role Analyses (from context-package.json)

   const roleAnalysisPaths = contextPackage.brainstorm_artifacts.role_analyses
     .flatMap(role => role.files.map(f => f.path));
   roleAnalysisPaths.forEach(path => Read(path));
   

5. Load Conflict Resolution (if exists)

   if (contextPackage.conflict_detection?.resolution_file) {
     Read(contextPackage.conflict_detection.resolution_file)
   } else if (contextPackage.brainstorm_artifacts?.conflict_resolution?.exists) {
     Read(contextPackage.brainstorm_artifacts.conflict_resolution.path)
   }
   

6. Code Analysis with Native Tools (optional)

   find . -name "*test*" -type f
   rg "describe|it\(|test\(" -g "*.ts"
   

7. MCP External Research (optional)

   mcp__exa__get_code_context_exa(
     query="TypeScript TDD best practices Red-Green-Refactor",
     tokensNum="dynamic"
   )
   

---

Step 5.1: Execute TDD Task Generation (Agent Invocation)

Task(
  subagent_type="action-planning-agent",
  run_in_background=false,
  description="Generate TDD planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
  prompt=`
## TASK OBJECTIVE
Generate TDD implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session

IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT implementing code.

CRITICAL: Follow the progressive loading strategy (load analysis.md files incrementally due to file size):
- **Core**: session metadata + context-package.json (always)
- **Selective**: synthesis_output OR (guidance + relevant role analyses) - NOT all
- **On-Demand**: conflict resolution (if conflict_risk >= medium), test context

## SESSION PATHS
Input:
  - Session Metadata: .workflow/active/${sessionId}/workflow-session.json
  - Context Package: .workflow/active/${sessionId}/.process/context-package.json
  - Test Context: .workflow/active/${sessionId}/.process/test-context-package.json

Output:
  - Task Dir: .workflow/active/${sessionId}/.task/
  - IMPL_PLAN: .workflow/active/${sessionId}/IMPL_PLAN.md
  - TODO_LIST: .workflow/active/${sessionId}/TODO_LIST.md

## CONTEXT METADATA
Session ID: ${sessionId}
Workflow Type: TDD
MCP Capabilities: {exa_code, exa_web, code_index}

## USER CONFIGURATION (from Phase 0)
Execution Method: ${userConfig.executionMethod}
Preferred CLI Tool: ${userConfig.preferredCliTool}
Supplementary Materials: ${userConfig.supplementaryMaterials}

## EXECUTION METHOD MAPPING
Based on userConfig.executionMethod, set task-level meta.execution_config:

"agent" ->
  meta.execution_config = { method: "agent", cli_tool: null, enable_resume: false }
  Agent executes Red-Green-Refactor phases directly

"cli" ->
  meta.execution_config = { method: "cli", cli_tool: userConfig.preferredCliTool, enable_resume: true }
  Agent executes pre_analysis, then hands off full context to CLI via buildCliHandoffPrompt()

"hybrid" ->
  Per-task decision: Analyze TDD cycle complexity, set method to "agent" OR "cli" per task
  - Simple cycles (<=5 test cases, <=3 files) -> method: "agent"
  - Complex cycles (>5 test cases, >3 files, integration tests) -> method: "cli"
  CLI tool: userConfig.preferredCliTool, enable_resume: true

IMPORTANT: Do NOT add command field to implementation steps. Execution routing is controlled by task-level meta.execution_config.method only.

## EXPLORATION CONTEXT (from context-package.exploration_results)
- Load exploration_results from context-package.json
- Use aggregated_insights.critical_files for focus_paths generation
- Apply aggregated_insights.constraints to acceptance criteria
- Reference aggregated_insights.all_patterns for implementation approach
- Use aggregated_insights.all_integration_points for precise modification locations
- Use conflict_indicators for risk-aware task sequencing

## CONFLICT RESOLUTION CONTEXT (if exists)
- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path
- If exists, load .process/conflict-resolution.json:
  - Apply planning_constraints as task constraints (for brainstorm-less workflows)
  - Reference resolved_conflicts for implementation approach alignment
  - Handle custom_conflicts with explicit task notes

## TEST CONTEXT INTEGRATION
- Load test-context-package.json for existing test patterns and coverage analysis
- Extract test framework configuration (Jest/Pytest/etc.)
- Identify existing test conventions and patterns
- Map coverage gaps to TDD Red phase test targets

## TDD DOCUMENT GENERATION TASK

### TDD-Specific Requirements Summary

#### Task Structure Philosophy
- **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)
- Subtasks only when complexity >2500 lines or >6 files per cycle
- **Maximum 18 tasks** (hard limit for TDD workflows)

#### TDD Cycle Mapping
- **Simple features**: IMPL-N with internal Red-Green-Refactor phases
- **Complex features**: IMPL-N (container) + IMPL-N.M (subtasks)
- Each cycle includes: test_count, test_cases array, implementation_scope, expected_coverage

#### Required Outputs Summary

##### 1. TDD Task JSON Files (.task/IMPL-*.json)
- **Location**: .workflow/active/${sessionId}/.task/
- **Schema**: Unified flat schema (task-schema.json) with TDD-specific metadata
  - meta.tdd_workflow: true (REQUIRED)
  - meta.max_iterations: 3 (Green phase test-fix cycle limit)
  - cli_execution.id: Unique CLI execution ID (format: {session_id}-{task_id})
  - cli_execution: Strategy object (new|resume|fork|merge_fork)
  - tdd_cycles: Array with quantified test cases and coverage
  - focus_paths: Absolute or clear relative paths (enhanced with exploration critical_files)
  - implementation: 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
    3. Refactor Phase (tdd_phase: "refactor"): Improve code quality
  - pre_analysis: Include exploration integration_points analysis
  - meta.execution_config: Set per userConfig.executionMethod (agent/cli/hybrid)

##### 2. IMPL_PLAN.md (TDD Variant)
- **Location**: .workflow/active/${sessionId}/IMPL_PLAN.md
- **Template**: ~/.ccw/workflows/cli-templates/prompts/workflow/impl-plan-template.txt
- **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown

##### 3. TODO_LIST.md
- **Location**: .workflow/active/${sessionId}/TODO_LIST.md
- **Format**: Hierarchical task list with internal TDD phase indicators (Red -> Green -> Refactor)

### CLI EXECUTION ID REQUIREMENTS (MANDATORY)

Each task JSON MUST include:
- **cli_execution.id**: Unique ID for CLI execution (format: {session_id}-{task_id})
- **cli_execution**: Strategy object based on depends_on:
  - No deps -> { "strategy": "new" }
  - 1 dep (single child) -> { "strategy": "resume", "resume_from": "parent-cli-id" }
  - 1 dep (multiple children) -> { "strategy": "fork", "resume_from": "parent-cli-id" }
  - N deps -> { "strategy": "merge_fork", "resume_from": ["id1", "id2", ...] }

### Quantification Requirements (MANDATORY)

**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]"

## SUCCESS CRITERIA
- All planning documents generated successfully:
  - Task JSONs valid and saved to .task/ directory with cli_execution.id
  - IMPL_PLAN.md created with complete TDD structure
  - TODO_LIST.md generated matching task JSONs
- CLI execution strategies assigned based on task dependencies
- Return completion status with document count and task breakdown summary
`
)

Note: Phase 0 now includes:

• Supplementary materials collection (file paths or inline content)
• Execution method preference (Agent/Hybrid/CLI)
• CLI tool preference (Codex/Gemini/Qwen/Auto)
• These preferences are passed to agent for task generation

CLI Tool Selection: CLI tool usage is determined semantically from user's task description. Include "use Codex/Gemini/Qwen" in your request for CLI execution.

Step 5.2: Parse Output

Extract: feature count, task count, CLI execution IDs assigned

Step 5.3: Validate Outputs

• plan.json exists (structured plan overview with _metadata.plan_type: "tdd")
• 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
  • cli_execution.id: {session_id}-{task_id}
  • cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }
  • implementation with exactly 3 steps (red/green/refactor)
  • Green phase includes test-fix-cycle configuration
  • focus_paths: absolute or clear relative paths (enhanced with exploration critical_files)
  • pre_analysis: includes exploration integration_points analysis
• IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
• User configuration applied:
  • If executionMethod == "cli" or "hybrid": command field added to steps
  • CLI tool preference reflected in execution guidance
• Task count <=18 (compliance with hard limit)

Red Flag Detection (Non-Blocking Warnings)

• Task count >18: WARNING: Task count exceeds hard limit - request re-scope
• Missing cli_execution.id: WARNING: Task lacks CLI execution ID for resume support
• Missing test-fix-cycle: WARNING: Green phase lacks auto-revert configuration
• Generic task names: WARNING: Vague task names suggest unclear TDD cycles
• Missing focus_paths: WARNING: Task lacks clear file scope for implementation

Action: Log warnings to .workflow/active/[sessionId]/.process/tdd-warnings.log (non-blocking)

TodoWrite Update (Phase 5 Skill executed - tasks attached)

[
  {"content": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
  {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
  {"content": "Phase 5: TDD Task Generation", "status": "in_progress", "activeForm": "Executing TDD task generation"},
  {"content": "  -> Discovery - analyze TDD requirements", "status": "in_progress", "activeForm": "Analyzing TDD requirements"},
  {"content": "  -> Planning - design Red-Green-Refactor cycles", "status": "pending", "activeForm": "Designing TDD cycles"},
  {"content": "  -> Output - generate IMPL tasks with internal TDD phases", "status": "pending", "activeForm": "Generating TDD tasks"},
  {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
]

Note: Agent execution 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": "Phase 1: Session Discovery", "status": "completed", "activeForm": "Executing session discovery"},
  {"content": "Phase 2: Context Gathering", "status": "completed", "activeForm": "Executing context gathering"},
  {"content": "Phase 3: Test Coverage Analysis", "status": "completed", "activeForm": "Executing test coverage analysis"},
  {"content": "Phase 5: TDD Task Generation", "status": "completed", "activeForm": "Executing TDD task generation"},
  {"content": "Phase 6: TDD Structure Validation", "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.

TDD Task Structure Reference

Quick Reference:

• Each TDD task contains complete Red-Green-Refactor cycle
• Task ID format: IMPL-N (simple) or IMPL-N.M (complex subtasks)
• Required metadata:
  • meta.tdd_workflow: true
  • meta.max_iterations: 3
  • cli_execution.id: "{session_id}-{task_id}"
  • cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }
• tdd_cycles array with quantified test cases and coverage:

  tdd_cycles: [
    {
      test_count: 5,
      test_cases: ["case1", "case2"],
      implementation_scope: "...",
      expected_coverage: ">=85%"
    }
  ]
  

• focus_paths use absolute or clear relative paths
• implementation: Exactly 3 steps with tdd_phase field ("red", "green", "refactor")
• pre_analysis: includes exploration integration_points analysis
• meta.execution_config: Set per userConfig.executionMethod (agent/cli/hybrid)

Output Files Structure

.workflow/active/{session-id}/
├── plan.json                        # Structured plan overview (TDD variant)
├── 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.json     # Conflict resolution results (if conflict_risk >= medium)
    ├── test-context-package.json    # Test coverage analysis
    ├── context-package.json         # Input from context-gather
    └── tdd-warnings.log             # Non-blocking warnings

Validation Rules

Task Completeness

• Every IMPL-N must contain complete TDD workflow in implementation
• 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 18 total tasks (simple + subtasks) - hard limit for TDD workflows
• Flat hierarchy (<=5 tasks) or two-level (6-18 tasks with containers)
• Re-scope requirements if >18 tasks needed

Output

• File: plan.json (structured plan overview)
• File: IMPL_PLAN.md (unified plan with TDD Implementation Tasks section)
• File: IMPL-*.json (task JSONs with internal TDD cycles)
• File: TODO_LIST.md (task list with TDD phase indicators)
• File: .process/tdd-warnings.log (non-blocking warnings)
• TodoWrite: Mark Phase 5 completed, Phase 6 in_progress

Next Phase

Return to orchestrator, then auto-continue to Phase 6: TDD Structure Validation.