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.

```javascript
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**:
```javascript
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**:
```javascript
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 `workflowPreferences.autoYes` is true, 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)
   ```javascript
   if (!memory.has("workflow-session.json")) {
     Read(`.workflow/active/${sessionId}/workflow-session.json`)
   }
   ```

2. **Load Context Package** (if not in memory)
   ```javascript
   if (!memory.has("context-package.json")) {
     Read(`.workflow/active/${sessionId}/.process/context-package.json`)
   }
   ```

3. **Load Test Context Package** (if not in memory)
   ```javascript
   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)
   ```javascript
   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)
   ```javascript
   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)
   ```bash
   find . -name "*test*" -type f
   rg "describe|it\(|test\(" -g "*.ts"
   ```

7. **MCP External Research** (optional)
   ```javascript
   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)

```javascript
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)

```json
[
  {"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)

```json
[
  {"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:
  ```javascript
  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](06-tdd-structure-validation.md).