workflow-tdd-plan

自动模式

使用 --yes 或 -y 时：跳过所有确认，使用默认值，自动验证。此技能仅用于规划，绝不执行实现。输出计划供用户审阅。

工作流 TDD 计划

用法

# Plan mode (default)
$workflow-tdd-plan "Build authentication system with JWT and OAuth"
$workflow-tdd-plan -y "Add rate limiting to API endpoints"
$workflow-tdd-plan --session WFS-auth "Extend with 2FA support"

# Verify mode
$workflow-tdd-plan verify --session WFS-auth
$workflow-tdd-plan verify

标志：

• -y, --yes：跳过所有确认（自动模式）
• --session ID：使用指定会话

---

概述

使用子 Agent 协调的多模式 TDD 规划流程。计划模式按顺序运行 6 个阶段，并根据条件分支；验证模式则针对现有计划运行 TDD 合规性验证。

核心原则：没有先行失败测试，就不编写生产代码

┌──────────────────────────────────────────────────────────────────┐
│                    WORKFLOW TDD PLAN PIPELINE                     │
├──────────────────────────────────────────────────────────────────┤
│                                                                    │
│  Mode Detection: plan | verify                                    │
│                                                                    │
│  ═══ Plan Mode (default) ═══                                      │
│                                                                    │
│  Phase 1: Session Discovery                                       │
│     ├─ Create or find workflow session                            │
│     └─ Initialize planning-notes.md with TDD context              │
│                                                                    │
│  Phase 2: Context Gathering (spawn_agent: context-search-agent)  │
│     ├─ Codebase analysis → context-package.json                  │
│     └─ Conflict risk assessment                                   │
│                                                                    │
│  Phase 3: Test Coverage Analysis (spawn_agent: cli-explore-agent)│
│     ├─ Detect test framework and conventions                      │
│     ├─ Analyze existing test coverage                             │
│     └─ Output: test-context-package.json                          │
│                                                                    │
│  Phase 4: Conflict Resolution (conditional: risk ≥ medium)       │
│     ├─ CLI-driven conflict analysis                               │
│     └─ User-selected resolution strategies                        │
│                                                                    │
│  Phase 5: TDD Task Generation (spawn_agent: action-planning-agent)│
│     ├─ Generate tasks with Red-Green-Refactor cycles              │
│     └─ Output: IMPL_PLAN.md + task JSONs + TODO_LIST.md          │
│                                                                    │
│  Phase 6: TDD Structure Validation                                │
│     ├─ Validate Red-Green-Refactor structure                      │
│     └─ Present Plan Confirmation Gate                             │
│                                                                    │
│  Plan Confirmation Gate (PLANNING ENDS HERE)                     │
│     ├─ "Verify TDD Compliance" → Phase 7                         │
│     ├─ "Done" → Display next-step command for user               │
│     └─ "Review Status" → Display inline                          │
│                                                                    │
│  ═══ Verify Mode ═══                                              │
│  Phase 7: TDD Verification (spawn_agent: cli-explore-agent)      │
│     └─ 4-dimension TDD compliance → TDD_COMPLIANCE_REPORT.md     │
│                                                                    │
└──────────────────────────────────────────────────────────────────┘

---

数据流

User Input (task description)
    │
    ↓ [Convert to TDD Structured Format]
    │   TDD: [Feature Name]
    │   GOAL: [objective]
    │   SCOPE: [boundaries]
    │   CONTEXT: [background]
    │   TEST_FOCUS: [test scenarios]
    │
Phase 1 ──→ sessionId, planning-notes.md
    │
Phase 2 ──→ context-package.json, conflictRisk
    │
Phase 3 ──→ test-context-package.json
    │
    ├── conflictRisk ≥ medium ──→ Phase 4 ──→ conflict-resolution.json
    └── conflictRisk < medium ──→ skip Phase 4
    │
Phase 5 ──→ IMPL_PLAN.md (with Red-Green-Refactor), task JSONs, TODO_LIST.md
    │
