Claude-Code-Workflow/.claude/skills/workflow-tdd/SKILL.md

name, description, allowed-tools

name	description	allowed-tools
workflow-tdd	Unified TDD workflow skill combining 6-phase TDD planning with Red-Green-Refactor task chain generation, and 4-phase TDD verification with compliance reporting. Triggers on "workflow:tdd-plan", "workflow:tdd-verify".	Skill, Task, AskUserQuestion, TaskCreate, TaskUpdate, TaskList, Read, Write, Edit, Bash, Glob, Grep

Workflow TDD

Unified TDD workflow skill combining TDD planning (Red-Green-Refactor task chain generation with test-first development structure) and TDD verification (compliance validation with quality gate reporting). Produces IMPL_PLAN.md, task JSONs with internal TDD cycles, and TDD_COMPLIANCE_REPORT.md.

Architecture Overview

┌──────────────────────────────────────────────────────────────────┐
│  Workflow TDD Orchestrator (SKILL.md)                            │
│  → Route by mode: plan | verify                                  │
│  → Pure coordinator: Execute phases, parse outputs, pass context │
└──────────────────────────────┬───────────────────────────────────┘
                                │
        ┌───────────────────────┴───────────────────────┐
        ↓                                               ↓
  ┌─────────────┐                                ┌───────────┐
  │  Plan Mode  │                                │  Verify   │
  │  (default)  │                                │   Mode    │
  │ Phase 1-6   │                                │  Phase 7  │
  └──────┬──────┘                                └───────────┘
         │
   ┌─────┼─────┬─────┬─────┬─────┐
   ↓     ↓     ↓     ↓     ↓     ↓
 ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐ ┌───┐
 │ 1 │ │ 2 │ │ 3 │ │ 4 │ │ 5 │ │ 6 │
 │Ses│ │Ctx│ │Tst│ │Con│ │Gen│ │Val│
 └───┘ └───┘ └───┘ └───┘ └─┬─┘ └───┘
                             ↓
                       ┌───────────┐
                       │ Confirm   │─── Verify ──→ Phase 7
                       │ (choice)  │─── Execute ─→ Skill("workflow-execute")
                       └───────────┘─── Review ──→ /workflow:status

Key Design Principles

1. Pure Orchestrator: SKILL.md routes and coordinates only; execution detail lives in phase files
2. Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute
3. Multi-Mode Routing: Single skill handles plan/verify via mode detection
4. Task Attachment Model: Sub-command tasks are ATTACHED, executed sequentially, then COLLAPSED
5. Auto-Continue: After each phase completes, automatically execute next pending phase
6. TDD Iron Law: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST - enforced in task structure

Auto Mode

When --yes or -y: Auto-continue all phases (skip confirmations), use recommended conflict resolutions, auto-select "Verify Plan Quality" after plan completion.

Mode Detection

const args = $ARGUMENTS
const mode = detectMode(args)

function detectMode(args) {
  // Skill trigger determines mode
  if (skillName === 'workflow:tdd-verify') return 'verify'
  return 'plan'  // default: workflow:tdd-plan
}

Execution Flow

Plan Mode (default)

Input Parsing:
   └─ Convert user input to TDD structured format (GOAL/SCOPE/CONTEXT/TEST_FOCUS)

Phase 1: Session Discovery
   └─ Ref: phases/01-session-discovery.md
      └─ Output: sessionId (WFS-xxx)

Phase 2: Context Gathering
   └─ Ref: phases/02-context-gathering.md
      ├─ Tasks attached: Analyze structure → Identify integration → Generate package
      └─ Output: contextPath + conflictRisk

Phase 3: Test Coverage Analysis
   └─ Ref: phases/03-test-coverage-analysis.md
      ├─ Tasks attached: Detect framework → Analyze coverage → Identify gaps
      └─ Output: testContextPath

