workflow-tdd-plan-plan

<purpose> 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. Triggers on "workflow-tdd-plan" (plan mode) or "workflow-tdd-verify" (verify mode). </purpose> <process> ## 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: ```javascript // ★ 统一 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 ```javascript 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/...")`: | Phase | Document | Purpose | Mode | Compact | |-------|----------|---------|------|---------| | 1 | phases/01-session-discovery.md | Create or discover TDD workflow session | plan | TodoWrite 驱动 | | 2 | phases/02-context-gathering.md | Gather project context and analyze codebase | plan | TodoWrite 驱动 | | 3 | phases/03-test-coverage-analysis.md | Analyze test coverage and framework detection | plan | TodoWrite 驱动 | | 4 | phases/04-conflict-resolution.md | Detect and resolve conflicts (conditional) | plan | TodoWrite 驱动 | | 5 | phases/05-tdd-task-generation.md | Generate TDD tasks with Red-Green-Refactor cycles | plan | TodoWrite 驱动 + sentinel | | 6 | phases/06-tdd-structure-validation.md | Validate TDD structure and present confirmation gate | plan | TodoWrite 驱动 + sentinel | | 7 | phases/07-tdd-verify.md | Full TDD compliance verification with quality gate | verify | TodoWrite 驱动 | **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 | 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 ## 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): ```json [ {"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): ```json [ {"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): ```json [ {"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"} ]