Phase 6 ──→ TDD structure validation
    │
    ├── Verify → Phase 7 → TDD_COMPLIANCE_REPORT.md
    ├── Execute → workflow-execute skill
    └── Review → inline display

---

会话结构

.workflow/active/WFS-{session}/
├── workflow-session.json              # Session metadata
├── planning-notes.md                  # Accumulated context across phases
├── IMPL_PLAN.md                       # Implementation plan with TDD cycles
├── plan.json                          # Structured plan overview
├── TODO_LIST.md                       # Task checklist
├── .task/                             # Task definitions with TDD phases
│   ├── IMPL-1.json                    # Each task has Red-Green-Refactor steps
│   └── IMPL-N.json
└── .process/
    ├── context-package.json           # Phase 2 output
    ├── test-context-package.json      # Phase 3 output
    ├── conflict-resolution.json       # Phase 4 output (conditional)
    └── TDD_COMPLIANCE_REPORT.md       # Phase 7 output

---

实现

会话初始化

const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()

// Parse flags
const AUTO_YES = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
const sessionMatch = $ARGUMENTS.match(/--session\s+(\S+)/)
const existingSessionId = sessionMatch ? sessionMatch[1] : null

// Mode detection
const cleanArgs = $ARGUMENTS
  .replace(/--yes|-y|--session\s+\S+/g, '').trim()

let mode = 'plan'
if (cleanArgs.startsWith('verify')) mode = 'verify'