Phase 4: Conflict Resolution (conditional: conflictRisk ≥ medium)
   └─ Decision (conflictRisk check):
      ├─ conflictRisk ≥ medium → Ref: phases/04-conflict-resolution.md
      │   ├─ Tasks attached: Detect conflicts → Log analysis → Apply strategies
      │   └─ Output: conflict-resolution.json
      └─ conflictRisk < medium → Skip to Phase 5

Phase 5: TDD Task Generation
   └─ Ref: phases/05-tdd-task-generation.md
      ├─ Tasks attached: Discovery → Planning → Output
      └─ Output: IMPL_PLAN.md, IMPL-*.json, TODO_LIST.md

Phase 6: TDD Structure Validation
   └─ Ref: phases/06-tdd-structure-validation.md
      └─ Output: Validation report + Plan Confirmation Gate

Plan Confirmation (User Decision Gate):
   └─ Decision (user choice):
      ├─ "Verify TDD Compliance" (Recommended) → Route to Phase 7 (tdd-verify)
      ├─ "Start Execution" → Skill(skill="workflow-execute")
      └─ "Review Status Only" → Route to /workflow:status

Verify Mode

Phase 7: TDD Verification
   └─ Ref: phases/07-tdd-verify.md
      └─ Output: TDD_COMPLIANCE_REPORT.md with quality gate recommendation

Phase Reference Documents (read on-demand when phase executes):

Phase	Document	Purpose	Mode
1	phases/01-session-discovery.md	Create or discover TDD workflow session	plan
2	phases/02-context-gathering.md	Gather project context and analyze codebase	plan
3	phases/03-test-coverage-analysis.md	Analyze test coverage and framework detection	plan
4	phases/04-conflict-resolution.md	Detect and resolve conflicts (conditional)	plan
5	phases/05-tdd-task-generation.md	Generate TDD tasks with Red-Green-Refactor cycles	plan
6	phases/06-tdd-structure-validation.md	Validate TDD structure and present confirmation gate	plan
7	phases/07-tdd-verify.md	Full TDD compliance verification with quality gate	verify

Core Rules

1. Start Immediately: First action is mode detection + TaskCreate initialization, second action is phase execution
2. No Preliminary Analysis: Do not read files, analyze structure, or gather context before Phase 1
3. Parse Every Output: Extract required data from each phase output for next phase
4. Auto-Continue via TaskList: Check TaskList status to execute next pending phase automatically
5. Track Progress: Update TaskCreate/TaskUpdate dynamically with task attachment/collapse pattern
6. Task Attachment Model: Skill execute attaches sub-tasks to current workflow. Orchestrator executes these attached tasks itself, then collapses them after completion
7. Progressive Phase Loading: Read phase docs ONLY when that phase is about to execute
8. DO NOT STOP: Continuous multi-phase workflow. After executing all attached tasks, immediately collapse them and execute next phase
9. TDD Context: All descriptions include "TDD:" prefix

TDD Compliance Requirements

The Iron Law

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Enforcement Method:

• Phase 5: implementation includes test-first steps (Red → Green → Refactor)
• Green phase: Includes test-fix-cycle configuration (max 3 iterations)
• Auto-revert: Triggered when max iterations reached without passing tests

Verification: Phase 6 validates Red-Green-Refactor structure in all generated tasks

TDD Compliance Checkpoint

Checkpoint	Validation Phase	Evidence Required
Test-first structure	Phase 5	implementation has 3 steps
Red phase exists	Phase 6	Step 1: tdd_phase: "red"
Green phase with test-fix	Phase 6	Step 2: tdd_phase: "green" + test-fix-cycle
Refactor phase exists	Phase 6	Step 3: tdd_phase: "refactor"

Core TDD Principles

Red Flags - STOP and Reassess:

• Code written before test
• Test passes immediately (no Red phase witnessed)
• Cannot explain why test should fail
• "Just this once" rationalization
• "Tests after achieve same goals" thinking

Why Order Matters:

• Tests written after code pass immediately → proves nothing
• Test-first forces edge case discovery before implementation
• Tests-after verify what was built, not what's required

