1. 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 ──→ Display session status inline

2. 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

3. Interactive Preference Collection

Before dispatching to phase execution, collect workflow preferences via AskUserQuestion:

// ★ 统一 auto mode 检测：-y/--yes 从 $ARGUMENTS 或 ccw 传播
const autoYes = /\b(-y|--yes)\b/.test($ARGUMENTS)

if (autoYes) {
  // 自动模式：跳过所有询问，使用默认值
  workflowPreferences = { autoYes: true }
} else {
  const prefResponse = AskUserQuestion({
    questions: [
      {
        question: "是否跳过所有确认步骤（自动模式）？",
        header: "Auto Mode",
        multiSelect: false,
        options: [
          { label: "Interactive (Recommended)", description: "交互模式，包含确认步骤" },
          { label: "Auto", description: "跳过所有确认，自动执行" }
        ]
      }
    ]
  })

  workflowPreferences = {
    autoYes: prefResponse.autoMode === 'Auto'
  }
}

workflowPreferences is passed to phase execution as context variable, referenced as workflowPreferences.autoYes within phases.

4. 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
}

5. Compact Recovery (Phase Persistence)

Multi-phase TDD planning (Phase 1-6/7) spans long conversations. Uses 双重保险: TodoWrite 跟踪 active phase 保护其不被压缩，sentinel 作为兜底。

⚠️ COMPACT DIRECTIVE: Context compression MUST check TodoWrite phase status. The phase currently marked in_progress is the active execution phase — preserve its FULL content. Only compress phases marked completed or pending.

6. Execution Flow — Plan Mode (default)

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

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

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

Phase 3: Test Coverage Analysis
   └─ Read("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 → Read("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
   └─ Read("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
   └─ Read("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" → Display session status inline

7. Execution Flow — Verify Mode

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

8. Phase Reference Documents

Read on-demand when phase executes using Read("phases/..."):

Compact Rules:

1. TodoWrite in_progress → 保留完整内容，禁止压缩
2. TodoWrite completed → 可压缩为摘要
3. sentinel fallback → Phase 5/6 包含 compact sentinel；若 compact 后仅存 sentinel 而无完整 Step 协议，必须立即 Read() 恢复对应 phase 文件

9. 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

10. 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

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

11. 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

12. 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" → Display session status inline

13. Data Flow — 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

14. 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.

15. 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="memory-capture")

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

16. 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

TDD Warning Patterns

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 skill

17. 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: Display session status inline
• Auto mode (workflowPreferences.autoYes): 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

18. Coordinator Checklist — 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

19. 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
• phases/02-context-gathering.md - Phase 2: Gather project context and analyze codebase (inline)
• phases/03-test-coverage-analysis.md - Phase 3: Analyze existing test patterns and coverage (inline)
• phases/04-conflict-resolution.md - Phase 4: Detect and resolve conflicts (inline, conditional)
• memory-capture skill - Phase 4: Memory optimization (if context approaching limits)
• phases/05-tdd-task-generation.md - Phase 5: Generate TDD tasks with Red-Green-Refactor cycles (inline)

Called by Verify Mode:

• phases/07-tdd-verify.md - Phase 7: Test coverage and cycle analysis (inline)

Follow-up Skills:

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

<auto_mode> When workflowPreferences.autoYes is true (triggered by -y/--yes flag):

• Skip all interactive confirmation prompts
• Use default values for all preference questions
• At Plan Confirmation Gate: Auto-select "Verify TDD Compliance"
• After verification: Auto-continue to execute if quality gate returns APPROVED
• All phases execute continuously without user intervention </auto_mode>

<success_criteria>

• Mode correctly detected from skill trigger name (plan vs verify)
• All 6 plan phases execute sequentially with proper data flow between them
• Phase files loaded progressively via Read() only when phase is about to execute
• TaskCreate/TaskUpdate tracks all phases with attachment/collapse pattern
• TDD Iron Law enforced: every task has Red-Green-Refactor structure
• Phase 4 (Conflict Resolution) conditionally executes based on conflictRisk level
• Plan Confirmation Gate presents three choices after Phase 6
• Verify mode (Phase 7) produces TDD_COMPLIANCE_REPORT.md with quality gate
• All outputs generated: IMPL_PLAN.md, IMPL-*.json, TODO_LIST.md
• Compact recovery preserves active phase content via TodoWrite status
• Error handling retries once on parsing failure, reports on persistent errors </success_criteria>