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：特定のセッションを使用します

---

概要

サブエージェントの連携を利用した、複数モードの 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 をスキップし、警告を表示して続行します
タスクの生成に失敗した	簡略化したコンテキストでエージェントを再試行します
検証に失敗した	部分的な結果を表示します
セッションが見つからない（検証時）	利用可能なセッションを一覧表示します

---

TDD 準拠要件

絶対原則

NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

Red-Green-Refactor サイクル

各タスクには以下が必要です：

1. Red：失敗するテストを書く（テストが有効であることを証明します）
2. Green：テストを通すための最小限のコードを実装する（test-fix-cycle を使用）
3. Refactor：テストを通したままコード品質を改善する

品質ゲート

• test-fix-cycle：最大 3 回
• 自動ロールバック：最大反復回数に達した場合に実行
• カバレッジ目標：プロジェクトごとに定義
• 受け入れ基準：テスト可能かつ測定可能であること

---

コンパクト化への対策

コンパクト化に関する指示：コンテキストが圧縮された場合：

• planning-notes.md を再読し、蓄積されたコンテキストを確認します
• workflow-session.json を再読し、セッション状態を確認します
• フェーズ 5 は最もトークンを消費します。圧縮された場合は、必要に応じてタスク JSON を再読します