Input Processing

Convert User Input to TDD Structured Format:

1. Simple text → Add TDD context:

   User: "Build authentication system"
   
   Structured:
   TDD: Authentication System
   GOAL: Build authentication system
   SCOPE: Core authentication features
   CONTEXT: New implementation
   TEST_FOCUS: Authentication scenarios
   

2. Detailed text → Extract components with TEST_FOCUS:

   User: "Add JWT authentication with email/password login and token refresh"
   
   Structured:
   TDD: JWT Authentication
   GOAL: Implement JWT-based authentication
   SCOPE: Email/password login, token generation, token refresh endpoints
   CONTEXT: JWT token-based security, refresh token rotation
   TEST_FOCUS: Login flow, token validation, refresh rotation, error cases
   

3. File/Issue → Read and structure with TDD

Data Flow

Plan Mode

User Input (task description)
    ↓
[Convert to TDD Structured Format]
    ↓ Structured Description:
    ↓   TDD: [Feature Name]
    ↓   GOAL: [objective]
    ↓   SCOPE: [boundaries]
    ↓   CONTEXT: [background]
    ↓   TEST_FOCUS: [test scenarios]
    ↓
Phase 1: session:start --auto "TDD: structured-description"
    ↓ Output: sessionId
    ↓
Phase 2: context-gather --session sessionId "structured-description"
    ↓ Input: sessionId + structured description
    ↓ Output: contextPath (context-package.json) + conflictRisk
    ↓
Phase 3: test-context-gather --session sessionId
    ↓ Input: sessionId
    ↓ Output: testContextPath (test-context-package.json)
    ↓
Phase 4: conflict-resolution [conditional: conflictRisk ≥ medium]
    ↓ Input: sessionId + contextPath + conflictRisk
    ↓ Output: conflict-resolution.json
    ↓ Skip if conflictRisk is none/low → proceed directly to Phase 5
    ↓
Phase 5: task-generate-tdd --session sessionId
    ↓ Input: sessionId + all accumulated context
    ↓ Output: IMPL_PLAN.md, IMPL-*.json, TODO_LIST.md
    ↓
Phase 6: TDD Structure Validation (internal)
    ↓ Validate Red-Green-Refactor structure
    ↓ Present Plan Confirmation Gate
    ↓
Plan Confirmation (User Decision Gate):
    ├─ "Verify TDD Compliance" (Recommended) → Route to Phase 7
    ├─ "Start Execution" → Skill(skill="workflow-execute")
    └─ "Review Status Only" → Route to /workflow:status

Verify Mode

Input: --session sessionId (or auto-detect)
    ↓
Phase 7: Session discovery → Chain validation → Coverage analysis → Report
    ↓ Output: TDD_COMPLIANCE_REPORT.md with quality gate

Session Memory Flow: Each phase receives session ID, which provides access to:

• Previous task summaries
• Existing context and analysis
• Session-specific configuration

TodoWrite Pattern

Core Concept: Dynamic task attachment and collapse for real-time visibility into TDD workflow execution.

Implementation Note: Phase files use TodoWrite syntax to describe the conceptual tracking pattern. At runtime, these are implemented via TaskCreate/TaskUpdate/TaskList tools. Map as follows:

• Initial list creation → TaskCreate for each item
• Status changes → TaskUpdate({ taskId, status })
• Sub-task attachment → TaskCreate + TaskUpdate({ addBlockedBy })
• Sub-task collapse → TaskUpdate({ status: "completed" }) + TaskUpdate({ status: "deleted" }) for collapsed sub-items

Key Principles

1. Task Attachment (when phase executed):

   • Sub-tasks are attached to orchestrator's TodoWrite
   • Phase 3, 4, 5: Multiple sub-tasks attached
   • Phase 1, 2, 6: Single task (atomic)
   • First attached task marked as in_progress, others as pending
   • Orchestrator executes these attached tasks sequentially

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

   • Applies to Phase 3, 4, 5: Remove detailed sub-tasks from TodoWrite
   • Collapse to high-level phase summary
   • Phase 1, 2, 6: No collapse needed (single task, just mark completed)
   • Maintains clean orchestrator-level view