const taskDescription = cleanArgs
  .replace(/^verify\s*/, '')
  .replace(/^["']|["']$/g, '')
  .trim()

// Convert to TDD structured format
function toTddStructured(desc) {
  const featureName = desc.split(/\s+/).slice(0, 3).join(' ')
  return `TDD: ${featureName}
GOAL: ${desc}
SCOPE: Core implementation
CONTEXT: New development
TEST_FOCUS: Unit tests, integration tests, edge cases`
}

const structuredDesc = toTddStructured(taskDescription)

---

阶段 1：会话发现（计划模式）

目标：创建或查找工作流会话，并初始化包含 TDD 上下文的规划笔记。

if (mode !== 'plan') {
  // verify: locate existing session
  // → Jump to Phase 7
}

let sessionId, sessionFolder

if (existingSessionId) {
  sessionId = existingSessionId
  sessionFolder = `.workflow/active/${sessionId}`
  if (!Bash(`test -d "${sessionFolder}" && echo yes`).trim()) {
    console.log(`ERROR: Session ${sessionId} not found`)
    return
  }
} else {
  // Auto-detect from .workflow/active/ or create new
  const sessions = Bash(`ls -d .workflow/active/WFS-* 2>/dev/null`).trim().split('\n').filter(Boolean)

  if (sessions.length === 0 || taskDescription) {
    // Create new session
    const slug = taskDescription.toLowerCase()
      .replace(/[^a-z0-9\u4e00-\u9fa5]+/g, '-').substring(0, 40)
    sessionId = `WFS-${slug}`
    sessionFolder = `.workflow/active/${sessionId}`
    Bash(`mkdir -p "${sessionFolder}/.task" "${sessionFolder}/.process"`)

    Write(`${sessionFolder}/workflow-session.json`, JSON.stringify({
      session_id: sessionId,
      status: 'planning',
      workflow_type: 'tdd',
      created_at: getUtc8ISOString(),
      task_description: taskDescription
    }, null, 2))
  } else if (sessions.length === 1) {
    sessionId = sessions[0].split('/').pop()
    sessionFolder = sessions[0]
  } else {
    // Multiple sessions — ask user
    if (AUTO_YES) {
      sessionFolder = sessions[0]
      sessionId = sessions[0].split('/').pop()
    } else {
      const answer = functions.request_user_input({
        questions: [{
          question: "Multiple sessions found. Select one:",
          header: "Session",
          options: sessions.slice(0, 4).map(s => ({
            label: s.split('/').pop(),
            description: s
          }))
        }]
      })
      sessionId = answer.Session
      sessionFolder = `.workflow/active/${sessionId}`
    }
  }
}

// Initialize planning-notes.md with TDD context
Write(`${sessionFolder}/planning-notes.md`, `# TDD Planning Notes

## User Intent
${structuredDesc}

## TDD Principles
- NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST
- Red-Green-Refactor cycle for all tasks
- Test-first forces edge case discovery before implementation
`)

console.log(`Session: ${sessionId}`)

---

阶段 2：上下文收集（spawn_agent）

目标：收集项目上下文，评估冲突风险。

console.log(`\n## Phase 2: Context Gathering\n`)

const ctxAgent = spawn_agent({
  agent_type: "context_search_agent",
  instruction: `
Gather implementation context for TDD planning.

**Session**: ${sessionFolder}
**Task**: ${taskDescription}
**Mode**: TDD_PLAN

### Steps
1. Analyze project structure (package.json, tsconfig, etc.)
2. Search for existing similar implementations
3. Identify integration points and dependencies
4. Assess conflict risk with existing code
5. Generate context package

### Output
Write context package to: ${sessionFolder}/.process/context-package.json
Format: {
  "critical_files": [...],
  "patterns": [...],
  "dependencies": [...],
  "integration_points": [...],
  "conflict_risk": "none" | "low" | "medium" | "high",
  "conflict_areas": [...],
  "constraints": [...]
}
`
})

wait_agent({ timeout_ms: 1800000 })  // 30 minutes
close_agent({ target: ctxAgent })

// Parse outputs
const contextPkg = JSON.parse(Read(`${sessionFolder}/.process/context-package.json`) || '{}')
const conflictRisk = contextPkg.conflict_risk || 'none'

// Update planning-notes.md
Edit(`${sessionFolder}/planning-notes.md`, {
  oldText: '## User Intent',
  newText: `## Context Findings
- Critical files: ${(contextPkg.critical_files || []).join(', ')}
- Conflict risk: ${conflictRisk}
- Constraints: ${(contextPkg.constraints || []).join('; ')}

## User Intent`
})

console.log(`  Context gathered. Conflict risk: ${conflictRisk}`)

---

阶段 3：测试覆盖率分析（spawn_agent）

目标：分析现有测试模式和覆盖率。

console.log(`\n## Phase 3: Test Coverage Analysis\n`)

const testAgent = spawn_agent({
  agent_type: "cli_explore_agent",
  instruction: `
Analyze test coverage and framework for TDD planning.

**Session**: ${sessionFolder}
**Context**: ${sessionFolder}/.process/context-package.json

### Steps
1. Detect test framework (Jest, Vitest, Mocha, etc.)
2. Identify test file patterns and conventions
3. Analyze existing test coverage
4. Identify coverage gaps
5. Extract test utilities and helpers

### Output
Write test context to: ${sessionFolder}/.process/test-context-package.json
Format: {
  "test_framework": "jest" | "vitest" | "mocha" | "other",
  "test_patterns": {
    "unit": "**/*.test.ts",
    "integration": "**/*.integration.test.ts"
  },
  "coverage_summary": {
    "lines": 75.5,
    "branches": 68.2,
    "functions": 80.1
  },
  "coverage_gaps": [...],
  "test_utilities": [...],
  "conventions": {
    "naming": "describe/it",
    "mocking": "jest.mock",
    "assertions": "expect"
  }
}
`
})

wait_agent({ timeout_ms: 1800000 })  // 30 minutes
close_agent({ target: testAgent })

const testContext = JSON.parse(Read(`${sessionFolder}/.process/test-context-package.json`) || '{}')

// Update planning-notes
Edit(`${sessionFolder}/planning-notes.md`, {
  oldText: '## TDD Principles',
  newText: `## Test Context
- Framework: ${testContext.test_framework || 'unknown'}
- Coverage: ${testContext.coverage_summary?.lines || 'N/A'}% lines
- Gaps: ${(testContext.coverage_gaps || []).join(', ')}

## TDD Principles`
})

console.log(`  Test framework: ${testContext.test_framework}`)

---

阶段 4：冲突解决（条件执行）

目标：在风险 ≥ 中等时检测并解决冲突。

if (['medium', 'high'].includes(conflictRisk)) {
  console.log(`\n## Phase 4: Conflict Resolution (risk: ${conflictRisk})\n`)

  Bash({
    command: `ccw cli -p "PURPOSE: Analyze and resolve conflicts between planned changes and existing codebase.
TASK:
  • Read context package for conflict areas
  • Analyze each conflict area in detail
  • Propose resolution strategies (refactor, adapt, isolate, defer)
  • For each conflict: assess impact and recommend approach
MODE: analysis
CONTEXT: @**/*
EXPECTED: JSON: {conflicts: [{area, severity, description, strategy, impact}], summary: string}
CONSTRAINTS: Focus on ${(contextPkg.conflict_areas || []).join(', ')}

TASK DESCRIPTION: ${taskDescription}" --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause`,
    run_in_background: true
  })
  // Wait for CLI → conflicts[]

  if (!AUTO_YES && conflicts.length > 0) {
    // Present conflicts and let user select strategies
    console.log(`\n### Conflicts Found: ${conflicts.length}\n`)
    conflicts.forEach((c, i) => {
      console.log(`${i + 1}. [${c.severity}] ${c.area}: ${c.description}`)
      console.log(`   Strategy: ${c.strategy} | Impact: ${c.impact}`)
    })

    const answer = functions.request_user_input({
      questions: [{
        question: "Accept conflict resolution strategies?",
        header: "Conflicts",
        options: [
          { label: "Accept All", description: "Apply all recommended strategies" },
          { label: "Review Each", description: "Approve strategies individually" },
          { label: "Skip", description: "Proceed without resolving" }
        ]
      }]
    })
  }

  // Write resolution
  Write(`${sessionFolder}/.process/conflict-resolution.json`,
    JSON.stringify({ conflicts, resolved_at: getUtc8ISOString() }, null, 2))
} else {
  console.log(`  Conflict risk: ${conflictRisk} — skipping Phase 4`)
}

---

阶段 5：TDD 任务生成（spawn_agent）

目标：生成包含 Red-Green-Refactor 循环的 IMPL_PLAN.md、任务 JSON 文件和 TODO_LIST.md。

console.log(`\n## Phase 5: TDD Task Generation\n`)

const planAgent = spawn_agent({
  agent_type: "action_planning_agent",
  instruction: `
Generate TDD implementation plan with Red-Green-Refactor cycles.

**Session**: ${sessionFolder}
**Task**: ${taskDescription}
**Context**: ${sessionFolder}/.process/context-package.json
**Test Context**: ${sessionFolder}/.process/test-context-package.json
**Planning Notes**: ${sessionFolder}/planning-notes.md
${conflictRisk === 'medium' || conflictRisk === 'high'
  ? `**Conflict Resolution**: ${sessionFolder}/.process/conflict-resolution.json` : ''}

### TDD Requirements
Each task MUST include Red-Green-Refactor cycle:
1. **Red Phase**: Write failing test first
   - Define test cases
   - Verify test fails (proves test is valid)
   - Document expected failure
2. **Green Phase**: Implement minimal code to pass
   - Write simplest implementation
   - Run tests until passing
   - Max 3 test-fix iterations (auto-revert if exceeded)
3. **Refactor Phase**: Improve code quality
   - Refactor with tests as safety net
   - Maintain passing tests
   - Document improvements

### Output Requirements
1. **IMPL_PLAN.md** at ${sessionFolder}/IMPL_PLAN.md
   - Section 1: Requirements Summary
   - Section 2: Test Strategy (framework, patterns, coverage goals)
   - Section 3: Task Breakdown with TDD cycles
   - Section 4: Implementation Strategy
   - Section 5: Risk Assessment
2. **plan.json** at ${sessionFolder}/plan.json
   - {task_ids[], recommended_execution, complexity, tdd_compliance: true}
3. **Task JSONs** at ${sessionFolder}/.task/IMPL-{N}.json
   - Each task has "implementation" array with 3 steps:
     [
       {step: 1, tdd_phase: "red", description: "Write failing test", ...},
       {step: 2, tdd_phase: "green", description: "Implement code", test_fix_cycle: {max_iterations: 3, auto_revert: true}},
       {step: 3, tdd_phase: "refactor", description: "Refactor code", ...}
     ]
4. **TODO_LIST.md** at ${sessionFolder}/TODO_LIST.md
   - Checkbox format: - [ ] IMPL-{N}: {title} (TDD)
`
})

wait_agent({ timeout_ms: 1800000 })  // 30 minutes
close_agent({ target: planAgent })

console.log(`  TDD tasks generated`)

---

阶段 6：TDD 结构验证

目标：验证所有任务中的 Red-Green-Refactor 结构。

console.log(`\n## Phase 6: TDD Structure Validation\n`)

// Read all task JSONs
const taskFiles = Bash(`ls ${sessionFolder}/.task/IMPL-*.json 2>/dev/null`).trim().split('\n').filter(Boolean)
const tasks = taskFiles.map(f => JSON.parse(Read(f)))

// Validate TDD structure
const validationErrors = []
for (const task of tasks) {
  const impl = task.implementation || []

  // Check 3-step structure
  if (impl.length !== 3) {
    validationErrors.push(`${task.id}: Expected 3 steps, found ${impl.length}`)
    continue
  }

  // Check Red phase
  if (impl[0].tdd_phase !== 'red') {
    validationErrors.push(`${task.id}: Step 1 must be Red phase`)
  }

  // Check Green phase with test-fix-cycle
  if (impl[1].tdd_phase !== 'green') {
    validationErrors.push(`${task.id}: Step 2 must be Green phase`)
  }
  if (!impl[1].test_fix_cycle || !impl[1].test_fix_cycle.max_iterations) {
    validationErrors.push(`${task.id}: Green phase missing test-fix-cycle config`)
  }

  // Check Refactor phase
  if (impl[2].tdd_phase !== 'refactor') {
    validationErrors.push(`${task.id}: Step 3 must be Refactor phase`)
  }
}

if (validationErrors.length > 0) {
  console.log(`\n### TDD Structure Validation Errors:\n`)
  validationErrors.forEach(e => console.log(`  - ${e}`))

  if (!AUTO_YES) {
    const answer = functions.request_user_input({
      questions: [{
        question: "TDD structure validation failed. Continue anyway?",
        header: "Validation",
        options: [
          { label: "Fix and Retry", description: "Regenerate tasks with correct structure" },
          { label: "Continue", description: "Proceed despite errors" },
          { label: "Abort", description: "Stop planning" }
        ]
      }]
    })

    if (answer.Validation === "Fix and Retry") {
      // Re-run Phase 5
      // → goto Phase 5
    } else if (answer.Validation === "Abort") {
      return
    }
  }
} else {
  console.log(`  ✓ All tasks have valid Red-Green-Refactor structure`)
}

// Plan Confirmation Gate
const taskCount = tasks.length
console.log(`\n## Plan Generated\n`)
console.log(`  Tasks: ${taskCount}`)
console.log(`  Plan: ${sessionFolder}/IMPL_PLAN.md`)

if (AUTO_YES) {
  console.log(`  [--yes] Auto-verifying TDD compliance...`)
  // → Fall through to Phase 7
} else {
  const nextStep = functions.request_user_input({
    questions: [{
      question: "TDD plan generated. What's next?",
      header: "Next Step",
      options: [
        { label: "Verify TDD Compliance (Recommended)", description: "Run full TDD compliance verification" },
        { label: "Done", description: "Planning complete — show next-step command" },
        { label: "Review Status", description: "Display plan summary inline" }
      ]
    }]
  })

  if (nextStep['Next Step'] === 'Done') {
    console.log(`\nPlanning complete. To execute, run: $workflow-execute --session ${sessionId}`)
    return  // STOP — this skill is planning-only
  }
  if (nextStep['Next Step'] === 'Review Status') {
    const plan = Read(`${sessionFolder}/IMPL_PLAN.md`)
    console.log(plan)
    return  // STOP — this skill is planning-only
  }
  // Verify → continue to Phase 7
}

---

阶段 7：TDD 验证（验证模式）

目标：执行完整的 TDD 合规性验证，并设置质量门禁。

if (mode === 'verify' || /* auto-verify from Phase 6 */) {
  console.log(`\n## Phase 7: TDD Verification\n`)

  // Find session if in verify mode entry
  if (mode === 'verify' && !sessionFolder) {
    // Session discovery (same logic as Phase 1)
  }

  const verifyAgent = spawn_agent({
    agent_type: "cli_explore_agent",
    instruction: `
Verify TDD compliance across 4 dimensions.

**Session**: ${sessionFolder}

### Verification Dimensions

**A. Test-First Structure**
- Every task has Red-Green-Refactor cycle
- Red phase defines failing tests
- Green phase implements code
- Refactor phase improves quality

**B. Test Coverage**
- All critical paths have tests
- Edge cases covered
- Integration points tested
- Coverage meets project standards

**C. Cycle Integrity**
- Red phase: test fails before implementation
- Green phase: minimal code to pass
- Refactor phase: maintains passing tests
- No production code without failing test first

**D. Quality Gates**
- Test-fix-cycle configured (max 3 iterations)
- Auto-revert on iteration limit
- Clear acceptance criteria
- Testable convergence conditions

### Output
Write report to: ${sessionFolder}/.process/TDD_COMPLIANCE_REPORT.md

Format:
# TDD Compliance Report

## Summary
- Quality Gate: APPROVED | CONDITIONAL | BLOCKED
- Tasks Analyzed: N
- Compliance Score: X%

## Dimension Scores
- A. Test-First Structure: PASS/WARN/FAIL
- B. Test Coverage: PASS/WARN/FAIL
- C. Cycle Integrity: PASS/WARN/FAIL
- D. Quality Gates: PASS/WARN/FAIL

## Issues Found
[List specific issues with task IDs]

## Recommendations
[Actionable recommendations]

## Quality Gate Decision
APPROVED: All dimensions PASS, ready for execution
CONDITIONAL: Minor warnings, can proceed with caution
BLOCKED: Critical failures, must fix before execution
`
  })

  wait_agent({ timeout_ms: 1800000 })  // 30 minutes
  close_agent({ target: verifyAgent })

  const report = Read(`${sessionFolder}/.process/TDD_COMPLIANCE_REPORT.md`)
  const qualityGate = report.match(/Quality Gate: (\w+)/)?.[1] || 'UNKNOWN'

  console.log(`  Quality gate: ${qualityGate}`)
  console.log(`  Report: ${sessionFolder}/.process/TDD_COMPLIANCE_REPORT.md`)

  console.log(`\nPlanning complete. To execute, run: $workflow-execute --session ${sessionId}`)
  // STOP — this skill is planning-only, NEVER proceed to execution
}

---

错误处理

错误	恢复方式
没有活动会话	指引：先运行 $workflow-tdd-plan "description"
上下文收集超时	缩小范围后重试
测试框架检测失败	在 test-context-package.json 中手动指定
TDD 结构验证失败	重新生成任务或手动修复
冲突分析失败	跳过阶段 4，并继续执行，同时显示警告
任务生成失败	使用简化的上下文重试 Agent
验证失败	显示部分结果
未找到会话（验证模式）	列出可用会话

---

TDD 合规性要求

铁律

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Red-Green-Refactor 循环

每项任务必须包含：

1. Red（红）：编写失败测试（证明测试有效）
2. Green（绿）：实现通过测试所需的最少代码（包含测试修复循环）
3. Refactor（重构）：提升代码质量（保持测试通过）

质量门禁

• 测试修复循环：最多 3 次迭代
• 自动回退：达到最大迭代次数时触发
• 覆盖率目标：按项目定义
• 验收标准：可测试且可衡量

---

压缩保护

压缩指令：如果上下文被压缩：

• 重新读取 planning-notes.md，获取累积的上下文
• 重新读取 workflow-session.json，获取会话状态
• 阶段 5 的 Token 消耗最高——如果上下文被压缩，按需重新读取任务 JSON 文件