workflow-tdd-plan

## Auto Mode When `--yes` or `-y`: Skip all confirmations, use defaults, auto-verify. **This skill is planning-only — it NEVER executes implementation. Output is the plan for user review.** # Workflow TDD Plan ## Usage ```bash # 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 ``` **Flags**: - `-y, --yes`: Skip all confirmations (auto mode) - `--session ID`: Use specific session --- ## Overview Multi-mode TDD planning pipeline using subagent coordination. Plan mode runs 6 sequential phases with conditional branching; verify mode operates on existing plans with TDD compliance validation. **Core Principle**: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST ``` ┌──────────────────────────────────────────────────────────────────┐ │ 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 │ │ │ └──────────────────────────────────────────────────────────────────┘ ``` --- ## Data Flow ``` 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 ``` --- ## Session Structure ``` .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 ``` --- ## Implementation ### Session Initialization ```javascript 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) ``` --- ### Phase 1: Session Discovery (Plan Mode) **Objective**: Create or find workflow session, initialize planning notes with TDD context. ```javascript 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}`) ``` --- ### Phase 2: Context Gathering (spawn_agent) **Objective**: Gather project context, assess conflict risk. ```javascript 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}`) ``` --- ### Phase 3: Test Coverage Analysis (spawn_agent) **Objective**: Analyze existing test patterns and coverage. ```javascript 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}`) ``` --- ### Phase 4: Conflict Resolution (Conditional) **Objective**: Detect and resolve conflicts when risk ≥ medium. ```javascript 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(', ')}