3. Continuous Execution: After completion, automatically proceed to next pending phase

Lifecycle: Initial pending → Phase executed (tasks ATTACHED) → Sub-tasks executed sequentially → Phase completed (tasks COLLAPSED for 3/4/5, marked completed for 1/2/6) → Next phase → Repeat

Initial State (Plan Mode):

[
  {"content": "Phase 1: Session Discovery", "status": "in_progress", "activeForm": "Executing session discovery"},
  {"content": "Phase 2: Context Gathering", "status": "pending", "activeForm": "Executing context gathering"},
  {"content": "Phase 3: Test Coverage Analysis", "status": "pending", "activeForm": "Executing test coverage analysis"},
  {"content": "Phase 5: TDD Task Generation", "status": "pending", "activeForm": "Executing TDD task generation"},
  {"content": "Phase 6: TDD Structure Validation", "status": "pending", "activeForm": "Validating TDD structure"}
]

Note: Phase 4 (Conflict Resolution) is added dynamically after Phase 2 if conflictRisk ≥ medium.

Phase 3 (Tasks Attached):

[
  {"content": "Phase 1: Session Discovery", "status": "completed"},
  {"content": "Phase 2: Context Gathering", "status": "completed"},
  {"content": "Phase 3: Test Coverage Analysis", "status": "in_progress"},
  {"content": "  → Detect test framework and conventions", "status": "in_progress"},
  {"content": "  → Analyze existing test coverage", "status": "pending"},
  {"content": "  → Identify coverage gaps", "status": "pending"},
  {"content": "Phase 5: TDD Task Generation", "status": "pending"},
  {"content": "Phase 6: TDD Structure Validation", "status": "pending"}
]

Phase 3 (Collapsed):

[
  {"content": "Phase 1: Session Discovery", "status": "completed"},
  {"content": "Phase 2: Context Gathering", "status": "completed"},
  {"content": "Phase 3: Test Coverage Analysis", "status": "completed"},
  {"content": "Phase 5: TDD Task Generation", "status": "pending"},
  {"content": "Phase 6: TDD Structure Validation", "status": "pending"}
]

Phase 5 (Tasks Attached):

[
  {"content": "Phase 1: Session Discovery", "status": "completed"},
  {"content": "Phase 2: Context Gathering", "status": "completed"},
  {"content": "Phase 3: Test Coverage Analysis", "status": "completed"},
  {"content": "Phase 5: TDD Task Generation", "status": "in_progress"},
  {"content": "  → Discovery - analyze TDD requirements", "status": "in_progress"},
  {"content": "  → Planning - design Red-Green-Refactor cycles", "status": "pending"},
  {"content": "  → Output - generate IMPL tasks with internal TDD phases", "status": "pending"},
  {"content": "Phase 6: TDD Structure Validation", "status": "pending"}
]

Note: See individual Phase descriptions for detailed TodoWrite Update examples.

Post-Phase Updates

Memory State Check

After heavy phases (Phase 2-3), evaluate context window usage:

• If memory usage is high (>110K tokens or approaching context limits):

  Skill(skill="compact")
  

• Memory compaction is particularly important after analysis phases

Planning Notes (Optional)

Similar to workflow-plan, a planning-notes.md can accumulate context across phases if needed. See Phase 1 for initialization.

Error Handling

• Parsing Failure: If output parsing fails, retry command once, then report error
• Validation Failure: Report which file/data is missing or invalid
• Command Failure: Keep phase in_progress, report error to user, do not proceed
• TDD Validation Failure: Report incomplete chains or wrong dependencies
• Session Not Found (verify mode): Report error with available sessions list

Error Handling Quick Reference

Error Type	Detection	Recovery Action
Parsing failure	Empty/malformed output	Retry once, then report
Missing context-package	File read error	Re-run /workflow:tools:context-gather
Invalid task JSON	jq parse error	Report malformed file path
Task count exceeds 18	Count validation ≥19	Request re-scope, split into multiple sessions
Missing cli_execution.id	All tasks lack ID	Regenerate tasks with phase 0 user config
Test-context missing	File not found	Re-run /workflow:tools:test-context-gather
Phase timeout	No response	Retry phase, check CLI connectivity
CLI tool not available	Tool not in cli-tools.json	Fall back to alternative preferred tool

TDD Warning Patterns

Pattern	Warning Message	Recommended Action
Task count >10	High task count detected	Consider splitting into multiple sessions
Missing test-fix-cycle	Green phase lacks auto-revert	Add max_iterations: 3 to task config
Red phase missing test path	Test file path not specified	Add explicit test file paths
Generic task names	Vague names like "Add feature"	Use specific behavior descriptions
No refactor criteria	Refactor phase lacks completion criteria	Define clear refactor scope

Non-Blocking Warning Policy

All warnings are advisory - they do not halt execution:

1. Warnings logged to .process/tdd-warnings.log
2. Summary displayed in Phase 6 output
3. User decides whether to address before /workflow:execute

Coordinator Checklist

Plan Mode

• Pre-Phase: Convert user input to TDD structured format (TDD/GOAL/SCOPE/CONTEXT/TEST_FOCUS)
• Initialize TaskCreate before any command (Phase 4 added dynamically after Phase 2)
• Execute Phase 1 immediately with structured description
• Parse session ID from Phase 1 output, store in memory
• Pass session ID and structured description to Phase 2 command
• Parse context path from Phase 2 output, store in memory
• Extract conflictRisk from context-package.json: Determine Phase 4 execution
• Execute Phase 3 (test coverage analysis) with sessionId
• Parse testContextPath from Phase 3 output, store in memory
• If conflictRisk ≥ medium: Launch Phase 4 conflict-resolution with sessionId and contextPath
• Wait for Phase 4 to finish executing (if executed), verify conflict-resolution.json created
• If conflictRisk is none/low: Skip Phase 4, proceed directly to Phase 5
• Pass session ID to Phase 5 command (TDD task generation)
• Verify all Phase 5 outputs (IMPL_PLAN.md, IMPL-*.json, TODO_LIST.md)
• Execute Phase 6 (internal TDD structure validation)
• Plan Confirmation Gate: Present user with choice (Verify → Phase 7 / Execute / Review Status)
• If user selects Verify: Read phases/07-tdd-verify.md, execute Phase 7 in-process
• If user selects Execute: Skill(skill="workflow-execute")
• If user selects Review: Route to /workflow:status
• Auto mode (--yes): Auto-select "Verify TDD Compliance", then auto-continue to execute if APPROVED
• Update TaskCreate/TaskUpdate after each phase
• After each phase, automatically continue to next phase based on TaskList status

Verify Mode

• Detect/validate session (from --session flag or auto-detect)
• Initialize TaskCreate with verification tasks
• Execute Phase 7 through all sub-phases (session validation → chain validation → coverage analysis → report generation)
• Present quality gate result and next step options

Related Skills

Prerequisite Skills:

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

Called by Plan Mode (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 (conditional)
• /compact - Phase 4: Memory optimization (if context approaching limits)
• /workflow:tools:task-generate-tdd - Phase 5: Generate TDD tasks with Red-Green-Refactor cycles

Called by Verify Mode:

• /workflow:tools:tdd-coverage-analysis - Phase 7: Test coverage and cycle analysis

Follow-up Skills:

• /workflow:tdd-verify - Verify TDD compliance (can also invoke via verify mode)
• /workflow:plan-verify - Verify plan quality and dependencies
• /workflow:status - Review TDD task breakdown
• Skill(skill="workflow-execute") - Begin TDD implementation