chore: bump version to 6.3.46

## Features

- New `ccw` command: Main process workflow orchestrator with auto intent-based workflow selection
- New CommandRegistry for dynamic command discovery and metadata management

## Improvements

- Optimize ccw-coordinator: Serial blocking execution model with hook-based continuation
- Refactor execution flow: Stop after CLI launch, wait for hook callbacks (no polling)
- Add task_id tracking and state.json checkpoints for resumable execution
- Consolidate documentation: Reduce report verbosity while maintaining all core information

## Documentation

- Add Execution Model comparison (main process vs external CLI)
- Add State Management section with TodoWrite tracking examples
- Update Type Comparison table highlighting ccw vs ccw-coordinator differences
- Simplify code examples with inline comments

## Changes Summary

- ccw-coordinator.md: +272/-26 (serial blocking), -143 docs (consolidation)
- ccw.md: +121/-352 (state management, execution model)
- Rename: CCW-COORDINATOR.md → ccw-coordinator.md (lowercase)

.claude/agents/tdd-developer.md

@@ -0,0 +1,530 @@
+---
+name: tdd-developer
+description: |
+  TDD-aware code execution agent specialized for Red-Green-Refactor workflows. Extends code-developer with TDD cycle awareness, automatic test-fix iteration, and CLI session resumption. Executes TDD tasks with phase-specific logic and test-driven quality gates.
+
+  Examples:
+  - Context: TDD task with Red-Green-Refactor phases
+    user: "Execute TDD task IMPL-1 with test-first development"
+    assistant: "I'll execute the Red-Green-Refactor cycle with automatic test-fix iteration"
+    commentary: Parse TDD metadata, execute phases sequentially with test validation
+
+  - Context: Green phase with failing tests
+    user: "Green phase implementation complete but tests failing"
+    assistant: "Starting test-fix cycle (max 3 iterations) with Gemini diagnosis"
+    commentary: Iterative diagnosis and fix until tests pass or max iterations reached
+
+color: green
+extends: code-developer
+tdd_aware: true
+---
+
+You are a TDD-specialized code execution agent focused on implementing high-quality, test-driven code. You receive TDD tasks with Red-Green-Refactor cycles and execute them with phase-specific logic and automatic test validation.
+
+## TDD Core Philosophy
+
+- **Test-First Development** - Write failing tests before implementation (Red phase)
+- **Minimal Implementation** - Write just enough code to pass tests (Green phase)
+- **Iterative Quality** - Refactor for clarity while maintaining test coverage (Refactor phase)
+- **Automatic Validation** - Run tests after each phase, iterate on failures
+
+## TDD Task JSON Schema Recognition
+
+**TDD-Specific Metadata**:
+```json
+{
+  "meta": {
+    "tdd_workflow": true,              // REQUIRED: Enables TDD mode
+    "max_iterations": 3,                // Green phase test-fix cycle limit
+    "cli_execution_id": "{session}-{task}",  // CLI session ID for resume
+    "cli_execution": {                  // CLI execution strategy
+      "strategy": "new|resume|fork|merge_fork",
+      "resume_from": "parent-cli-id"    // For resume/fork strategies; array for merge_fork
+      // Note: For merge_fork, resume_from is array: ["id1", "id2", ...]
+    }
+  },
+  "context": {
+    "tdd_cycles": [                     // Test cases and coverage targets
+      {
+        "test_count": 5,
+        "test_cases": ["case1", "case2", ...],
+        "implementation_scope": "...",
+        "expected_coverage": ">=85%"
+      }
+    ],
+    "focus_paths": [...],               // Absolute or clear relative paths
+    "requirements": [...],
+    "acceptance": [...]                 // Test commands for validation
+  },
+  "flow_control": {
+    "pre_analysis": [...],              // Context gathering steps
+    "implementation_approach": [        // Red-Green-Refactor steps
+      {
+        "step": 1,
+        "title": "Red Phase: Write failing tests",
+        "tdd_phase": "red",             // REQUIRED: Phase identifier
+        "description": "Write 5 test cases: [...]",
+        "modification_points": [...],
+        "command": "..."                // Optional CLI command
+      },
+      {
+        "step": 2,
+        "title": "Green Phase: Implement to pass tests",
+        "tdd_phase": "green",           // Triggers test-fix cycle
+        "description": "Implement N functions...",
+        "modification_points": [...],
+        "command": "..."
+      },
+      {
+        "step": 3,
+        "title": "Refactor Phase: Improve code quality",
+        "tdd_phase": "refactor",
+        "description": "Apply N refactorings...",
+        "modification_points": [...]
+      }
+    ]
+  }
+}
+```
+
+## TDD Execution Process
+
+### 1. TDD Task Recognition
+
+**Step 1.1: Detect TDD Mode**
+```
+IF meta.tdd_workflow == true:
+  → Enable TDD execution mode
+  → Parse TDD-specific metadata
+  → Prepare phase-specific execution logic
+ELSE:
+  → Delegate to code-developer (standard execution)
+```
+
+**Step 1.2: Parse TDD Metadata**
+```javascript
+// Extract TDD configuration
+const tddConfig = {
+  maxIterations: taskJson.meta.max_iterations || 3,
+  cliExecutionId: taskJson.meta.cli_execution_id,
+  cliStrategy: taskJson.meta.cli_execution?.strategy,
+  resumeFrom: taskJson.meta.cli_execution?.resume_from,
+  testCycles: taskJson.context.tdd_cycles || [],
+  acceptanceTests: taskJson.context.acceptance || []
+}
+
+// Identify phases
+const phases = taskJson.flow_control.implementation_approach
+  .filter(step => step.tdd_phase)
+  .map(step => ({
+    step: step.step,
+    phase: step.tdd_phase,  // "red", "green", or "refactor"
+    ...step
+  }))
+```
+
+**Step 1.3: Validate TDD Task Structure**
+```
+REQUIRED CHECKS:
+- [ ] meta.tdd_workflow is true
+- [ ] flow_control.implementation_approach has exactly 3 steps
+- [ ] Each step has tdd_phase field ("red", "green", "refactor")
+- [ ] context.acceptance includes test command
+- [ ] Green phase has modification_points or command
+
+IF validation fails:
+  → Report invalid TDD task structure
+  → Request task regeneration with /workflow:tools:task-generate-tdd
+```
+
+### 2. Phase-Specific Execution
+
+#### Red Phase: Write Failing Tests
+
+**Objectives**:
+- Write test cases that verify expected behavior
+- Ensure tests fail (proving they test something real)
+- Document test scenarios clearly
+
+**Execution Flow**:
+```
+STEP 1: Parse Red Phase Requirements
+  → Extract test_count and test_cases from context.tdd_cycles
+  → Extract test file paths from modification_points
+  → Load existing test patterns from focus_paths
+
+STEP 2: Execute Red Phase Implementation
+  IF step.command exists:
+    → Execute CLI command with session resume
+    → Build CLI command: ccw cli -p "..." --resume {resume_from} --tool {tool} --mode write
+  ELSE:
+    → Direct agent implementation
+    → Create test files in modification_points
+    → Write test cases following test_cases enumeration
+    → Use context.shared_context.conventions for test style
+
+STEP 3: Validate Red Phase (Test Must Fail)
+  → Execute test command from context.acceptance
+  → Parse test output
+  IF tests pass:
+    ⚠️ WARNING: Tests passing in Red phase - may not test real behavior
+    → Log warning, continue to Green phase
+  IF tests fail:
+    ✅ SUCCESS: Tests failing as expected
+    → Proceed to Green phase
+```
+
+**Red Phase Quality Gates**:
+- [ ] All specified test cases written (verify count matches test_count)
+- [ ] Test files exist in expected locations
+- [ ] Tests execute without syntax errors
+- [ ] Tests fail with clear error messages
+
+#### Green Phase: Implement to Pass Tests (with Test-Fix Cycle)
+
+**Objectives**:
+- Write minimal code to pass tests
+- Iterate on failures with automatic diagnosis
+- Achieve test pass rate and coverage targets
+
+**Execution Flow with Test-Fix Cycle**:
+```
+STEP 1: Parse Green Phase Requirements
+  → Extract implementation_scope from context.tdd_cycles
+  → Extract target files from modification_points
+  → Set max_iterations from meta.max_iterations (default: 3)
+
+STEP 2: Initial Implementation
+  IF step.command exists:
+    → Execute CLI command with session resume
+    → Build CLI command: ccw cli -p "..." --resume {resume_from} --tool {tool} --mode write
+  ELSE:
+    → Direct agent implementation
+    → Implement functions in modification_points
+    → Follow logic_flow sequence
+    → Use minimal code to pass tests (no over-engineering)
+
+STEP 3: Test-Fix Cycle (CRITICAL TDD FEATURE)
+  FOR iteration in 1..meta.max_iterations:
+
+    STEP 3.1: Run Test Suite
+      → Execute test command from context.acceptance
+      → Capture test output (stdout + stderr)
+      → Parse test results (pass count, fail count, coverage)
+
+    STEP 3.2: Evaluate Results
+      IF all tests pass AND coverage >= expected_coverage:
+        ✅ SUCCESS: Green phase complete
+        → Log final test results
+        → Store pass rate and coverage
+        → Break loop, proceed to Refactor phase
+
+      ELSE IF iteration < max_iterations:
+        ⚠️ ITERATION {iteration}: Tests failing, starting diagnosis
+
+        STEP 3.3: Diagnose Failures with Gemini
+          → Build diagnosis prompt:
+            PURPOSE: Diagnose test failures in TDD Green phase to identify root cause and generate fix strategy
+            TASK:
+              • Analyze test output: {test_output}
+              • Review implementation: {modified_files}
+              • Identify failure patterns (syntax, logic, edge cases, missing functionality)
+              • Generate specific fix recommendations with code snippets
+            MODE: analysis
+            CONTEXT: @{modified_files} | Test Output: {test_output}
+            EXPECTED: Diagnosis report with root cause and actionable fix strategy
+
+          → Execute: Bash(
+              command="ccw cli -p '{diagnosis_prompt}' --tool gemini --mode analysis --rule analysis-diagnose-bug-root-cause",
+              timeout=300000  // 5 min
+            )
+          → Parse diagnosis output → Extract fix strategy
+
+        STEP 3.4: Apply Fixes
+          → Parse fix recommendations from diagnosis
+          → Apply fixes to implementation files
+          → Use Edit tool for targeted changes
+          → Log changes to .process/green-fix-iteration-{iteration}.md
+
+        STEP 3.5: Continue to Next Iteration
+          → iteration++
+          → Repeat from STEP 3.1
+
+      ELSE:  // iteration == max_iterations AND tests still failing
+        ❌ FAILURE: Max iterations reached without passing tests
+
+        STEP 3.6: Auto-Revert (Safety Net)
+          → Log final failure diagnostics
+          → Revert all changes made during Green phase
+          → Store failure report in .process/green-phase-failure.md
+          → Report to user with diagnostics:
+            "Green phase failed after {max_iterations} iterations.
+             All changes reverted. See diagnostics in green-phase-failure.md"
+          → HALT execution (do not proceed to Refactor phase)
+```
+
+**Green Phase Quality Gates**:
+- [ ] All tests pass (100% pass rate)
+- [ ] Coverage meets expected_coverage target (e.g., >=85%)
+- [ ] Implementation follows modification_points specification
+- [ ] Code compiles and runs without errors
+- [ ] Fix iteration count logged
+
+**Test-Fix Cycle Output Artifacts**:
+```
+.workflow/active/{session-id}/.process/
+├── green-fix-iteration-1.md    # First fix attempt
+├── green-fix-iteration-2.md    # Second fix attempt
+├── green-fix-iteration-3.md    # Final fix attempt
+└── green-phase-failure.md      # Failure report (if max iterations reached)
+```
+
+#### Refactor Phase: Improve Code Quality
+
+**Objectives**:
+- Improve code clarity and structure
+- Remove duplication and complexity
+- Maintain test coverage (no regressions)
+
+**Execution Flow**:
+```
+STEP 1: Parse Refactor Phase Requirements
+  → Extract refactoring targets from description
+  → Load refactoring scope from modification_points
+
+STEP 2: Execute Refactor Implementation
+  IF step.command exists:
+    → Execute CLI command with session resume
+  ELSE:
+    → Direct agent refactoring
+    → Apply refactorings from logic_flow
+    → Follow refactoring best practices:
+      • Extract functions for clarity
+      • Remove duplication (DRY principle)
+      • Simplify complex logic
+      • Improve naming
+      • Add documentation where needed
+
+STEP 3: Regression Testing (REQUIRED)
+  → Execute test command from context.acceptance
+  → Verify all tests still pass
+  IF tests fail:
+    ⚠️ REGRESSION DETECTED: Refactoring broke tests
+    → Revert refactoring changes
+    → Report regression to user
+    → HALT execution
+  IF tests pass:
+    ✅ SUCCESS: Refactoring complete with no regressions
+    → Proceed to task completion
+```
+
+**Refactor Phase Quality Gates**:
+- [ ] All refactorings applied as specified
+- [ ] All tests still pass (no regressions)
+- [ ] Code complexity reduced (if measurable)
+- [ ] Code readability improved
+
+### 3. CLI Execution Integration
+
+**CLI Session Resumption** (when step.command exists):
+
+**Build CLI Command with Resume Strategy**:
+```javascript
+function buildCliCommand(step, tddConfig) {
+  const baseCommand = step.command  // From task JSON
+
+  // Parse cli_execution strategy
+  switch (tddConfig.cliStrategy) {
+    case "new":
+      // First task - start fresh conversation
+      return `ccw cli -p "${baseCommand}" --tool ${tool} --mode write --id ${tddConfig.cliExecutionId}`
+
+    case "resume":
+      // Single child - continue same conversation
+      return `ccw cli -p "${baseCommand}" --resume ${tddConfig.resumeFrom} --tool ${tool} --mode write`
+
+    case "fork":
+      // Multiple children - branch with parent context
+      return `ccw cli -p "${baseCommand}" --resume ${tddConfig.resumeFrom} --id ${tddConfig.cliExecutionId} --tool ${tool} --mode write`
+
+    case "merge_fork":
+      // Multiple parents - merge contexts
+      // resume_from is an array for merge_fork strategy
+      const mergeIds = Array.isArray(tddConfig.resumeFrom)
+        ? tddConfig.resumeFrom.join(',')
+        : tddConfig.resumeFrom
+      return `ccw cli -p "${baseCommand}" --resume ${mergeIds} --id ${tddConfig.cliExecutionId} --tool ${tool} --mode write`
+
+    default:
+      // Fallback - no resume
+      return `ccw cli -p "${baseCommand}" --tool ${tool} --mode write`
+  }
+}
+```
+
+**Execute CLI Command**:
+```javascript
+// TDD agent runs in foreground - can receive hook callbacks
+Bash(
+  command=buildCliCommand(step, tddConfig),
+  timeout=3600000,  // 60 min for CLI execution
+  run_in_background=false  // Agent can receive task completion hooks
+)
+```
+
+### 4. Context Loading (Inherited from code-developer)
+
+**Standard Context Sources**:
+- Task JSON: `context.requirements`, `context.acceptance`, `context.focus_paths`
+- Context Package: `context_package_path` → brainstorm artifacts, exploration results
+- Tech Stack: `context.shared_context.tech_stack` (skip auto-detection if present)
+
+**TDD-Enhanced Context**:
+- `context.tdd_cycles`: Test case enumeration and coverage targets
+- `meta.max_iterations`: Test-fix cycle configuration
+- Exploration results: `context_package.exploration_results` for critical_files and integration_points
+
+### 5. Quality Gates (TDD-Enhanced)
+
+**Before Task Complete** (all phases):
+- [ ] Red Phase: Tests written and failing
+- [ ] Green Phase: All tests pass with coverage >= target
+- [ ] Refactor Phase: No test regressions
+- [ ] Code follows project conventions
+- [ ] All modification_points addressed
+
+**TDD-Specific Validations**:
+- [ ] Test count matches tdd_cycles.test_count
+- [ ] Coverage meets tdd_cycles.expected_coverage
+- [ ] Green phase iteration count ≤ max_iterations
+- [ ] No auto-revert triggered (Green phase succeeded)
+
+### 6. Task Completion (TDD-Enhanced)
+
+**Upon completing TDD task:**
+
+1. **Verify TDD Compliance**:
+   - All three phases completed (Red → Green → Refactor)
+   - Final test run shows 100% pass rate
+   - Coverage meets or exceeds expected_coverage
+
+2. **Update TODO List** (same as code-developer):
+   - Mark completed tasks with [x]
+   - Add summary links
+   - Update task progress
+
+3. **Generate TDD-Enhanced Summary**:
+   ```markdown
+   # Task: [Task-ID] [Name]
+
+   ## TDD Cycle Summary
+
+   ### Red Phase: Write Failing Tests
+   - Test Cases Written: {test_count} (expected: {tdd_cycles.test_count})
+   - Test Files: {test_file_paths}
+   - Initial Result: ✅ All tests failing as expected
+
+   ### Green Phase: Implement to Pass Tests
+   - Implementation Scope: {implementation_scope}
+   - Test-Fix Iterations: {iteration_count}/{max_iterations}
+   - Final Test Results: {pass_count}/{total_count} passed ({pass_rate}%)
+   - Coverage: {actual_coverage} (target: {expected_coverage})
+   - Iteration Details: See green-fix-iteration-*.md
+
+   ### Refactor Phase: Improve Code Quality
+   - Refactorings Applied: {refactoring_count}
+   - Regression Test: ✅ All tests still passing
+   - Final Test Results: {pass_count}/{total_count} passed
+
+   ## Implementation Summary
+
+   ### Files Modified
+   - `[file-path]`: [brief description of changes]
+
+   ### Content Added
+   - **[ComponentName]**: [purpose/functionality]
+   - **[functionName()]**: [purpose/parameters/returns]
+
+   ## Status: ✅ Complete (TDD Compliant)
+   ```
+
+## TDD-Specific Error Handling
+
+**Red Phase Errors**:
+- Tests pass immediately → Warning (may not test real behavior)
+- Test syntax errors → Fix and retry
+- Missing test files → Report and halt
+
+**Green Phase Errors**:
+- Max iterations reached → Auto-revert + failure report
+- Tests never run → Report configuration error
+- Coverage tools unavailable → Continue with pass rate only
+
+**Refactor Phase Errors**:
+- Regression detected → Revert refactoring
+- Tests fail to run → Keep original code
+
+## Key Differences from code-developer
+
+| Feature | code-developer | tdd-developer |
+|---------|----------------|---------------|
+| TDD Awareness | ❌ No | ✅ Yes |
+| Phase Recognition | ❌ Generic steps | ✅ Red/Green/Refactor |
+| Test-Fix Cycle | ❌ No | ✅ Green phase iteration |
+| Auto-Revert | ❌ No | ✅ On max iterations |
+| CLI Resume | ❌ No | ✅ Full strategy support |
+| TDD Metadata | ❌ Ignored | ✅ Parsed and used |
+| Test Validation | ❌ Manual | ✅ Automatic per phase |
+| Coverage Tracking | ❌ No | ✅ Yes (if available) |
+
+## Quality Checklist (TDD-Enhanced)
+
+Before completing any TDD task, verify:
+- [ ] **TDD Structure Validated** - meta.tdd_workflow is true, 3 phases present
+- [ ] **Red Phase Complete** - Tests written and initially failing
+- [ ] **Green Phase Complete** - All tests pass, coverage >= target
+- [ ] **Refactor Phase Complete** - No regressions, code improved
+- [ ] **Test-Fix Iterations Logged** - green-fix-iteration-*.md exists
+- [ ] Code follows project conventions
+- [ ] CLI session resume used correctly (if applicable)
+- [ ] TODO list updated
+- [ ] TDD-enhanced summary generated
+
+## Key Reminders
+
+**NEVER:**
+- Skip Red phase validation (must confirm tests fail)
+- Proceed to Refactor if Green phase tests failing
+- Exceed max_iterations without auto-reverting
+- Ignore tdd_phase indicators
+
+**ALWAYS:**
+- Parse meta.tdd_workflow to detect TDD mode
+- Run tests after each phase
+- Use test-fix cycle in Green phase
+- Auto-revert on max iterations failure
+- Generate TDD-enhanced summaries
+- Use CLI resume strategies when step.command exists
+- Log all test-fix iterations to .process/
+
+**Bash Tool (CLI Execution in TDD Agent)**:
+- Use `run_in_background=false` - TDD agent can receive hook callbacks
+- Set timeout ≥60 minutes for CLI commands:
+  ```javascript
+  Bash(command="ccw cli -p '...' --tool codex --mode write", timeout=3600000)
+  ```
+
+## Execution Mode Decision
+
+**When to use tdd-developer vs code-developer**:
+- ✅ Use tdd-developer: `meta.tdd_workflow == true` in task JSON
+- ❌ Use code-developer: No TDD metadata, generic implementation tasks
+
+**Task Routing** (by workflow orchestrator):
+```javascript
+if (taskJson.meta?.tdd_workflow) {
+  agent = "tdd-developer"  // Use TDD-aware agent
+} else {
+  agent = "code-developer"  // Use generic agent
+}
+```

.claude/commands/ccw.md

@@ -0,0 +1,486 @@
+---
+name: ccw
+description: Main workflow orchestrator - analyze intent, select workflow, execute command chain in main process
+argument-hint: "\"task description\""
+allowed-tools: SlashCommand(*), TodoWrite(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*)
+---
+
+# CCW Command - Main Workflow Orchestrator
+
+Main process orchestrator: intent analysis → workflow selection → command chain execution.
+
+## Core Concept: Minimum Execution Units (最小执行单元)
+
+**Definition**: A set of commands that must execute together as an atomic group to achieve a meaningful workflow milestone.
+
+**Why This Matters**:
+- **Prevents Incomplete States**: Avoid stopping after task generation without execution
+- **User Experience**: User gets complete results, not intermediate artifacts requiring manual follow-up
+- **Workflow Integrity**: Maintains logical coherence of multi-step operations
+
+**Key Units in CCW**:
+
+| Unit Type | Pattern | Example |
+|-----------|---------|---------|
+| **Planning + Execution** | plan-cmd → execute-cmd | lite-plan → lite-execute |
+| **Testing** | test-gen-cmd → test-exec-cmd | test-fix-gen → test-cycle-execute |
+| **Review** | review-cmd → fix-cmd | review-session-cycle → review-fix |
+
+**Atomic Rules**:
+1. CCW automatically groups commands into minimum units - never splits them
+2. Pipeline visualization shows units with `【 】` markers
+3. Error handling preserves unit boundaries (retry/skip affects whole unit)
+
+## Execution Model
+
+**Synchronous (Main Process)**: Commands execute via SlashCommand in main process, blocking until complete.
+
+```
+User Input → Analyze Intent → Select Workflow → [Confirm] → Execute Chain
+                                                              ↓
+                                                    SlashCommand (blocking)
+                                                              ↓
+                                                    Update TodoWrite
+                                                              ↓
+                                                    Next Command...
+```
+
+**vs ccw-coordinator**: External CLI execution with background tasks and hook callbacks.
+
+## 5-Phase Workflow
+
+### Phase 1: Analyze Intent
+
+```javascript
+function analyzeIntent(input) {
+  return {
+    goal: extractGoal(input),
+    scope: extractScope(input),
+    constraints: extractConstraints(input),
+    task_type: detectTaskType(input),       // bugfix|feature|tdd|review|exploration|...
+    complexity: assessComplexity(input),    // low|medium|high
+    clarity_score: calculateClarity(input)  // 0-3 (>=2 = clear)
+  };
+}
+
+// Task type detection (priority order)
+function detectTaskType(text) {
+  const patterns = {
+    'bugfix-hotfix': /urgent|production|critical/ && /fix|bug/,
+    'bugfix': /fix|bug|error|crash|fail|debug/,
+    'issue-batch': /issues?|batch/ && /fix|resolve/,
+    'exploration': /uncertain|explore|research|what if/,
+    'multi-perspective': /multi-perspective|compare|cross-verify/,
+    'quick-task': /quick|simple|small/ && /feature|function/,
+    'ui-design': /ui|design|component|style/,
+    'tdd': /tdd|test-driven|test first/,
+    'test-fix': /test fail|fix test|failing test/,
+    'review': /review|code review/,
+    'documentation': /docs|documentation|readme/
+  };
+  for (const [type, pattern] of Object.entries(patterns)) {
+    if (pattern.test(text)) return type;
+  }
+  return 'feature';
+}
+```
+
+**Output**: `Type: [task_type] | Goal: [goal] | Complexity: [complexity] | Clarity: [clarity_score]/3`
+
+---
+
+### Phase 1.5: Requirement Clarification (if clarity_score < 2)
+
+```javascript
+async function clarifyRequirements(analysis) {
+  if (analysis.clarity_score >= 2) return analysis;
+
+  const questions = generateClarificationQuestions(analysis);  // Goal, Scope, Constraints
+  const answers = await AskUserQuestion({ questions });
+  return updateAnalysis(analysis, answers);
+}
+```
+
+**Questions**: Goal (Create/Fix/Optimize/Analyze), Scope (Single file/Module/Cross-module/System), Constraints (Backward compat/Skip tests/Urgent hotfix)
+
+---
+
+### Phase 2: Select Workflow & Build Command Chain
+
+```javascript
+function selectWorkflow(analysis) {
+  const levelMap = {
+    'bugfix-hotfix':     { level: 2, flow: 'bugfix.hotfix' },
+    'bugfix':            { level: 2, flow: 'bugfix.standard' },
+    'issue-batch':       { level: 'Issue', flow: 'issue' },
+    'exploration':       { level: 4, flow: 'full' },
+    'quick-task':        { level: 1, flow: 'lite-lite-lite' },
+    'ui-design':         { level: analysis.complexity === 'high' ? 4 : 3, flow: 'ui' },
+    'tdd':               { level: 3, flow: 'tdd' },
+    'test-fix':          { level: 3, flow: 'test-fix-gen' },
+    'review':            { level: 3, flow: 'review-fix' },
+    'documentation':     { level: 2, flow: 'docs' },
+    'feature':           { level: analysis.complexity === 'high' ? 3 : 2, flow: analysis.complexity === 'high' ? 'coupled' : 'rapid' }
+  };
+
+  const selected = levelMap[analysis.task_type] || levelMap['feature'];
+  return buildCommandChain(selected, analysis);
+}
+
+// Build command chain (port-based matching with Minimum Execution Units)
+function buildCommandChain(workflow, analysis) {
+  const chains = {
+    // Level 1 - Rapid
+    'lite-lite-lite': [
+      { cmd: '/workflow:lite-lite-lite', args: `"${analysis.goal}"` }
+    ],
+
+    // Level 2 - Lightweight
+    'rapid': [
+      // Unit: Quick Implementation【lite-plan → lite-execute】
+      { cmd: '/workflow:lite-plan', args: `"${analysis.goal}"`, unit: 'quick-impl' },
+      { cmd: '/workflow:lite-execute', args: '--in-memory', unit: 'quick-impl' },
+      // Unit: Test Validation【test-fix-gen → test-cycle-execute】
+      ...(analysis.constraints?.includes('skip-tests') ? [] : [
+        { cmd: '/workflow:test-fix-gen', args: '', unit: 'test-validation' },
+        { cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
+      ])
+    ],
+
+    'bugfix.standard': [
+      // Unit: Bug Fix【lite-fix → lite-execute】
+      { cmd: '/workflow:lite-fix', args: `"${analysis.goal}"`, unit: 'bug-fix' },
+      { cmd: '/workflow:lite-execute', args: '--in-memory', unit: 'bug-fix' },
+      // Unit: Test Validation【test-fix-gen → test-cycle-execute】
+      ...(analysis.constraints?.includes('skip-tests') ? [] : [
+        { cmd: '/workflow:test-fix-gen', args: '', unit: 'test-validation' },
+        { cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
+      ])
+    ],
+
+    'bugfix.hotfix': [
+      { cmd: '/workflow:lite-fix', args: `--hotfix "${analysis.goal}"` }
+    ],
+
+    'multi-cli-plan': [
+      // Unit: Multi-CLI Planning【multi-cli-plan → lite-execute】
+      { cmd: '/workflow:multi-cli-plan', args: `"${analysis.goal}"`, unit: 'multi-cli' },
+      { cmd: '/workflow:lite-execute', args: '--in-memory', unit: 'multi-cli' },
+      // Unit: Test Validation【test-fix-gen → test-cycle-execute】
+      ...(analysis.constraints?.includes('skip-tests') ? [] : [
+        { cmd: '/workflow:test-fix-gen', args: '', unit: 'test-validation' },
+        { cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
+      ])
+    ],
+
+    'docs': [
+      // Unit: Quick Implementation【lite-plan → lite-execute】
+      { cmd: '/workflow:lite-plan', args: `"${analysis.goal}"`, unit: 'quick-impl' },
+      { cmd: '/workflow:lite-execute', args: '--in-memory', unit: 'quick-impl' }
+    ],
+
+    // Level 3 - Standard
+    'coupled': [
+      // Unit: Verified Planning【plan → plan-verify】
+      { cmd: '/workflow:plan', args: `"${analysis.goal}"`, unit: 'verified-planning' },
+      { cmd: '/workflow:plan-verify', args: '', unit: 'verified-planning' },
+      // Execution
+      { cmd: '/workflow:execute', args: '' },
+      // Unit: Code Review【review-session-cycle → review-fix】
+      { cmd: '/workflow:review-session-cycle', args: '', unit: 'code-review' },
+      { cmd: '/workflow:review-fix', args: '', unit: 'code-review' },
+      // Unit: Test Validation【test-fix-gen → test-cycle-execute】
+      ...(analysis.constraints?.includes('skip-tests') ? [] : [
+        { cmd: '/workflow:test-fix-gen', args: '', unit: 'test-validation' },
+        { cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
+      ])
+    ],
+
+    'tdd': [
+      // Unit: TDD Planning + Execution【tdd-plan → execute】
+      { cmd: '/workflow:tdd-plan', args: `"${analysis.goal}"`, unit: 'tdd-planning' },
+      { cmd: '/workflow:execute', args: '', unit: 'tdd-planning' },
+      // TDD Verification
+      { cmd: '/workflow:tdd-verify', args: '' }
+    ],
+
+    'test-fix-gen': [
+      // Unit: Test Validation【test-fix-gen → test-cycle-execute】
+      { cmd: '/workflow:test-fix-gen', args: `"${analysis.goal}"`, unit: 'test-validation' },
+      { cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
+    ],
+
+    'review-fix': [
+      // Unit: Code Review【review-session-cycle → review-fix】
+      { cmd: '/workflow:review-session-cycle', args: '', unit: 'code-review' },
+      { cmd: '/workflow:review-fix', args: '', unit: 'code-review' },
+      // Unit: Test Validation【test-fix-gen → test-cycle-execute】
+      { cmd: '/workflow:test-fix-gen', args: '', unit: 'test-validation' },
+      { cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
+    ],
+
+    'ui': [
+      { cmd: '/workflow:ui-design:explore-auto', args: `"${analysis.goal}"` },
+      // Unit: Planning + Execution【plan → execute】
+      { cmd: '/workflow:plan', args: '', unit: 'plan-execute' },
+      { cmd: '/workflow:execute', args: '', unit: 'plan-execute' }
+    ],
+
+    // Level 4 - Brainstorm
+    'full': [
+      { cmd: '/workflow:brainstorm:auto-parallel', args: `"${analysis.goal}"` },
+      // Unit: Verified Planning【plan → plan-verify】
+      { cmd: '/workflow:plan', args: '', unit: 'verified-planning' },
+      { cmd: '/workflow:plan-verify', args: '', unit: 'verified-planning' },
+      // Execution
+      { cmd: '/workflow:execute', args: '' },
+      // Unit: Test Validation【test-fix-gen → test-cycle-execute】
+      { cmd: '/workflow:test-fix-gen', args: '', unit: 'test-validation' },
+      { cmd: '/workflow:test-cycle-execute', args: '', unit: 'test-validation' }
+    ],
+
+    // Issue Workflow
+    'issue': [
+      { cmd: '/issue:discover', args: '' },
+      { cmd: '/issue:plan', args: '--all-pending' },
+      { cmd: '/issue:queue', args: '' },
+      { cmd: '/issue:execute', args: '' }
+    ]
+  };
+
+  return chains[workflow.flow] || chains['rapid'];
+}
+```
+
+**Output**: `Level [X] - [flow] | Pipeline: [...] | Commands: [1. /cmd1 2. /cmd2 ...]`
+
+---
+
+### Phase 3: User Confirmation
+
+```javascript
+async function getUserConfirmation(chain) {
+  const response = await AskUserQuestion({
+    questions: [{
+      question: "Execute this command chain?",
+      header: "Confirm",
+      options: [
+        { label: "Confirm", description: "Start" },
+        { label: "Adjust", description: "Modify" },
+        { label: "Cancel", description: "Abort" }
+      ]
+    }]
+  });
+
+  if (response.error === "Cancel") throw new Error("Cancelled");
+  if (response.error === "Adjust") return await adjustChain(chain);
+  return chain;
+}
+```
+
+---
+
+### Phase 4: Setup TODO Tracking
+
+```javascript
+function setupTodoTracking(chain, workflow) {
+  const todos = chain.map((step, i) => ({
+    content: `CCW:${workflow}: [${i + 1}/${chain.length}] ${step.cmd}`,
+    status: i === 0 ? 'in_progress' : 'pending',
+    activeForm: `Executing ${step.cmd}`
+  }));
+  TodoWrite({ todos });
+}
+```
+
+**Output**: `-> CCW:rapid: [1/3] /workflow:lite-plan | CCW:rapid: [2/3] /workflow:lite-execute | ...`
+
+---
+
+### Phase 5: Execute Command Chain
+
+```javascript
+async function executeCommandChain(chain, workflow) {
+  let previousResult = null;
+
+  for (let i = 0; i < chain.length; i++) {
+    try {
+      const fullCommand = assembleCommand(chain[i], previousResult);
+      const result = await SlashCommand({ command: fullCommand });
+
+      previousResult = { ...result, success: true };
+      updateTodoStatus(i, chain.length, workflow, 'completed');
+
+    } catch (error) {
+      const action = await handleError(chain[i], error, i);
+      if (action === 'retry') {
+        i--;  // Retry
+      } else if (action === 'abort') {
+        return { success: false, error: error.message };
+      }
+      // 'skip' - continue
+    }
+  }
+
+  return { success: true, completed: chain.length };
+}
+
+// Assemble full command with session/plan parameters
+function assembleCommand(step, previousResult) {
+  let command = step.cmd;
+  if (step.args) {
+    command += ` ${step.args}`;
+  } else if (previousResult?.session_id) {
+    command += ` --session="${previousResult.session_id}"`;
+  }
+  return command;
+}
+
+// Update TODO: mark current as complete, next as in-progress
+function updateTodoStatus(index, total, workflow, status) {
+  const todos = getAllCurrentTodos();
+  const updated = todos.map(todo => {
+    if (todo.content.startsWith(`CCW:${workflow}:`)) {
+      const stepNum = extractStepIndex(todo.content);
+      if (stepNum === index + 1) return { ...todo, status };
+      if (stepNum === index + 2 && status === 'completed') return { ...todo, status: 'in_progress' };
+    }
+    return todo;
+  });
+  TodoWrite({ todos: updated });
+}
+
+// Error handling: Retry/Skip/Abort
+async function handleError(step, error, index) {
+  const response = await AskUserQuestion({
+    questions: [{
+      question: `${step.cmd} failed: ${error.message}`,
+      header: "Error",
+      options: [
+        { label: "Retry", description: "Re-execute" },
+        { label: "Skip", description: "Continue next" },
+        { label: "Abort", description: "Stop" }
+      ]
+    }]
+  });
+  return { Retry: 'retry', Skip: 'skip', Abort: 'abort' }[response.Error] || 'abort';
+}
+```
+
+---
+
+## Execution Flow Summary
+
+```
+User Input
+    |
+Phase 1: Analyze Intent
+    |-- Extract: goal, scope, constraints, task_type, complexity, clarity
+    +-- If clarity < 2 -> Phase 1.5: Clarify Requirements
+    |
+Phase 2: Select Workflow & Build Chain
+    |-- Map task_type -> Level (1/2/3/4/Issue)
+    |-- Select flow based on complexity
+    +-- Build command chain (port-based)
+    |
+Phase 3: User Confirmation (optional)
+    |-- Show pipeline visualization
+    +-- Allow adjustment
+    |
+Phase 4: Setup TODO Tracking
+    +-- Create todos with CCW prefix
+    |
+Phase 5: Execute Command Chain
+    |-- For each command:
+    |   |-- Assemble full command
+    |   |-- Execute via SlashCommand
+    |   |-- Update TODO status
+    |   +-- Handle errors (retry/skip/abort)
+    +-- Return workflow result
+```
+
+---
+
+## Pipeline Examples (with Minimum Execution Units)
+
+**Note**: `【 】` marks Minimum Execution Units - commands execute together as atomic groups.
+
+| Input | Type | Level | Pipeline (with Units) |
+|-------|------|-------|-----------------------|
+| "Add API endpoint" | feature (low) | 2 |【lite-plan → lite-execute】→【test-fix-gen → test-cycle-execute】|
+| "Fix login timeout" | bugfix | 2 |【lite-fix → lite-execute】→【test-fix-gen → test-cycle-execute】|
+| "OAuth2 system" | feature (high) | 3 |【plan → plan-verify】→ execute →【review-session-cycle → review-fix】→【test-fix-gen → test-cycle-execute】|
+| "Implement with TDD" | tdd | 3 |【tdd-plan → execute】→ tdd-verify |
+| "Uncertain: real-time arch" | exploration | 4 | brainstorm:auto-parallel →【plan → plan-verify】→ execute →【test-fix-gen → test-cycle-execute】|
+
+---
+
+## Key Design Principles
+
+1. **Main Process Execution** - Use SlashCommand in main process, no external CLI
+2. **Intent-Driven** - Auto-select workflow based on task intent
+3. **Port-Based Chaining** - Build command chain using port matching
+4. **Minimum Execution Units** - Commands grouped into atomic units, never split (e.g., lite-plan → lite-execute)
+5. **Progressive Clarification** - Low clarity triggers clarification phase
+6. **TODO Tracking** - Use CCW prefix to isolate workflow todos
+7. **Unit-Aware Error Handling** - Retry/skip/abort affects whole unit, not individual commands
+8. **User Control** - Optional user confirmation at each phase
+
+---
+
+## State Management
+
+**TodoWrite-Based Tracking**: All execution state tracked via TodoWrite with `CCW:` prefix.
+
+```javascript
+// Initial state
+todos = [
+  { content: "CCW:rapid: [1/3] /workflow:lite-plan", status: "in_progress" },
+  { content: "CCW:rapid: [2/3] /workflow:lite-execute", status: "pending" },
+  { content: "CCW:rapid: [3/3] /workflow:test-cycle-execute", status: "pending" }
+];
+
+// After command 1 completes
+todos = [
+  { content: "CCW:rapid: [1/3] /workflow:lite-plan", status: "completed" },
+  { content: "CCW:rapid: [2/3] /workflow:lite-execute", status: "in_progress" },
+  { content: "CCW:rapid: [3/3] /workflow:test-cycle-execute", status: "pending" }
+];
+```
+
+**vs ccw-coordinator**: Extensive state.json with task_id, status transitions, hook callbacks.
+
+---
+
+## Type Comparison: ccw vs ccw-coordinator
+
+| Aspect | ccw | ccw-coordinator |
+|--------|-----|-----------------|
+| **Type** | Main process (SlashCommand) | External CLI (ccw cli + hook callbacks) |
+| **Execution** | Synchronous blocking | Async background with hook completion |
+| **Workflow** | Auto intent-based selection | Manual chain building |
+| **Intent Analysis** | 5-phase clarity check | 3-phase requirement analysis |
+| **State** | TodoWrite only (in-memory) | state.json + checkpoint/resume |
+| **Error Handling** | Retry/skip/abort (interactive) | Retry/skip/abort (via AskUser) |
+| **Use Case** | Auto workflow for any task | Manual orchestration, large chains |
+
+---
+
+## Usage
+
+```bash
+# Auto-select workflow
+ccw "Add user authentication"
+
+# Complex requirement (triggers clarification)
+ccw "Optimize system performance"
+
+# Bug fix
+ccw "Fix memory leak in WebSocket handler"
+
+# TDD development
+ccw "Implement user registration with TDD"
+
+# Exploratory task
+ccw "Uncertain about architecture for real-time notifications"
+```

.claude/commands/issue/discover-by-prompt.md

@@ -1,10 +1,14 @@
 ---
 name: issue:discover-by-prompt
 description: Discover issues from user prompt with Gemini-planned iterative multi-agent exploration. Uses ACE semantic search for context gathering and supports cross-module comparison (e.g., frontend vs backend API contracts).
-argument-hint: "<prompt> [--scope=src/**] [--depth=standard|deep] [--max-iterations=5]"
+argument-hint: "[-y|--yes] <prompt> [--scope=src/**] [--depth=standard|deep] [--max-iterations=5]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*), AskUserQuestion(*), Glob(*), Grep(*), mcp__ace-tool__search_context(*), mcp__exa__search(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-continue all iterations, skip confirmations.
+
 # Issue Discovery by Prompt
 
 ## Quick Start

.claude/commands/issue/discover.md

@@ -1,10 +1,14 @@
 ---
 name: issue:discover
 description: Discover potential issues from multiple perspectives (bug, UX, test, quality, security, performance, maintainability, best-practices) using CLI explore. Supports Exa external research for security and best-practices perspectives.
-argument-hint: "<path-pattern> [--perspectives=bug,ux,...] [--external]"
+argument-hint: "[-y|--yes] <path-pattern> [--perspectives=bug,ux,...] [--external]"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*), Task(*), AskUserQuestion(*), Glob(*), Grep(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-select all perspectives, skip confirmations.
+
 # Issue Discovery Command
 
 ## Quick Start

.claude/commands/issue/execute.md

@@ -1,10 +1,14 @@
 ---
 name: execute
 description: Execute queue with DAG-based parallel orchestration (one commit per solution)
-argument-hint: "--queue <queue-id> [--worktree [<existing-path>]]"
+argument-hint: "[-y|--yes] --queue <queue-id> [--worktree [<existing-path>]]"
 allowed-tools: TodoWrite(*), Bash(*), Read(*), AskUserQuestion(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm execution, use recommended settings.
+
 # Issue Execute Command (/issue:execute)
 
 ## Overview
@@ -312,65 +316,60 @@ batch.forEach(id => updateTodo(id, 'completed'));
 function dispatchExecutor(solutionId, executorType, worktreePath = null) {
   // If worktree is provided, executor works in that directory
   // No per-solution worktree creation - ONE worktree for entire queue
-  const cdCommand = worktreePath ? `cd "${worktreePath}"` : '';
 
+  // Pre-defined values (replaced at dispatch time, NOT by executor)
+  const SOLUTION_ID = solutionId;
+  const WORK_DIR = worktreePath || null;
+
+  // Build prompt without markdown code blocks to avoid escaping issues
   const prompt = `
-## Execute Solution ${solutionId}
-${worktreePath ? `
-### Step 0: Enter Queue Worktree
-\`\`\`bash
-cd "${worktreePath}"
-\`\`\`
-` : ''}
-### Step 1: Get Solution (read-only)
-\`\`\`bash
-ccw issue detail ${solutionId}
-\`\`\`
+## Execute Solution: ${SOLUTION_ID}
+${WORK_DIR ? `Working Directory: ${WORK_DIR}` : ''}
+
+### Step 1: Get Solution Details
+Run this command to get the full solution with all tasks:
+  ccw issue detail ${SOLUTION_ID}
 
 ### Step 2: Execute All Tasks Sequentially
 The detail command returns a FULL SOLUTION with all tasks.
 Execute each task in order (T1 → T2 → T3 → ...):
 
 For each task:
-1. Follow task.implementation steps
-2. Run task.test commands
-3. Verify task.acceptance criteria
-(Do NOT commit after each task)
+- Follow task.implementation steps
+- Run task.test commands
+- Verify task.acceptance criteria
+- Do NOT commit after each task
 
 ### Step 3: Commit Solution (Once)
-After ALL tasks pass, commit once with formatted summary:
-\`\`\`bash
-git add <all-modified-files>
-git commit -m "[type](scope): [solution.description]
+After ALL tasks pass, commit once with formatted summary.
 
-## Solution Summary
-- Solution-ID: ${solutionId}
-- Tasks: T1, T2, ...
+Command:
+  git add -A
+  git commit -m "<type>(<scope>): <description>
 
-## Tasks Completed
-- [T1] task1.title: action
-- [T2] task2.title: action
+  Solution: ${SOLUTION_ID}
+  Tasks completed: <list task IDs>
 
-## Files Modified
-- file1.ts
-- file2.ts
+  Changes:
+  - <file1>: <what changed>
+  - <file2>: <what changed>
 
-## Verification
-- All tests passed
-- All acceptance criteria verified"
-\`\`\`
+  Verified: all tests passed"
+
+Replace <type> with: feat|fix|refactor|docs|test
+Replace <scope> with: affected module name
+Replace <description> with: brief summary from solution
 
 ### Step 4: Report Completion
-\`\`\`bash
-ccw issue done ${solutionId} --result '{"summary": "...", "files_modified": [...], "commit": {"hash": "...", "type": "feat"}, "tasks_completed": N}'
-\`\`\`
+On success, run:
+  ccw issue done ${SOLUTION_ID} --result '{"summary": "<brief>", "files_modified": ["<file1>", "<file2>"], "commit": {"hash": "<hash>", "type": "<type>"}, "tasks_completed": <N>}'
 
-If any task failed:
-\`\`\`bash
-ccw issue done ${solutionId} --fail --reason '{"task_id": "TX", "error_type": "test_failure", "message": "..."}'
-\`\`\`
+On failure, run:
+  ccw issue done ${SOLUTION_ID} --fail --reason '{"task_id": "<TX>", "error_type": "<test_failure|build_error|other>", "message": "<error details>"}'
 
-**Note**: Do NOT cleanup worktree after this solution. Worktree is shared by all solutions in the queue.
+### Important Notes
+- Do NOT cleanup worktree - it is shared by all solutions in the queue
+- Replace all <placeholder> values with actual values from your execution
 `;
 
   // For CLI tools, pass --cd to set working directory

.claude/commands/issue/new.md

@@ -1,10 +1,14 @@
 ---
 name: new
 description: Create structured issue from GitHub URL or text description
-argument-hint: "<github-url | text-description> [--priority 1-5]"
+argument-hint: "[-y|--yes] <github-url | text-description> [--priority 1-5]"
 allowed-tools: TodoWrite(*), Bash(*), Read(*), AskUserQuestion(*), mcp__ace-tool__search_context(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Skip clarification questions, create issue with inferred details.
+
 # Issue New Command (/issue:new)
 
 ## Core Principle

.claude/commands/issue/plan.md

@@ -1,10 +1,14 @@
 ---
 name: plan
 description: Batch plan issue resolution using issue-plan-agent (explore + plan closed-loop)
-argument-hint: "--all-pending <issue-id>[,<issue-id>,...] [--batch-size 3] "
+argument-hint: "[-y|--yes] --all-pending <issue-id>[,<issue-id>,...] [--batch-size 3]"
 allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*), Bash(*), Read(*), Write(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-bind solutions without confirmation, use recommended settings.
+
 # Issue Plan Command (/issue:plan)
 
 ## Overview
@@ -55,11 +59,11 @@ Unified planning command using **issue-plan-agent** that combines exploration an
 ## Execution Process
 
 ```
-Phase 1: Issue Loading
+Phase 1: Issue Loading & Intelligent Grouping
    ├─ Parse input (single, comma-separated, or --all-pending)
    ├─ Fetch issue metadata (ID, title, tags)
    ├─ Validate issues exist (create if needed)
-   └─ Group by similarity (shared tags or title keywords, max 3 per batch)
+   └─ Intelligent grouping via Gemini (semantic similarity, max 3 per batch)
 
 Phase 2: Unified Explore + Plan (issue-plan-agent)
    ├─ Launch issue-plan-agent per batch
@@ -119,46 +123,11 @@ if (useAllPending) {
 }
 // Note: Agent fetches full issue content via `ccw issue status <id> --json`
 
-// Semantic grouping via Gemini CLI (max 4 issues per group)
-async function groupBySimilarityGemini(issues) {
-  const issueSummaries = issues.map(i => ({
-    id: i.id, title: i.title, tags: i.tags
-  }));
+// Intelligent grouping: Analyze issues by title/tags, group semantically similar ones
+// Strategy: Same module/component, related bugs, feature clusters
+// Constraint: Max ${batchSize} issues per batch
 
-  const prompt = `
-PURPOSE: Group similar issues by semantic similarity for batch processing; maximize within-group coherence; max 4 issues per group
-TASK: • Analyze issue titles/tags semantically • Identify functional/architectural clusters • Assign each issue to one group
-MODE: analysis
-CONTEXT: Issue metadata only
-EXPECTED: JSON with groups array, each containing max 4 issue_ids, theme, rationale
-CONSTRAINTS: Each issue in exactly one group | Max 4 issues per group | Balance group sizes
-
-INPUT:
-${JSON.stringify(issueSummaries, null, 2)}
-
-OUTPUT FORMAT:
-{"groups":[{"group_id":1,"theme":"...","issue_ids":["..."],"rationale":"..."}],"ungrouped":[]}
-`;
-
-  const taskId = Bash({
-    command: `ccw cli -p "${prompt}" --tool gemini --mode analysis`,
-    run_in_background: true, timeout: 600000
-  });
-  const output = TaskOutput({ task_id: taskId, block: true });
-
-  // Extract JSON from potential markdown code blocks
-  function extractJsonFromMarkdown(text) {
-    const jsonMatch = text.match(/```json\s*\n([\s\S]*?)\n```/) ||
-                      text.match(/```\s*\n([\s\S]*?)\n```/);
-    return jsonMatch ? jsonMatch[1] : text;
-  }
-
-  const result = JSON.parse(extractJsonFromMarkdown(output));
-  return result.groups.map(g => g.issue_ids.map(id => issues.find(i => i.id === id)));
-}
-
-const batches = await groupBySimilarityGemini(issues);
-console.log(`Processing ${issues.length} issues in ${batches.length} batch(es) (max 4 issues/agent)`);
+console.log(`Processing ${issues.length} issues in ${batches.length} batch(es)`);
 
 TodoWrite({
   todos: batches.map((_, i) => ({
@@ -207,7 +176,9 @@ ${issueList}
    -  Add explicit verification steps to prevent same failure mode
 6. **If github_url exists**: Add final task to comment on GitHub issue
 7. Write solution to: .workflow/issues/solutions/{issue-id}.jsonl
-8. Single solution → auto-bind; Multiple → return for selection
+8. **CRITICAL - Binding Decision**:
+   - Single solution → **MUST execute**: ccw issue bind <issue-id> <solution-id>
+   - Multiple solutions → Return pending_selection only (no bind)
 
 ### Failure-Aware Planning Rules
 - **Extract failure patterns**: Parse issue.feedback where type='failure' and stage='execute'
@@ -265,35 +236,55 @@ for (let i = 0; i < agentTasks.length; i += MAX_PARALLEL) {
     }
     agentResults.push(summary);  // Store for Phase 3 conflict aggregation
 
+    // Verify binding for bound issues (agent should have executed bind)
     for (const item of summary.bound || []) {
-      console.log(`✓ ${item.issue_id}: ${item.solution_id} (${item.task_count} tasks)`);
+      const status = JSON.parse(Bash(`ccw issue status ${item.issue_id} --json`).trim());
+      if (status.bound_solution_id === item.solution_id) {
+        console.log(`✓ ${item.issue_id}: ${item.solution_id} (${item.task_count} tasks)`);
+      } else {
+        // Fallback: agent failed to bind, execute here
+        Bash(`ccw issue bind ${item.issue_id} ${item.solution_id}`);
+        console.log(`✓ ${item.issue_id}: ${item.solution_id} (${item.task_count} tasks) [recovered]`);
+      }
     }
-    // Collect and notify pending selections
+    // Collect pending selections for Phase 3
     for (const pending of summary.pending_selection || []) {
-      console.log(`⏳ ${pending.issue_id}: ${pending.solutions.length} solutions → awaiting selection`);
       pendingSelections.push(pending);
     }
-    if (summary.conflicts?.length > 0) {
-      console.log(`⚠ Conflicts: ${summary.conflicts.length} detected (will resolve in Phase 3)`);
-    }
     updateTodo(`Plan batch ${batchIndex + 1}`, 'completed');
   }
 }
 ```
 
-### Phase 3: Conflict Resolution & Solution Selection
+### Phase 3: Solution Selection (if pending)
 
-**Conflict Handling:**
-- Collect `conflicts` from all agent results
-- Low/Medium severity → auto-resolve with `recommended_resolution`
-- High severity → use `AskUserQuestion` to let user choose resolution
+```javascript
+// Handle multi-solution issues
+for (const pending of pendingSelections) {
+  if (pending.solutions.length === 0) continue;
 
-**Multi-Solution Selection:**
-- If `pending_selection` contains issues with multiple solutions:
-  - Use `AskUserQuestion` to present options (solution ID + task count + description)
-  - Extract selected solution ID from user response
-  - Verify solution file exists, recover from payload if missing
-  - Bind selected solution via `ccw issue bind <issue-id> <solution-id>`
+  const options = pending.solutions.slice(0, 4).map(sol => ({
+    label: `${sol.id} (${sol.task_count} tasks)`,
+    description: sol.description || sol.approach || 'No description'
+  }));
+
+  const answer = AskUserQuestion({
+    questions: [{
+      question: `Issue ${pending.issue_id}: which solution to bind?`,
+      header: pending.issue_id,
+      options: options,
+      multiSelect: false
+    }]
+  });
+
+  const selected = answer[Object.keys(answer)[0]];
+  if (!selected || selected === 'Other') continue;
+
+  const solId = selected.split(' ')[0];
+  Bash(`ccw issue bind ${pending.issue_id} ${solId}`);
+  console.log(`✓ ${pending.issue_id}: ${solId} bound`);
+}
+```
 
 ### Phase 4: Summary
 

.claude/commands/issue/queue.md

@@ -1,10 +1,14 @@
 ---
 name: queue
 description: Form execution queue from bound solutions using issue-queue-agent (solution-level)
-argument-hint: "[--queues <n>] [--issue <id>]"
+argument-hint: "[-y|--yes] [--queues <n>] [--issue <id>]"
 allowed-tools: TodoWrite(*), Task(*), Bash(*), Read(*), Write(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm queue formation, use recommended conflict resolutions.
+
 # Issue Queue Command (/issue:queue)
 
 ## Overview
@@ -28,12 +32,13 @@ Queue formation command using **issue-queue-agent** that analyzes all bound solu
 | Operation | Correct | Incorrect |
 |-----------|---------|-----------|
 | List issues (brief) | `ccw issue list --status planned --brief` | `Read('issues.jsonl')` |
+| **Batch solutions (NEW)** | `ccw issue solutions --status planned --brief` | Loop `ccw issue solution <id>` |
 | List queue (brief) | `ccw issue queue --brief` | `Read('queues/*.json')` |
 | Read issue details | `ccw issue status <id> --json` | `Read('issues.jsonl')` |
 | Get next item | `ccw issue next --json` | `Read('queues/*.json')` |
 | Update status | `ccw issue update <id> --status ...` | Direct file edit |
 | Sync from queue | `ccw issue update --from-queue` | Direct file edit |
-| **Read solution (brief)** | `ccw issue solution <id> --brief` | `Read('solutions/*.jsonl')` |
+| Read solution (single) | `ccw issue solution <id> --brief` | `Read('solutions/*.jsonl')` |
 
 **Output Options**:
 - `--brief`: JSON with minimal fields (id, status, counts)
@@ -131,24 +136,23 @@ Phase 7: Active Queue Check & Decision (REQUIRED)
 ### Phase 1: Solution Loading & Distribution
 
 **Data Loading:**
-- Use `ccw issue list --status planned --brief` to get planned issues with `bound_solution_id`
-- If no planned issues found → display message, suggest `/issue:plan`
-
-**Solution Brief Loading** (for each planned issue):
-```bash
-ccw issue solution <issue-id> --brief
-# Returns: [{ solution_id, is_bound, task_count, files_touched[] }]
-```
+- Use `ccw issue solutions --status planned --brief` to get all planned issues with solutions in **one call**
+- Returns: Array of `{ issue_id, solution_id, is_bound, task_count, files_touched[], priority }`
+- If no bound solutions found → display message, suggest `/issue:plan`
 
 **Build Solution Objects:**
-```json
-{
-  "issue_id": "ISS-xxx",
-  "solution_id": "SOL-ISS-xxx-1",
-  "task_count": 3,
-  "files_touched": ["src/auth.ts", "src/utils.ts"],
-  "priority": "medium"
+```javascript
+// Single CLI call replaces N individual queries
+const result = Bash(`ccw issue solutions --status planned --brief`).trim();
+const solutions = result ? JSON.parse(result) : [];
+
+if (solutions.length === 0) {
+  console.log('No bound solutions found. Run /issue:plan first.');
+  return;
 }
+
+// solutions already in correct format:
+// { issue_id, solution_id, is_bound, task_count, files_touched[], priority }
 ```
 
 **Multi-Queue Distribution** (if `--queues > 1`):

.claude/commands/task/breakdown.md

@@ -1,9 +1,13 @@
 ---
 name: breakdown
 description: Decompose complex task into subtasks with dependency mapping, creates child task JSONs with parent references and execution order
-argument-hint: "task-id"
+argument-hint: "[-y|--yes] task-id"
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm breakdown, use recommended subtask structure.
+
 # Task Breakdown Command (/task:breakdown)
 
 ## Overview

.claude/commands/task/replan.md

@@ -1,10 +1,14 @@
 ---
 name: replan
 description: Update task JSON with new requirements or batch-update multiple tasks from verification report, tracks changes in task-changes.json
-argument-hint: "task-id [\"text\"|file.md] | --batch [verification-report.md]"
+argument-hint: "[-y|--yes] task-id [\"text\"|file.md] | --batch [verification-report.md]"
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm updates, use recommended changes.
+
 # Task Replan Command (/task:replan)
 
 > **⚠️ DEPRECATION NOTICE**: This command is maintained for backward compatibility. For new workflows, use `/workflow:replan` which provides:
@@ -353,7 +357,7 @@ Review error details in summary report
 
 # No replan recommendations found
 Verification report contains no replan recommendations
-Check report content or use /workflow:action-plan-verify first
+Check report content or use /workflow:plan-verify first
 ```
 
 ## Batch Mode Integration

.claude/commands/workflow/action-plan-verify.md

@@ -1,8 +1,8 @@
 ---
-name: action-plan-verify
-description: Perform non-destructive cross-artifact consistency analysis between IMPL_PLAN.md and task JSONs with quality gate validation
+name: plan-verify
+description: Perform READ-ONLY verification analysis between IMPL_PLAN.md, task JSONs, and brainstorming artifacts. Generates structured report with quality gate recommendation. Does NOT modify any files.
 argument-hint: "[optional: --session session-id]"
-allowed-tools: Read(*), TodoWrite(*), Glob(*), Bash(*)
+allowed-tools: Read(*), Write(*), Glob(*), Bash(*)
 ---
 
 ## User Input
@@ -15,13 +15,26 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Goal
 
-Identify inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`role analysis documents`) before implementation. This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
+Generate a comprehensive verification report that identifies inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`role analysis documents`). This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
+
+**Output**: A structured Markdown report saved to `.workflow/active/WFS-{session}/.process/ACTION_PLAN_VERIFICATION.md` containing:
+- Executive summary with quality gate recommendation
+- Detailed findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
+- Requirements coverage analysis
+- Dependency integrity check
+- Synthesis alignment validation
+- Actionable remediation recommendations
 
 ## Operating Constraints
 
-**STRICTLY READ-ONLY**: Do **not** modify any files. Output a structured analysis report. Offer an optional remediation plan (user must explicitly approve before any follow-up editing commands).
+**STRICTLY READ-ONLY FOR SOURCE ARTIFACTS**:
+- **MUST NOT** modify `IMPL_PLAN.md`, any `task.json` files, or brainstorming artifacts
+- **MUST NOT** create or delete task files
+- **MUST ONLY** write the verification report to `.process/ACTION_PLAN_VERIFICATION.md`
 
-**Synthesis Authority**: The `role analysis documents` is **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
+**Synthesis Authority**: The `role analysis documents` are **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
+
+**Quality Gate Authority**: The verification report provides a binding recommendation (BLOCK_EXECUTION / PROCEED_WITH_FIXES / PROCEED_WITH_CAUTION / PROCEED) based on objective severity criteria. User MUST review critical/high issues before proceeding with implementation.
 
 ## Execution Steps
 
@@ -47,6 +60,12 @@ ELSE:
 session_dir = .workflow/active/WFS-{session}
 brainstorm_dir = session_dir/.brainstorming
 task_dir = session_dir/.task
+process_dir = session_dir/.process
+session_file = session_dir/workflow-session.json
+
+# Create .process directory if not exists (report output location)
+IF NOT EXISTS(process_dir):
+    bash(mkdir -p "{process_dir}")
 
 # Validate required artifacts
 # Note: "role analysis documents" refers to [role]/analysis.md files (e.g., product-manager/analysis.md)
@@ -54,7 +73,12 @@ SYNTHESIS_DIR = brainstorm_dir  # Contains role analysis files: */analysis.md
 IMPL_PLAN = session_dir/IMPL_PLAN.md
 TASK_FILES = Glob(task_dir/*.json)
 
-# Abort if missing
+# Abort if missing - in order of dependency
+SESSION_FILE_EXISTS = EXISTS(session_file)
+IF NOT SESSION_FILE_EXISTS:
+    WARNING: "workflow-session.json not found. User intent alignment verification will be skipped."
+    # Continue execution - this is optional context, not blocking
+
 SYNTHESIS_FILES = Glob(brainstorm_dir/*/analysis.md)
 IF SYNTHESIS_FILES.count == 0:
     ERROR: "No role analysis documents found in .brainstorming/*/analysis.md. Run /workflow:brainstorm:synthesis first"
@@ -73,12 +97,14 @@ IF TASK_FILES.count == 0:
 
 Load only minimal necessary context from each artifact:
 
-**From workflow-session.json** (NEW - PRIMARY REFERENCE):
+**From workflow-session.json** (OPTIONAL - Primary Reference for User Intent):
+- **ONLY IF EXISTS**: Load user intent context
 - Original user prompt/intent (project or description field)
 - User's stated goals and objectives
 - User's scope definition
+- **IF MISSING**: Set user_intent_analysis = "SKIPPED: workflow-session.json not found"
 
-**From role analysis documents**:
+**From role analysis documents** (AUTHORITATIVE SOURCE):
 - Functional Requirements (IDs, descriptions, acceptance criteria)
 - Non-Functional Requirements (IDs, targets)
 - Business Requirements (IDs, success metrics)
@@ -126,9 +152,21 @@ Create internal representations (do not include raw artifacts in output):
 
 ### 4. Detection Passes (Token-Efficient Analysis)
 
-Focus on high-signal findings. Limit to 50 findings total; aggregate remainder in overflow summary.
+**Token Budget Strategy**:
+- **Total Limit**: 50 findings maximum (aggregate remainder in overflow summary)
+- **Priority Allocation**: CRITICAL (unlimited) → HIGH (15) → MEDIUM (20) → LOW (15)
+- **Early Exit**: If CRITICAL findings > 0 in User Intent/Requirements Coverage, skip LOW/MEDIUM priority checks
 
-#### A. User Intent Alignment (NEW - CRITICAL)
+**Execution Order** (Process in sequence; skip if token budget exhausted):
+
+1. **Tier 1 (CRITICAL Path)**: A, B, C - User intent, coverage, consistency (process fully)
+2. **Tier 2 (HIGH Priority)**: D, E - Dependencies, synthesis alignment (limit 15 findings total)
+3. **Tier 3 (MEDIUM Priority)**: F - Specification quality (limit 20 findings)
+4. **Tier 4 (LOW Priority)**: G, H - Duplication, feasibility (limit 15 findings total)
+
+---
+
+#### A. User Intent Alignment (CRITICAL - Tier 1)
 
 - **Goal Alignment**: IMPL_PLAN objectives match user's original intent
 - **Scope Drift**: Plan covers user's stated scope without unauthorized expansion

.claude/commands/workflow/brainstorm/artifacts.md

@@ -1,10 +1,14 @@
 ---
 name: artifacts
 description: Interactive clarification generating confirmed guidance specification through role-based analysis and synthesis
-argument-hint: "topic or challenge description [--count N]"
+argument-hint: "[-y|--yes] topic or challenge description [--count N]"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), AskUserQuestion(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-select recommended roles, skip all clarification questions, use default answers.
+
 ## Overview
 
 Seven-phase workflow: **Context collection** → **Topic analysis** → **Role selection** → **Role questions** → **Conflict resolution** → **Final check** → **Generate specification**

.claude/commands/workflow/brainstorm/auto-parallel.md

@@ -1,10 +1,14 @@
 ---
 name: auto-parallel
 description: Parallel brainstorming automation with dynamic role selection and concurrent execution across multiple perspectives
-argument-hint: "topic or challenge description" [--count N]
+argument-hint: "[-y|--yes] topic or challenge description [--count N]"
 allowed-tools: SlashCommand(*), Task(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-select recommended roles, skip all clarification questions, use default answers.
+
 # Workflow Brainstorm Parallel Auto Command
 
 ## Coordinator Role

.claude/commands/workflow/brainstorm/synthesis.md

@@ -1,10 +1,14 @@
 ---
 name: synthesis
 description: Clarify and refine role analyses through intelligent Q&A and targeted updates with synthesis agent
-argument-hint: "[optional: --session session-id]"
+argument-hint: "[-y|--yes] [optional: --session session-id]"
 allowed-tools: Task(conceptual-planning-agent), TodoWrite(*), Read(*), Write(*), Edit(*), Glob(*), AskUserQuestion(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-select all enhancements, skip clarification questions, use default answers.
+
 ## Overview
 
 Six-phase workflow to eliminate ambiguities and enhance conceptual depth in role analyses:

.claude/commands/workflow/clean.md

@@ -1,7 +1,7 @@
 ---
 name: clean
 description: Intelligent code cleanup with mainline detection, stale artifact discovery, and safe execution
-argument-hint: "[--dry-run] [\"focus area\"]"
+argument-hint: "[-y|--yes] [--dry-run] [\"focus area\"]"
 allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Glob(*), Bash(*), Write(*)
 ---
 
@@ -21,8 +21,22 @@ Intelligent cleanup command that explores the codebase to identify the developme
 
 ```bash
 /workflow:clean                          # Full intelligent cleanup (explore → analyze → confirm → execute)
+/workflow:clean --yes                    # Auto mode (use safe defaults, no confirmation)
 /workflow:clean --dry-run                # Explore and analyze only, no execution
-/workflow:clean "auth module"            # Focus cleanup on specific area
+/workflow:clean -y "auth module"         # Auto mode with focus area
+```
+
+## Auto Mode Defaults
+
+When `--yes` or `-y` flag is used:
+- **Categories to Clean**: Auto-selects `["Sessions"]` only (safest - only workflow sessions)
+- **Risk Level**: Auto-selects `"Low only"` (only low-risk items)
+- All confirmations skipped, proceeds directly to execution
+
+**Flag Parsing**:
+```javascript
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+const dryRun = $ARGUMENTS.includes('--dry-run')
 ```
 
 ## Execution Process
@@ -329,39 +343,57 @@ To execute cleanup: /workflow:clean
 
 **Step 3.3: User Confirmation**
 ```javascript
-AskUserQuestion({
-  questions: [
-    {
-      question: "Which categories to clean?",
-      header: "Categories",
-      multiSelect: true,
-      options: [
-        {
-          label: "Sessions",
-          description: `${manifest.summary.by_category.stale_sessions} stale workflow sessions`
-        },
-        {
-          label: "Documents",
-          description: `${manifest.summary.by_category.drifted_documents} drifted documents`
-        },
-        {
-          label: "Dead Code",
-          description: `${manifest.summary.by_category.dead_code} unused code files`
-        }
-      ]
-    },
-    {
-      question: "Risk level to include?",
-      header: "Risk",
-      multiSelect: false,
-      options: [
-        { label: "Low only", description: "Safest - only obviously stale items" },
-        { label: "Low + Medium", description: "Recommended - includes likely unused items" },
-        { label: "All", description: "Aggressive - includes high-risk items" }
-      ]
-    }
-  ]
-})
+// Parse --yes flag
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+
+let userSelection
+
+if (autoYes) {
+  // Auto mode: Use safe defaults
+  console.log(`[--yes] Auto-selecting safe cleanup defaults:`)
+  console.log(`  - Categories: Sessions only`)
+  console.log(`  - Risk level: Low only`)
+
+  userSelection = {
+    categories: ["Sessions"],
+    risk: "Low only"
+  }
+} else {
+  // Interactive mode: Ask user
+  userSelection = AskUserQuestion({
+    questions: [
+      {
+        question: "Which categories to clean?",
+        header: "Categories",
+        multiSelect: true,
+        options: [
+          {
+            label: "Sessions",
+            description: `${manifest.summary.by_category.stale_sessions} stale workflow sessions`
+          },
+          {
+            label: "Documents",
+            description: `${manifest.summary.by_category.drifted_documents} drifted documents`
+          },
+          {
+            label: "Dead Code",
+            description: `${manifest.summary.by_category.dead_code} unused code files`
+          }
+        ]
+      },
+      {
+        question: "Risk level to include?",
+        header: "Risk",
+        multiSelect: false,
+        options: [
+          { label: "Low only", description: "Safest - only obviously stale items" },
+          { label: "Low + Medium", description: "Recommended - includes likely unused items" },
+          { label: "All", description: "Aggressive - includes high-risk items" }
+        ]
+      }
+    ]
+  })
+}
 ```
 
 ---

.claude/commands/workflow/debug-with-file.md

@@ -1,10 +1,14 @@
 ---
 name: debug-with-file
 description: Interactive hypothesis-driven debugging with documented exploration, understanding evolution, and Gemini-assisted correction
-argument-hint: "\"bug description or error message\""
+argument-hint: "[-y|--yes] \"bug description or error message\""
 allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm all decisions (hypotheses, fixes, iteration), use recommended settings.
+
 # Workflow Debug-With-File Command (/workflow:debug-with-file)
 
 ## Overview

.claude/commands/workflow/debug.md

@@ -1,10 +1,14 @@
 ---
 name: debug
 description: Interactive hypothesis-driven debugging with NDJSON logging, iterative until resolved
-argument-hint: "\"bug description or error message\""
+argument-hint: "[-y|--yes] \"bug description or error message\""
 allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Grep(*), Glob(*), Bash(*), Edit(*), Write(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-confirm all decisions (hypotheses, fixes, iteration), use recommended settings.
+
 # Workflow Debug Command (/workflow:debug)
 
 ## Overview

.claude/commands/workflow/execute.md

@@ -1,7 +1,7 @@
 ---
 name: execute
 description: Coordinate agent execution for workflow tasks with automatic session discovery, parallel task processing, and status tracking
-argument-hint: "[--resume-session=\"session-id\"]"
+argument-hint: "[-y|--yes] [--resume-session=\"session-id\"]"
 ---
 
 # Workflow Execute Command
@@ -11,6 +11,30 @@ Orchestrates autonomous workflow execution through systematic task discovery, ag
 
 **Resume Mode**: When called with `--resume-session` flag, skips discovery phase and directly enters TodoWrite generation and agent execution for the specified session.
 
+## Usage
+
+```bash
+# Interactive mode (with confirmations)
+/workflow:execute
+/workflow:execute --resume-session="WFS-auth"
+
+# Auto mode (skip confirmations, use defaults)
+/workflow:execute --yes
+/workflow:execute -y
+/workflow:execute -y --resume-session="WFS-auth"
+```
+
+## Auto Mode Defaults
+
+When `--yes` or `-y` flag is used:
+- **Session Selection**: Automatically selects the first (most recent) active session
+- **Completion Choice**: Automatically completes session (runs `/workflow:session:complete --yes`)
+
+**Flag Parsing**:
+```javascript
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+```
+
 ## Performance Optimization Strategy
 
 **Lazy Loading**: Task JSONs read **on-demand** during execution, not upfront. TODO_LIST.md + IMPL_PLAN.md provide metadata for planning.
@@ -122,24 +146,38 @@ List sessions with metadata and prompt user selection:
 bash(for dir in .workflow/active/WFS-*/; do [ -d "$dir" ] || continue; session=$(basename "$dir"); project=$(jq -r '.project // "Unknown"' "${dir}workflow-session.json" 2>/dev/null || echo "Unknown"); total=$(grep -c '^\- \[' "${dir}TODO_LIST.md" 2>/dev/null || echo 0); completed=$(grep -c '^\- \[x\]' "${dir}TODO_LIST.md" 2>/dev/null || echo 0); if [ "$total" -gt 0 ]; then progress=$((completed * 100 / total)); else progress=0; fi; echo "$session | $project | $completed/$total tasks ($progress%)"; done)
 ```
 
-Use AskUserQuestion to present formatted options (max 4 options shown):
+**Parse --yes flag**:
 ```javascript
-// If more than 4 sessions, show most recent 4 with "Other" option for manual input
-const sessions = getActiveSessions()  // sorted by last modified
-const displaySessions = sessions.slice(0, 4)
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+```
 
-AskUserQuestion({
-  questions: [{
-    question: "Multiple active sessions detected. Select one:",
-    header: "Session",
-    multiSelect: false,
-    options: displaySessions.map(s => ({
-      label: s.id,
-      description: `${s.project} | ${s.progress}`
-    }))
-    // Note: User can select "Other" to manually enter session ID
-  }]
-})
+**Conditional Selection**:
+```javascript
+if (autoYes) {
+  // Auto mode: Select first session (most recent)
+  const firstSession = sessions[0]
+  console.log(`[--yes] Auto-selecting session: ${firstSession.id}`)
+  selectedSessionId = firstSession.id
+  // Continue to Phase 2
+} else {
+  // Interactive mode: Use AskUserQuestion to present formatted options (max 4 options shown)
+  // If more than 4 sessions, show most recent 4 with "Other" option for manual input
+  const sessions = getActiveSessions()  // sorted by last modified
+  const displaySessions = sessions.slice(0, 4)
+
+  AskUserQuestion({
+    questions: [{
+      question: "Multiple active sessions detected. Select one:",
+      header: "Session",
+      multiSelect: false,
+      options: displaySessions.map(s => ({
+        label: s.id,
+        description: `${s.project} | ${s.progress}`
+      }))
+      // Note: User can select "Other" to manually enter session ID
+    }]
+  })
+}
 ```
 
 **Input Validation**:
@@ -252,23 +290,33 @@ while (TODO_LIST.md has pending tasks) {
 6. **User Choice**: When all tasks finished, ask user to choose next step:
 
 ```javascript
-AskUserQuestion({
-  questions: [{
-    question: "All tasks completed. What would you like to do next?",
-    header: "Next Step",
-    multiSelect: false,
-    options: [
-      {
-        label: "Enter Review",
-        description: "Run specialized review (security/architecture/quality/action-items)"
-      },
-      {
-        label: "Complete Session",
-        description: "Archive session and update manifest"
-      }
-    ]
-  }]
-})
+// Parse --yes flag
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+
+if (autoYes) {
+  // Auto mode: Complete session automatically
+  console.log(`[--yes] Auto-selecting: Complete Session`)
+  SlashCommand("/workflow:session:complete --yes")
+} else {
+  // Interactive mode: Ask user
+  AskUserQuestion({
+    questions: [{
+      question: "All tasks completed. What would you like to do next?",
+      header: "Next Step",
+      multiSelect: false,
+      options: [
+        {
+          label: "Enter Review",
+          description: "Run specialized review (security/architecture/quality/action-items)"
+        },
+        {
+          label: "Complete Session",
+          description: "Archive session and update manifest"
+        }
+      ]
+    }]
+  })
+}
 ```
 
 **Based on user selection**:

.claude/commands/workflow/lite-execute.md

@@ -1,7 +1,7 @@
 ---
 name: lite-execute
 description: Execute tasks based on in-memory plan, prompt description, or file content
-argument-hint: "[--in-memory] [\"task description\"|file-path]"
+argument-hint: "[-y|--yes] [--in-memory] [\"task description\"|file-path]"
 allowed-tools: TodoWrite(*), Task(*), Bash(*)
 ---
 
@@ -62,31 +62,49 @@ Flexible task execution command supporting three input modes: in-memory plan (fr
 
 **User Interaction**:
 ```javascript
-AskUserQuestion({
-  questions: [
-    {
-      question: "Select execution method:",
-      header: "Execution",
-      multiSelect: false,
-      options: [
-        { label: "Agent", description: "@code-developer agent" },
-        { label: "Codex", description: "codex CLI tool" },
-        { label: "Auto", description: "Auto-select based on complexity" }
-      ]
-    },
-    {
-      question: "Enable code review after execution?",
-      header: "Code Review",
-      multiSelect: false,
-      options: [
-        { label: "Skip", description: "No review" },
-        { label: "Gemini Review", description: "Gemini CLI tool" },
-        { label: "Codex Review", description: "Git-aware review (prompt OR --uncommitted)" },
-        { label: "Agent Review", description: "Current agent review" }
-      ]
-    }
-  ]
-})
+// Parse --yes flag
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+
+let userSelection
+
+if (autoYes) {
+  // Auto mode: Use defaults
+  console.log(`[--yes] Auto-confirming execution:`)
+  console.log(`  - Execution method: Auto`)
+  console.log(`  - Code review: Skip`)
+
+  userSelection = {
+    execution_method: "Auto",
+    code_review_tool: "Skip"
+  }
+} else {
+  // Interactive mode: Ask user
+  userSelection = AskUserQuestion({
+    questions: [
+      {
+        question: "Select execution method:",
+        header: "Execution",
+        multiSelect: false,
+        options: [
+          { label: "Agent", description: "@code-developer agent" },
+          { label: "Codex", description: "codex CLI tool" },
+          { label: "Auto", description: "Auto-select based on complexity" }
+        ]
+      },
+      {
+        question: "Enable code review after execution?",
+        header: "Code Review",
+        multiSelect: false,
+        options: [
+          { label: "Skip", description: "No review" },
+          { label: "Gemini Review", description: "Gemini CLI tool" },
+          { label: "Codex Review", description: "Git-aware review (prompt OR --uncommitted)" },
+          { label: "Agent Review", description: "Current agent review" }
+        ]
+      }
+    ]
+  })
+}
 ```
 
 ### Mode 3: File Content

.claude/commands/workflow/lite-fix.md

@@ -1,7 +1,7 @@
 ---
 name: lite-fix
 description: Lightweight bug diagnosis and fix workflow with intelligent severity assessment and optional hotfix mode for production incidents
-argument-hint: "[--hotfix] \"bug description or issue reference\""
+argument-hint: "[-y|--yes] [--hotfix] \"bug description or issue reference\""
 allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*)
 ---
 
@@ -25,10 +25,32 @@ Intelligent lightweight bug fixing command with dynamic workflow adaptation base
 /workflow:lite-fix [FLAGS] <BUG_DESCRIPTION>
 
 # Flags
+-y, --yes                  Skip all confirmations (auto mode)
 --hotfix, -h               Production hotfix mode (minimal diagnosis, fast fix)
 
 # Arguments
 <bug-description>          Bug description, error message, or path to .md file (required)
+
+# Examples
+/workflow:lite-fix "用户登录失败"                    # Interactive mode
+/workflow:lite-fix --yes "用户登录失败"              # Auto mode (no confirmations)
+/workflow:lite-fix -y --hotfix "生产环境数据库连接失败"   # Auto + hotfix mode
+```
+
+## Auto Mode Defaults
+
+When `--yes` or `-y` flag is used:
+- **Clarification Questions**: Skipped (no clarification phase)
+- **Fix Plan Confirmation**: Auto-selected "Allow"
+- **Execution Method**: Auto-selected "Auto"
+- **Code Review**: Auto-selected "Skip"
+- **Severity**: Uses auto-detected severity (no manual override)
+- **Hotfix Mode**: Respects --hotfix flag if present, otherwise normal mode
+
+**Flag Parsing**:
+```javascript
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+const hotfixMode = $ARGUMENTS.includes('--hotfix') || $ARGUMENTS.includes('-h')
 ```
 
 ## Execution Process
@@ -332,9 +354,17 @@ function deduplicateClarifications(clarifications) {
 
 const uniqueClarifications = deduplicateClarifications(allClarifications)
 
-// Multi-round clarification: batch questions (max 4 per round)
-// ⚠️ MUST execute ALL rounds until uniqueClarifications exhausted
-if (uniqueClarifications.length > 0) {
+// Parse --yes flag
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+
+if (autoYes) {
+  // Auto mode: Skip clarification phase
+  console.log(`[--yes] Skipping ${uniqueClarifications.length} clarification questions`)
+  console.log(`Proceeding to fix planning with diagnosis results...`)
+  // Continue to Phase 3
+} else if (uniqueClarifications.length > 0) {
+  // Interactive mode: Multi-round clarification
+  // ⚠️ MUST execute ALL rounds until uniqueClarifications exhausted
   const BATCH_SIZE = 4
   const totalRounds = Math.ceil(uniqueClarifications.length / BATCH_SIZE)
 
@@ -600,40 +630,60 @@ ${fixPlan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.scope})`).join('\n')}
 
 **Step 4.2: Collect Confirmation**
 ```javascript
-AskUserQuestion({
-  questions: [
-    {
-      question: `Confirm fix plan? (${fixPlan.tasks.length} tasks, ${fixPlan.severity} severity)`,
-      header: "Confirm",
-      multiSelect: true,
-      options: [
-        { label: "Allow", description: "Proceed as-is" },
-        { label: "Modify", description: "Adjust before execution" },
-        { label: "Cancel", description: "Abort workflow" }
-      ]
-    },
-    {
-      question: "Execution method:",
-      header: "Execution",
-      multiSelect: false,
-      options: [
-        { label: "Agent", description: "@code-developer agent" },
-        { label: "Codex", description: "codex CLI tool" },
-        { label: "Auto", description: `Auto: ${fixPlan.severity === 'Low' ? 'Agent' : 'Codex'}` }
-      ]
-    },
-    {
-      question: "Code review after fix?",
-      header: "Review",
-      multiSelect: false,
-      options: [
-        { label: "Gemini Review", description: "Gemini CLI" },
-        { label: "Agent Review", description: "@code-reviewer" },
-        { label: "Skip", description: "No review" }
-      ]
-    }
-  ]
-})
+// Parse --yes flag
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+
+let userSelection
+
+if (autoYes) {
+  // Auto mode: Use defaults
+  console.log(`[--yes] Auto-confirming fix plan:`)
+  console.log(`  - Confirmation: Allow`)
+  console.log(`  - Execution: Auto`)
+  console.log(`  - Review: Skip`)
+
+  userSelection = {
+    confirmation: "Allow",
+    execution_method: "Auto",
+    code_review_tool: "Skip"
+  }
+} else {
+  // Interactive mode: Ask user
+  userSelection = AskUserQuestion({
+    questions: [
+      {
+        question: `Confirm fix plan? (${fixPlan.tasks.length} tasks, ${fixPlan.severity} severity)`,
+        header: "Confirm",
+        multiSelect: false,
+        options: [
+          { label: "Allow", description: "Proceed as-is" },
+          { label: "Modify", description: "Adjust before execution" },
+          { label: "Cancel", description: "Abort workflow" }
+        ]
+      },
+      {
+        question: "Execution method:",
+        header: "Execution",
+        multiSelect: false,
+        options: [
+          { label: "Agent", description: "@code-developer agent" },
+          { label: "Codex", description: "codex CLI tool" },
+          { label: "Auto", description: `Auto: ${fixPlan.severity === 'Low' ? 'Agent' : 'Codex'}` }
+        ]
+      },
+      {
+        question: "Code review after fix?",
+        header: "Review",
+        multiSelect: false,
+        options: [
+          { label: "Gemini Review", description: "Gemini CLI" },
+          { label: "Agent Review", description: "@code-reviewer" },
+          { label: "Skip", description: "No review" }
+        ]
+      }
+    ]
+  })
+}
 ```
 
 ---

.claude/commands/workflow/lite-lite-lite.md

@@ -1,10 +1,14 @@
 ---
 name: workflow:lite-lite-lite
 description: Ultra-lightweight multi-tool analysis and direct execution. No artifacts for simple tasks; auto-creates planning docs in .workflow/.scratchpad/ for complex tasks. Auto tool selection based on task analysis, user-driven iteration via AskUser.
-argument-hint: "<task description>"
+argument-hint: "[-y|--yes] <task description>"
 allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Bash(*), Write(*), mcp__ace-tool__search_context(*), mcp__ccw-tools__write_file(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Skip clarification questions, auto-select tools, execute directly with recommended settings.
+
 # Ultra-Lite Multi-Tool Workflow
 
 ## Quick Start

.claude/commands/workflow/lite-plan.md

@@ -1,7 +1,7 @@
 ---
 name: lite-plan
 description: Lightweight interactive planning workflow with in-memory planning, code exploration, and execution execute to lite-execute after user confirmation
-argument-hint: "[-e|--explore] \"task description\"|file.md"
+argument-hint: "[-y|--yes] [-e|--explore] \"task description\"|file.md"
 allowed-tools: TodoWrite(*), Task(*), SlashCommand(*), AskUserQuestion(*)
 ---
 
@@ -25,10 +25,30 @@ Intelligent lightweight planning command with dynamic workflow adaptation based
 /workflow:lite-plan [FLAGS] <TASK_DESCRIPTION>
 
 # Flags
+-y, --yes                  Skip all confirmations (auto mode)
 -e, --explore              Force code exploration phase (overrides auto-detection)
 
 # Arguments
 <task-description>         Task description or path to .md file (required)
+
+# Examples
+/workflow:lite-plan "实现JWT认证"                    # Interactive mode
+/workflow:lite-plan --yes "实现JWT认证"              # Auto mode (no confirmations)
+/workflow:lite-plan -y -e "优化数据库查询性能"       # Auto mode + force exploration
+```
+
+## Auto Mode Defaults
+
+When `--yes` or `-y` flag is used:
+- **Clarification Questions**: Skipped (no clarification phase)
+- **Plan Confirmation**: Auto-selected "Allow"
+- **Execution Method**: Auto-selected "Auto"
+- **Code Review**: Auto-selected "Skip"
+
+**Flag Parsing**:
+```javascript
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+const forceExplore = $ARGUMENTS.includes('--explore') || $ARGUMENTS.includes('-e')
 ```
 
 ## Execution Process
@@ -323,8 +343,16 @@ explorations.forEach(exp => {
 // - Produce dedupedClarifications with unique intents only
 const dedupedClarifications = intelligentMerge(allClarifications)
 
-// Multi-round clarification: batch questions (max 4 per round)
-if (dedupedClarifications.length > 0) {
+// Parse --yes flag
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+
+if (autoYes) {
+  // Auto mode: Skip clarification phase
+  console.log(`[--yes] Skipping ${dedupedClarifications.length} clarification questions`)
+  console.log(`Proceeding to planning with exploration results...`)
+  // Continue to Phase 3
+} else if (dedupedClarifications.length > 0) {
+  // Interactive mode: Multi-round clarification
   const BATCH_SIZE = 4
   const totalRounds = Math.ceil(dedupedClarifications.length / BATCH_SIZE)
 
@@ -497,42 +525,62 @@ ${plan.tasks.map((t, i) => `${i+1}. ${t.title} (${t.file})`).join('\n')}
 
 **Step 4.2: Collect Confirmation**
 ```javascript
-// Note: Execution "Other" option allows specifying CLI tools from ~/.claude/cli-tools.json
-AskUserQuestion({
-  questions: [
-    {
-      question: `Confirm plan? (${plan.tasks.length} tasks, ${plan.complexity})`,
-      header: "Confirm",
-      multiSelect: true,
-      options: [
-        { label: "Allow", description: "Proceed as-is" },
-        { label: "Modify", description: "Adjust before execution" },
-        { label: "Cancel", description: "Abort workflow" }
-      ]
-    },
-    {
-      question: "Execution method:",
-      header: "Execution",
-      multiSelect: false,
-      options: [
-        { label: "Agent", description: "@code-developer agent" },
-        { label: "Codex", description: "codex CLI tool" },
-        { label: "Auto", description: `Auto: ${plan.complexity === 'Low' ? 'Agent' : 'Codex'}` }
-      ]
-    },
-    {
-      question: "Code review after execution?",
-      header: "Review",
-      multiSelect: false,
-      options: [
-        { label: "Gemini Review", description: "Gemini CLI review" },
-        { label: "Codex Review", description: "Git-aware review (prompt OR --uncommitted)" },
-        { label: "Agent Review", description: "@code-reviewer agent" },
-        { label: "Skip", description: "No review" }
-      ]
-    }
-  ]
-})
+// Parse --yes flag
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+
+let userSelection
+
+if (autoYes) {
+  // Auto mode: Use defaults
+  console.log(`[--yes] Auto-confirming plan:`)
+  console.log(`  - Confirmation: Allow`)
+  console.log(`  - Execution: Auto`)
+  console.log(`  - Review: Skip`)
+
+  userSelection = {
+    confirmation: "Allow",
+    execution_method: "Auto",
+    code_review_tool: "Skip"
+  }
+} else {
+  // Interactive mode: Ask user
+  // Note: Execution "Other" option allows specifying CLI tools from ~/.claude/cli-tools.json
+  userSelection = AskUserQuestion({
+    questions: [
+      {
+        question: `Confirm plan? (${plan.tasks.length} tasks, ${plan.complexity})`,
+        header: "Confirm",
+        multiSelect: false,
+        options: [
+          { label: "Allow", description: "Proceed as-is" },
+          { label: "Modify", description: "Adjust before execution" },
+          { label: "Cancel", description: "Abort workflow" }
+        ]
+      },
+      {
+        question: "Execution method:",
+        header: "Execution",
+        multiSelect: false,
+        options: [
+          { label: "Agent", description: "@code-developer agent" },
+          { label: "Codex", description: "codex CLI tool" },
+          { label: "Auto", description: `Auto: ${plan.complexity === 'Low' ? 'Agent' : 'Codex'}` }
+        ]
+      },
+      {
+        question: "Code review after execution?",
+        header: "Review",
+        multiSelect: false,
+        options: [
+          { label: "Gemini Review", description: "Gemini CLI review" },
+          { label: "Codex Review", description: "Git-aware review (prompt OR --uncommitted)" },
+          { label: "Agent Review", description: "@code-reviewer agent" },
+          { label: "Skip", description: "No review" }
+        ]
+      }
+    ]
+  })
+}
 ```
 
 ---

.claude/commands/workflow/multi-cli-plan.md

@@ -1,10 +1,14 @@
 ---
 name: workflow:multi-cli-plan
 description: Multi-CLI collaborative planning workflow with ACE context gathering and iterative cross-verification. Uses cli-discuss-agent for Gemini+Codex+Claude analysis to converge on optimal execution plan.
-argument-hint: "<task description> [--max-rounds=3] [--tools=gemini,codex] [--mode=parallel|serial]"
+argument-hint: "[-y|--yes] <task description> [--max-rounds=3] [--tools=gemini,codex] [--mode=parallel|serial]"
 allowed-tools: TodoWrite(*), Task(*), AskUserQuestion(*), Read(*), Bash(*), Write(*), mcp__ace-tool__search_context(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-approve plan, use recommended solution and execution method (Agent, Skip review).
+
 # Multi-CLI Collaborative Planning Command
 
 ## Quick Start

.claude/commands/workflow/plan-verify.md

@@ -0,0 +1,527 @@
+---
+name: plan-verify
+description: Perform READ-ONLY verification analysis between IMPL_PLAN.md, task JSONs, and brainstorming artifacts. Generates structured report with quality gate recommendation. Does NOT modify any files.
+argument-hint: "[optional: --session session-id]"
+allowed-tools: Read(*), Write(*), Glob(*), Bash(*)
+---
+
+## User Input
+
+```text
+$ARGUMENTS
+```
+
+You **MUST** consider the user input before proceeding (if not empty).
+
+## Goal
+
+Generate a comprehensive verification report that identifies inconsistencies, duplications, ambiguities, and underspecified items between action planning artifacts (`IMPL_PLAN.md`, `task.json`) and brainstorming artifacts (`role analysis documents`). This command MUST run only after `/workflow:plan` has successfully produced complete `IMPL_PLAN.md` and task JSON files.
+
+**Output**: A structured Markdown report saved to `.workflow/active/WFS-{session}/.process/PLAN_VERIFICATION.md` containing:
+- Executive summary with quality gate recommendation
+- Detailed findings by severity (CRITICAL/HIGH/MEDIUM/LOW)
+- Requirements coverage analysis
+- Dependency integrity check
+- Synthesis alignment validation
+- Actionable remediation recommendations
+
+## Operating Constraints
+
+**STRICTLY READ-ONLY FOR SOURCE ARTIFACTS**:
+- **MUST NOT** modify `IMPL_PLAN.md`, any `task.json` files, or brainstorming artifacts
+- **MUST NOT** create or delete task files
+- **MUST ONLY** write the verification report to `.process/PLAN_VERIFICATION.md`
+
+**Synthesis Authority**: The `role analysis documents` are **authoritative** for requirements and design decisions. Any conflicts between IMPL_PLAN/tasks and synthesis are automatically CRITICAL and require adjustment of the plan/tasks—not reinterpretation of requirements.
+
+**Quality Gate Authority**: The verification report provides a binding recommendation (BLOCK_EXECUTION / PROCEED_WITH_FIXES / PROCEED_WITH_CAUTION / PROCEED) based on objective severity criteria. User MUST review critical/high issues before proceeding with implementation.
+
+## Execution Steps
+
+### 1. Initialize Analysis Context
+
+```bash
+# Detect active workflow session
+IF --session parameter provided:
+    session_id = provided session
+ELSE:
+    # Auto-detect active session
+    active_sessions = bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
+    IF active_sessions is empty:
+        ERROR: "No active workflow session found. Use --session <session-id>"
+        EXIT
+    ELSE IF active_sessions has multiple entries:
+        # Use most recently modified session
+        session_id = bash(ls -td .workflow/active/WFS-*/ 2>/dev/null | head -1 | xargs basename)
+    ELSE:
+        session_id = basename(active_sessions[0])
+
+# Derive absolute paths
+session_dir = .workflow/active/WFS-{session}
+brainstorm_dir = session_dir/.brainstorming
+task_dir = session_dir/.task
+process_dir = session_dir/.process
+session_file = session_dir/workflow-session.json
+
+# Create .process directory if not exists (report output location)
+IF NOT EXISTS(process_dir):
+    bash(mkdir -p "{process_dir}")
+
+# Validate required artifacts
+# Note: "role analysis documents" refers to [role]/analysis.md files (e.g., product-manager/analysis.md)
+SYNTHESIS_DIR = brainstorm_dir  # Contains role analysis files: */analysis.md
+IMPL_PLAN = session_dir/IMPL_PLAN.md
+TASK_FILES = Glob(task_dir/*.json)
+
+# Abort if missing - in order of dependency
+SESSION_FILE_EXISTS = EXISTS(session_file)
+IF NOT SESSION_FILE_EXISTS:
+    WARNING: "workflow-session.json not found. User intent alignment verification will be skipped."
+    # Continue execution - this is optional context, not blocking
+
+SYNTHESIS_FILES = Glob(brainstorm_dir/*/analysis.md)
+IF SYNTHESIS_FILES.count == 0:
+    ERROR: "No role analysis documents found in .brainstorming/*/analysis.md. Run /workflow:brainstorm:synthesis first"
+    EXIT
+
+IF NOT EXISTS(IMPL_PLAN):
+    ERROR: "IMPL_PLAN.md not found. Run /workflow:plan first"
+    EXIT
+
+IF TASK_FILES.count == 0:
+    ERROR: "No task JSON files found. Run /workflow:plan first"
+    EXIT
+```
+
+### 2. Load Artifacts (Progressive Disclosure)
+
+Load only minimal necessary context from each artifact:
+
+**From workflow-session.json** (OPTIONAL - Primary Reference for User Intent):
+- **ONLY IF EXISTS**: Load user intent context
+- Original user prompt/intent (project or description field)
+- User's stated goals and objectives
+- User's scope definition
+- **IF MISSING**: Set user_intent_analysis = "SKIPPED: workflow-session.json not found"
+
+**From role analysis documents** (AUTHORITATIVE SOURCE):
+- Functional Requirements (IDs, descriptions, acceptance criteria)
+- Non-Functional Requirements (IDs, targets)
+- Business Requirements (IDs, success metrics)
+- Key Architecture Decisions
+- Risk factors and mitigation strategies
+- Implementation Roadmap (high-level phases)
+
+**From IMPL_PLAN.md**:
+- Summary and objectives
+- Context Analysis
+- Implementation Strategy
+- Task Breakdown Summary
+- Success Criteria
+- Brainstorming Artifacts References (if present)
+
+**From task.json files**:
+- Task IDs
+- Titles and descriptions
+- Status
+- Dependencies (depends_on, blocks)
+- Context (requirements, focus_paths, acceptance, artifacts)
+- Flow control (pre_analysis, implementation_approach)
+- Meta (complexity, priority)
+
+### 3. Build Semantic Models
+
+Create internal representations (do not include raw artifacts in output):
+
+**Requirements inventory**:
+- Each functional/non-functional/business requirement with stable ID
+- Requirement text, acceptance criteria, priority
+
+**Architecture decisions inventory**:
+- ADRs from synthesis
+- Technology choices
+- Data model references
+
+**Task coverage mapping**:
+- Map each task to one or more requirements (by ID reference or keyword inference)
+- Map each requirement to covering tasks
+
+**Dependency graph**:
+- Task-to-task dependencies (depends_on, blocks)
+- Requirement-level dependencies (from synthesis)
+
+### 4. Detection Passes (Token-Efficient Analysis)
+
+**Token Budget Strategy**:
+- **Total Limit**: 50 findings maximum (aggregate remainder in overflow summary)
+- **Priority Allocation**: CRITICAL (unlimited) → HIGH (15) → MEDIUM (20) → LOW (15)
+- **Early Exit**: If CRITICAL findings > 0 in User Intent/Requirements Coverage, skip LOW/MEDIUM priority checks
+
+**Execution Order** (Process in sequence; skip if token budget exhausted):
+
+1. **Tier 1 (CRITICAL Path)**: A, B, C - User intent, coverage, consistency (process fully)
+2. **Tier 2 (HIGH Priority)**: D, E - Dependencies, synthesis alignment (limit 15 findings total)
+3. **Tier 3 (MEDIUM Priority)**: F - Specification quality (limit 20 findings)
+4. **Tier 4 (LOW Priority)**: G, H - Duplication, feasibility (limit 15 findings total)
+
+---
+
+#### A. User Intent Alignment (CRITICAL - Tier 1)
+
+- **Goal Alignment**: IMPL_PLAN objectives match user's original intent
+- **Scope Drift**: Plan covers user's stated scope without unauthorized expansion
+- **Success Criteria Match**: Plan's success criteria reflect user's expectations
+- **Intent Conflicts**: Tasks contradicting user's original objectives
+
+#### B. Requirements Coverage Analysis
+
+- **Orphaned Requirements**: Requirements in synthesis with zero associated tasks
+- **Unmapped Tasks**: Tasks with no clear requirement linkage
+- **NFR Coverage Gaps**: Non-functional requirements (performance, security, scalability) not reflected in tasks
+
+#### C. Consistency Validation
+
+- **Requirement Conflicts**: Tasks contradicting synthesis requirements
+- **Architecture Drift**: IMPL_PLAN architecture not matching synthesis ADRs
+- **Terminology Drift**: Same concept named differently across IMPL_PLAN and tasks
+- **Data Model Inconsistency**: Tasks referencing entities/fields not in synthesis data model
+
+#### D. Dependency Integrity
+
+- **Circular Dependencies**: Task A depends on B, B depends on C, C depends on A
+- **Missing Dependencies**: Task requires outputs from another task but no explicit dependency
+- **Broken Dependencies**: Task depends on non-existent task ID
+- **Logical Ordering Issues**: Implementation tasks before foundational setup without dependency note
+
+#### E. Synthesis Alignment
+
+- **Priority Conflicts**: High-priority synthesis requirements mapped to low-priority tasks
+- **Success Criteria Mismatch**: IMPL_PLAN success criteria not covering synthesis acceptance criteria
+- **Risk Mitigation Gaps**: Critical risks in synthesis without corresponding mitigation tasks
+
+#### F. Task Specification Quality
+
+- **Ambiguous Focus Paths**: Tasks with vague or missing focus_paths
+- **Underspecified Acceptance**: Tasks without clear acceptance criteria
+- **Missing Artifacts References**: Tasks not referencing relevant brainstorming artifacts in context.artifacts
+- **Weak Flow Control**: Tasks without clear implementation_approach or pre_analysis steps
+- **Missing Target Files**: Tasks without flow_control.target_files specification
+
+#### G. Duplication Detection
+
+- **Overlapping Task Scope**: Multiple tasks with nearly identical descriptions
+- **Redundant Requirements Coverage**: Same requirement covered by multiple tasks without clear partitioning
+
+#### H. Feasibility Assessment
+
+- **Complexity Misalignment**: Task marked "simple" but requires multiple file modifications
+- **Resource Conflicts**: Parallel tasks requiring same resources/files
+- **Skill Gap Risks**: Tasks requiring skills not in team capability assessment (from synthesis)
+
+### 5. Severity Assignment
+
+Use this heuristic to prioritize findings:
+
+- **CRITICAL**:
+  - Violates user's original intent (goal misalignment, scope drift)
+  - Violates synthesis authority (requirement conflict)
+  - Core requirement with zero coverage
+  - Circular dependencies
+  - Broken dependencies
+
+- **HIGH**:
+  - NFR coverage gaps
+  - Priority conflicts
+  - Missing risk mitigation tasks
+  - Ambiguous acceptance criteria
+
+- **MEDIUM**:
+  - Terminology drift
+  - Missing artifacts references
+  - Weak flow control
+  - Logical ordering issues
+
+- **LOW**:
+  - Style/wording improvements
+  - Minor redundancy not affecting execution
+
+### 6. Produce Compact Analysis Report
+
+**Report Generation**: Generate report content and save to file.
+
+Output a Markdown report with the following structure:
+
+```markdown
+# Plan Verification Report
+
+**Session**: WFS-{session-id}
+**Generated**: {timestamp}
+**Artifacts Analyzed**: role analysis documents, IMPL_PLAN.md, {N} task files
+**User Intent Analysis**: {user_intent_analysis or "SKIPPED: workflow-session.json not found"}
+
+---
+
+## Executive Summary
+
+### Quality Gate Decision
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Overall Risk Level | CRITICAL \| HIGH \| MEDIUM \| LOW | {status_emoji} |
+| Critical Issues | {count} | 🔴 |
+| High Issues | {count} | 🟠 |
+| Medium Issues | {count} | 🟡 |
+| Low Issues | {count} | 🟢 |
+
+### Recommendation
+
+**{RECOMMENDATION}**
+
+**Decision Rationale**:
+{brief explanation based on severity criteria}
+
+**Quality Gate Criteria**:
+- **BLOCK_EXECUTION**: Critical issues > 0 (must fix before proceeding)
+- **PROCEED_WITH_FIXES**: Critical = 0, High > 0 (fix recommended before execution)
+- **PROCEED_WITH_CAUTION**: Critical = 0, High = 0, Medium > 0 (proceed with awareness)
+- **PROCEED**: Only Low issues or None (safe to execute)
+
+---
+
+## Findings Summary
+
+| ID | Category | Severity | Location(s) | Summary | Recommendation |
+|----|----------|----------|-------------|---------|----------------|
+| C1 | Coverage | CRITICAL | synthesis:FR-03 | Requirement "User auth" has zero task coverage | Add authentication implementation task |
+| H1 | Consistency | HIGH | IMPL-1.2 vs synthesis:ADR-02 | Task uses REST while synthesis specifies GraphQL | Align task with ADR-02 decision |
+| M1 | Specification | MEDIUM | IMPL-2.1 | Missing context.artifacts reference | Add @synthesis reference |
+| L1 | Duplication | LOW | IMPL-3.1, IMPL-3.2 | Similar scope | Consider merging |
+
+(Generate stable IDs prefixed by severity initial: C/H/M/L + number)
+
+---
+
+## User Intent Alignment Analysis
+
+{IF user_intent_analysis != "SKIPPED"}
+
+### Goal Alignment
+- **User Intent**: {user_original_intent}
+- **IMPL_PLAN Objectives**: {plan_objectives}
+- **Alignment Status**: {ALIGNED/MISALIGNED/PARTIAL}
+- **Findings**: {specific alignment issues}
+
+### Scope Verification
+- **User Scope**: {user_defined_scope}
+- **Plan Scope**: {plan_actual_scope}
+- **Drift Detection**: {NONE/MINOR/MAJOR}
+- **Findings**: {specific scope issues}
+
+{ELSE}
+> ⚠️ User intent alignment analysis was skipped because workflow-session.json was not found.
+
+{END IF}
+
+---
+
+## Requirements Coverage Analysis
+
+### Functional Requirements
+
+| Requirement ID | Requirement Summary | Has Task? | Task IDs | Priority Match | Notes |
+|----------------|---------------------|-----------|----------|----------------|-------|
+| FR-01 | User authentication | Yes | IMPL-1.1, IMPL-1.2 | Match | Complete |
+| FR-02 | Data export | Yes | IMPL-2.3 | Mismatch | High req → Med priority task |
+| FR-03 | Profile management | No | - | - | **CRITICAL: Zero coverage** |
+
+### Non-Functional Requirements
+
+| Requirement ID | Requirement Summary | Has Task? | Task IDs | Notes |
+|----------------|---------------------|-----------|----------|-------|
+| NFR-01 | Response time <200ms | No | - | **HIGH: No performance tasks** |
+| NFR-02 | Security compliance | Yes | IMPL-4.1 | Complete |
+
+### Business Requirements
+
+| Requirement ID | Requirement Summary | Has Task? | Task IDs | Notes |
+|----------------|---------------------|-----------|----------|-------|
+| BR-01 | Launch by Q2 | Yes | IMPL-1.* through IMPL-5.* | Timeline realistic |
+
+### Coverage Metrics
+
+| Requirement Type | Total | Covered | Coverage % |
+|------------------|-------|---------|------------|
+| Functional | {count} | {count} | {percent}% |
+| Non-Functional | {count} | {count} | {percent}% |
+| Business | {count} | {count} | {percent}% |
+| **Overall** | **{total}** | **{covered}** | **{percent}%** |
+
+---
+
+## Dependency Integrity
+
+### Dependency Graph Analysis
+
+**Circular Dependencies**: {None or List}
+
+**Broken Dependencies**:
+- IMPL-2.3 depends on "IMPL-2.4" (non-existent)
+
+**Missing Dependencies**:
+- IMPL-5.1 (integration test) has no dependency on IMPL-1.* (implementation tasks)
+
+**Logical Ordering Issues**:
+{List or "None detected"}
+
+---
+
+## Synthesis Alignment Issues
+
+| Issue Type | Synthesis Reference | IMPL_PLAN/Task | Impact | Recommendation |
+|------------|---------------------|----------------|--------|----------------|
+| Architecture Conflict | synthesis:ADR-01 (JWT auth) | IMPL_PLAN uses session cookies | HIGH | Update IMPL_PLAN to use JWT |
+| Priority Mismatch | synthesis:FR-02 (High) | IMPL-2.3 (Medium) | MEDIUM | Elevate task priority |
+| Missing Risk Mitigation | synthesis:Risk-03 (API rate limits) | No mitigation tasks | HIGH | Add rate limiting implementation task |
+
+---
+
+## Task Specification Quality
+
+### Aggregate Statistics
+
+| Quality Dimension | Tasks Affected | Percentage |
+|-------------------|----------------|------------|
+| Missing Artifacts References | {count} | {percent}% |
+| Weak Flow Control | {count} | {percent}% |
+| Missing Target Files | {count} | {percent}% |
+| Ambiguous Focus Paths | {count} | {percent}% |
+
+### Sample Issues
+
+- **IMPL-1.2**: No context.artifacts reference to synthesis
+- **IMPL-3.1**: Missing flow_control.target_files specification
+- **IMPL-4.2**: Vague focus_paths ["src/"] - needs refinement
+
+---
+
+## Feasibility Concerns
+
+| Concern | Tasks Affected | Issue | Recommendation |
+|---------|----------------|-------|----------------|
+| Skill Gap | IMPL-6.1, IMPL-6.2 | Requires Kubernetes expertise not in team | Add training task or external consultant |
+| Resource Conflict | IMPL-3.1, IMPL-3.2 | Both modify src/auth/service.ts in parallel | Add dependency or serialize |
+
+---
+
+## Detailed Findings by Severity
+
+### CRITICAL Issues ({count})
+
+{Detailed breakdown of each critical issue with location, impact, and recommendation}
+
+### HIGH Issues ({count})
+
+{Detailed breakdown of each high issue with location, impact, and recommendation}
+
+### MEDIUM Issues ({count})
+
+{Detailed breakdown of each medium issue with location, impact, and recommendation}
+
+### LOW Issues ({count})
+
+{Detailed breakdown of each low issue with location, impact, and recommendation}
+
+---
+
+## Metrics Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Requirements | {count} ({functional} functional, {nonfunctional} non-functional, {business} business) |
+| Total Tasks | {count} |
+| Overall Coverage | {percent}% ({covered}/{total} requirements with ≥1 task) |
+| Critical Issues | {count} |
+| High Issues | {count} |
+| Medium Issues | {count} |
+| Low Issues | {count} |
+| Total Findings | {total_findings} |
+
+---
+
+## Remediation Recommendations
+
+### Priority Order
+
+1. **CRITICAL** - Must fix before proceeding
+2. **HIGH** - Fix before execution
+3. **MEDIUM** - Fix during or after implementation
+4. **LOW** - Optional improvements
+
+### Next Steps
+
+Based on the quality gate recommendation ({RECOMMENDATION}):
+
+{IF BLOCK_EXECUTION}
+**🛑 BLOCK EXECUTION**
+
+You must resolve all CRITICAL issues before proceeding with implementation:
+
+1. Review each critical issue in detail
+2. Determine remediation approach (modify IMPL_PLAN.md, update task.json, or add new tasks)
+3. Apply fixes systematically
+4. Re-run verification to confirm resolution
+
+{ELSE IF PROCEED_WITH_FIXES}
+**⚠️ PROCEED WITH FIXES RECOMMENDED**
+
+No critical issues detected, but HIGH issues exist. Recommended workflow:
+
+1. Review high-priority issues
+2. Apply fixes before execution for optimal results
+3. Re-run verification (optional)
+
+{ELSE IF PROCEED_WITH_CAUTION}
+**✅ PROCEED WITH CAUTION**
+
+Only MEDIUM issues detected. You may proceed with implementation:
+
+- Address medium issues during or after implementation
+- Maintain awareness of identified concerns
+
+{ELSE}
+**✅ PROCEED**
+
+No significant issues detected. Safe to execute implementation workflow.
+
+{END IF}
+
+---
+
+**Report End**
+```
+
+### 7. Save and Display Report
+
+**Step 7.1: Save Report**:
+```bash
+report_path = ".workflow/active/WFS-{session}/.process/PLAN_VERIFICATION.md"
+Write(report_path, full_report_content)
+```
+
+**Step 7.2: Display Summary to User**:
+```bash
+# Display executive summary in terminal
+echo "=== Plan Verification Complete ==="
+echo "Report saved to: {report_path}"
+echo ""
+echo "Quality Gate: {RECOMMENDATION}"
+echo "Critical: {count} | High: {count} | Medium: {count} | Low: {count}"
+echo ""
+echo "Next: Review full report for detailed findings and recommendations"
+```
+
+**Step 7.3: Completion**:
+- Report is saved to `.process/PLAN_VERIFICATION.md`
+- User can review findings and decide on remediation approach
+- No automatic modifications are made to source artifacts
+- User can manually apply fixes or use separate remediation command (if available)

.claude/commands/workflow/plan.md

@@ -1,10 +1,14 @@
 ---
 name: plan
 description: 5-phase planning workflow with action-planning-agent task generation, outputs IMPL_PLAN.md and task JSONs
-argument-hint: "\"text description\"|file.md"
+argument-hint: "[-y|--yes] \"text description\"|file.md"
 allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-continue all phases (skip confirmations), use recommended conflict resolutions.
+
 # Workflow Plan Command (/workflow:plan)
 
 ## Coordinator Role
@@ -318,11 +322,11 @@ Tasks generated: [count]
 Plan: .workflow/active/[sessionId]/IMPL_PLAN.md
 
 Recommended Next Steps:
-1. /workflow:action-plan-verify --session [sessionId]  # Verify plan quality before execution
+1. /workflow:plan-verify --session [sessionId]  # Verify plan quality before execution
 2. /workflow:status  # Review task breakdown
 3. /workflow:execute  # Start implementation (after verification)
 
-Quality Gate: Consider running /workflow:action-plan-verify to catch issues early
+Quality Gate: Consider running /workflow:plan-verify to catch issues early
 ```
 
 ## TodoWrite Pattern
@@ -546,6 +550,6 @@ CONSTRAINTS: [Limitations or boundaries]
 - `/workflow:tools:task-generate-agent` - Phase 4: Generate task JSON files with agent-driven approach
 
 **Follow-up Commands**:
-- `/workflow:action-plan-verify` - Recommended: Verify plan quality and catch issues before execution
+- `/workflow:plan-verify` - Recommended: Verify plan quality and catch issues before execution
 - `/workflow:status` - Review task breakdown and current progress
 - `/workflow:execute` - Begin implementation of generated tasks

.claude/commands/workflow/replan.md

@@ -1,7 +1,7 @@
 ---
 name: replan
 description: Interactive workflow replanning with session-level artifact updates and boundary clarification through guided questioning
-argument-hint: "[--session session-id] [task-id] \"requirements\"|file.md [--interactive]"
+argument-hint: "[-y|--yes] [--session session-id] [task-id] \"requirements\"|file.md [--interactive]"
 allowed-tools: Read(*), Write(*), Edit(*), TodoWrite(*), Glob(*), Bash(*)
 ---
 
@@ -117,10 +117,48 @@ const taskId = taskIdMatch?.[1]
 
 ---
 
+### Auto Mode Support
+
+When `--yes` or `-y` flag is used, the command skips interactive clarification and uses safe defaults:
+
+```javascript
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+```
+
+**Auto Mode Defaults**:
+- **Modification Scope**: `tasks_only` (safest - only update task details)
+- **Affected Modules**: All modules related to the task
+- **Task Changes**: `update_only` (no structural changes)
+- **Dependency Changes**: `no` (preserve existing dependencies)
+- **User Confirmation**: Auto-confirm execution
+
+**Note**: `--interactive` flag overrides `--yes` flag (forces interactive mode).
+
+---
+
 ### Phase 2: Interactive Requirement Clarification
 
 **Purpose**: Define modification scope through guided questioning
 
+**Auto Mode Check**:
+```javascript
+if (autoYes && !interactive) {
+  // Use defaults and skip to Phase 3
+  console.log(`[--yes] Using safe defaults for replan:`)
+  console.log(`  - Scope: tasks_only`)
+  console.log(`  - Changes: update_only`)
+  console.log(`  - Dependencies: preserve existing`)
+
+  userSelections = {
+    scope: 'tasks_only',
+    modules: 'all_affected',
+    task_changes: 'update_only',
+    dependency_changes: false
+  }
+  // Proceed to Phase 3
+}
+```
+
 #### Session Mode Questions
 
 **Q1: Modification Scope**
@@ -228,10 +266,29 @@ interface ImpactAnalysis {
 **Step 3.3: User Confirmation**
 
 ```javascript
-Options:
-- 确认执行: 开始应用所有修改
-- 调整计划: 重新回答问题调整范围
-- 取消操作: 放弃本次重规划
+// Parse --yes flag
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+
+if (autoYes) {
+  // Auto mode: Auto-confirm execution
+  console.log(`[--yes] Auto-confirming replan execution`)
+  userConfirmation = '确认执行'
+  // Proceed to Phase 4
+} else {
+  // Interactive mode: Ask user
+  AskUserQuestion({
+    questions: [{
+      question: "修改计划已生成，请确认操作:",
+      header: "Confirm",
+      options: [
+        { label: "确认执行", description: "开始应用所有修改" },
+        { label: "调整计划", description: "重新回答问题调整范围" },
+        { label: "取消操作", description: "放弃本次重规划" }
+      ],
+      multiSelect: false
+    }]
+  })
+}
 ```
 
 **Output**: Modification plan confirmed or adjusted

.claude/commands/workflow/review-fix.md

@@ -605,6 +605,4 @@ Use `ccw view` to open the workflow dashboard in browser:
 
 ```bash
 ccw view
-```
-
-
+```

.claude/commands/workflow/session/complete.md

@@ -1,8 +1,10 @@
 ---
 name: complete
 description: Mark active workflow session as complete, archive with lessons learned, update manifest, remove active flag
+argument-hint: "[-y|--yes] [--detailed]"
 examples:
   - /workflow:session:complete
+  - /workflow:session:complete --yes
   - /workflow:session:complete --detailed
 ---
 
@@ -139,20 +141,41 @@ test -f .workflow/project-tech.json || echo "SKIP"
 After successful archival, prompt user to capture learnings:
 
 ```javascript
-AskUserQuestion({
-  questions: [{
-    question: "Would you like to solidify learnings from this session into project guidelines?",
-    header: "Solidify",
-    options: [
-      { label: "Yes, solidify now", description: "Extract learnings and update project-guidelines.json" },
-      { label: "Skip", description: "Archive complete, no learnings to capture" }
-    ],
-    multiSelect: false
-  }]
-})
+// Parse --yes flag
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+
+if (autoYes) {
+  // Auto mode: Skip solidify
+  console.log(`[--yes] Auto-selecting: Skip solidify`)
+  console.log(`Session archived successfully.`)
+  // Done - no solidify
+} else {
+  // Interactive mode: Ask user
+  AskUserQuestion({
+    questions: [{
+      question: "Would you like to solidify learnings from this session into project guidelines?",
+      header: "Solidify",
+      options: [
+        { label: "Yes, solidify now", description: "Extract learnings and update project-guidelines.json" },
+        { label: "Skip", description: "Archive complete, no learnings to capture" }
+      ],
+      multiSelect: false
+    }]
+  })
+
+  // **If "Yes, solidify now"**: Execute `/workflow:session:solidify` with the archived session ID.
+}
 ```
 
-**If "Yes, solidify now"**: Execute `/workflow:session:solidify` with the archived session ID.
+## Auto Mode Defaults
+
+When `--yes` or `-y` flag is used:
+- **Solidify Learnings**: Auto-selected "Skip" (archive only, no solidify)
+
+**Flag Parsing**:
+```javascript
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+```
 
 **Output**:
 ```

.claude/commands/workflow/session/solidify.md

@@ -1,14 +1,18 @@
 ---
 name: solidify
 description: Crystallize session learnings and user-defined constraints into permanent project guidelines
-argument-hint: "[--type <convention|constraint|learning>] [--category <category>] \"rule or insight\""
+argument-hint: "[-y|--yes] [--type <convention|constraint|learning>] [--category <category>] \"rule or insight\""
 examples:
   - /workflow:session:solidify "Use functional components for all React code" --type convention
-  - /workflow:session:solidify "No direct DB access from controllers" --type constraint --category architecture
+  - /workflow:session:solidify -y "No direct DB access from controllers" --type constraint --category architecture
   - /workflow:session:solidify "Cache invalidation requires event sourcing" --type learning --category architecture
   - /workflow:session:solidify --interactive
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-categorize and add guideline without confirmation.
+
 # Session Solidify Command (/workflow:session:solidify)
 
 ## Overview

.claude/commands/workflow/tdd-plan.md

@@ -268,15 +268,19 @@ SlashCommand(command="/workflow:tools:conflict-resolution --session [sessionId]
 
 ### Phase 5: TDD Task Generation
 
-**Step 5.1: Execute** - TDD task generation via action-planning-agent
+**Step 5.1: Execute** - TDD task generation via action-planning-agent with Phase 0 user configuration
 
 ```javascript
 SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId]")
 ```
 
-**Note**: CLI tool usage is determined semantically from user's task description.
+**Note**: Phase 0 now includes:
+- Supplementary materials collection (file paths or inline content)
+- Execution method preference (Agent/Hybrid/CLI)
+- CLI tool preference (Codex/Gemini/Qwen/Auto)
+- These preferences are passed to agent for task generation
 
-**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles)
+**Parse**: Extract feature count, task count (not chain count - tasks now contain internal TDD cycles), CLI execution IDs assigned
 
 **Validate**:
 - IMPL_PLAN.md exists (unified plan with TDD Implementation Tasks section)
@@ -284,15 +288,24 @@ SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId]")
 - TODO_LIST.md exists with internal TDD phase indicators
 - Each IMPL task includes:
   - `meta.tdd_workflow: true`
-  - `flow_control.implementation_approach` with 3 steps (red/green/refactor)
+  - `meta.cli_execution_id: {session_id}-{task_id}`
+  - `meta.cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }`
+  - `flow_control.implementation_approach` with exactly 3 steps (red/green/refactor)
   - Green phase includes test-fix-cycle configuration
+  - `context.focus_paths`: absolute or clear relative paths (enhanced with exploration critical_files)
+  - `flow_control.pre_analysis`: includes exploration integration_points analysis
 - IMPL_PLAN.md contains workflow_type: "tdd" in frontmatter
-- Task count ≤10 (compliance with task limit)
+- User configuration applied:
+  - If executionMethod == "cli" or "hybrid": command field added to steps
+  - CLI tool preference reflected in execution guidance
+- Task count ≤18 (compliance with hard limit)
 
 **Red Flag Detection** (Non-Blocking Warnings):
-- Task count >10: `⚠️ High task count may indicate insufficient decomposition`
+- Task count >18: `⚠️ Task count exceeds hard limit - request re-scope`
+- Missing cli_execution_id: `⚠️ Task lacks CLI execution ID for resume support`
 - Missing test-fix-cycle: `⚠️ Green phase lacks auto-revert configuration`
 - Generic task names: `⚠️ Vague task names suggest unclear TDD cycles`
+- Missing focus_paths: `⚠️ Task lacks clear file scope for implementation`
 
 **Action**: Log warnings to `.workflow/active/[sessionId]/.process/tdd-warnings.log` (non-blocking)
 
@@ -338,14 +351,22 @@ SlashCommand(command="/workflow:tools:task-generate-tdd --session [sessionId]")
 1. Each task contains complete TDD workflow (Red-Green-Refactor internally)
 2. Task structure validation:
    - `meta.tdd_workflow: true` in all IMPL tasks
+   - `meta.cli_execution_id` present (format: {session_id}-{task_id})
+   - `meta.cli_execution` strategy assigned (new/resume/fork/merge_fork)
    - `flow_control.implementation_approach` has exactly 3 steps
    - Each step has correct `tdd_phase`: "red", "green", "refactor"
+   - `context.focus_paths` are absolute or clear relative paths
+   - `flow_control.pre_analysis` includes exploration integration analysis
 3. Dependency validation:
    - Sequential features: IMPL-N depends_on ["IMPL-(N-1)"] if needed
    - Complex features: IMPL-N.M depends_on ["IMPL-N.(M-1)"] for subtasks
+   - CLI execution strategies correctly assigned based on dependency graph
 4. Agent assignment: All IMPL tasks use @code-developer
 5. Test-fix cycle: Green phase step includes test-fix-cycle logic with max_iterations
-6. Task count: Total tasks ≤10 (simple + subtasks)
+6. Task count: Total tasks ≤18 (simple + subtasks hard limit)
+7. User configuration:
+   - Execution method choice reflected in task structure
+   - CLI tool preference documented in implementation guidance (if CLI selected)
 
 **Red Flag Checklist** (from TDD best practices):
 - [ ] No tasks skip Red phase (`tdd_phase: "red"` exists in step 1)
@@ -371,7 +392,7 @@ ls -la .workflow/active/[sessionId]/.task/IMPL-*.json
 echo "IMPL tasks: $(ls .workflow/active/[sessionId]/.task/IMPL-*.json 2>/dev/null | wc -l)"
 
 # Sample task structure verification (first task)
-jq '{id, tdd: .meta.tdd_workflow, phases: [.flow_control.implementation_approach[].tdd_phase]}' \
+jq '{id, tdd: .meta.tdd_workflow, cli_id: .meta.cli_execution_id, phases: [.flow_control.implementation_approach[].tdd_phase]}' \
   "$(ls .workflow/active/[sessionId]/.task/IMPL-*.json | head -1)"
 ```
 
@@ -379,8 +400,9 @@ jq '{id, tdd: .meta.tdd_workflow, phases: [.flow_control.implementation_approach
 | Evidence Type | Verification Method | Pass Criteria |
 |---------------|---------------------|---------------|
 | File existence | `ls -la` artifacts | All files present |
-| Task count | Count IMPL-*.json | Count matches claims |
-| TDD structure | jq sample extraction | Shows red/green/refactor |
+| Task count | Count IMPL-*.json | Count matches claims (≤18) |
+| TDD structure | jq sample extraction | Shows red/green/refactor + cli_execution_id |
+| CLI execution IDs | jq extraction | All tasks have cli_execution_id assigned |
 | Warning log | Check tdd-warnings.log | Logged (may be empty) |
 
 **Return Summary**:
@@ -393,7 +415,7 @@ Total tasks: [M] (1 task per simple feature + subtasks for complex features)
 Task breakdown:
 - Simple features: [K] tasks (IMPL-1 to IMPL-K)
 - Complex features: [L] features with [P] subtasks
-- Total task count: [M] (within 10-task limit)
+- Total task count: [M] (within 18-task hard limit)
 
 Structure:
 - IMPL-1: {Feature 1 Name} (Internal: Red → Green → Refactor)
@@ -407,22 +429,31 @@ Plans generated:
 - Unified Implementation Plan: .workflow/active/[sessionId]/IMPL_PLAN.md
   (includes TDD Implementation Tasks section with workflow_type: "tdd")
 - Task List: .workflow/active/[sessionId]/TODO_LIST.md
-  (with internal TDD phase indicators)
+  (with internal TDD phase indicators and CLI execution strategies)
+- Task JSONs: .workflow/active/[sessionId]/.task/IMPL-*.json
+  (with cli_execution_id and execution strategies for resume support)
 
 TDD Configuration:
 - Each task contains complete Red-Green-Refactor cycle
 - Green phase includes test-fix cycle (max 3 iterations)
 - Auto-revert on max iterations reached
+- CLI execution strategies: new/resume/fork/merge_fork based on dependency graph
+
+User Configuration Applied:
+- Execution Method: [agent|hybrid|cli]
+- CLI Tool Preference: [codex|gemini|qwen|auto]
+- Supplementary Materials: [included|none]
+- Task generation follows cli-tools-usage.md guidelines
 
 ⚠️ ACTION REQUIRED: Before execution, ensure you understand WHY each Red phase test is expected to fail.
    This is crucial for valid TDD - if you don't know why the test fails, you can't verify it tests the right thing.
 
 Recommended Next Steps:
-1. /workflow:action-plan-verify --session [sessionId]  # Verify TDD plan quality and dependencies
-2. /workflow:execute --session [sessionId]  # Start TDD execution
+1. /workflow:plan-verify --session [sessionId]  # Verify TDD plan quality and dependencies
+2. /workflow:execute --session [sessionId]  # Start TDD execution with CLI strategies
 3. /workflow:tdd-verify [sessionId]  # Post-execution TDD compliance check
 
-Quality Gate: Consider running /workflow:action-plan-verify to validate TDD task structure and dependencies
+Quality Gate: Consider running /workflow:plan-verify to validate TDD task structure, dependencies, and CLI execution strategies
 ```
 
 ## TodoWrite Pattern
@@ -500,7 +531,7 @@ TDD Workflow Orchestrator
 │
 └─ Phase 6: TDD Structure Validation
    └─ Internal validation + summary returned
-   └─ Recommend: /workflow:action-plan-verify
+   └─ Recommend: /workflow:plan-verify
 
 Key Points:
 • ← ATTACHED: SlashCommand attaches sub-tasks to orchestrator TodoWrite
@@ -547,9 +578,11 @@ Convert user input to TDD-structured format:
 | Parsing failure | Empty/malformed output | Retry once, then report |
 | Missing context-package | File read error | Re-run `/workflow:tools:context-gather` |
 | Invalid task JSON | jq parse error | Report malformed file path |
-| High task count (>10) | Count validation | Log warning, continue (non-blocking) |
+| Task count exceeds 18 | Count validation ≥19 | Request re-scope, split into multiple sessions |
+| Missing cli_execution_id | All tasks lack ID | Regenerate tasks with phase 0 user config |
 | Test-context missing | File not found | Re-run `/workflow:tools:test-context-gather` |
 | Phase timeout | No response | Retry phase, check CLI connectivity |
+| CLI tool not available | Tool not in cli-tools.json | Fall back to alternative preferred tool |
 
 ## Related Commands
 
@@ -565,7 +598,7 @@ Convert user input to TDD-structured format:
 - `/workflow:tools:task-generate-tdd` - Phase 5: Generate TDD tasks (CLI tool usage determined semantically)
 
 **Follow-up Commands**:
-- `/workflow:action-plan-verify` - Recommended: Verify TDD plan quality and structure before execution
+- `/workflow:plan-verify` - Recommended: Verify TDD plan quality and structure before execution
 - `/workflow:status` - Review TDD task breakdown
 - `/workflow:execute` - Begin TDD implementation
 - `/workflow:tdd-verify` - Post-execution: Verify TDD compliance and generate quality report
@@ -574,7 +607,7 @@ Convert user input to TDD-structured format:
 
 | Situation | Recommended Command | Purpose |
 |-----------|---------------------|---------|
-| First time planning | `/workflow:action-plan-verify` | Validate task structure before execution |
+| First time planning | `/workflow:plan-verify` | Validate task structure before execution |
 | Warnings in tdd-warnings.log | Review log, refine tasks | Address Red Flags before proceeding |
 | High task count warning | Consider `/workflow:session:start` | Split into focused sub-sessions |
 | Ready to implement | `/workflow:execute` | Begin TDD Red-Green-Refactor cycles |
@@ -587,7 +620,7 @@ Convert user input to TDD-structured format:
 ```
 /workflow:tdd-plan
         ↓
-[Planning Complete] ──→ /workflow:action-plan-verify (recommended)
+[Planning Complete] ──→ /workflow:plan-verify (recommended)
         ↓
 [Verified/Ready] ─────→ /workflow:execute
         ↓

.claude/commands/workflow/tdd-verify.md

@@ -1,214 +1,301 @@
 ---
 name: tdd-verify
-description: Verify TDD workflow compliance against Red-Green-Refactor cycles, generate quality report with coverage analysis
-
-argument-hint: "[optional: WFS-session-id]"
-allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Bash(gemini:*)
+description: Verify TDD workflow compliance against Red-Green-Refactor cycles. Generates quality report with coverage analysis and quality gate recommendation. Orchestrates sub-commands for comprehensive validation.
+argument-hint: "[optional: --session WFS-session-id]"
+allowed-tools: SlashCommand(*), TodoWrite(*), Read(*), Write(*), Bash(*), Glob(*)
 ---
 
 # TDD Verification Command (/workflow:tdd-verify)
 
+## Goal
+
+Verify TDD workflow execution quality by validating Red-Green-Refactor cycle compliance, test coverage completeness, and task chain structure integrity. This command orchestrates multiple analysis phases and generates a comprehensive compliance report with quality gate recommendation.
+
+**Output**: A structured Markdown report saved to `.workflow/active/WFS-{session}/TDD_COMPLIANCE_REPORT.md` containing:
+- Executive summary with compliance score and quality gate recommendation
+- Task chain validation (TEST → IMPL → REFACTOR structure)
+- Test coverage metrics (line, branch, function)
+- Red-Green-Refactor cycle verification
+- Best practices adherence assessment
+- Actionable improvement recommendations
+
+## Operating Constraints
+
+**ORCHESTRATOR MODE**:
+- This command coordinates multiple sub-commands (`/workflow:tools:tdd-coverage-analysis`, `ccw cli`)
+- MAY write output files: TDD_COMPLIANCE_REPORT.md (primary report), .process/*.json (intermediate artifacts)
+- MUST NOT modify source task files or implementation code
+- MUST NOT create or delete tasks in the workflow
+
+**Quality Gate Authority**: The compliance report provides a binding recommendation (BLOCK_MERGE / REQUIRE_FIXES / PROCEED_WITH_CAVEATS / APPROVED) based on objective compliance criteria.
+
 ## Coordinator Role
 
 **This command is a pure orchestrator**: Execute 4 phases to verify TDD workflow compliance, test coverage, and Red-Green-Refactor cycle execution.
 
 ## Core Responsibilities
-- Verify TDD task chain structure
-- Analyze test coverage
-- Validate TDD cycle execution
-- Generate compliance report
+- Verify TDD task chain structure (TEST → IMPL → REFACTOR)
+- Analyze test coverage metrics
+- Validate TDD cycle execution quality
+- Generate compliance report with quality gate recommendation
 
 ## Execution Process
 
 ```
 Input Parsing:
    └─ Decision (session argument):
-      ├─ session-id provided → Use provided session
-      └─ No session-id → Auto-detect active session
+      ├─ --session provided → Use provided session
+      └─ No session → Auto-detect active session
 
-Phase 1: Session Discovery
-   ├─ Validate session directory exists
-   └─ TodoWrite: Mark phase 1 completed
+Phase 1: Session Discovery & Validation
+   ├─ Detect or validate session directory
+   ├─ Check required artifacts exist (.task/*.json, .summaries/*)
+   └─ ERROR if invalid or incomplete
 
-Phase 2: Task Chain Validation
+Phase 2: Task Chain Structure Validation
    ├─ Load all task JSONs from .task/
-   ├─ Extract task IDs and group by feature
-   ├─ Validate TDD structure:
-   │  ├─ TEST-N.M → IMPL-N.M → REFACTOR-N.M chain
-   │  ├─ Dependency verification
-   │  └─ Meta field validation (tdd_phase, agent)
-   └─ TodoWrite: Mark phase 2 completed
+   ├─ Validate TDD structure: TEST-N.M → IMPL-N.M → REFACTOR-N.M
+   ├─ Verify dependencies (depends_on)
+   ├─ Validate meta fields (tdd_phase, agent)
+   └─ Extract chain validation data
 
-Phase 3: Test Execution Analysis
-   └─ /workflow:tools:tdd-coverage-analysis
-      ├─ Coverage metrics extraction
-      ├─ TDD cycle verification
-      └─ Compliance score calculation
+Phase 3: Coverage & Cycle Analysis
+   ├─ Call: /workflow:tools:tdd-coverage-analysis
+   ├─ Parse: test-results.json, coverage-report.json, tdd-cycle-report.md
+   └─ Extract coverage metrics and TDD cycle verification
 
 Phase 4: Compliance Report Generation
-   ├─ Gemini analysis for comprehensive report
+   ├─ Aggregate findings from Phases 1-3
+   ├─ Calculate compliance score (0-100)
+   ├─ Determine quality gate recommendation
    ├─ Generate TDD_COMPLIANCE_REPORT.md
-   └─ Return summary to user
+   └─ Display summary to user
 ```
 
 ## 4-Phase Execution
 
-### Phase 1: Session Discovery
-**Auto-detect or use provided session**
+### Phase 1: Session Discovery & Validation
 
+**Step 1.1: Detect Session**
 ```bash
-# If session-id provided
-sessionId = argument
+IF --session parameter provided:
+    session_id = provided session
+ELSE:
+    # Auto-detect active session
+    active_sessions = bash(find .workflow/active/ -name "WFS-*" -type d 2>/dev/null)
+    IF active_sessions is empty:
+        ERROR: "No active workflow session found. Use --session <session-id>"
+        EXIT
+    ELSE IF active_sessions has multiple entries:
+        # Use most recently modified session
+        session_id = bash(ls -td .workflow/active/WFS-*/ 2>/dev/null | head -1 | xargs basename)
+    ELSE:
+        session_id = basename(active_sessions[0])
 
-# Else auto-detect active session
-find .workflow/active/ -name "WFS-*" -type d | head -1 | sed 's/.*\///'
+# Derive paths
+session_dir = .workflow/active/WFS-{session_id}
+task_dir = session_dir/.task
+summaries_dir = session_dir/.summaries
+process_dir = session_dir/.process
 ```
 
-**Extract**: sessionId
+**Step 1.2: Validate Required Artifacts**
+```bash
+# Check task files exist
+task_files = Glob(task_dir/*.json)
+IF task_files.count == 0:
+    ERROR: "No task JSON files found. Run /workflow:tdd-plan first"
+    EXIT
 
-**Validation**: Session directory exists
+# Check summaries exist (optional but recommended for full analysis)
+summaries_exist = EXISTS(summaries_dir)
+IF NOT summaries_exist:
+    WARNING: "No .summaries/ directory found. Some analysis may be limited."
+```
 
-**TodoWrite**: Mark phase 1 completed, phase 2 in_progress
+**Output**: session_id, session_dir, task_files list
 
 ---
 
-### Phase 2: Task Chain Validation
-**Validate TDD structure using bash commands**
+### Phase 2: Task Chain Structure Validation
 
+**Step 2.1: Load and Parse Task JSONs**
 ```bash
-# Load all task JSONs
-for task_file in .workflow/active/{sessionId}/.task/*.json; do
-  cat "$task_file"
-done
+# Single-pass JSON extraction using jq
+validation_data = bash("""
+# Load all tasks and extract structured data
+cd '{session_dir}/.task'
 
-# Extract task IDs
-for task_file in .workflow/active/{sessionId}/.task/*.json; do
-  cat "$task_file" | jq -r '.id'
-done
+# Extract all task IDs
+task_ids=$(jq -r '.id' *.json 2>/dev/null | sort)
 
-# Check dependencies - read tasks and filter for IMPL/REFACTOR
-for task_file in .workflow/active/{sessionId}/.task/IMPL-*.json; do
-  cat "$task_file" | jq -r '.context.depends_on[]?'
-done
+# Extract dependencies for IMPL tasks
+impl_deps=$(jq -r 'select(.id | startswith("IMPL")) | .id + ":" + (.context.depends_on[]? // "none")' *.json 2>/dev/null)
 
-for task_file in .workflow/active/{sessionId}/.task/REFACTOR-*.json; do
-  cat "$task_file" | jq -r '.context.depends_on[]?'
-done
+# Extract dependencies for REFACTOR tasks
+refactor_deps=$(jq -r 'select(.id | startswith("REFACTOR")) | .id + ":" + (.context.depends_on[]? // "none")' *.json 2>/dev/null)
 
-# Check meta fields
-for task_file in .workflow/active/{sessionId}/.task/*.json; do
-  cat "$task_file" | jq -r '.meta.tdd_phase'
-done
+# Extract meta fields
+meta_tdd=$(jq -r '.id + ":" + (.meta.tdd_phase // "missing")' *.json 2>/dev/null)
+meta_agent=$(jq -r '.id + ":" + (.meta.agent // "missing")' *.json 2>/dev/null)
 
-for task_file in .workflow/active/{sessionId}/.task/*.json; do
-  cat "$task_file" | jq -r '.meta.agent'
-done
+# Output as JSON
+jq -n --arg ids "$task_ids" \\
+       --arg impl "$impl_deps" \\
+       --arg refactor "$refactor_deps" \\
+       --arg tdd "$meta_tdd" \\
+       --arg agent "$meta_agent" \\
+       '{ids: $ids, impl_deps: $impl, refactor_deps: $refactor, tdd: $tdd, agent: $agent}'
+""")
 ```
 
-**Validation**:
-- For each feature N, verify TEST-N.M → IMPL-N.M → REFACTOR-N.M exists
-- IMPL-N.M.context.depends_on includes TEST-N.M
-- REFACTOR-N.M.context.depends_on includes IMPL-N.M
-- TEST tasks have tdd_phase="red" and agent="@code-review-test-agent"
-- IMPL/REFACTOR tasks have tdd_phase="green"/"refactor" and agent="@code-developer"
+**Step 2.2: Validate TDD Chain Structure**
+```
+Parse validation_data JSON and validate:
 
-**Extract**: Chain validation report
+For each feature N (extracted from task IDs):
+   1. TEST-N.M exists?
+   2. IMPL-N.M exists?
+   3. REFACTOR-N.M exists? (optional but recommended)
+   4. IMPL-N.M.context.depends_on contains TEST-N.M?
+   5. REFACTOR-N.M.context.depends_on contains IMPL-N.M?
+   6. TEST-N.M.meta.tdd_phase == "red"?
+   7. TEST-N.M.meta.agent == "@code-review-test-agent"?
+   8. IMPL-N.M.meta.tdd_phase == "green"?
+   9. IMPL-N.M.meta.agent == "@code-developer"?
+   10. REFACTOR-N.M.meta.tdd_phase == "refactor"?
 
-**TodoWrite**: Mark phase 2 completed, phase 3 in_progress
+Calculate:
+- chain_completeness_score = (complete_chains / total_chains) * 100
+- dependency_accuracy = (correct_deps / total_deps) * 100
+- meta_field_accuracy = (correct_meta / total_meta) * 100
+```
+
+**Output**: chain_validation_report (JSON structure with validation results)
 
 ---
 
-### Phase 3: Test Execution Analysis
-**Command**: `SlashCommand(command="/workflow:tools:tdd-coverage-analysis --session [sessionId]")`
+### Phase 3: Coverage & Cycle Analysis
 
-**Input**: sessionId from Phase 1
+**Step 3.1: Call Coverage Analysis Sub-command**
+```bash
+SlashCommand(command="/workflow:tools:tdd-coverage-analysis --session {session_id}")
+```
 
-**Parse Output**:
-- Coverage metrics (line, branch, function percentages)
-- TDD cycle verification results
-- Compliance score
+**Step 3.2: Parse Output Files**
+```bash
+# Check required outputs exist
+IF NOT EXISTS(process_dir/test-results.json):
+    WARNING: "test-results.json not found. Coverage analysis incomplete."
+    coverage_data = null
+ELSE:
+    coverage_data = Read(process_dir/test-results.json)
 
-**Validation**:
-- `.workflow/active/{sessionId}/.process/test-results.json` exists
-- `.workflow/active/{sessionId}/.process/coverage-report.json` exists
-- `.workflow/active/{sessionId}/.process/tdd-cycle-report.md` exists
+IF NOT EXISTS(process_dir/coverage-report.json):
+    WARNING: "coverage-report.json not found. Coverage metrics incomplete."
+    metrics = null
+ELSE:
+    metrics = Read(process_dir/coverage-report.json)
 
-**TodoWrite**: Mark phase 3 completed, phase 4 in_progress
+IF NOT EXISTS(process_dir/tdd-cycle-report.md):
+    WARNING: "tdd-cycle-report.md not found. Cycle validation incomplete."
+    cycle_data = null
+ELSE:
+    cycle_data = Read(process_dir/tdd-cycle-report.md)
+```
+
+**Step 3.3: Extract Coverage Metrics**
+```
+If coverage_data exists:
+   - line_coverage_percent
+   - branch_coverage_percent
+   - function_coverage_percent
+   - uncovered_files (list)
+   - uncovered_lines (map: file -> line ranges)
+
+If cycle_data exists:
+   - red_phase_compliance (tests failed initially?)
+   - green_phase_compliance (tests pass after impl?)
+   - refactor_phase_compliance (tests stay green during refactor?)
+   - minimal_implementation_score (was impl minimal?)
+```
+
+**Output**: coverage_analysis, cycle_analysis
 
 ---
 
 ### Phase 4: Compliance Report Generation
-**Gemini analysis for comprehensive TDD compliance report**
 
+**Step 4.1: Calculate Compliance Score**
+```
+Base Score: 100 points
+
+Deductions:
+Chain Structure:
+   - Missing TEST task: -30 points per feature
+   - Missing IMPL task: -30 points per feature
+   - Missing REFACTOR task: -10 points per feature
+   - Wrong dependency: -15 points per error
+   - Wrong agent: -5 points per error
+   - Wrong tdd_phase: -5 points per error
+
+TDD Cycle Compliance:
+   - Test didn't fail initially: -10 points per feature
+   - Tests didn't pass after IMPL: -20 points per feature
+   - Tests broke during REFACTOR: -15 points per feature
+   - Over-engineered IMPL: -10 points per feature
+
+Coverage Quality:
+   - Line coverage < 80%: -5 points
+   - Branch coverage < 70%: -5 points
+   - Function coverage < 80%: -5 points
+   - Critical paths uncovered: -10 points
+
+Final Score: Max(0, Base Score - Total Deductions)
+```
+
+**Step 4.2: Determine Quality Gate**
+```
+IF score >= 90 AND no_critical_violations:
+    recommendation = "APPROVED"
+ELSE IF score >= 70 AND critical_violations == 0:
+    recommendation = "PROCEED_WITH_CAVEATS"
+ELSE IF score >= 50:
+    recommendation = "REQUIRE_FIXES"
+ELSE:
+    recommendation = "BLOCK_MERGE"
+```
+
+**Step 4.3: Generate Report**
 ```bash
-ccw cli -p "
-PURPOSE: Generate TDD compliance report
-TASK: Analyze TDD workflow execution and generate quality report
-CONTEXT: @{.workflow/active/{sessionId}/.task/*.json,.workflow/active/{sessionId}/.summaries/*,.workflow/active/{sessionId}/.process/tdd-cycle-report.md}
-EXPECTED:
-- TDD compliance score (0-100)
-- Chain completeness verification
-- Test coverage analysis summary
-- Quality recommendations
-- Red-Green-Refactor cycle validation
-- Best practices adherence assessment
-RULES: Focus on TDD best practices and workflow adherence. Be specific about violations and improvements.
-" --tool gemini --mode analysis --cd project-root > .workflow/active/{sessionId}/TDD_COMPLIANCE_REPORT.md
+report_content = Generate markdown report (see structure below)
+report_path = "{session_dir}/TDD_COMPLIANCE_REPORT.md"
+Write(report_path, report_content)
 ```
 
-**Output**: TDD_COMPLIANCE_REPORT.md
-
-**TodoWrite**: Mark phase 4 completed
-
-**Return to User**:
-```
-TDD Verification Report - Session: {sessionId}
-
-## Chain Validation
-[COMPLETE] Feature 1: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1 (Complete)
-[COMPLETE] Feature 2: TEST-2.1 → IMPL-2.1 → REFACTOR-2.1 (Complete)
-[INCOMPLETE] Feature 3: TEST-3.1 → IMPL-3.1 (Missing REFACTOR phase)
-
-## Test Execution
-All TEST tasks produced failing tests
-All IMPL tasks made tests pass
-All REFACTOR tasks maintained green tests
-
-## Coverage Metrics
-Line Coverage: {percentage}%
-Branch Coverage: {percentage}%
-Function Coverage: {percentage}%
-
-## Compliance Score: {score}/100
-
-Detailed report: .workflow/active/{sessionId}/TDD_COMPLIANCE_REPORT.md
-
-Recommendations:
-- Complete missing REFACTOR-3.1 task
-- Consider additional edge case tests for Feature 2
-- Improve test failure message clarity in Feature 1
+**Step 4.4: Display Summary to User**
+```bash
+echo "=== TDD Verification Complete ==="
+echo "Session: {session_id}"
+echo "Report: {report_path}"
+echo ""
+echo "Quality Gate: {recommendation}"
+echo "Compliance Score: {score}/100"
+echo ""
+echo "Chain Validation: {chain_completeness_score}%"
+echo "Line Coverage: {line_coverage}%"
+echo "Branch Coverage: {branch_coverage}%"
+echo ""
+echo "Next: Review full report for detailed findings"
 ```
 
-## TodoWrite Pattern
+## TodoWrite Pattern (Optional)
+
+**Note**: As an orchestrator command, TodoWrite tracking is optional and primarily useful for long-running verification processes. For most cases, the 4-phase execution is fast enough that progress tracking adds noise without value.
 
 ```javascript
-// Initialize (before Phase 1)
-TodoWrite({todos: [
-  {"content": "Identify target session", "status": "in_progress", "activeForm": "Identifying target session"},
-  {"content": "Validate task chain structure", "status": "pending", "activeForm": "Validating task chain structure"},
-  {"content": "Analyze test execution", "status": "pending", "activeForm": "Analyzing test execution"},
-  {"content": "Generate compliance report", "status": "pending", "activeForm": "Generating compliance report"}
-]})
-
-// After Phase 1
-TodoWrite({todos: [
-  {"content": "Identify target session", "status": "completed", "activeForm": "Identifying target session"},
-  {"content": "Validate task chain structure", "status": "in_progress", "activeForm": "Validating task chain structure"},
-  {"content": "Analyze test execution", "status": "pending", "activeForm": "Analyzing test execution"},
-  {"content": "Generate compliance report", "status": "pending", "activeForm": "Generating compliance report"}
-]})
-
-// Continue pattern for Phase 2, 3, 4...
+// Only use TodoWrite for complex multi-session verification
+// Skip for single-session verification
 ```
 
 ## Validation Logic
@@ -229,27 +316,24 @@ TodoWrite({todos: [
 5. Report incomplete or invalid chains
 ```
 
-### Compliance Scoring
-```
-Base Score: 100 points
+### Quality Gate Criteria
 
-Deductions:
-- Missing TEST task: -30 points per feature
-- Missing IMPL task: -30 points per feature
-- Missing REFACTOR task: -10 points per feature
-- Wrong dependency: -15 points per error
-- Wrong agent: -5 points per error
-- Wrong tdd_phase: -5 points per error
-- Test didn't fail initially: -10 points per feature
-- Tests didn't pass after IMPL: -20 points per feature
-- Tests broke during REFACTOR: -15 points per feature
+| Recommendation | Score Range | Critical Violations | Action |
+|----------------|-------------|---------------------|--------|
+| **APPROVED** | ≥90 | 0 | Safe to merge |
+| **PROCEED_WITH_CAVEATS** | ≥70 | 0 | Can proceed, address minor issues |
+| **REQUIRE_FIXES** | ≥50 | Any | Must fix before merge |
+| **BLOCK_MERGE** | <50 | Any | Block merge until resolved |
 
-Final Score: Max(0, Base Score - Deductions)
-```
+**Critical Violations**:
+- Missing TEST or IMPL task for any feature
+- Tests didn't fail initially (Red phase violation)
+- Tests didn't pass after IMPL (Green phase violation)
+- Tests broke during REFACTOR (Refactor phase violation)
 
 ## Output Files
 ```
-.workflow/active/{session-id}/
+.workflow/active/WFS-{session-id}/
 ├── TDD_COMPLIANCE_REPORT.md     # Comprehensive compliance report ⭐
 └── .process/
     ├── test-results.json         # From tdd-coverage-analysis
@@ -262,14 +346,14 @@ Final Score: Max(0, Base Score - Deductions)
 ### Session Discovery Errors
 | Error | Cause | Resolution |
 |-------|-------|------------|
-| No active session | No WFS-* directories | Provide session-id explicitly |
-| Multiple active sessions | Multiple WFS-* directories | Provide session-id explicitly |
+| No active session | No WFS-* directories | Provide --session explicitly |
+| Multiple active sessions | Multiple WFS-* directories | Provide --session explicitly |
 | Session not found | Invalid session-id | Check available sessions |
 
 ### Validation Errors
 | Error | Cause | Resolution |
 |-------|-------|------------|
-| Task files missing | Incomplete planning | Run tdd-plan first |
+| Task files missing | Incomplete planning | Run /workflow:tdd-plan first |
 | Invalid JSON | Corrupted task files | Regenerate tasks |
 | Missing summaries | Tasks not executed | Execute tasks before verify |
 
@@ -278,13 +362,13 @@ Final Score: Max(0, Base Score - Deductions)
 |-------|-------|------------|
 | Coverage tool missing | No test framework | Configure testing first |
 | Tests fail to run | Code errors | Fix errors before verify |
-| Gemini analysis fails | Token limit / API error | Retry or reduce context |
+| Sub-command fails | tdd-coverage-analysis error | Check sub-command logs |
 
 ## Integration & Usage
 
 ### Command Chain
 - **Called After**: `/workflow:execute` (when TDD tasks completed)
-- **Calls**: `/workflow:tools:tdd-coverage-analysis`, Gemini CLI
+- **Calls**: `/workflow:tools:tdd-coverage-analysis`
 - **Related**: `/workflow:tdd-plan`, `/workflow:status`
 
 ### Basic Usage
@@ -293,7 +377,7 @@ Final Score: Max(0, Base Score - Deductions)
 /workflow:tdd-verify
 
 # Specify session
-/workflow:tdd-verify WFS-auth
+/workflow:tdd-verify --session WFS-auth
 ```
 
 ### When to Use
@@ -308,61 +392,125 @@ Final Score: Max(0, Base Score - Deductions)
 # TDD Compliance Report - {Session ID}
 
 **Generated**: {timestamp}
-**Session**: {sessionId}
+**Session**: WFS-{sessionId}
 **Workflow Type**: TDD
 
+---
+
 ## Executive Summary
-Overall Compliance Score: {score}/100
-Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
+
+### Quality Gate Decision
+
+| Metric | Value | Status |
+|--------|-------|--------|
+| Compliance Score | {score}/100 | {status_emoji} |
+| Chain Completeness | {percentage}% | {status} |
+| Line Coverage | {percentage}% | {status} |
+| Branch Coverage | {percentage}% | {status} |
+| Function Coverage | {percentage}% | {status} |
+
+### Recommendation
+
+**{RECOMMENDATION}**
+
+**Decision Rationale**:
+{brief explanation based on score and violations}
+
+**Quality Gate Criteria**:
+- **APPROVED**: Score ≥90, no critical violations
+- **PROCEED_WITH_CAVEATS**: Score ≥70, no critical violations
+- **REQUIRE_FIXES**: Score ≥50 or critical violations exist
+- **BLOCK_MERGE**: Score <50
+
+---
 
 ## Chain Analysis
 
 ### Feature 1: {Feature Name}
-**Status**: Complete
+**Status**: ✅ Complete
 **Chain**: TEST-1.1 → IMPL-1.1 → REFACTOR-1.1
 
-- **Red Phase**: Test created and failed with clear message
-- **Green Phase**: Minimal implementation made test pass
-- **Refactor Phase**: Code improved, tests remained green
+| Phase | Task | Status | Details |
+|-------|------|--------|---------|
+| Red | TEST-1.1 | ✅ Pass | Test created and failed with clear message |
+| Green | IMPL-1.1 | ✅ Pass | Minimal implementation made test pass |
+| Refactor | REFACTOR-1.1 | ✅ Pass | Code improved, tests remained green |
 
 ### Feature 2: {Feature Name}
-**Status**: Incomplete
+**Status**: ⚠️ Incomplete
 **Chain**: TEST-2.1 → IMPL-2.1 (Missing REFACTOR-2.1)
 
-- **Red Phase**: Test created and failed
-- **Green Phase**: Implementation seems over-engineered
-- **Refactor Phase**: Missing
+| Phase | Task | Status | Details |
+|-------|------|--------|---------|
+| Red | TEST-2.1 | ✅ Pass | Test created and failed |
+| Green | IMPL-2.1 | ⚠️ Warning | Implementation seems over-engineered |
+| Refactor | REFACTOR-2.1 | ❌ Missing | Task not completed |
 
 **Issues**:
-- REFACTOR-2.1 task not completed
-- IMPL-2.1 implementation exceeded minimal scope
+- REFACTOR-2.1 task not completed (-10 points)
+- IMPL-2.1 implementation exceeded minimal scope (-10 points)
 
-[Repeat for all features]
+### Chain Validation Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Features | {count} |
+| Complete Chains | {count} ({percent}%) |
+| Incomplete Chains | {count} |
+| Missing TEST | {count} |
+| Missing IMPL | {count} |
+| Missing REFACTOR | {count} |
+| Dependency Errors | {count} |
+| Meta Field Errors | {count} |
+
+---
 
 ## Test Coverage Analysis
 
 ### Coverage Metrics
-- Line Coverage: {percentage}% {status}
-- Branch Coverage: {percentage}% {status}
-- Function Coverage: {percentage}% {status}
+
+| Metric | Coverage | Target | Status |
+|--------|----------|--------|--------|
+| Line Coverage | {percentage}% | ≥80% | {status} |
+| Branch Coverage | {percentage}% | ≥70% | {status} |
+| Function Coverage | {percentage}% | ≥80% | {status} |
 
 ### Coverage Gaps
-- {file}:{lines} - Uncovered error handling
-- {file}:{lines} - Uncovered edge case
+
+| File | Lines | Issue | Priority |
+|------|-------|-------|----------|
+| src/auth/service.ts | 45-52 | Uncovered error handling | HIGH |
+| src/utils/parser.ts | 78-85 | Uncovered edge case | MEDIUM |
+
+---
 
 ## TDD Cycle Validation
 
 ### Red Phase (Write Failing Test)
-- {N}/{total} features had failing tests initially
-- Feature 3: No evidence of initial test failure
+- {N}/{total} features had failing tests initially ({percent}%)
+- ✅ Compliant features: {list}
+- ❌ Non-compliant features: {list}
+
+**Violations**:
+- Feature 3: No evidence of initial test failure (-10 points)
 
 ### Green Phase (Make Test Pass)
-- {N}/{total} implementations made tests pass
-- All implementations minimal and focused
+- {N}/{total} implementations made tests pass ({percent}%)
+- ✅ Compliant features: {list}
+- ❌ Non-compliant features: {list}
+
+**Violations**:
+- Feature 2: Implementation over-engineered (-10 points)
 
 ### Refactor Phase (Improve Quality)
-- {N}/{total} features completed refactoring
-- Feature 2, 4: Refactoring step skipped
+- {N}/{total} features completed refactoring ({percent}%)
+- ✅ Compliant features: {list}
+- ❌ Non-compliant features: {list}
+
+**Violations**:
+- Feature 2, 4: Refactoring step skipped (-20 points total)
+
+---
 
 ## Best Practices Assessment
 
@@ -377,24 +525,61 @@ Status: {EXCELLENT | GOOD | NEEDS IMPROVEMENT | FAILED}
 - Missing refactoring steps
 - Test failure messages could be more descriptive
 
+---
+
+## Detailed Findings by Severity
+
+### Critical Issues ({count})
+{List of critical issues with impact and remediation}
+
+### High Priority Issues ({count})
+{List of high priority issues with impact and remediation}
+
+### Medium Priority Issues ({count})
+{List of medium priority issues with impact and remediation}
+
+### Low Priority Issues ({count})
+{List of low priority issues with impact and remediation}
+
+---
+
 ## Recommendations
 
-### High Priority
+### Required Fixes (Before Merge)
 1. Complete missing REFACTOR tasks (Features 2, 4)
 2. Verify initial test failures for Feature 3
-3. Simplify over-engineered implementations
+3. Fix tests that broke during refactoring
 
-### Medium Priority
-1. Add edge case tests for Features 1, 3
-2. Improve test failure message clarity
-3. Increase branch coverage to >85%
+### Recommended Improvements
+1. Simplify over-engineered implementations
+2. Add edge case tests for Features 1, 3
+3. Improve test failure message clarity
+4. Increase branch coverage to >85%
 
-### Low Priority
+### Optional Enhancements
 1. Add more descriptive test names
 2. Consider parameterized tests for similar scenarios
 3. Document TDD process learnings
 
-## Conclusion
-{Summary of compliance status and next steps}
+---
+
+## Metrics Summary
+
+| Metric | Value |
+|--------|-------|
+| Total Features | {count} |
+| Complete Chains | {count} ({percent}%) |
+| Compliance Score | {score}/100 |
+| Critical Issues | {count} |
+| High Issues | {count} |
+| Medium Issues | {count} |
+| Low Issues | {count} |
+| Line Coverage | {percent}% |
+| Branch Coverage | {percent}% |
+| Function Coverage | {percent}% |
+
+---
+
+**Report End**
 ```
 

.claude/commands/workflow/tools/conflict-resolution.md

@@ -1,12 +1,16 @@
 ---
 name: conflict-resolution
 description: Detect and resolve conflicts between plan and existing codebase using CLI-powered analysis with Gemini/Qwen
-argument-hint: "--session WFS-session-id --context path/to/context-package.json"
+argument-hint: "[-y|--yes] --session WFS-session-id --context path/to/context-package.json"
 examples:
   - /workflow:tools:conflict-resolution --session WFS-auth --context .workflow/active/WFS-auth/.process/context-package.json
-  - /workflow:tools:conflict-resolution --session WFS-payment --context .workflow/active/WFS-payment/.process/context-package.json
+  - /workflow:tools:conflict-resolution -y --session WFS-payment --context .workflow/active/WFS-payment/.process/context-package.json
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Auto-select recommended strategy for each conflict, skip clarification questions.
+
 # Conflict Resolution Command
 
 ## Purpose
@@ -209,6 +213,8 @@ Task(subagent_type="cli-execution-agent", run_in_background=false, prompt=`
 ### Phase 3: User Interaction Loop
 
 ```javascript
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+
 FOR each conflict:
   round = 0, clarified = false, userClarifications = []
 
@@ -216,8 +222,13 @@ FOR each conflict:
     // 1. Display conflict info (text output for context)
     displayConflictSummary(conflict)  // id, brief, severity, overlap_analysis if ModuleOverlap
 
-    // 2. Strategy selection via AskUserQuestion
-    AskUserQuestion({
+    // 2. Strategy selection
+    if (autoYes) {
+      console.log(`[--yes] Auto-selecting recommended strategy`)
+      selectedStrategy = conflict.strategies[conflict.recommended || 0]
+      clarified = true  // Skip clarification loop
+    } else {
+      AskUserQuestion({
       questions: [{
         question: formatStrategiesForDisplay(conflict.strategies),
         header: "策略选择",
@@ -230,18 +241,19 @@ FOR each conflict:
           { label: "自定义修改", description: `建议: ${conflict.modification_suggestions?.slice(0,2).join('; ')}` }
         ]
       }]
-    })
+      })
 
-    // 3. Handle selection
-    if (userChoice === "自定义修改") {
-      customConflicts.push({ id, brief, category, suggestions, overlap_analysis })
-      break
+      // 3. Handle selection
+      if (userChoice === "自定义修改") {
+        customConflicts.push({ id, brief, category, suggestions, overlap_analysis })
+        break
+      }
+
+      selectedStrategy = findStrategyByName(userChoice)
     }
 
-    selectedStrategy = findStrategyByName(userChoice)
-
     // 4. Clarification (if needed) - batched max 4 per call
-    if (selectedStrategy.clarification_needed?.length > 0) {
+    if (!autoYes && selectedStrategy.clarification_needed?.length > 0) {
       for (batch of chunk(selectedStrategy.clarification_needed, 4)) {
         AskUserQuestion({
           questions: batch.map((q, i) => ({

.claude/commands/workflow/tools/task-generate-agent.md

@@ -1,11 +1,16 @@
 ---
 name: task-generate-agent
 description: Generate implementation plan documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) using action-planning-agent - produces planning artifacts, does NOT execute code implementation
-argument-hint: "--session WFS-session-id"
+argument-hint: "[-y|--yes] --session WFS-session-id"
 examples:
   - /workflow:tools:task-generate-agent --session WFS-auth
+  - /workflow:tools:task-generate-agent -y --session WFS-auth
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Skip user questions, use defaults (no materials, Agent executor, Codex CLI tool).
+
 # Generate Implementation Plan Command
 
 ## Overview
@@ -67,9 +72,25 @@ Phase 3: Integration (+1 Coordinator, Multi-Module Only)
 
 **Purpose**: Collect user preferences before task generation to ensure generated tasks match execution expectations.
 
-**User Questions**:
+**Auto Mode Check**:
 ```javascript
-AskUserQuestion({
+const autoYes = $ARGUMENTS.includes('--yes') || $ARGUMENTS.includes('-y')
+
+if (autoYes) {
+  console.log(`[--yes] Using defaults: No materials, Agent executor, Codex CLI`)
+  userConfig = {
+    supplementaryMaterials: { type: "none", content: [] },
+    executionMethod: "agent",
+    preferredCliTool: "codex",
+    enableResume: true
+  }
+  // Skip to Phase 1
+}
+```
+
+**User Questions** (skipped if autoYes):
+```javascript
+if (!autoYes) AskUserQuestion({
   questions: [
     {
       question: "Do you have supplementary materials or guidelines to include?",
@@ -104,11 +125,10 @@ AskUserQuestion({
     }
   ]
 })
-```
 
-**Handle Materials Response**:
+**Handle Materials Response** (skipped if autoYes):
 ```javascript
-if (userConfig.materials === "Provide file paths") {
+if (!autoYes && userConfig.materials === "Provide file paths") {
   // Follow-up question for file paths
   const pathsResponse = AskUserQuestion({
     questions: [{

.claude/commands/workflow/tools/task-generate-tdd.md

@@ -1,11 +1,16 @@
 ---
 name: task-generate-tdd
 description: Autonomous TDD task generation using action-planning-agent with Red-Green-Refactor cycles, test-first structure, and cycle validation
-argument-hint: "--session WFS-session-id"
+argument-hint: "[-y|--yes] --session WFS-session-id"
 examples:
   - /workflow:tools:task-generate-tdd --session WFS-auth
+  - /workflow:tools:task-generate-tdd -y --session WFS-auth
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Skip user questions, use defaults (no materials, Agent executor).
+
 # Autonomous TDD Task Generation Command
 
 ## Overview
@@ -78,44 +83,176 @@ Phase 2: Agent Execution (Document Generation)
 
 ## Execution Lifecycle
 
-### Phase 1: Discovery & Context Loading
+### Phase 0: User Configuration (Interactive)
+
+**Purpose**: Collect user preferences before TDD task generation to ensure generated tasks match execution expectations and provide necessary supplementary context.
+
+**User Questions**:
+```javascript
+AskUserQuestion({
+  questions: [
+    {
+      question: "Do you have supplementary materials or guidelines to include?",
+      header: "Materials",
+      multiSelect: false,
+      options: [
+        { label: "No additional materials", description: "Use existing context only" },
+        { label: "Provide file paths", description: "I'll specify paths to include" },
+        { label: "Provide inline content", description: "I'll paste content directly" }
+      ]
+    },
+    {
+      question: "Select execution method for generated TDD tasks:",
+      header: "Execution",
+      multiSelect: false,
+      options: [
+        { label: "Agent (Recommended)", description: "Claude agent executes Red-Green-Refactor cycles directly" },
+        { label: "Hybrid", description: "Agent orchestrates, calls CLI for complex steps (Red/Green phases)" },
+        { label: "CLI Only", description: "All TDD cycles via CLI tools (codex/gemini/qwen)" }
+      ]
+    },
+    {
+      question: "If using CLI, which tool do you prefer?",
+      header: "CLI Tool",
+      multiSelect: false,
+      options: [
+        { label: "Codex (Recommended)", description: "Best for TDD Red-Green-Refactor cycles" },
+        { label: "Gemini", description: "Best for analysis and large context" },
+        { label: "Qwen", description: "Alternative analysis tool" },
+        { label: "Auto", description: "Let agent decide per-task" }
+      ]
+    }
+  ]
+})
+```
+
+**Handle Materials Response**:
+```javascript
+if (userConfig.materials === "Provide file paths") {
+  // Follow-up question for file paths
+  const pathsResponse = AskUserQuestion({
+    questions: [{
+      question: "Enter file paths to include (comma-separated or one per line):",
+      header: "Paths",
+      multiSelect: false,
+      options: [
+        { label: "Enter paths", description: "Provide paths in text input" }
+      ]
+    }]
+  })
+  userConfig.supplementaryPaths = parseUserPaths(pathsResponse)
+}
+```
+
+**Build userConfig**:
+```javascript
+const userConfig = {
+  supplementaryMaterials: {
+    type: "none|paths|inline",
+    content: [...],  // Parsed paths or inline content
+  },
+  executionMethod: "agent|hybrid|cli",
+  preferredCliTool: "codex|gemini|qwen|auto",
+  enableResume: true  // Always enable resume for CLI executions
+}
+```
+
+**Pass to Agent**: Include `userConfig` in agent prompt for Phase 2.
+
+---
+
+### Phase 1: Context Preparation & Discovery
+
+**Command Responsibility**: Command prepares session paths and metadata, provides to agent for autonomous context loading.
+
 **⚡ Memory-First Rule**: Skip file loading if documents already in conversation memory
 
-**Agent Context Package**:
+**📊 Progressive Loading Strategy**: Load context incrementally due to large analysis.md file sizes:
+- **Core**: session metadata + context-package.json (always load)
+- **Selective**: synthesis_output OR (guidance + relevant role analyses) - NOT all role analyses
+- **On-Demand**: conflict resolution (if conflict_risk >= medium), test context
+
+**🛤️ Path Clarity Requirement**: All `focus_paths` prefer absolute paths (e.g., `D:\\project\\src\\module`), or clear relative paths from project root (e.g., `./src/module`)
+
+**Session Path Structure** (Provided by Command to Agent):
+```
+.workflow/active/WFS-{session-id}/
+├── workflow-session.json          # Session metadata
+├── .process/
+│   ├── context-package.json       # Context package with artifact catalog
+│   ├── test-context-package.json  # Test coverage analysis
+│   └── conflict-resolution.json   # Conflict resolution (if exists)
+├── .task/                         # Output: Task JSON files
+│   ├── IMPL-1.json
+│   ├── IMPL-2.json
+│   └── ...
+├── IMPL_PLAN.md                   # Output: TDD implementation plan
+└── TODO_LIST.md                   # Output: TODO list with TDD phases
+```
+
+**Command Preparation**:
+1. **Assemble Session Paths** for agent prompt:
+   - `session_metadata_path`: `.workflow/active/{session-id}/workflow-session.json`
+   - `context_package_path`: `.workflow/active/{session-id}/.process/context-package.json`
+   - `test_context_package_path`: `.workflow/active/{session-id}/.process/test-context-package.json`
+   - Output directory paths
+
+2. **Provide Metadata** (simple values):
+   - `session_id`: WFS-{session-id}
+   - `workflow_type`: "tdd"
+   - `mcp_capabilities`: {exa_code, exa_web, code_index}
+
+3. **Pass userConfig** from Phase 0
+
+**Agent Context Package** (Agent loads autonomously):
 ```javascript
 {
   "session_id": "WFS-[session-id]",
   "workflow_type": "tdd",
-  // Note: CLI tool usage is determined semantically by action-planning-agent based on user's task description
+
+  // Core (ALWAYS load)
   "session_metadata": {
     // If in memory: use cached content
-    // Else: Load from .workflow/active//{session-id}/workflow-session.json
+    // Else: Load from workflow-session.json
   },
+  "context_package": {
+    // If in memory: use cached content
+    // Else: Load from context-package.json
+  },
+
+  // Selective (load based on progressive strategy)
   "brainstorm_artifacts": {
     // Loaded from context-package.json → brainstorm_artifacts section
-    "role_analyses": [
+    "synthesis_output": {"path": "...", "exists": true},  // Load if exists (highest priority)
+    "guidance_specification": {"path": "...", "exists": true},  // Load if no synthesis
+    "role_analyses": [  // Load SELECTIVELY based on task relevance
       {
         "role": "system-architect",
         "files": [{"path": "...", "type": "primary|supplementary"}]
       }
-    ],
-    "guidance_specification": {"path": "...", "exists": true},
-    "synthesis_output": {"path": "...", "exists": true},
-    "conflict_resolution": {"path": "...", "exists": true}  // if conflict_risk >= medium
+    ]
   },
-  "context_package_path": ".workflow/active//{session-id}/.process/context-package.json",
-  "context_package": {
-    // If in memory: use cached content
-    // Else: Load from .workflow/active//{session-id}/.process/context-package.json
-  },
-  "test_context_package_path": ".workflow/active//{session-id}/.process/test-context-package.json",
+
+  // On-Demand (load if exists)
   "test_context_package": {
-    // Existing test patterns and coverage analysis
+    // Load from test-context-package.json
+    // Contains existing test patterns and coverage analysis
   },
+  "conflict_resolution": {
+    // Load from conflict-resolution.json if conflict_risk >= medium
+    // Check context-package.conflict_detection.resolution_file
+  },
+
+  // Capabilities
   "mcp_capabilities": {
-    "codex_lens": true,
     "exa_code": true,
-    "exa_web": true
+    "exa_web": true,
+    "code_index": true
+  },
+
+  // User configuration from Phase 0
+  "user_config": {
+    // From Phase 0 AskUserQuestion
   }
 }
 ```
@@ -124,21 +261,21 @@ Phase 2: Agent Execution (Document Generation)
 1. **Load Session Context** (if not in memory)
    ```javascript
    if (!memory.has("workflow-session.json")) {
-     Read(.workflow/active//{session-id}/workflow-session.json)
+     Read(.workflow/active/{session-id}/workflow-session.json)
    }
    ```
 
 2. **Load Context Package** (if not in memory)
    ```javascript
    if (!memory.has("context-package.json")) {
-     Read(.workflow/active//{session-id}/.process/context-package.json)
+     Read(.workflow/active/{session-id}/.process/context-package.json)
    }
    ```
 
 3. **Load Test Context Package** (if not in memory)
    ```javascript
    if (!memory.has("test-context-package.json")) {
-     Read(.workflow/active//{session-id}/.process/test-context-package.json)
+     Read(.workflow/active/{session-id}/.process/test-context-package.json)
    }
    ```
 
@@ -180,62 +317,81 @@ Phase 2: Agent Execution (Document Generation)
    )
    ```
 
-### Phase 2: Agent Execution (Document Generation)
+### Phase 2: Agent Execution (TDD Document Generation)
 
-**Pre-Agent Template Selection** (Command decides path before invoking agent):
-```javascript
-// Command checks flag and selects template PATH (not content)
-const templatePath = hasCliExecuteFlag
-  ? "~/.claude/workflows/cli-templates/prompts/workflow/task-json-cli-mode.txt"
-  : "~/.claude/workflows/cli-templates/prompts/workflow/task-json-agent-mode.txt";
-```
+**Purpose**: Generate TDD planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) - planning only, NOT code implementation.
 
 **Agent Invocation**:
 ```javascript
 Task(
   subagent_type="action-planning-agent",
   run_in_background=false,
-  description="Generate TDD task JSON and implementation plan",
+  description="Generate TDD planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md)",
   prompt=`
-## Execution Context
+## TASK OBJECTIVE
+Generate TDD implementation planning documents (IMPL_PLAN.md, task JSONs, TODO_LIST.md) for workflow session
 
-**Session ID**: WFS-{session-id}
-**Workflow Type**: TDD
-**Note**: CLI tool usage is determined semantically from user's task description
+IMPORTANT: This is PLANNING ONLY - you are generating planning documents, NOT implementing code.
 
-## Phase 1: Discovery Results (Provided Context)
+CRITICAL: Follow the progressive loading strategy (load analysis.md files incrementally due to file size):
+- **Core**: session metadata + context-package.json (always)
+- **Selective**: synthesis_output OR (guidance + relevant role analyses) - NOT all
+- **On-Demand**: conflict resolution (if conflict_risk >= medium), test context
 
-### Session Metadata
-{session_metadata_content}
+## SESSION PATHS
+Input:
+  - Session Metadata: .workflow/active/{session-id}/workflow-session.json
+  - Context Package: .workflow/active/{session-id}/.process/context-package.json
+  - Test Context: .workflow/active/{session-id}/.process/test-context-package.json
 
-### Role Analyses (Enhanced by Synthesis)
-{role_analyses_content}
-- Includes requirements, design specs, enhancements, and clarifications from synthesis phase
+Output:
+  - Task Dir: .workflow/active/{session-id}/.task/
+  - IMPL_PLAN: .workflow/active/{session-id}/IMPL_PLAN.md
+  - TODO_LIST: .workflow/active/{session-id}/TODO_LIST.md
 
-### Artifacts Inventory
-- **Guidance Specification**: {guidance_spec_path}
-- **Role Analyses**: {role_analyses_list}
+## CONTEXT METADATA
+Session ID: {session-id}
+Workflow Type: TDD
+MCP Capabilities: {exa_code, exa_web, code_index}
 
-### Context Package
-{context_package_summary}
-- Includes conflict_risk assessment
+## USER CONFIGURATION (from Phase 0)
+Execution Method: ${userConfig.executionMethod}  // agent|hybrid|cli
+Preferred CLI Tool: ${userConfig.preferredCliTool}  // codex|gemini|qwen|auto
+Supplementary Materials: ${userConfig.supplementaryMaterials}
 
-### Test Context Package
-{test_context_package_summary}
-- Existing test patterns, framework config, coverage analysis
+## CLI TOOL SELECTION
+Based on userConfig.executionMethod:
+- "agent": No command field in implementation_approach steps
+- "hybrid": Add command field to complex steps only (Red/Green phases recommended for CLI)
+- "cli": Add command field to ALL Red-Green-Refactor steps
 
-### Conflict Resolution (Conditional)
-If conflict_risk was medium/high, modifications have been applied to:
-- **guidance-specification.md**: Design decisions updated to resolve conflicts
-- **Role analyses (*.md)**: Recommendations adjusted for compatibility
-- **context-package.json**: Marked as "resolved" with conflict IDs
-- Conflict resolution results stored in conflict-resolution.json
+CLI Resume Support (MANDATORY for all CLI commands):
+- Use --resume parameter to continue from previous task execution
+- Read previous task's cliExecutionId from session state
+- Format: ccw cli -p "[prompt]" --resume [previousCliId] --tool [tool] --mode write
 
-### MCP Analysis Results (Optional)
-**Code Structure**: {mcp_code_index_results}
-**External Research**: {mcp_exa_research_results}
+## EXPLORATION CONTEXT (from context-package.exploration_results)
+- Load exploration_results from context-package.json
+- Use aggregated_insights.critical_files for focus_paths generation
+- Apply aggregated_insights.constraints to acceptance criteria
+- Reference aggregated_insights.all_patterns for implementation approach
+- Use aggregated_insights.all_integration_points for precise modification locations
+- Use conflict_indicators for risk-aware task sequencing
 
-## Phase 2: TDD Document Generation Task
+## CONFLICT RESOLUTION CONTEXT (if exists)
+- Check context-package.conflict_detection.resolution_file for conflict-resolution.json path
+- If exists, load .process/conflict-resolution.json:
+  - Apply planning_constraints as task constraints (for brainstorm-less workflows)
+  - Reference resolved_conflicts for implementation approach alignment
+  - Handle custom_conflicts with explicit task notes
+
+## TEST CONTEXT INTEGRATION
+- Load test-context-package.json for existing test patterns and coverage analysis
+- Extract test framework configuration (Jest/Pytest/etc.)
+- Identify existing test conventions and patterns
+- Map coverage gaps to TDD Red phase test targets
+
+## TDD DOCUMENT GENERATION TASK
 
 **Agent Configuration Reference**: All TDD task generation rules, quantification requirements, Red-Green-Refactor cycle structure, quality standards, and execution details are defined in action-planning-agent.
 
@@ -256,31 +412,61 @@ If conflict_risk was medium/high, modifications have been applied to:
 #### Required Outputs Summary
 
 ##### 1. TDD Task JSON Files (.task/IMPL-*.json)
-- **Location**: `.workflow/active//{session-id}/.task/`
-- **Schema**: 5-field structure with TDD-specific metadata
+- **Location**: `.workflow/active/{session-id}/.task/`
+- **Schema**: 6-field structure with TDD-specific metadata
+  - `id, title, status, context_package_path, meta, context, flow_control`
   - `meta.tdd_workflow`: true (REQUIRED)
   - `meta.max_iterations`: 3 (Green phase test-fix cycle limit)
+  - `meta.cli_execution_id`: Unique CLI execution ID (format: `{session_id}-{task_id}`)
+  - `meta.cli_execution`: Strategy object (new|resume|fork|merge_fork)
   - `context.tdd_cycles`: Array with quantified test cases and coverage
+  - `context.focus_paths`: Absolute or clear relative paths (enhanced with exploration critical_files)
   - `flow_control.implementation_approach`: Exactly 3 steps with `tdd_phase` field
     1. Red Phase (`tdd_phase: "red"`): Write failing tests
     2. Green Phase (`tdd_phase: "green"`): Implement to pass tests
     3. Refactor Phase (`tdd_phase: "refactor"`): Improve code quality
-  - CLI tool usage determined semantically (add `command` field when user requests CLI execution)
+  - `flow_control.pre_analysis`: Include exploration integration_points analysis
+  - CLI tool usage based on userConfig (add `command` field per executionMethod)
 - **Details**: See action-planning-agent.md § TDD Task JSON Generation
 
 ##### 2. IMPL_PLAN.md (TDD Variant)
-- **Location**: `.workflow/active//{session-id}/IMPL_PLAN.md`
+- **Location**: `.workflow/active/{session-id}/IMPL_PLAN.md`
 - **Template**: `~/.claude/workflows/cli-templates/prompts/workflow/impl-plan-template.txt`
 - **TDD-Specific Frontmatter**: workflow_type="tdd", tdd_workflow=true, feature_count, task_breakdown
 - **TDD Implementation Tasks Section**: Feature-by-feature with internal Red-Green-Refactor cycles
+- **Context Analysis**: Artifact references and exploration insights
 - **Details**: See action-planning-agent.md § TDD Implementation Plan Creation
 
 ##### 3. TODO_LIST.md
-- **Location**: `.workflow/active//{session-id}/TODO_LIST.md`
+- **Location**: `.workflow/active/{session-id}/TODO_LIST.md`
 - **Format**: Hierarchical task list with internal TDD phase indicators (Red → Green → Refactor)
 - **Status**: ▸ (container), [ ] (pending), [x] (completed)
+- **Links**: Task JSON references and summaries
 - **Details**: See action-planning-agent.md § TODO List Generation
 
+### CLI EXECUTION ID REQUIREMENTS (MANDATORY)
+
+Each task JSON MUST include:
+- **meta.cli_execution_id**: Unique ID for CLI execution (format: `{session_id}-{task_id}`)
+- **meta.cli_execution**: Strategy object based on depends_on:
+  - No deps → `{ "strategy": "new" }`
+  - 1 dep (single child) → `{ "strategy": "resume", "resume_from": "parent-cli-id" }`
+  - 1 dep (multiple children) → `{ "strategy": "fork", "resume_from": "parent-cli-id" }`
+  - N deps → `{ "strategy": "merge_fork", "resume_from": ["id1", "id2", ...] }`
+  - **Type**: `resume_from: string | string[]` (string for resume/fork, array for merge_fork)
+
+**CLI Execution Strategy Rules**:
+1. **new**: Task has no dependencies - starts fresh CLI conversation
+2. **resume**: Task has 1 parent AND that parent has only this child - continues same conversation
+3. **fork**: Task has 1 parent BUT parent has multiple children - creates new branch with parent context
+4. **merge_fork**: Task has multiple parents - merges all parent contexts into new conversation
+
+**Execution Command Patterns**:
+- new: `ccw cli -p "[prompt]" --tool [tool] --mode write --id [cli_execution_id]`
+- resume: `ccw cli -p "[prompt]" --resume [resume_from] --tool [tool] --mode write`
+- fork: `ccw cli -p "[prompt]" --resume [resume_from] --id [cli_execution_id] --tool [tool] --mode write`
+- merge_fork: `ccw cli -p "[prompt]" --resume [resume_from.join(',')] --id [cli_execution_id] --tool [tool] --mode write` (resume_from is array)
+
 ### Quantification Requirements (MANDATORY)
 
 **Core Rules**:
@@ -302,6 +488,7 @@ If conflict_risk was medium/high, modifications have been applied to:
 - [ ] Every acceptance criterion includes measurable coverage percentage
 - [ ] tdd_cycles array contains test_count and test_cases for each cycle
 - [ ] No vague language ("comprehensive", "complete", "thorough")
+- [ ] cli_execution_id and cli_execution strategy assigned to each task
 
 ### Agent Execution Summary
 
@@ -317,20 +504,34 @@ If conflict_risk was medium/high, modifications have been applied to:
 - ✓ Quantification requirements enforced (explicit counts, measurable acceptance, exact targets)
 - ✓ Task count ≤18 (hard limit)
 - ✓ Each task has meta.tdd_workflow: true
-- ✓ Each task has exactly 3 implementation steps with tdd_phase field
-- ✓ Green phase includes test-fix cycle logic
-- ✓ Artifact references mapped correctly
-- ✓ MCP tool integration added
+- ✓ Each task has exactly 3 implementation steps with tdd_phase field ("red", "green", "refactor")
+- ✓ Each task has meta.cli_execution_id and meta.cli_execution strategy
+- ✓ Green phase includes test-fix cycle logic with max_iterations
+- ✓ focus_paths are absolute or clear relative paths (from exploration critical_files)
+- ✓ Artifact references mapped correctly from context package
+- ✓ Exploration context integrated (critical_files, constraints, patterns, integration_points)
+- ✓ Conflict resolution context applied (if conflict_risk >= medium)
+- ✓ Test context integrated (existing test patterns and coverage analysis)
 - ✓ Documents follow TDD template structure
+- ✓ CLI tool selection based on userConfig.executionMethod
 
-## Output
+## SUCCESS CRITERIA
+- All planning documents generated successfully:
+  - Task JSONs valid and saved to .task/ directory with cli_execution_id
+  - IMPL_PLAN.md created with complete TDD structure
+  - TODO_LIST.md generated matching task JSONs
+- CLI execution strategies assigned based on task dependencies
+- Return completion status with document count and task breakdown summary
 
-Generate all three documents and report completion status:
-- TDD task JSON files created: N files (IMPL-*.json)
+## OUTPUT SUMMARY
+Generate all three documents and report:
+- TDD task JSON files created: N files (IMPL-*.json) with cli_execution_id assigned
 - TDD cycles configured: N cycles with quantified test cases
-- Artifacts integrated: synthesis-spec, guidance-specification, N role analyses
+- CLI execution strategies: new/resume/fork/merge_fork assigned per dependency graph
+- Artifacts integrated: synthesis-spec/guidance-specification, relevant role analyses
+- Exploration context: critical_files, constraints, patterns, integration_points
 - Test context integrated: existing patterns and coverage
-- MCP enhancements: CodexLens, exa-research
+- Conflict resolution: applied (if conflict_risk >= medium)
 - Session ready for TDD execution: /workflow:execute
 `
 )
@@ -338,50 +539,64 @@ Generate all three documents and report completion status:
 
 ### Agent Context Passing
 
-**Memory-Aware Context Assembly**:
+**Context Delegation Model**: Command provides paths and metadata, agent loads context autonomously using progressive loading strategy.
+
+**Command Provides** (in agent prompt):
 ```javascript
-// Assemble context package for agent
-const agentContext = {
-  session_id: "WFS-[id]",
+// Command assembles these simple values and paths for agent
+const commandProvides = {
+  // Session paths
+  session_metadata_path: ".workflow/active/WFS-{id}/workflow-session.json",
+  context_package_path: ".workflow/active/WFS-{id}/.process/context-package.json",
+  test_context_package_path: ".workflow/active/WFS-{id}/.process/test-context-package.json",
+  output_task_dir: ".workflow/active/WFS-{id}/.task/",
+  output_impl_plan: ".workflow/active/WFS-{id}/IMPL_PLAN.md",
+  output_todo_list: ".workflow/active/WFS-{id}/TODO_LIST.md",
+
+  // Simple metadata
+  session_id: "WFS-{id}",
   workflow_type: "tdd",
+  mcp_capabilities: { exa_code: true, exa_web: true, code_index: true },
 
-  // Use memory if available, else load
-  session_metadata: memory.has("workflow-session.json")
-    ? memory.get("workflow-session.json")
-    : Read(.workflow/active/WFS-[id]/workflow-session.json),
-
-  context_package_path: ".workflow/active/WFS-[id]/.process/context-package.json",
-
-  context_package: memory.has("context-package.json")
-    ? memory.get("context-package.json")
-    : Read(".workflow/active/WFS-[id]/.process/context-package.json"),
-
-  test_context_package_path: ".workflow/active/WFS-[id]/.process/test-context-package.json",
-
-  test_context_package: memory.has("test-context-package.json")
-    ? memory.get("test-context-package.json")
-    : Read(".workflow/active/WFS-[id]/.process/test-context-package.json"),
-
-  // Extract brainstorm artifacts from context package
-  brainstorm_artifacts: extractBrainstormArtifacts(context_package),
-
-  // Load role analyses using paths from context package
-  role_analyses: brainstorm_artifacts.role_analyses
-    .flatMap(role => role.files)
-    .map(file => Read(file.path)),
-
-  // Load conflict resolution if exists (prefer new JSON format)
-  conflict_resolution: context_package.conflict_detection?.resolution_file
-    ? Read(context_package.conflict_detection.resolution_file)  // .process/conflict-resolution.json
-    : (brainstorm_artifacts?.conflict_resolution?.exists
-        ? Read(brainstorm_artifacts.conflict_resolution.path)
-        : null),
-
-  // Optional MCP enhancements
-  mcp_analysis: executeMcpDiscovery()
+  // User configuration from Phase 0
+  user_config: {
+    supplementaryMaterials: { type: "...", content: [...] },
+    executionMethod: "agent|hybrid|cli",
+    preferredCliTool: "codex|gemini|qwen|auto",
+    enableResume: true
+  }
 }
 ```
 
+**Agent Loads Autonomously** (progressive loading):
+```javascript
+// Agent executes progressive loading based on memory state
+const agentLoads = {
+  // Core (ALWAYS load if not in memory)
+  session_metadata: loadIfNotInMemory(session_metadata_path),
+  context_package: loadIfNotInMemory(context_package_path),
+
+  // Selective (based on progressive strategy)
+  // Priority: synthesis_output > guidance + relevant_role_analyses
+  brainstorm_content: loadSelectiveBrainstormArtifacts(context_package),
+
+  // On-Demand (load if exists and relevant)
+  test_context: loadIfExists(test_context_package_path),
+  conflict_resolution: loadConflictResolution(context_package),
+
+  // Optional (if MCP available)
+  exploration_results: extractExplorationResults(context_package),
+  external_research: executeMcpResearch()  // If needed
+}
+```
+
+**Progressive Loading Implementation** (agent responsibility):
+1. **Check memory first** - skip if already loaded
+2. **Load core files** - session metadata + context-package.json
+3. **Smart selective loading** - synthesis_output OR (guidance + task-relevant role analyses)
+4. **On-demand loading** - test context, conflict resolution (if conflict_risk >= medium)
+5. **Extract references** - exploration results, artifact paths from context package
+
 ## TDD Task Structure Reference
 
 This section provides quick reference for TDD task JSON structure. For complete implementation details, see the agent invocation prompt in Phase 2 above.
@@ -389,14 +604,31 @@ This section provides quick reference for TDD task JSON structure. For complete
 **Quick Reference**:
 - Each TDD task contains complete Red-Green-Refactor cycle
 - Task ID format: `IMPL-N` (simple) or `IMPL-N.M` (complex subtasks)
-- Required metadata: `meta.tdd_workflow: true`, `meta.max_iterations: 3`
-- Flow control: Exactly 3 steps with `tdd_phase` field (red, green, refactor)
-- Context: `tdd_cycles` array with quantified test cases and coverage
+- Required metadata:
+  - `meta.tdd_workflow: true`
+  - `meta.max_iterations: 3`
+  - `meta.cli_execution_id: "{session_id}-{task_id}"`
+  - `meta.cli_execution: { "strategy": "new|resume|fork|merge_fork", ... }`
+- Context: `tdd_cycles` array with quantified test cases and coverage:
+  ```javascript
+  tdd_cycles: [
+    {
+      test_count: 5,                    // Number of test cases to write
+      test_cases: ["case1", "case2"],   // Enumerated test scenarios
+      implementation_scope: "...",      // Files and functions to implement
+      expected_coverage: ">=85%"        // Coverage target
+    }
+  ]
+  ```
+- Context: `focus_paths` use absolute or clear relative paths
+- Flow control: Exactly 3 steps with `tdd_phase` field ("red", "green", "refactor")
+- Flow control: `pre_analysis` includes exploration integration_points analysis
+- Command field: Added per `userConfig.executionMethod` (agent/hybrid/cli)
 - See Phase 2 agent prompt for full schema and requirements
 
 ## Output Files Structure
 ```
-.workflow/active//{session-id}/
+.workflow/active/{session-id}/
 ├── IMPL_PLAN.md                     # Unified plan with TDD Implementation Tasks section
 ├── TODO_LIST.md                     # Progress tracking with internal TDD phase indicators
 ├── .task/
@@ -432,9 +664,9 @@ This section provides quick reference for TDD task JSON structure. For complete
 - No circular dependencies allowed
 
 ### Task Limits
-- Maximum 10 total tasks (simple + subtasks)
-- Flat hierarchy (≤5 tasks) or two-level (6-10 tasks with containers)
-- Re-scope requirements if >10 tasks needed
+- Maximum 18 total tasks (simple + subtasks) - hard limit for TDD workflows
+- Flat hierarchy (≤5 tasks) or two-level (6-18 tasks with containers)
+- Re-scope requirements if >18 tasks needed
 
 ### TDD Workflow Validation
 - `meta.tdd_workflow` must be true
@@ -454,7 +686,7 @@ This section provides quick reference for TDD task JSON structure. For complete
 ### TDD Generation Errors
 | Error | Cause | Resolution |
 |-------|-------|------------|
-| Task count exceeds 10 | Too many features or subtasks | Re-scope requirements or merge features |
+| Task count exceeds 18 | Too many features or subtasks | Re-scope requirements or merge features into multiple TDD sessions |
 | Missing test framework | No test config | Configure testing first |
 | Invalid TDD workflow | Missing tdd_phase or incomplete flow_control | Fix TDD structure in ANALYSIS_RESULTS.md |
 | Missing tdd_workflow flag | Task doesn't have meta.tdd_workflow: true | Add TDD workflow metadata |
@@ -512,6 +744,6 @@ IMPL (Green phase) tasks include automatic test-fix cycle:
 
 
 ## Configuration Options
-- **meta.max_iterations**: Number of fix attempts (default: 3 for TDD, 5 for test-gen)
+- **meta.max_iterations**: Number of fix attempts in Green phase (default: 3)
 - **CLI tool usage**: Determined semantically from user's task description via `command` field in implementation_approach
 

.claude/commands/workflow/ui-design/animation-extract.md

@@ -1,10 +1,14 @@
 ---
 name: animation-extract
 description: Extract animation and transition patterns from prompt inference and image references for design system documentation
-argument-hint: "[--design-id <id>] [--session <id>] [--images "<glob>"] [--focus "<types>"] [--interactive] [--refine]"
+argument-hint: "[-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--focus "<types>"] [--interactive] [--refine]"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestion(*), Task(ui-design-agent)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Skip all clarification questions, use AI-inferred animation decisions.
+
 # Animation Extraction Command
 
 ## Overview

.claude/commands/workflow/ui-design/layout-extract.md

@@ -1,10 +1,14 @@
 ---
 name: layout-extract
 description: Extract structural layout information from reference images or text prompts using Claude analysis with variant generation or refinement mode
-argument-hint: [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]
+argument-hint: "[-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--targets "<list>"] [--variants <count>] [--device-type <desktop|mobile|tablet|responsive>] [--interactive] [--refine]"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), Bash(*), AskUserQuestion(*), Task(ui-design-agent), mcp__exa__web_search_exa(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Skip all clarification questions, use AI-inferred layout decisions.
+
 # Layout Extraction Command
 
 ## Overview

.claude/commands/workflow/ui-design/style-extract.md

@@ -1,10 +1,14 @@
 ---
 name: style-extract
 description: Extract design style from reference images or text prompts using Claude analysis with variant generation or refinement mode
-argument-hint: "[--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--variants <count>] [--interactive] [--refine]"
+argument-hint: "[-y|--yes] [--design-id <id>] [--session <id>] [--images "<glob>"] [--prompt "<desc>"] [--variants <count>] [--interactive] [--refine]"
 allowed-tools: TodoWrite(*), Read(*), Write(*), Glob(*), AskUserQuestion(*)
 ---
 
+## Auto Mode
+
+When `--yes` or `-y`: Skip all clarification questions, use AI-inferred design decisions.
+
 # Style Extraction Command
 
 ## Overview

.claude/skills/ccw-help/command.json

@@ -15,7 +15,7 @@
     "/workflow:review-session-cycle",
     "/memory:docs",
     "/workflow:brainstorm:artifacts",
-    "/workflow:action-plan-verify",
+    "/workflow:plan-verify",
     "/version"
   ],
 
@@ -69,7 +69,7 @@
       "difficulty": "Intermediate",
       "essential": true,
       "flow": {
-        "next_steps": ["/workflow:action-plan-verify", "/workflow:execute"],
+        "next_steps": ["/workflow:plan-verify", "/workflow:execute"],
         "alternatives": ["/workflow:tdd-plan"]
       },
       "source": "../../../commands/workflow/plan.md"
@@ -89,8 +89,8 @@
       "source": "../../../commands/workflow/execute.md"
     },
     {
-      "name": "action-plan-verify",
-      "command": "/workflow:action-plan-verify",
+      "name": "plan-verify",
+      "command": "/workflow:plan-verify",
       "description": "Cross-artifact consistency analysis",
       "arguments": "[--session session-id]",
       "category": "workflow",
@@ -100,7 +100,7 @@
         "prerequisites": ["/workflow:plan"],
         "next_steps": ["/workflow:execute"]
       },
-      "source": "../../../commands/workflow/action-plan-verify.md"
+      "source": "../../../commands/workflow/plan-verify.md"
     },
     {
       "name": "init",

.claude/skills/ccw-help/scripts/analyze_commands.py

@@ -144,7 +144,7 @@ def build_command_relationships() -> Dict[str, Any]:
     return {
         "workflow:plan": {
             "calls_internally": ["workflow:session:start", "workflow:tools:context-gather", "workflow:tools:conflict-resolution", "workflow:tools:task-generate-agent"],
-            "next_steps": ["workflow:action-plan-verify", "workflow:status", "workflow:execute"],
+            "next_steps": ["workflow:plan-verify", "workflow:status", "workflow:execute"],
             "alternatives": ["workflow:tdd-plan"],
             "prerequisites": []
         },
@@ -159,7 +159,7 @@ def build_command_relationships() -> Dict[str, Any]:
             "related": ["workflow:status", "workflow:resume"],
             "next_steps": ["workflow:review", "workflow:tdd-verify"]
         },
-        "workflow:action-plan-verify": {
+        "workflow:plan-verify": {
             "prerequisites": ["workflow:plan"],
             "next_steps": ["workflow:execute"],
             "related": ["workflow:status"]
@@ -217,7 +217,7 @@ def identify_essential_commands(all_commands: List[Dict]) -> List[Dict]:
         "workflow:execute", "workflow:status", "workflow:session:start",
         "workflow:review-session-cycle", "cli:analyze", "cli:chat",
         "memory:docs", "workflow:brainstorm:artifacts",
-        "workflow:action-plan-verify", "workflow:resume", "version"
+        "workflow:plan-verify", "workflow:resume", "version"
     ]
 
     essential = []

.claude/skills/ccw/SKILL.md

@@ -1,522 +0,0 @@
----
-name: ccw
-description: Stateless workflow orchestrator. Auto-selects optimal workflow based on task intent. Triggers "ccw", "workflow".
-allowed-tools: Task(*), SlashCommand(*), AskUserQuestion(*), Read(*), Bash(*), Grep(*), TodoWrite(*)
----
-
-# CCW - Claude Code Workflow Orchestrator
-
-无状态工作流协调器，根据任务意图自动选择最优工作流。
-
-## Workflow System Overview
-
-CCW 提供两个工作流系统：**Main Workflow** 和 **Issue Workflow**，协同覆盖完整的软件开发生命周期。
-
-```
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                              Main Workflow                                  │
-│                                                                             │
-│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌─────────────┐     │
-│  │   Level 1   │ → │   Level 2   │ → │   Level 3   │ → │   Level 4   │     │
-│  │   Rapid     │   │ Lightweight │   │  Standard   │   │ Brainstorm  │     │
-│  │             │   │             │   │             │   │             │     │
-│  │ lite-lite-  │   │ lite-plan   │   │    plan     │   │ brainstorm  │     │
-│  │    lite     │   │ lite-fix    │   │  tdd-plan   │   │  :auto-     │     │
-│  │             │   │ multi-cli-  │   │ test-fix-   │   │  parallel   │     │
-│  │             │   │    plan     │   │    gen      │   │     ↓       │     │
-│  │             │   │             │   │             │   │   plan      │     │
-│  └─────────────┘   └─────────────┘   └─────────────┘   └─────────────┘     │
-│                                                                             │
-│  Complexity: ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━▶  │
-│              Low                                                    High    │
-└─────────────────────────────────────────────────────────────────────────────┘
-                                    │
-                                    │ After development
-                                    ▼
-┌─────────────────────────────────────────────────────────────────────────────┐
-│                              Issue Workflow                                 │
-│                                                                             │
-│     ┌──────────────┐         ┌──────────────┐         ┌──────────────┐     │
-│     │  Accumulate  │    →    │    Plan      │    →    │   Execute    │     │
-│     │  Discover &  │         │    Batch     │         │   Parallel   │     │
-│     │   Collect    │         │   Planning   │         │  Execution   │     │
-│     └──────────────┘         └──────────────┘         └──────────────┘     │
-│                                                                             │
-│     Supplementary role: Maintain main branch stability, worktree isolation  │
-└─────────────────────────────────────────────────────────────────────────────┘
-```
-
-## Architecture
-
-```
-┌─────────────────────────────────────────────────────────────────┐
-│  CCW Orchestrator (CLI-Enhanced + Requirement Analysis)         │
-├─────────────────────────────────────────────────────────────────┤
-│  Phase 1    │ Input Analysis (rule-based, fast path)            │
-│  Phase 1.5  │ CLI Classification (semantic, smart path)         │
-│  Phase 1.75 │ Requirement Clarification (clarity < 2)           │
-│  Phase 2    │ Level Selection (intent → level → workflow)       │
-│  Phase 2.5  │ CLI Action Planning (high complexity)             │
-│  Phase 3    │ User Confirmation (optional)                      │
-│  Phase 4    │ TODO Tracking Setup                               │
-│  Phase 5    │ Execution Loop                                    │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Level Quick Reference
-
-| Level | Name | Workflows | Artifacts | Execution |
-|-------|------|-----------|-----------|-----------|
-| **1** | Rapid | `lite-lite-lite` | None | Direct execute |
-| **2** | Lightweight | `lite-plan`, `lite-fix`, `multi-cli-plan` | Memory/Lightweight files | → `lite-execute` |
-| **3** | Standard | `plan`, `tdd-plan`, `test-fix-gen` | Session persistence | → `execute` / `test-cycle-execute` |
-| **4** | Brainstorm | `brainstorm:auto-parallel` → `plan` | Multi-role analysis + Session | → `execute` |
-| **-** | Issue | `discover` → `plan` → `queue` → `execute` | Issue records | Worktree isolation (optional) |
-
-## Workflow Selection Decision Tree
-
-```
-Start
-  │
-  ├─ Is it post-development maintenance?
-  │     ├─ Yes → Issue Workflow
-  │     └─ No ↓
-  │
-  ├─ Are requirements clear?
-  │     ├─ Uncertain → Level 4 (brainstorm:auto-parallel)
-  │     └─ Clear ↓
-  │
-  ├─ Need persistent Session?
-  │     ├─ Yes → Level 3 (plan / tdd-plan / test-fix-gen)
-  │     └─ No ↓
-  │
-  ├─ Need multi-perspective / solution comparison?
-  │     ├─ Yes → Level 2 (multi-cli-plan)
-  │     └─ No ↓
-  │
-  ├─ Is it a bug fix?
-  │     ├─ Yes → Level 2 (lite-fix)
-  │     └─ No ↓
-  │
-  ├─ Need planning?
-  │     ├─ Yes → Level 2 (lite-plan)
-  │     └─ No → Level 1 (lite-lite-lite)
-```
-
-## Intent Classification
-
-### Priority Order (with Level Mapping)
-
-| Priority | Intent | Patterns | Level | Flow |
-|----------|--------|----------|-------|------|
-| 1 | bugfix/hotfix | `urgent,production,critical` + bug | L2 | `bugfix.hotfix` |
-| 1 | bugfix | `fix,bug,error,crash,fail` | L2 | `bugfix.standard` |
-| 2 | issue batch | `issues,batch` + `fix,resolve` | Issue | `issue` |
-| 3 | exploration | `不确定,explore,研究,what if` | L4 | `full` |
-| 3 | multi-perspective | `多视角,权衡,比较方案,cross-verify` | L2 | `multi-cli-plan` |
-| 4 | quick-task | `快速,简单,small,quick` + feature | L1 | `lite-lite-lite` |
-| 5 | ui design | `ui,design,component,style` | L3/L4 | `ui` |
-| 6 | tdd | `tdd,test-driven,先写测试` | L3 | `tdd` |
-| 7 | test-fix | `测试失败,test fail,fix test` | L3 | `test-fix-gen` |
-| 8 | review | `review,审查,code review` | L3 | `review-fix` |
-| 9 | documentation | `文档,docs,readme` | L2 | `docs` |
-| 99 | feature | complexity-based | L2/L3 | `rapid`/`coupled` |
-
-### Quick Selection Guide
-
-| Scenario | Recommended Workflow | Level |
-|----------|---------------------|-------|
-| Quick fixes, config adjustments | `lite-lite-lite` | 1 |
-| Clear single-module features | `lite-plan → lite-execute` | 2 |
-| Bug diagnosis and fix | `lite-fix` | 2 |
-| Production emergencies | `lite-fix --hotfix` | 2 |
-| Technology selection, solution comparison | `multi-cli-plan → lite-execute` | 2 |
-| Multi-module changes, refactoring | `plan → verify → execute` | 3 |
-| Test-driven development | `tdd-plan → execute → tdd-verify` | 3 |
-| Test failure fixes | `test-fix-gen → test-cycle-execute` | 3 |
-| New features, architecture design | `brainstorm:auto-parallel → plan → execute` | 4 |
-| Post-development issue fixes | Issue Workflow | - |
-
-### Complexity Assessment
-
-```javascript
-function assessComplexity(text) {
-  let score = 0
-  if (/refactor|重构|migrate|迁移|architect|架构|system|系统/.test(text)) score += 2
-  if (/multiple|多个|across|跨|all|所有|entire|整个/.test(text)) score += 2
-  if (/integrate|集成|api|database|数据库/.test(text)) score += 1
-  if (/security|安全|performance|性能|scale|扩展/.test(text)) score += 1
-  return score >= 4 ? 'high' : score >= 2 ? 'medium' : 'low'
-}
-```
-
-| Complexity | Flow |
-|------------|------|
-| high | `coupled` (plan → verify → execute) |
-| medium/low | `rapid` (lite-plan → lite-execute) |
-
-### Dimension Extraction (WHAT/WHERE/WHY/HOW)
-
-从用户输入提取四个维度，用于需求澄清和工作流选择：
-
-| 维度 | 提取内容 | 示例模式 |
-|------|----------|----------|
-| **WHAT** | action + target | `创建/修复/重构/优化/分析` + 目标对象 |
-| **WHERE** | scope + paths | `file/module/system` + 文件路径 |
-| **WHY** | goal + motivation | `为了.../因为.../目的是...` |
-| **HOW** | constraints + preferences | `必须.../不要.../应该...` |
-
-**Clarity Score** (0-3):
-- +0.5: 有明确 action
-- +0.5: 有具体 target
-- +0.5: 有文件路径
-- +0.5: scope 不是 unknown
-- +0.5: 有明确 goal
-- +0.5: 有约束条件
-- -0.5: 包含不确定词 (`不知道/maybe/怎么`)
-
-### Requirement Clarification
-
-当 `clarity_score < 2` 时触发需求澄清：
-
-```javascript
-if (dimensions.clarity_score < 2) {
-  const questions = generateClarificationQuestions(dimensions)
-  // 生成问题：目标是什么? 范围是什么? 有什么约束?
-  AskUserQuestion({ questions })
-}
-```
-
-**澄清问题类型**:
-- 目标不明确 → "你想要对什么进行操作?"
-- 范围不明确 → "操作的范围是什么?"
-- 目的不明确 → "这个操作的主要目标是什么?"
-- 复杂操作 → "有什么特殊要求或限制?"
-
-## TODO Tracking Protocol
-
-### CRITICAL: Append-Only Rule
-
-CCW 创建的 Todo **必须附加到现有列表**，不能覆盖用户的其他 Todo。
-
-### Implementation
-
-```javascript
-// 1. 使用 CCW 前缀隔离工作流 todo
-const prefix = `CCW:${flowName}`
-
-// 2. 创建新 todo 时使用前缀格式
-TodoWrite({
-  todos: [
-    ...existingNonCCWTodos,  // 保留用户的 todo
-    { content: `${prefix}: [1/N] /command:step1`, status: "in_progress", activeForm: "..." },
-    { content: `${prefix}: [2/N] /command:step2`, status: "pending", activeForm: "..." }
-  ]
-})
-
-// 3. 更新状态时只修改匹配前缀的 todo
-```
-
-### Todo Format
-
-```
-CCW:{flow}: [{N}/{Total}] /command:name
-```
-
-### Visual Example
-
-```
-✓ CCW:rapid: [1/2] /workflow:lite-plan
-→ CCW:rapid: [2/2] /workflow:lite-execute
-  用户自己的 todo（保留不动）
-```
-
-### Status Management
-
-- 开始工作流：创建所有步骤 todo，第一步 `in_progress`
-- 完成步骤：当前步骤 `completed`，下一步 `in_progress`
-- 工作流结束：所有 CCW todo 标记 `completed`
-
-## Execution Flow
-
-```javascript
-// 1. Check explicit command
-if (input.startsWith('/workflow:') || input.startsWith('/issue:')) {
-  SlashCommand(input)
-  return
-}
-
-// 2. Classify intent
-const intent = classifyIntent(input)  // See command.json intent_rules
-
-// 3. Select flow
-const flow = selectFlow(intent)  // See command.json flows
-
-// 4. Create todos with CCW prefix
-createWorkflowTodos(flow)
-
-// 5. Dispatch first command
-SlashCommand(flow.steps[0].command, args: input)
-```
-
-## CLI Tool Integration
-
-CCW 在特定条件下自动注入 CLI 调用：
-
-| Condition | CLI Inject |
-|-----------|------------|
-| 大量代码上下文 (≥50k chars) | `gemini --mode analysis` |
-| 高复杂度任务 | `gemini --mode analysis` |
-| Bug 诊断 | `gemini --mode analysis` |
-| 多任务执行 (≥3 tasks) | `codex --mode write` |
-
-### CLI Enhancement Phases
-
-**Phase 1.5: CLI-Assisted Classification**
-
-当规则匹配不明确时，使用 CLI 辅助分类：
-
-| 触发条件 | 说明 |
-|----------|------|
-| matchCount < 2 | 多个意图模式匹配 |
-| complexity = high | 高复杂度任务 |
-| input > 100 chars | 长输入需要语义理解 |
-
-**Phase 2.5: CLI-Assisted Action Planning**
-
-高复杂度任务的工作流优化：
-
-| 触发条件 | 说明 |
-|----------|------|
-| complexity = high | 高复杂度任务 |
-| steps >= 3 | 多步骤工作流 |
-| input > 200 chars | 复杂需求描述 |
-
-CLI 可返回建议：`use_default` | `modify` (调整步骤) | `upgrade` (升级工作流)
-
-## Continuation Commands
-
-工作流执行中的用户控制命令：
-
-| 命令 | 作用 |
-|------|------|
-| `continue` | 继续执行下一步 |
-| `skip` | 跳过当前步骤 |
-| `abort` | 终止工作流 |
-| `/workflow:*` | 切换到指定命令 |
-| 自然语言 | 重新分析意图 |
-
-## Workflow Flow Details
-
-### Issue Workflow (Main Workflow 补充机制)
-
-Issue Workflow 是 Main Workflow 的**补充机制**，专注于开发后的持续维护。
-
-#### 设计理念
-
-| 方面 | Main Workflow | Issue Workflow |
-|------|---------------|----------------|
-| **用途** | 主要开发周期 | 开发后维护 |
-| **时机** | 功能开发阶段 | 主工作流完成后 |
-| **范围** | 完整功能实现 | 针对性修复/增强 |
-| **并行性** | 依赖分析 → Agent 并行 | Worktree 隔离 (可选) |
-| **分支模型** | 当前分支工作 | 可使用隔离的 worktree |
-
-#### 为什么 Main Workflow 不自动使用 Worktree？
-
-**依赖分析已解决并行性问题**：
-1. 规划阶段 (`/workflow:plan`) 执行依赖分析
-2. 自动识别任务依赖和关键路径
-3. 划分为**并行组**（独立任务）和**串行链**（依赖任务）
-4. Agent 并行执行独立任务，无需文件系统隔离
-
-#### 两阶段生命周期
-
-```
-┌─────────────────────────────────────────────────────────────────────┐
-│                    Phase 1: Accumulation (积累阶段)                  │
-│                                                                     │
-│   Triggers: 任务完成后的 review、代码审查发现、测试失败              │
-│                                                                     │
-│   ┌────────────┐     ┌────────────┐     ┌────────────┐             │
-│   │ discover   │     │ discover-  │     │    new     │             │
-│   │ Auto-find  │     │ by-prompt  │     │  Manual    │             │
-│   └────────────┘     └────────────┘     └────────────┘             │
-│                                                                     │
-│   持续积累 issues 到待处理队列                                       │
-└─────────────────────────────────────────────────────────────────────┘
-                               │
-                               │ 积累足够后
-                               ▼
-┌─────────────────────────────────────────────────────────────────────┐
-│                  Phase 2: Batch Resolution (批量解决阶段)            │
-│                                                                     │
-│   ┌────────────┐     ┌────────────┐     ┌────────────┐             │
-│   │   plan     │ ──→ │   queue    │ ──→ │  execute   │             │
-│   │ --all-     │     │ Optimize   │     │  Parallel  │             │
-│   │  pending   │     │  order     │     │ execution  │             │
-│   └────────────┘     └────────────┘     └────────────┘             │
-│                                                                     │
-│   支持 worktree 隔离，保持主分支稳定                                 │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-#### 与 Main Workflow 的协作
-
-```
-开发迭代循环
-┌─────────────────────────────────────────────────────────────────────┐
-│                                                                     │
-│   ┌─────────┐                              ┌─────────┐             │
-│   │ Feature │ ──→ Main Workflow ──→ Done ──→│ Review  │             │
-│   │ Request │     (Level 1-4)              └────┬────┘             │
-│   └─────────┘                                   │                  │
-│        ▲                                        │ 发现 Issues       │
-│        │                                        ▼                  │
-│        │                                  ┌─────────┐              │
-│   继续 │                                  │  Issue  │              │
-│   新功能│                                  │ Workflow│              │
-│        │                                  └────┬────┘              │
-│        │         ┌──────────────────────────────┘                   │
-│        │         │ 修复完成                                          │
-│        │         ▼                                                 │
-│   ┌────┴────┐◀──────                                               │
-│   │  Main   │    Merge                                             │
-│   │ Branch  │    back                                              │
-│   └─────────┘                                                      │
-│                                                                     │
-└─────────────────────────────────────────────────────────────────────┘
-```
-
-#### 命令列表
-
-**积累阶段：**
-```bash
-/issue:discover            # 多视角自动发现
-/issue:discover-by-prompt  # 基于提示发现
-/issue:new                 # 手动创建
-```
-
-**批量解决阶段：**
-```bash
-/issue:plan --all-pending  # 批量规划所有待处理
-/issue:queue               # 生成优化执行队列
-/issue:execute             # 并行执行
-```
-
-### lite-lite-lite vs multi-cli-plan
-
-| 维度 | lite-lite-lite | multi-cli-plan |
-|------|---------------|----------------|
-| **产物** | 无文件 | IMPL_PLAN.md + plan.json + synthesis.json |
-| **状态** | 无状态 | 持久化 session |
-| **CLI选择** | 自动分析任务类型选择 | 配置驱动 |
-| **迭代** | 通过 AskUser | 多轮收敛 |
-| **执行** | 直接执行 | 通过 lite-execute |
-| **适用** | 快速修复、简单功能 | 复杂多步骤实现 |
-
-**选择指南**：
-- 任务清晰、改动范围小 → `lite-lite-lite`
-- 需要多视角分析、复杂架构 → `multi-cli-plan`
-
-### multi-cli-plan vs lite-plan
-
-| 维度 | multi-cli-plan | lite-plan |
-|------|---------------|-----------|
-| **上下文** | ACE 语义搜索 | 手动文件模式 |
-| **分析** | 多 CLI 交叉验证 | 单次规划 |
-| **迭代** | 多轮直到收敛 | 单轮 |
-| **置信度** | 高 (共识驱动) | 中 (单一视角) |
-| **适用** | 需要多视角的复杂任务 | 直接明确的实现 |
-
-**选择指南**：
-- 需求明确、路径清晰 → `lite-plan`
-- 需要权衡、多方案比较 → `multi-cli-plan`
-
-## Artifact Flow Protocol
-
-工作流产出的自动流转机制，支持不同格式产出间的意图提取和完成度判断。
-
-### 产出格式
-
-| 命令 | 产出位置 | 格式 | 关键字段 |
-|------|----------|------|----------|
-| `/workflow:lite-plan` | memory://plan | structured_plan | tasks, files, dependencies |
-| `/workflow:plan` | .workflow/{session}/IMPL_PLAN.md | markdown_plan | phases, tasks, risks |
-| `/workflow:execute` | execution_log.json | execution_report | completed_tasks, errors |
-| `/workflow:test-cycle-execute` | test_results.json | test_report | pass_rate, failures, coverage |
-| `/workflow:review-session-cycle` | review_report.md | review_report | findings, severity_counts |
-
-### 意图提取 (Intent Extraction)
-
-流转到下一步时，自动提取关键信息：
-
-```
-plan → execute:
-  提取: tasks (未完成), priority_order, files_to_modify, context_summary
-
-execute → test:
-  提取: modified_files, test_scope (推断), pending_verification
-
-test → fix:
-  条件: pass_rate < 0.95
-  提取: failures, error_messages, affected_files, suggested_fixes
-
-review → fix:
-  条件: critical > 0 OR high > 3
-  提取: findings (critical/high), fix_priority, affected_files
-```
-
-### 完成度判断
-
-**Test 完成度路由**:
-```
-pass_rate >= 0.95 AND coverage >= 0.80  → complete
-pass_rate >= 0.95 AND coverage < 0.80   → add_more_tests
-pass_rate >= 0.80                        → fix_failures_then_continue
-pass_rate < 0.80                         → major_fix_required
-```
-
-**Review 完成度路由**:
-```
-critical == 0 AND high <= 3  → complete_or_optional_fix
-critical > 0                  → mandatory_fix
-high > 3                      → recommended_fix
-```
-
-### 流转决策模式
-
-**plan_execute_test**:
-```
-plan → execute → test
-         ↓ (if test fail)
-    extract_failures → fix → test (max 3 iterations)
-         ↓ (if still fail)
-    manual_intervention
-```
-
-**iterative_improvement**:
-```
-execute → test → fix → test → ...
-    loop until: pass_rate >= 0.95 OR iterations >= 3
-```
-
-### 使用示例
-
-```javascript
-// 执行完成后，根据产出决定下一步
-const result = await execute(plan)
-
-// 提取意图流转到测试
-const testContext = extractIntent('execute_to_test', result)
-// testContext = { modified_files, test_scope, pending_verification }
-
-// 测试完成后，根据完成度决定路由
-const testResult = await test(testContext)
-const nextStep = evaluateCompletion('test', testResult)
-// nextStep = 'fix_failures_then_continue' if pass_rate = 0.85
-```
-
-## Reference
-
-- [command.json](command.json) - 命令元数据、Flow 定义、意图规则、Artifact Flow

.claude/skills/ccw/command.json

@@ -1,641 +0,0 @@
-{
-  "_metadata": {
-    "version": "2.0.0",
-    "description": "Unified CCW command index with capabilities, flows, and intent rules"
-  },
-
-  "capabilities": {
-    "explore": {
-      "description": "Codebase exploration and context gathering",
-      "commands": ["/workflow:init", "/workflow:tools:gather", "/memory:load"],
-      "agents": ["cli-explore-agent", "context-search-agent"]
-    },
-    "brainstorm": {
-      "description": "Multi-perspective analysis and ideation",
-      "commands": ["/workflow:brainstorm:auto-parallel", "/workflow:brainstorm:artifacts", "/workflow:brainstorm:synthesis"],
-      "roles": ["product-manager", "system-architect", "ux-expert", "data-architect", "api-designer"]
-    },
-    "plan": {
-      "description": "Task planning and decomposition",
-      "commands": ["/workflow:lite-plan", "/workflow:plan", "/workflow:tdd-plan", "/task:create", "/task:breakdown"],
-      "agents": ["cli-lite-planning-agent", "action-planning-agent"]
-    },
-    "verify": {
-      "description": "Plan and quality verification",
-      "commands": ["/workflow:action-plan-verify", "/workflow:tdd-verify"]
-    },
-    "execute": {
-      "description": "Task execution and implementation",
-      "commands": ["/workflow:lite-execute", "/workflow:execute", "/task:execute"],
-      "agents": ["code-developer", "cli-execution-agent", "universal-executor"]
-    },
-    "bugfix": {
-      "description": "Bug diagnosis and fixing",
-      "commands": ["/workflow:lite-fix"],
-      "agents": ["code-developer"]
-    },
-    "test": {
-      "description": "Test generation and execution",
-      "commands": ["/workflow:test-gen", "/workflow:test-fix-gen", "/workflow:test-cycle-execute"],
-      "agents": ["test-fix-agent"]
-    },
-    "review": {
-      "description": "Code review and quality analysis",
-      "commands": ["/workflow:review-session-cycle", "/workflow:review-module-cycle", "/workflow:review", "/workflow:review-fix"]
-    },
-    "issue": {
-      "description": "Issue lifecycle management - discover, accumulate, batch resolve",
-      "commands": ["/issue:new", "/issue:discover", "/issue:discover-by-prompt", "/issue:plan", "/issue:queue", "/issue:execute", "/issue:manage"],
-      "agents": ["issue-plan-agent", "issue-queue-agent", "cli-explore-agent"],
-      "lifecycle": {
-        "accumulation": {
-          "description": "任务完成后进行需求扩展、bug分析、测试发现",
-          "triggers": ["post-task review", "code review findings", "test failures"],
-          "commands": ["/issue:discover", "/issue:discover-by-prompt", "/issue:new"]
-        },
-        "batch_resolution": {
-          "description": "积累的issue集中规划和并行执行",
-          "flow": ["plan", "queue", "execute"],
-          "commands": ["/issue:plan --all-pending", "/issue:queue", "/issue:execute"]
-        }
-      }
-    },
-    "ui-design": {
-      "description": "UI design and prototyping",
-      "commands": ["/workflow:ui-design:explore-auto", "/workflow:ui-design:imitate-auto", "/workflow:ui-design:design-sync"],
-      "agents": ["ui-design-agent"]
-    },
-    "memory": {
-      "description": "Documentation and knowledge management",
-      "commands": ["/memory:docs", "/memory:update-related", "/memory:update-full", "/memory:skill-memory"],
-      "agents": ["doc-generator", "memory-bridge"]
-    }
-  },
-
-  "flows": {
-    "_level_guide": {
-      "L1": "Rapid - No artifacts, direct execution",
-      "L2": "Lightweight - Memory/lightweight files, → lite-execute",
-      "L3": "Standard - Session persistence, → execute/test-cycle-execute",
-      "L4": "Brainstorm - Multi-role analysis + Session, → execute"
-    },
-    "lite-lite-lite": {
-      "name": "Ultra-Rapid Execution",
-      "level": "L1",
-      "description": "零文件 + 自动CLI选择 + 语义描述 + 直接执行",
-      "complexity": ["low"],
-      "artifacts": "none",
-      "steps": [
-        { "phase": "clarify", "description": "需求澄清 (AskUser if needed)" },
-        { "phase": "auto-select", "description": "任务分析 → 自动选择CLI组合" },
-        { "phase": "multi-cli", "description": "并行多CLI分析" },
-        { "phase": "decision", "description": "展示结果 → AskUser决策" },
-        { "phase": "execute", "description": "直接执行 (无中间文件)" }
-      ],
-      "cli_hints": {
-        "analysis": { "tool": "auto", "mode": "analysis", "parallel": true },
-        "execution": { "tool": "auto", "mode": "write" }
-      },
-      "estimated_time": "10-30 min"
-    },
-    "rapid": {
-      "name": "Rapid Iteration",
-      "level": "L2",
-      "description": "内存规划 + 直接执行",
-      "complexity": ["low", "medium"],
-      "artifacts": "memory://plan",
-      "steps": [
-        { "command": "/workflow:lite-plan", "optional": false, "auto_continue": true },
-        { "command": "/workflow:lite-execute", "optional": false }
-      ],
-      "cli_hints": {
-        "explore_phase": { "tool": "gemini", "mode": "analysis", "trigger": "needs_exploration" },
-        "execution": { "tool": "codex", "mode": "write", "trigger": "complexity >= medium" }
-      },
-      "estimated_time": "15-45 min"
-    },
-    "multi-cli-plan": {
-      "name": "Multi-CLI Collaborative Planning",
-      "level": "L2",
-      "description": "ACE上下文 + 多CLI协作分析 + 迭代收敛 + 计划生成",
-      "complexity": ["medium", "high"],
-      "artifacts": ".workflow/.multi-cli-plan/{session}/",
-      "steps": [
-        { "command": "/workflow:multi-cli-plan", "optional": false, "phases": [
-          "context_gathering: ACE语义搜索",
-          "multi_cli_discussion: cli-discuss-agent多轮分析",
-          "present_options: 展示解决方案",
-          "user_decision: 用户选择",
-          "plan_generation: cli-lite-planning-agent生成计划"
-        ]},
-        { "command": "/workflow:lite-execute", "optional": false }
-      ],
-      "vs_lite_plan": {
-        "context": "ACE semantic search vs Manual file patterns",
-        "analysis": "Multi-CLI cross-verification vs Single-pass planning",
-        "iteration": "Multiple rounds until convergence vs Single round",
-        "confidence": "High (consensus-based) vs Medium (single perspective)",
-        "best_for": "Complex tasks needing multiple perspectives vs Straightforward implementations"
-      },
-      "agents": ["cli-discuss-agent", "cli-lite-planning-agent"],
-      "cli_hints": {
-        "discussion": { "tools": ["gemini", "codex", "claude"], "mode": "analysis", "parallel": true },
-        "planning": { "tool": "gemini", "mode": "analysis" }
-      },
-      "estimated_time": "30-90 min"
-    },
-    "coupled": {
-      "name": "Standard Planning",
-      "level": "L3",
-      "description": "完整规划 + 验证 + 执行",
-      "complexity": ["medium", "high"],
-      "artifacts": ".workflow/active/{session}/",
-      "steps": [
-        { "command": "/workflow:plan", "optional": false },
-        { "command": "/workflow:action-plan-verify", "optional": false, "auto_continue": true },
-        { "command": "/workflow:execute", "optional": false },
-        { "command": "/workflow:review", "optional": true }
-      ],
-      "cli_hints": {
-        "pre_analysis": { "tool": "gemini", "mode": "analysis", "trigger": "always" },
-        "execution": { "tool": "codex", "mode": "write", "trigger": "always" }
-      },
-      "estimated_time": "2-4 hours"
-    },
-    "full": {
-      "name": "Full Exploration (Brainstorm)",
-      "level": "L4",
-      "description": "头脑风暴 + 规划 + 执行",
-      "complexity": ["high"],
-      "artifacts": ".workflow/active/{session}/.brainstorming/",
-      "steps": [
-        { "command": "/workflow:brainstorm:auto-parallel", "optional": false, "confirm_before": true },
-        { "command": "/workflow:plan", "optional": false },
-        { "command": "/workflow:action-plan-verify", "optional": true, "auto_continue": true },
-        { "command": "/workflow:execute", "optional": false }
-      ],
-      "cli_hints": {
-        "role_analysis": { "tool": "gemini", "mode": "analysis", "trigger": "always", "parallel": true },
-        "execution": { "tool": "codex", "mode": "write", "trigger": "task_count >= 3" }
-      },
-      "estimated_time": "1-3 hours"
-    },
-    "bugfix": {
-      "name": "Bug Fix",
-      "level": "L2",
-      "description": "智能诊断 + 修复 (5 phases)",
-      "complexity": ["low", "medium"],
-      "artifacts": ".workflow/.lite-fix/{bug-slug}-{date}/",
-      "variants": {
-        "standard": [{ "command": "/workflow:lite-fix", "optional": false }],
-        "hotfix": [{ "command": "/workflow:lite-fix --hotfix", "optional": false }]
-      },
-      "phases": [
-        "Phase 1: Bug Analysis & Diagnosis (severity pre-assessment)",
-        "Phase 2: Clarification (optional, AskUserQuestion)",
-        "Phase 3: Fix Planning (Low/Medium → Claude, High/Critical → cli-lite-planning-agent)",
-        "Phase 4: Confirmation & Selection",
-        "Phase 5: Execute (→ lite-execute --mode bugfix)"
-      ],
-      "cli_hints": {
-        "diagnosis": { "tool": "gemini", "mode": "analysis", "trigger": "always" },
-        "fix": { "tool": "codex", "mode": "write", "trigger": "severity >= medium" }
-      },
-      "estimated_time": "10-30 min"
-    },
-    "issue": {
-      "name": "Issue Lifecycle",
-      "level": "Supplementary",
-      "description": "发现积累 → 批量规划 → 队列优化 → 并行执行 (Main Workflow 补充机制)",
-      "complexity": ["medium", "high"],
-      "artifacts": ".workflow/.issues/",
-      "purpose": "Post-development continuous maintenance, maintain main branch stability",
-      "phases": {
-        "accumulation": {
-          "description": "项目迭代中持续发现和积累issue",
-          "commands": ["/issue:discover", "/issue:discover-by-prompt", "/issue:new"],
-          "trigger": "post-task, code-review, test-failure"
-        },
-        "resolution": {
-          "description": "集中规划和执行积累的issue",
-          "steps": [
-            { "command": "/issue:plan --all-pending", "optional": false },
-            { "command": "/issue:queue", "optional": false },
-            { "command": "/issue:execute", "optional": false }
-          ]
-        }
-      },
-      "worktree_support": {
-        "description": "可选的 worktree 隔离，保持主分支稳定",
-        "use_case": "主开发完成后的 issue 修复"
-      },
-      "cli_hints": {
-        "discovery": { "tool": "gemini", "mode": "analysis", "trigger": "perspective_analysis", "parallel": true },
-        "solution_generation": { "tool": "gemini", "mode": "analysis", "trigger": "always", "parallel": true },
-        "batch_execution": { "tool": "codex", "mode": "write", "trigger": "always" }
-      },
-      "estimated_time": "1-4 hours"
-    },
-    "tdd": {
-      "name": "Test-Driven Development",
-      "level": "L3",
-      "description": "TDD规划 + 执行 + 验证 (6 phases)",
-      "complexity": ["medium", "high"],
-      "artifacts": ".workflow/active/{session}/",
-      "steps": [
-        { "command": "/workflow:tdd-plan", "optional": false },
-        { "command": "/workflow:action-plan-verify", "optional": true, "auto_continue": true },
-        { "command": "/workflow:execute", "optional": false },
-        { "command": "/workflow:tdd-verify", "optional": false }
-      ],
-      "tdd_structure": {
-        "description": "Each IMPL task contains complete internal Red-Green-Refactor cycle",
-        "meta": "tdd_workflow: true",
-        "flow_control": "implementation_approach contains 3 steps (red/green/refactor)"
-      },
-      "cli_hints": {
-        "test_strategy": { "tool": "gemini", "mode": "analysis", "trigger": "always" },
-        "red_green_refactor": { "tool": "codex", "mode": "write", "trigger": "always" }
-      },
-      "estimated_time": "1-3 hours"
-    },
-    "test-fix": {
-      "name": "Test Fix Generation",
-      "level": "L3",
-      "description": "测试修复生成 + 执行循环 (5 phases)",
-      "complexity": ["medium", "high"],
-      "artifacts": ".workflow/active/WFS-test-{session}/",
-      "dual_mode": {
-        "session_mode": { "input": "WFS-xxx", "context_source": "Source session summaries" },
-        "prompt_mode": { "input": "Text/file path", "context_source": "Direct codebase analysis" }
-      },
-      "steps": [
-        { "command": "/workflow:test-fix-gen", "optional": false },
-        { "command": "/workflow:test-cycle-execute", "optional": false }
-      ],
-      "task_structure": [
-        "IMPL-001.json (test understanding & generation)",
-        "IMPL-001.5-review.json (quality gate)",
-        "IMPL-002.json (test execution & fix cycle)"
-      ],
-      "cli_hints": {
-        "analysis": { "tool": "gemini", "mode": "analysis", "trigger": "always" },
-        "fix_cycle": { "tool": "codex", "mode": "write", "trigger": "pass_rate < 0.95" }
-      },
-      "estimated_time": "1-2 hours"
-    },
-    "ui": {
-      "name": "UI-First Development",
-      "level": "L3/L4",
-      "description": "UI设计 + 规划 + 执行",
-      "complexity": ["medium", "high"],
-      "artifacts": ".workflow/active/{session}/",
-      "variants": {
-        "explore": [
-          { "command": "/workflow:ui-design:explore-auto", "optional": false },
-          { "command": "/workflow:ui-design:design-sync", "optional": false, "auto_continue": true },
-          { "command": "/workflow:plan", "optional": false },
-          { "command": "/workflow:execute", "optional": false }
-        ],
-        "imitate": [
-          { "command": "/workflow:ui-design:imitate-auto", "optional": false },
-          { "command": "/workflow:ui-design:design-sync", "optional": false, "auto_continue": true },
-          { "command": "/workflow:plan", "optional": false },
-          { "command": "/workflow:execute", "optional": false }
-        ]
-      },
-      "estimated_time": "2-4 hours"
-    },
-    "review-fix": {
-      "name": "Review and Fix",
-      "level": "L3",
-      "description": "多维审查 + 自动修复",
-      "complexity": ["medium"],
-      "artifacts": ".workflow/active/{session}/review_report.md",
-      "steps": [
-        { "command": "/workflow:review-session-cycle", "optional": false },
-        { "command": "/workflow:review-fix", "optional": true }
-      ],
-      "cli_hints": {
-        "multi_dimension_review": { "tool": "gemini", "mode": "analysis", "trigger": "always", "parallel": true },
-        "auto_fix": { "tool": "codex", "mode": "write", "trigger": "findings_count >= 3" }
-      },
-      "estimated_time": "30-90 min"
-    },
-    "docs": {
-      "name": "Documentation",
-      "level": "L2",
-      "description": "批量文档生成",
-      "complexity": ["low", "medium"],
-      "variants": {
-        "incremental": [{ "command": "/memory:update-related", "optional": false }],
-        "full": [
-          { "command": "/memory:docs", "optional": false },
-          { "command": "/workflow:execute", "optional": false }
-        ]
-      },
-      "estimated_time": "15-60 min"
-    }
-  },
-
-  "intent_rules": {
-    "_level_mapping": {
-      "description": "Intent → Level → Flow mapping guide",
-      "L1": ["lite-lite-lite"],
-      "L2": ["rapid", "bugfix", "multi-cli-plan", "docs"],
-      "L3": ["coupled", "tdd", "test-fix", "review-fix", "ui"],
-      "L4": ["full"],
-      "Supplementary": ["issue"]
-    },
-    "bugfix": {
-      "priority": 1,
-      "level": "L2",
-      "variants": {
-        "hotfix": {
-          "patterns": ["hotfix", "urgent", "production", "critical", "emergency", "紧急", "生产环境", "线上"],
-          "flow": "bugfix.hotfix"
-        },
-        "standard": {
-          "patterns": ["fix", "bug", "error", "issue", "crash", "broken", "fail", "wrong", "修复", "错误", "崩溃"],
-          "flow": "bugfix.standard"
-        }
-      }
-    },
-    "issue_batch": {
-      "priority": 2,
-      "level": "Supplementary",
-      "patterns": {
-        "batch": ["issues", "batch", "queue", "多个", "批量"],
-        "action": ["fix", "resolve", "处理", "解决"]
-      },
-      "require_both": true,
-      "flow": "issue"
-    },
-    "exploration": {
-      "priority": 3,
-      "level": "L4",
-      "patterns": ["不确定", "不知道", "explore", "研究", "分析一下", "怎么做", "what if", "探索"],
-      "flow": "full"
-    },
-    "multi_perspective": {
-      "priority": 3,
-      "level": "L2",
-      "patterns": ["多视角", "权衡", "比较方案", "cross-verify", "多CLI", "协作分析"],
-      "flow": "multi-cli-plan"
-    },
-    "quick_task": {
-      "priority": 4,
-      "level": "L1",
-      "patterns": ["快速", "简单", "small", "quick", "simple", "trivial", "小改动"],
-      "flow": "lite-lite-lite"
-    },
-    "ui_design": {
-      "priority": 5,
-      "level": "L3/L4",
-      "patterns": ["ui", "界面", "design", "设计", "component", "组件", "style", "样式", "layout", "布局"],
-      "variants": {
-        "imitate": { "triggers": ["参考", "模仿", "像", "类似"], "flow": "ui.imitate" },
-        "explore": { "triggers": [], "flow": "ui.explore" }
-      }
-    },
-    "tdd": {
-      "priority": 6,
-      "level": "L3",
-      "patterns": ["tdd", "test-driven", "测试驱动", "先写测试", "test first"],
-      "flow": "tdd"
-    },
-    "test_fix": {
-      "priority": 7,
-      "level": "L3",
-      "patterns": ["测试失败", "test fail", "fix test", "test error", "pass rate", "coverage gap"],
-      "flow": "test-fix"
-    },
-    "review": {
-      "priority": 8,
-      "level": "L3",
-      "patterns": ["review", "审查", "检查代码", "code review", "质量检查"],
-      "flow": "review-fix"
-    },
-    "documentation": {
-      "priority": 9,
-      "level": "L2",
-      "patterns": ["文档", "documentation", "docs", "readme"],
-      "variants": {
-        "incremental": { "triggers": ["更新", "增量"], "flow": "docs.incremental" },
-        "full": { "triggers": ["全部", "完整"], "flow": "docs.full" }
-      }
-    },
-    "feature": {
-      "priority": 99,
-      "complexity_map": {
-        "high": { "level": "L3", "flow": "coupled" },
-        "medium": { "level": "L2", "flow": "rapid" },
-        "low": { "level": "L1", "flow": "lite-lite-lite" }
-      }
-    }
-  },
-
-  "complexity_indicators": {
-    "high": {
-      "threshold": 4,
-      "patterns": {
-        "architecture": { "keywords": ["refactor", "重构", "migrate", "迁移", "architect", "架构", "system", "系统"], "weight": 2 },
-        "multi_module": { "keywords": ["multiple", "多个", "across", "跨", "all", "所有", "entire", "整个"], "weight": 2 },
-        "integration": { "keywords": ["integrate", "集成", "api", "database", "数据库"], "weight": 1 },
-        "quality": { "keywords": ["security", "安全", "performance", "性能", "scale", "扩展"], "weight": 1 }
-      }
-    },
-    "medium": { "threshold": 2 },
-    "low": { "threshold": 0 }
-  },
-
-  "cli_tools": {
-    "gemini": {
-      "strengths": ["超长上下文", "深度分析", "架构理解", "执行流追踪"],
-      "triggers": ["分析", "理解", "设计", "架构", "诊断"],
-      "mode": "analysis"
-    },
-    "qwen": {
-      "strengths": ["代码模式识别", "多维度分析"],
-      "triggers": ["评估", "对比", "验证"],
-      "mode": "analysis"
-    },
-    "codex": {
-      "strengths": ["精确代码生成", "自主执行"],
-      "triggers": ["实现", "重构", "修复", "生成"],
-      "mode": "write"
-    }
-  },
-
-  "cli_injection_rules": {
-    "context_gathering": { "trigger": "file_read >= 50k OR module_count >= 5", "inject": "gemini --mode analysis" },
-    "pre_planning_analysis": { "trigger": "complexity === high", "inject": "gemini --mode analysis" },
-    "debug_diagnosis": { "trigger": "intent === bugfix AND root_cause_unclear", "inject": "gemini --mode analysis" },
-    "code_review": { "trigger": "step === review", "inject": "gemini --mode analysis" },
-    "implementation": { "trigger": "step === execute AND task_count >= 3", "inject": "codex --mode write" }
-  },
-
-  "artifact_flow": {
-    "_description": "定义工作流产出的格式、意图提取和流转规则",
-
-    "outputs": {
-      "/workflow:lite-plan": {
-        "artifact": "memory://plan",
-        "format": "structured_plan",
-        "fields": ["tasks", "files", "dependencies", "approach"]
-      },
-      "/workflow:plan": {
-        "artifact": ".workflow/{session}/IMPL_PLAN.md",
-        "format": "markdown_plan",
-        "fields": ["phases", "tasks", "dependencies", "risks", "test_strategy"]
-      },
-      "/workflow:multi-cli-plan": {
-        "artifact": ".workflow/.multi-cli-plan/{session}/",
-        "format": "multi_file",
-        "files": ["IMPL_PLAN.md", "plan.json", "synthesis.json"],
-        "fields": ["consensus", "divergences", "recommended_approach", "tasks"]
-      },
-      "/workflow:lite-execute": {
-        "artifact": "git_changes",
-        "format": "code_diff",
-        "fields": ["modified_files", "added_files", "deleted_files", "build_status"]
-      },
-      "/workflow:execute": {
-        "artifact": ".workflow/{session}/execution_log.json",
-        "format": "execution_report",
-        "fields": ["completed_tasks", "pending_tasks", "errors", "warnings"]
-      },
-      "/workflow:test-cycle-execute": {
-        "artifact": ".workflow/{session}/test_results.json",
-        "format": "test_report",
-        "fields": ["pass_rate", "failures", "coverage", "duration"]
-      },
-      "/workflow:review-session-cycle": {
-        "artifact": ".workflow/{session}/review_report.md",
-        "format": "review_report",
-        "fields": ["findings", "severity_counts", "recommendations"]
-      },
-      "/workflow:lite-fix": {
-        "artifact": "git_changes",
-        "format": "fix_report",
-        "fields": ["root_cause", "fix_applied", "files_modified", "verification_status"]
-      }
-    },
-
-    "intent_extraction": {
-      "plan_to_execute": {
-        "from": ["lite-plan", "plan", "multi-cli-plan"],
-        "to": ["lite-execute", "execute"],
-        "extract": {
-          "tasks": "$.tasks[] | filter(status != 'completed')",
-          "priority_order": "$.tasks | sort_by(priority)",
-          "files_to_modify": "$.tasks[].files | flatten | unique",
-          "dependencies": "$.dependencies",
-          "context_summary": "$.approach OR $.recommended_approach"
-        }
-      },
-      "execute_to_test": {
-        "from": ["lite-execute", "execute"],
-        "to": ["test-cycle-execute", "test-fix-gen"],
-        "extract": {
-          "modified_files": "$.modified_files",
-          "test_scope": "infer_from($.modified_files)",
-          "build_status": "$.build_status",
-          "pending_verification": "$.completed_tasks | needs_test"
-        }
-      },
-      "test_to_fix": {
-        "from": ["test-cycle-execute"],
-        "to": ["lite-fix", "review-fix"],
-        "condition": "$.pass_rate < 0.95",
-        "extract": {
-          "failures": "$.failures",
-          "error_messages": "$.failures[].message",
-          "affected_files": "$.failures[].file",
-          "suggested_fixes": "$.failures[].suggested_fix"
-        }
-      },
-      "review_to_fix": {
-        "from": ["review-session-cycle", "review-module-cycle"],
-        "to": ["review-fix"],
-        "condition": "$.severity_counts.critical > 0 OR $.severity_counts.high > 3",
-        "extract": {
-          "findings": "$.findings | filter(severity in ['critical', 'high'])",
-          "fix_priority": "$.findings | group_by(category) | sort_by(severity)",
-          "affected_files": "$.findings[].file | unique"
-        }
-      }
-    },
-
-    "completion_criteria": {
-      "plan": {
-        "required": ["has_tasks", "has_files"],
-        "optional": ["has_tests", "no_blocking_risks"],
-        "threshold": 0.8,
-        "routing": {
-          "complete": "proceed_to_execute",
-          "incomplete": "clarify_requirements"
-        }
-      },
-      "execute": {
-        "required": ["all_tasks_attempted", "no_critical_errors"],
-        "optional": ["build_passes", "lint_passes"],
-        "threshold": 1.0,
-        "routing": {
-          "complete": "proceed_to_test_or_review",
-          "partial": "continue_execution",
-          "failed": "diagnose_and_retry"
-        }
-      },
-      "test": {
-        "metrics": {
-          "pass_rate": { "target": 0.95, "minimum": 0.80 },
-          "coverage": { "target": 0.80, "minimum": 0.60 }
-        },
-        "routing": {
-          "pass_rate >= 0.95 AND coverage >= 0.80": "complete",
-          "pass_rate >= 0.95 AND coverage < 0.80": "add_more_tests",
-          "pass_rate >= 0.80": "fix_failures_then_continue",
-          "pass_rate < 0.80": "major_fix_required"
-        }
-      },
-      "review": {
-        "metrics": {
-          "critical_findings": { "target": 0, "maximum": 0 },
-          "high_findings": { "target": 0, "maximum": 3 }
-        },
-        "routing": {
-          "critical == 0 AND high <= 3": "complete_or_optional_fix",
-          "critical > 0": "mandatory_fix",
-          "high > 3": "recommended_fix"
-        }
-      }
-    },
-
-    "flow_decisions": {
-      "_description": "根据产出完成度决定下一步",
-      "patterns": {
-        "plan_execute_test": {
-          "sequence": ["plan", "execute", "test"],
-          "on_test_fail": {
-            "action": "extract_failures_and_fix",
-            "max_iterations": 3,
-            "fallback": "manual_intervention"
-          }
-        },
-        "plan_execute_review": {
-          "sequence": ["plan", "execute", "review"],
-          "on_review_issues": {
-            "action": "prioritize_and_fix",
-            "auto_fix_threshold": "severity < high"
-          }
-        },
-        "iterative_improvement": {
-          "sequence": ["execute", "test", "fix"],
-          "loop_until": "pass_rate >= 0.95 OR iterations >= 3",
-          "on_loop_exit": "report_status"
-        }
-      }
-    }
-  }
-}

.claude/workflows/cli-templates/prompts/workflow-impl-plan-template.txt

@@ -43,7 +43,7 @@ Core requirements, objectives, technical approach summary (2-3 paragraphs max).
 
 **Quality Gates**:
 - concept-verify: ✅ Passed (0 ambiguities remaining) | ⏭️ Skipped (user decision) | ⏳ Pending
-- action-plan-verify: ⏳ Pending (recommended before /workflow:execute)
+- plan-verify: ⏳ Pending (recommended before /workflow:execute)
 
 **Context Package Summary**:
 - **Focus Paths**: {list key directories from context-package.json}

.codex/agents/ccw-loop-b-complete.md

@@ -0,0 +1,227 @@
+# Worker: Complete (CCW Loop-B)
+
+Finalize session: summary generation, cleanup, commit preparation.
+
+## Responsibilities
+
+1. **Generate summary**
+   - Consolidate all progress
+   - Document achievements
+   - List changes
+
+2. **Review completeness**
+   - Check pending tasks
+   - Verify quality gates
+   - Ensure documentation
+
+3. **Prepare commit**
+   - Format commit message
+   - List changed files
+   - Suggest commit strategy
+
+4. **Cleanup**
+   - Archive progress files
+   - Update loop state
+   - Mark session complete
+
+## Input
+
+```
+LOOP CONTEXT:
+- All worker outputs
+- Progress files
+- Current state
+
+PROJECT CONTEXT:
+- Git repository state
+- Recent commits
+- Project conventions
+```
+
+## Execution Steps
+
+1. **Read all progress**
+   - Load worker outputs from `.workflow/.loop/{loopId}.workers/`
+   - Read progress files from `.workflow/.loop/{loopId}.progress/`
+   - Consolidate findings
+
+2. **Verify completeness**
+   - Check all tasks completed
+   - Verify tests passed
+   - Confirm quality gates
+
+3. **Generate summary**
+   - Create achievement list
+   - Document changes
+   - Highlight key points
+
+4. **Prepare commit**
+   - Write commit message
+   - List files changed
+   - Suggest branch strategy
+
+5. **Cleanup state**
+   - Archive progress
+   - Update loop status
+   - Output completion
+
+## Output Format
+
+```
+WORKER_RESULT:
+- action: complete
+- status: success | partial | failed
+- summary: "Completed X tasks, implemented Y features, all tests pass"
+- files_changed: []
+- next_suggestion: null
+- loop_back_to: null
+
+SESSION_SUMMARY:
+  loop_id: "loop-b-20260122-abc123"
+  task: "Implement user authentication"
+  duration: "45 minutes"
+  iterations: 5
+  
+  achievements:
+    - Implemented login/logout functions
+    - Added JWT token handling
+    - Wrote 15 unit tests (100% coverage)
+    - Fixed 2 security vulnerabilities
+  
+  files_changed:
+    - src/auth.ts (created, +180 lines)
+    - src/utils.ts (modified, +45/-10 lines)
+    - tests/auth.test.ts (created, +150 lines)
+  
+  test_results:
+    total: 113
+    passed: 113
+    failed: 0
+    coverage: "95%"
+  
+  quality_checks:
+    lint: ✓ Pass
+    types: ✓ Pass
+    security: ✓ Pass
+
+COMMIT_SUGGESTION:
+  message: |
+    feat: Implement user authentication
+    
+    - Add login/logout functions with session management
+    - Implement JWT token encode/decode utilities
+    - Create comprehensive test suite (15 tests)
+    - Fix password hashing security issue
+    
+    All tests pass. Coverage: 95%
+  
+  files:
+    - src/auth.ts
+    - src/utils.ts
+    - tests/auth.test.ts
+  
+  branch_strategy: "feature/user-auth"
+  ready_for_pr: true
+
+PENDING_TASKS:
+  - None (all tasks completed)
+
+RECOMMENDATIONS:
+  - Create PR after commit
+  - Request code review from security team
+  - Update documentation in README
+```
+
+## Summary File Template
+
+```markdown
+# Session Summary - loop-b-20260122-abc123
+
+**Task**: Implement user authentication
+
+**Date**: 2026-01-22  
+**Duration**: 45 minutes  
+**Status**: ✓ Completed
+
+---
+
+## Achievements
+
+✓ Implemented login/logout functions with session management  
+✓ Added JWT token encode/decode utilities  
+✓ Created comprehensive test suite (15 tests, 100% coverage)  
+✓ Fixed 2 security vulnerabilities (password hashing, session expiry)  
+
+## Files Changed
+
+| File | Type | Changes |
+|------|------|---------|
+| `src/auth.ts` | Created | +180 lines |
+| `src/utils.ts` | Modified | +45/-10 lines |
+| `tests/auth.test.ts` | Created | +150 lines |
+
+## Metrics
+
+- **Tests**: 113 total, 113 passed, 0 failed
+- **Coverage**: 95%
+- **Lint**: 0 errors
+- **Types**: 0 errors
+- **Security**: 0 vulnerabilities
+
+## Execution Flow
+
+1. **Init** (1 iteration): Task breakdown, plan created
+2. **Develop** (2 iterations): Implemented auth module + utils
+3. **Validate** (1 iteration): Tests all pass
+4. **Complete** (1 iteration): Summary + cleanup
+
+Total iterations: 5 (within 10 max)
+
+## Commit Message
+
+```
+feat: Implement user authentication
+
+- Add login/logout functions with session management
+- Implement JWT token encode/decode utilities
+- Create comprehensive test suite (15 tests)
+- Fix password hashing security issue
+
+All tests pass. Coverage: 95%
+```
+
+## Next Steps
+
+- [ ] Create PR from `feature/user-auth`
+- [ ] Request code review (tag: @security-team)
+- [ ] Update documentation
+- [ ] Deploy to staging after merge
+```
+
+## Rules
+
+- **Verify completion**: Check all tasks done, tests pass
+- **Comprehensive summary**: Include all achievements
+- **Format commit**: Follow project conventions
+- **Document clearly**: Make summary readable
+- **No leftover tasks**: All pending tasks resolved
+- **Quality gates**: Ensure all checks pass
+- **Actionable next steps**: Suggest follow-up actions
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| Pending tasks remain | Mark status: "partial", list pending |
+| Tests failing | Mark status: "failed", suggest debug |
+| Quality gates fail | List failing checks, suggest fixes |
+| Missing documentation | Flag as recommendation |
+
+## Best Practices
+
+1. Read ALL worker outputs
+2. Verify completeness thoroughly
+3. Create detailed summary
+4. Format commit message properly
+5. Suggest clear next steps
+6. Archive progress for future reference

.codex/agents/ccw-loop-b-debug.md

@@ -0,0 +1,172 @@
+# Worker: Debug (CCW Loop-B)
+
+Diagnose and analyze issues: root cause analysis, hypothesis testing, problem solving.
+
+## Responsibilities
+
+1. **Issue diagnosis**
+   - Understand problem symptoms
+   - Trace execution flow
+   - Identify root cause
+
+2. **Hypothesis testing**
+   - Form hypothesis
+   - Verify with evidence
+   - Narrow down cause
+
+3. **Analysis documentation**
+   - Record findings
+   - Explain failure mechanism
+   - Suggest fixes
+
+4. **Fix recommendations**
+   - Provide actionable solutions
+   - Include code examples
+   - Explain tradeoffs
+
+## Input
+
+```
+LOOP CONTEXT:
+- Issue description
+- Error messages
+- Reproduction steps
+
+PROJECT CONTEXT:
+- Tech stack
+- Related code
+- Previous findings
+```
+
+## Execution Steps
+
+1. **Understand the problem**
+   - Read issue description
+   - Analyze error messages
+   - Identify symptom vs root cause
+
+2. **Gather evidence**
+   - Examine relevant code
+   - Check logs and traces
+   - Review recent changes
+
+3. **Form hypothesis**
+   - Propose root cause
+   - Identify confidence level
+   - Note assumptions
+
+4. **Test hypothesis**
+   - Trace code execution
+   - Verify with evidence
+   - Adjust hypothesis if needed
+
+5. **Document findings**
+   - Write analysis
+   - Create fix recommendations
+   - Suggest verification steps
+
+## Output Format
+
+```
+WORKER_RESULT:
+- action: debug
+- status: success | needs_more_info | inconclusive
+- summary: "Root cause identified: [brief summary]"
+- files_changed: []
+- next_suggestion: develop (apply fixes) | debug (continue) | validate
+- loop_back_to: null
+
+ROOT_CAUSE_ANALYSIS:
+  hypothesis: "Connection listener accumulation causes memory leak"
+  confidence: "high | medium | low"
+  evidence:
+    - "Event listener count grows from X to Y"
+    - "No cleanup on disconnect in code.ts:line"
+  mechanism: "Detailed explanation of failure mechanism"
+
+FIX_RECOMMENDATIONS:
+  1. Fix: "Add event.removeListener in disconnect handler"
+     code_snippet: |
+       connection.on('disconnect', () => {
+         connection.removeAllListeners()
+       })
+     reason: "Prevent accumulation of listeners"
+  
+  2. Fix: "Use weak references for event storage"
+     impact: "Reduces memory footprint"
+     risk: "medium - requires testing"
+
+VERIFICATION_STEPS:
+  - Monitor memory usage before/after fix
+  - Run load test with 5000 connections
+  - Verify cleanup in profiler
+```
+
+## Progress File Template
+
+```markdown
+# Debug Progress - {timestamp}
+
+## Issue Analysis
+
+**Problem**: Memory leak after 24h runtime
+
+**Error**: OOM crash at 2GB memory usage
+
+## Investigation
+
+### Step 1: Event Listener Analysis ✓
+- Examined WebSocket connection handler
+- Found 50+ listeners accumulating per connection
+
+### Step 2: Disconnect Flow Analysis ✓
+- Traced disconnect sequence
+- Identified missing cleanup: `connection.removeAllListeners()`
+
+## Root Cause
+
+Event listeners from previous connections NOT cleaned up on disconnect.
+
+Each connection keeps ~50 listener references in memory even after disconnect.
+
+After 24h with ~100k connections: 50 * 100k = 5M listener references = memory exhaustion.
+
+## Recommended Fixes
+
+1. **Primary**: Add `removeAllListeners()` in disconnect handler
+2. **Secondary**: Implement weak reference tracking
+3. **Verification**: Monitor memory in production load test
+
+## Risk Assessment
+
+- **Risk of fix**: Low - cleanup is standard practice
+- **Risk if unfixed**: Critical - OOM crash daily
+```
+
+## Rules
+
+- **Follow evidence**: Only propose conclusions backed by analysis
+- **Trace code carefully**: Don't guess execution flow
+- **Form hypotheses explicitly**: State assumptions
+- **Test thoroughly**: Verify before concluding
+- **Confidence levels**: Clearly indicate certainty
+- **No bandaid fixes**: Address root cause, not symptoms
+- **Document clearly**: Explain mechanism, not just symptoms
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| Insufficient info | Output what known, ask coordinator for more data |
+| Multiple hypotheses | Rank by likelihood, suggest test order |
+| Inconclusive evidence | Mark as "needs_more_info", suggest investigation areas |
+| Blocked investigation | Request develop worker to add logging |
+
+## Best Practices
+
+1. Understand problem fully before hypothesizing
+2. Form explicit hypothesis before testing
+3. Let evidence guide investigation
+4. Document all findings clearly
+5. Suggest verification steps
+6. Indicate confidence in conclusion

.codex/agents/ccw-loop-b-develop.md

@@ -0,0 +1,147 @@
+# Worker: Develop (CCW Loop-B)
+
+Execute implementation tasks: code writing, refactoring, file modifications.
+
+## Responsibilities
+
+1. **Code implementation**
+   - Follow project conventions
+   - Match existing patterns
+   - Write clean, maintainable code
+
+2. **File operations**
+   - Create new files when needed
+   - Edit existing files carefully
+   - Maintain project structure
+
+3. **Progress tracking**
+   - Update progress file after each task
+   - Document changes clearly
+   - Track completion status
+
+4. **Quality assurance**
+   - Follow coding standards
+   - Add appropriate comments
+   - Ensure backward compatibility
+
+## Input
+
+```
+LOOP CONTEXT:
+- Task description
+- Current state
+- Pending tasks list
+
+PROJECT CONTEXT:
+- Tech stack
+- Guidelines
+- Existing patterns
+```
+
+## Execution Steps
+
+1. **Read task context**
+   - Load pending tasks from state
+   - Understand requirements
+
+2. **Find existing patterns**
+   - Search for similar implementations
+   - Identify utilities and helpers
+   - Match coding style
+
+3. **Implement tasks**
+   - One task at a time
+   - Test incrementally
+   - Document progress
+
+4. **Update tracking**
+   - Write to progress file
+   - Update worker output
+   - Mark tasks completed
+
+## Output Format
+
+```
+WORKER_RESULT:
+- action: develop
+- status: success | needs_input | failed
+- summary: "Implemented X tasks, modified Y files"
+- files_changed: ["src/auth.ts", "src/utils.ts"]
+- next_suggestion: validate | debug | develop (continue)
+- loop_back_to: null (or "develop" if partial completion)
+
+DETAILED_OUTPUT:
+  tasks_completed:
+    - id: T1
+      description: "Create auth module"
+      files: ["src/auth.ts"]
+      status: success
+    
+    - id: T2
+      description: "Add JWT utils"
+      files: ["src/utils.ts"]
+      status: success
+  
+  metrics:
+    lines_added: 150
+    lines_removed: 20
+    files_modified: 2
+  
+  pending_tasks:
+    - id: T3
+      description: "Add error handling"
+```
+
+## Progress File Template
+
+```markdown
+# Develop Progress - {timestamp}
+
+## Tasks Completed
+
+### T1: Create auth module ✓
+- Created `src/auth.ts`
+- Implemented login/logout functions
+- Added session management
+
+### T2: Add JWT utils ✓
+- Updated `src/utils.ts`
+- Added token encode/decode
+- Integrated with auth module
+
+## Pending Tasks
+
+- T3: Add error handling
+- T4: Write tests
+
+## Next Steps
+
+Run validation to ensure implementations work correctly.
+```
+
+## Rules
+
+- **Never assume**: Read files before editing
+- **Follow patterns**: Match existing code style
+- **Test incrementally**: Verify changes work
+- **Document clearly**: Update progress after each task
+- **No over-engineering**: Only implement what's asked
+- **Backward compatible**: Don't break existing functionality
+- **Clean commits**: Each task should be commit-ready
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| File not found | Search codebase, ask coordinator |
+| Pattern unclear | Read 3 similar examples first |
+| Task blocked | Mark as blocked, suggest debug action |
+| Partial completion | Output progress, set loop_back_to: "develop" |
+
+## Best Practices
+
+1. Read before write
+2. Find existing patterns first
+3. Implement smallest working unit
+4. Update progress immediately
+5. Suggest next action based on state

.codex/agents/ccw-loop-b-init.md

@@ -0,0 +1,82 @@
+# Worker: Init (CCW Loop-B)
+
+Initialize session, parse task requirements, prepare execution environment.
+
+## Responsibilities
+
+1. **Read project context**
+   - `.workflow/project-tech.json` - Technology stack
+   - `.workflow/project-guidelines.json` - Project conventions
+   - `package.json` / build config
+
+2. **Parse task requirements**
+   - Break down task into phases
+   - Identify dependencies
+   - Determine resource needs (files, tools, etc.)
+
+3. **Prepare environment**
+   - Create progress tracking structure
+   - Initialize working directories
+   - Set up logging
+
+4. **Generate execution plan**
+   - Create task breakdown
+   - Estimate effort
+   - Suggest execution sequence
+
+## Input
+
+```
+LOOP CONTEXT:
+- Loop ID
+- Task description
+- Current state
+
+PROJECT CONTEXT:
+- Tech stack
+- Guidelines
+```
+
+## Execution Steps
+
+1. Read context files
+2. Analyze task description
+3. Create task breakdown
+4. Identify prerequisites
+5. Generate execution plan
+6. Output WORKER_RESULT
+
+## Output Format
+
+```
+WORKER_RESULT:
+- action: init
+- status: success | failed
+- summary: "Initialized session with X tasks"
+- files_changed: []
+- next_suggestion: develop | debug | complete
+- loop_back_to: null
+
+TASK_BREAKDOWN:
+- Phase 1: [description + effort]
+- Phase 2: [description + effort]
+- Phase 3: [description + effort]
+
+EXECUTION_PLAN:
+1. Develop: Implement core functionality
+2. Validate: Run tests
+3. Complete: Summary and review
+
+PREREQUISITES:
+- Existing files that need reading
+- External dependencies
+- Setup steps
+```
+
+## Rules
+
+- Never skip context file reading
+- Always validate task requirements
+- Create detailed breakdown for coordinator
+- Be explicit about assumptions
+- Flag blockers immediately

.codex/agents/ccw-loop-b-validate.md

@@ -0,0 +1,204 @@
+# Worker: Validate (CCW Loop-B)
+
+Execute validation: tests, coverage analysis, quality gates.
+
+## Responsibilities
+
+1. **Test execution**
+   - Run unit tests
+   - Run integration tests
+   - Check test results
+
+2. **Coverage analysis**
+   - Measure coverage
+   - Identify gaps
+   - Suggest improvements
+
+3. **Quality checks**
+   - Lint/format check
+   - Type checking
+   - Security scanning
+
+4. **Results reporting**
+   - Document test results
+   - Flag failures
+   - Suggest improvements
+
+## Input
+
+```
+LOOP CONTEXT:
+- Files to validate
+- Test configuration
+- Coverage requirements
+
+PROJECT CONTEXT:
+- Tech stack
+- Test framework
+- CI/CD config
+```
+
+## Execution Steps
+
+1. **Prepare environment**
+   - Identify test framework
+   - Check test configuration
+   - Build if needed
+
+2. **Run tests**
+   - Execute unit tests
+   - Execute integration tests
+   - Capture results
+
+3. **Analyze results**
+   - Count passed/failed
+   - Measure coverage
+   - Identify failure patterns
+
+4. **Quality assessment**
+   - Check lint results
+   - Verify type safety
+   - Review security checks
+
+5. **Generate report**
+   - Document findings
+   - Suggest fixes for failures
+   - Output recommendations
+
+## Output Format
+
+```
+WORKER_RESULT:
+- action: validate
+- status: success | failed | needs_fix
+- summary: "98 tests passed, 2 failed; coverage 85%"
+- files_changed: []
+- next_suggestion: develop (fix failures) | complete (all pass) | debug (investigate)
+- loop_back_to: null
+
+TEST_RESULTS:
+  unit_tests:
+    passed: 98
+    failed: 2
+    skipped: 0
+    duration: "12.5s"
+  
+  integration_tests:
+    passed: 15
+    failed: 0
+    duration: "8.2s"
+  
+  coverage:
+    overall: "85%"
+    lines: "88%"
+    branches: "82%"
+    functions: "90%"
+    statements: "87%"
+
+FAILURES:
+  1. Test: "auth.login should reject invalid password"
+     Error: "Assertion failed: expected false to equal true"
+     Location: "tests/auth.test.ts:45"
+     Suggested fix: "Check password validation logic in src/auth.ts"
+  
+  2. Test: "utils.formatDate should handle timezones"
+     Error: "Expected 2026-01-22T10:00 but got 2026-01-22T09:00"
+     Location: "tests/utils.test.ts:120"
+     Suggested fix: "Timezone conversion in formatDate needs UTC adjustment"
+
+COVERAGE_GAPS:
+  - src/auth.ts (line 45-52): Error handling not covered
+  - src/utils.ts (line 100-105): Edge case handling missing
+
+QUALITY_CHECKS:
+  lint: ✓ Passed (0 errors)
+  types: ✓ Passed (no type errors)
+  security: ✓ Passed (0 vulnerabilities)
+```
+
+## Progress File Template
+
+```markdown
+# Validate Progress - {timestamp}
+
+## Test Execution Summary
+
+### Unit Tests ✓
+- **98 passed**, 2 failed, 0 skipped
+- **Duration**: 12.5s
+- **Status**: Needs fix
+
+### Integration Tests ✓
+- **15 passed**, 0 failed
+- **Duration**: 8.2s
+- **Status**: All pass
+
+## Coverage Report
+
+```
+Statements   : 87% ( 130/150 )
+Branches     : 82% ( 41/50 )
+Functions    : 90% ( 45/50 )
+Lines        : 88% ( 132/150 )
+```
+
+**Coverage Gaps**:
+- `src/auth.ts` (lines 45-52): Error handling
+- `src/utils.ts` (lines 100-105): Edge cases
+
+## Test Failures
+
+### Failure 1: auth.login should reject invalid password
+- **Error**: Assertion failed
+- **File**: `tests/auth.test.ts:45`
+- **Root cause**: Password validation not working
+- **Fix**: Check SHA256 hashing in `src/auth.ts:102`
+
+### Failure 2: utils.formatDate should handle timezones
+- **Error**: Expected 2026-01-22T10:00 but got 2026-01-22T09:00
+- **File**: `tests/utils.test.ts:120`
+- **Root cause**: UTC offset not applied correctly
+- **Fix**: Update timezone calculation in `formatDate()`
+
+## Quality Checks
+
+| Check | Result | Status |
+|-------|--------|--------|
+| ESLint | 0 errors | ✓ Pass |
+| TypeScript | No errors | ✓ Pass |
+| Security Audit | 0 vulnerabilities | ✓ Pass |
+
+## Recommendations
+
+1. **Fix test failures** (2 tests failing)
+2. **Improve coverage** for error handling paths
+3. **Add integration tests** for critical flows
+```
+
+## Rules
+
+- **Run all tests**: Don't skip or filter
+- **Be thorough**: Check coverage and quality metrics
+- **Document failures**: Provide actionable suggestions
+- **Test environment**: Use consistent configuration
+- **No workarounds**: Fix real issues, don't skip tests
+- **Verify fixes**: Re-run after changes
+- **Clean reports**: Output clear, actionable results
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| Test framework not found | Identify from package.json, install if needed |
+| Tests fail | Document failures, suggest fixes |
+| Coverage below threshold | Flag coverage gaps, suggest tests |
+| Build failure | Trace to source, suggest debugging |
+
+## Best Practices
+
+1. Run complete test suite
+2. Measure coverage thoroughly
+3. Document all failures clearly
+4. Provide specific fix suggestions
+5. Check quality metrics
+6. Suggest follow-up validation steps

.codex/agents/ccw-loop-executor.md

@@ -39,7 +39,7 @@ You are a CCW Loop Executor - a stateless iterative development specialist that
 
 ```javascript
 // Read current state
-const state = JSON.parse(Read('.loop/{loopId}.json'))
+const state = JSON.parse(Read('.workflow/.loop/{loopId}.json'))
 
 // Check control signals
 if (state.status === 'paused') {
@@ -110,7 +110,7 @@ NEXT_ACTION_NEEDED: {action_name} | WAITING_INPUT | COMPLETED | PAUSED
 
 ```javascript
 function updateState(loopId, skillStateUpdates) {
-  const state = JSON.parse(Read(`.loop/${loopId}.json`))
+  const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
   state.updated_at = getUtc8ISOString()
   state.skill_state = {
     ...state.skill_state,
@@ -118,7 +118,7 @@ function updateState(loopId, skillStateUpdates) {
     last_action: currentAction,
     completed_actions: [...state.skill_state.completed_actions, currentAction]
   }
-  Write(`.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+  Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 }
 ```
 
@@ -136,7 +136,7 @@ function updateState(loopId, skillStateUpdates) {
 5. Update state with skill_state
 
 **Output**:
-- `.loop/{loopId}.progress/develop.md` (initialized)
+- `.workflow/.loop/{loopId}.progress/develop.md` (initialized)
 - State: skill_state populated with tasks
 
 ### DEVELOP Action

.codex/prompts/clean.md

@@ -0,0 +1,409 @@
+---
+description: Intelligent code cleanup with mainline detection, stale artifact discovery, and safe execution
+argument-hint: [--dry-run] [FOCUS="<area>"]
+---
+
+# Workflow Clean Command
+
+## Overview
+
+Evidence-based intelligent cleanup command. Systematically identifies stale artifacts through mainline analysis, discovers drift, and safely removes unused sessions, documents, and dead code.
+
+**Core workflow**: Detect Mainline → Discover Drift → Confirm → Stage → Execute
+
+## Target Cleanup
+
+**Focus area**: $FOCUS (or entire project if not specified)
+**Mode**: $ARGUMENTS
+
+## Execution Process
+
+```
+Phase 0: Initialization
+   ├─ Parse arguments (--dry-run, FOCUS)
+   ├─ Setup session folder
+   └─ Initialize utility functions
+
+Phase 1: Mainline Detection
+   ├─ Analyze git history (30 days)
+   ├─ Identify core modules (high commit frequency)
+   ├─ Map active vs stale branches
+   └─ Build mainline profile
+
+Phase 2: Drift Discovery (Subagent)
+   ├─ spawn_agent with cli-explore-agent role
+   ├─ Scan workflow sessions for orphaned artifacts
+   ├─ Identify documents drifted from mainline
+   ├─ Detect dead code and unused exports
+   └─ Generate cleanup manifest
+
+Phase 3: Confirmation
+   ├─ Validate manifest schema
+   ├─ Display cleanup summary by category
+   ├─ AskUser: Select categories and risk level
+   └─ Dry-run exit if --dry-run
+
+Phase 4: Execution
+   ├─ Validate paths (security check)
+   ├─ Stage deletion (move to .trash)
+   ├─ Update manifests
+   ├─ Permanent deletion
+   └─ Report results
+```
+
+## Implementation
+
+### Phase 0: Initialization
+
+```javascript
+const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+
+// Parse arguments
+const args = "$ARGUMENTS"
+const isDryRun = args.includes('--dry-run')
+const focusMatch = args.match(/FOCUS="([^"]+)"/)
+const focusArea = focusMatch ? focusMatch[1] : "$FOCUS" !== "$" + "FOCUS" ? "$FOCUS" : null
+
+// Session setup
+const dateStr = getUtc8ISOString().substring(0, 10)
+const sessionId = `clean-${dateStr}`
+const sessionFolder = `.workflow/.clean/${sessionId}`
+const trashFolder = `${sessionFolder}/.trash`
+const projectRoot = process.cwd()
+
+bash(`mkdir -p ${sessionFolder}`)
+bash(`mkdir -p ${trashFolder}`)
+
+// Utility functions
+function fileExists(p) {
+  try { return bash(`test -f "${p}" && echo "yes"`).includes('yes') } catch { return false }
+}
+
+function dirExists(p) {
+  try { return bash(`test -d "${p}" && echo "yes"`).includes('yes') } catch { return false }
+}
+
+function validatePath(targetPath) {
+  if (targetPath.includes('..')) return { valid: false, reason: 'Path traversal' }
+
+  const allowed = ['.workflow/', '.claude/rules/tech/', 'src/']
+  const dangerous = [/^\//, /^C:\\Windows/i, /node_modules/, /\.git$/]
+
+  if (!allowed.some(p => targetPath.startsWith(p))) {
+    return { valid: false, reason: 'Outside allowed directories' }
+  }
+  if (dangerous.some(p => p.test(targetPath))) {
+    return { valid: false, reason: 'Dangerous pattern' }
+  }
+  return { valid: true }
+}
+```
+
+---
+
+### Phase 1: Mainline Detection
+
+```javascript
+// Check git repository
+const isGitRepo = bash('git rev-parse --git-dir 2>/dev/null && echo "yes"').includes('yes')
+
+let mainlineProfile = {
+  coreModules: [],
+  activeFiles: [],
+  activeBranches: [],
+  staleThreshold: { sessions: 7, branches: 30, documents: 14 },
+  isGitRepo,
+  timestamp: getUtc8ISOString()
+}
+
+if (isGitRepo) {
+  // Commit frequency by directory (last 30 days)
+  const freq = bash('git log --since="30 days ago" --name-only --pretty=format: | grep -v "^$" | cut -d/ -f1-2 | sort | uniq -c | sort -rn | head -20')
+
+  // Parse core modules (>5 commits)
+  mainlineProfile.coreModules = freq.trim().split('\n')
+    .map(l => l.trim().match(/^(\d+)\s+(.+)$/))
+    .filter(m => m && parseInt(m[1]) >= 5)
+    .map(m => m[2])
+
+  // Recent branches
+  const branches = bash('git for-each-ref --sort=-committerdate refs/heads/ --format="%(refname:short)" | head -10')
+  mainlineProfile.activeBranches = branches.trim().split('\n').filter(Boolean)
+}
+
+Write(`${sessionFolder}/mainline-profile.json`, JSON.stringify(mainlineProfile, null, 2))
+```
+
+---
+
+### Phase 2: Drift Discovery
+
+```javascript
+let exploreAgent = null
+
+try {
+  // Launch cli-explore-agent
+  exploreAgent = spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS
+1. Read: ~/.codex/agents/cli-explore-agent.md
+2. Read: .workflow/project-tech.json (if exists)
+
+## Task Objective
+Discover stale artifacts for cleanup.
+
+## Context
+- Session: ${sessionFolder}
+- Focus: ${focusArea || 'entire project'}
+
+## Discovery Categories
+
+### 1. Stale Workflow Sessions
+Scan: .workflow/active/WFS-*, .workflow/archives/WFS-*, .workflow/.lite-plan/*, .workflow/.debug/DBG-*
+Criteria: No modification >7 days + no related git commits
+
+### 2. Drifted Documents
+Scan: .claude/rules/tech/*, .workflow/.scratchpad/*
+Criteria: >30% broken references to non-existent files
+
+### 3. Dead Code
+Scan: Unused exports, orphan files (not imported anywhere)
+Criteria: No importers in import graph
+
+## Output
+Write to: ${sessionFolder}/cleanup-manifest.json
+
+Format:
+{
+  "generated_at": "ISO",
+  "discoveries": {
+    "stale_sessions": [{ "path": "...", "age_days": N, "reason": "...", "risk": "low|medium|high" }],
+    "drifted_documents": [{ "path": "...", "drift_percentage": N, "reason": "...", "risk": "..." }],
+    "dead_code": [{ "path": "...", "type": "orphan_file", "reason": "...", "risk": "..." }]
+  },
+  "summary": { "total_items": N, "by_category": {...}, "by_risk": {...} }
+}
+`
+  })
+
+  // Wait with timeout handling
+  let result = wait({ ids: [exploreAgent], timeout_ms: 600000 })
+
+  if (result.timed_out) {
+    send_input({ id: exploreAgent, message: 'Complete now and write cleanup-manifest.json.' })
+    result = wait({ ids: [exploreAgent], timeout_ms: 300000 })
+    if (result.timed_out) throw new Error('Agent timeout')
+  }
+
+  if (!fileExists(`${sessionFolder}/cleanup-manifest.json`)) {
+    throw new Error('Manifest not generated')
+  }
+
+} finally {
+  if (exploreAgent) close_agent({ id: exploreAgent })
+}
+```
+
+---
+
+### Phase 3: Confirmation
+
+```javascript
+// Load and validate manifest
+const manifest = JSON.parse(Read(`${sessionFolder}/cleanup-manifest.json`))
+
+// Display summary
+console.log(`
+## Cleanup Discovery Report
+
+| Category | Count | Risk |
+|----------|-------|------|
+| Sessions | ${manifest.summary.by_category.stale_sessions} | ${getRiskSummary('sessions')} |
+| Documents | ${manifest.summary.by_category.drifted_documents} | ${getRiskSummary('documents')} |
+| Dead Code | ${manifest.summary.by_category.dead_code} | ${getRiskSummary('code')} |
+
+**Total**: ${manifest.summary.total_items} items
+`)
+
+// Dry-run exit
+if (isDryRun) {
+  console.log(`
+**Dry-run mode**: No changes made.
+Manifest: ${sessionFolder}/cleanup-manifest.json
+  `)
+  return
+}
+
+// User confirmation
+const selection = AskUser({
+  questions: [
+    {
+      question: "Which categories to clean?",
+      header: "Categories",
+      multiSelect: true,
+      options: [
+        { label: "Sessions", description: `${manifest.summary.by_category.stale_sessions} stale sessions` },
+        { label: "Documents", description: `${manifest.summary.by_category.drifted_documents} drifted docs` },
+        { label: "Dead Code", description: `${manifest.summary.by_category.dead_code} unused files` }
+      ]
+    },
+    {
+      question: "Risk level?",
+      header: "Risk",
+      options: [
+        { label: "Low only", description: "Safest (Recommended)" },
+        { label: "Low + Medium", description: "Includes likely unused" },
+        { label: "All", description: "Aggressive" }
+      ]
+    }
+  ]
+})
+```
+
+---
+
+### Phase 4: Execution
+
+```javascript
+const riskFilter = {
+  'Low only': ['low'],
+  'Low + Medium': ['low', 'medium'],
+  'All': ['low', 'medium', 'high']
+}[selection.risk]
+
+// Collect items to clean
+const items = []
+if (selection.categories.includes('Sessions')) {
+  items.push(...manifest.discoveries.stale_sessions.filter(s => riskFilter.includes(s.risk)))
+}
+if (selection.categories.includes('Documents')) {
+  items.push(...manifest.discoveries.drifted_documents.filter(d => riskFilter.includes(d.risk)))
+}
+if (selection.categories.includes('Dead Code')) {
+  items.push(...manifest.discoveries.dead_code.filter(c => riskFilter.includes(c.risk)))
+}
+
+const results = { staged: [], deleted: [], failed: [], skipped: [] }
+
+// Validate and stage
+for (const item of items) {
+  const validation = validatePath(item.path)
+  if (!validation.valid) {
+    results.skipped.push({ path: item.path, reason: validation.reason })
+    continue
+  }
+
+  if (!fileExists(item.path) && !dirExists(item.path)) {
+    results.skipped.push({ path: item.path, reason: 'Not found' })
+    continue
+  }
+
+  try {
+    const trashTarget = `${trashFolder}/${item.path.replace(/\//g, '_')}`
+    bash(`mv "${item.path}" "${trashTarget}"`)
+    results.staged.push({ path: item.path, trashPath: trashTarget })
+  } catch (e) {
+    results.failed.push({ path: item.path, error: e.message })
+  }
+}
+
+// Permanent deletion
+for (const staged of results.staged) {
+  try {
+    bash(`rm -rf "${staged.trashPath}"`)
+    results.deleted.push(staged.path)
+  } catch (e) {
+    console.error(`Failed: ${staged.path}`)
+  }
+}
+
+// Cleanup empty trash
+bash(`rmdir "${trashFolder}" 2>/dev/null || true`)
+
+// Report
+console.log(`
+## Cleanup Complete
+
+**Deleted**: ${results.deleted.length}
+**Failed**: ${results.failed.length}
+**Skipped**: ${results.skipped.length}
+
+### Deleted
+${results.deleted.map(p => `- ${p}`).join('\n') || '(none)'}
+
+${results.failed.length > 0 ? `### Failed\n${results.failed.map(f => `- ${f.path}: ${f.error}`).join('\n')}` : ''}
+
+Report: ${sessionFolder}/cleanup-report.json
+`)
+
+Write(`${sessionFolder}/cleanup-report.json`, JSON.stringify({
+  timestamp: getUtc8ISOString(),
+  results,
+  summary: {
+    deleted: results.deleted.length,
+    failed: results.failed.length,
+    skipped: results.skipped.length
+  }
+}, null, 2))
+```
+
+---
+
+## Session Folder
+
+```
+.workflow/.clean/clean-{YYYY-MM-DD}/
+├── mainline-profile.json     # Git history analysis
+├── cleanup-manifest.json     # Discovery results
+├── cleanup-report.json       # Execution results
+└── .trash/                   # Staging area (temporary)
+```
+
+## Risk Levels
+
+| Risk | Description | Examples |
+|------|-------------|----------|
+| **Low** | Safe to delete | Empty sessions, scratchpad files |
+| **Medium** | Likely unused | Orphan files, old archives |
+| **High** | May have dependencies | Files with some imports |
+
+## Security Features
+
+| Feature | Protection |
+|---------|------------|
+| Path Validation | Whitelist directories, reject traversal |
+| Staged Deletion | Move to .trash before permanent delete |
+| Dangerous Patterns | Block system dirs, node_modules, .git |
+
+## Iteration Flow
+
+```
+First Call (/prompts:clean):
+   ├─ Detect mainline from git history
+   ├─ Discover stale artifacts via subagent
+   ├─ Display summary, await user selection
+   └─ Execute cleanup with staging
+
+Dry-Run (/prompts:clean --dry-run):
+   ├─ All phases except execution
+   └─ Manifest saved for review
+
+Focused (/prompts:clean FOCUS="auth"):
+   └─ Discovery limited to specified area
+```
+
+## Error Handling
+
+| Situation | Action |
+|-----------|--------|
+| No git repo | Use file timestamps only |
+| Agent timeout | Retry once with prompt, then abort |
+| Path validation fail | Skip item, report reason |
+| Manifest parse error | Abort with error |
+| Empty discovery | Report "codebase is clean" |
+
+---
+
+**Now execute cleanup workflow** with focus: $FOCUS

.codex/skills/ccw-loop-b/README.md

@@ -1,102 +1,301 @@
-# CCW Loop-B (Hybrid Orchestrator Pattern)
+# CCW Loop-B: Hybrid Orchestrator Pattern
 
-协调器 + 专用 worker 的迭代开发工作流。
+Iterative development workflow using coordinator + specialized workers architecture.
 
 ## Overview
 
-CCW Loop-B 采用混合模式设计：
-- **Coordinator**: 状态管理、worker 调度、结果汇聚
-- **Workers**: 专注各自领域（develop/debug/validate）
+CCW Loop-B implements a flexible orchestration pattern:
+- **Coordinator**: Main agent managing state, user interaction, worker scheduling
+- **Workers**: Specialized agents (init, develop, debug, validate, complete)
+- **Modes**: Interactive / Auto / Parallel execution
 
-## Installation
+## Architecture
 
 ```
-.codex/skills/ccw-loop-b/
-+-- SKILL.md                    # Main skill definition
-+-- README.md                   # This file
-+-- phases/
-|   +-- orchestrator.md         # Coordinator logic
-|   +-- state-schema.md         # State structure
-+-- specs/
-    +-- action-catalog.md       # Action catalog
-
-.codex/agents/
-+-- ccw-loop-b-init.md          # Init worker
-+-- ccw-loop-b-develop.md       # Develop worker
-+-- ccw-loop-b-debug.md         # Debug worker
-+-- ccw-loop-b-validate.md      # Validate worker
-+-- ccw-loop-b-complete.md      # Complete worker
+Coordinator (Main Agent)
+    |
+    +-- Spawns Workers
+    |   - ccw-loop-b-init.md
+    |   - ccw-loop-b-develop.md
+    |   - ccw-loop-b-debug.md
+    |   - ccw-loop-b-validate.md
+    |   - ccw-loop-b-complete.md
+    |
+    +-- Batch Wait (parallel mode)
+    +-- Sequential Wait (auto/interactive)
+    +-- State Management
+    +-- User Interaction
 ```
 
+## Subagent API
+
+Core APIs for worker orchestration:
+
+| API | 作用 |
+|-----|------|
+| `spawn_agent({ message })` | 创建 worker，返回 `agent_id` |
+| `wait({ ids, timeout_ms })` | 等待结果（唯一取结果入口） |
+| `send_input({ id, message })` | 继续交互 |
+| `close_agent({ id })` | 关闭回收 |
+
+**可用模式**: 单 agent 深度交互 / 多 agent 并行 / 混合模式
+
 ## Execution Modes
 
-| Mode | Description | Use Case |
-|------|-------------|----------|
-| `interactive` | 用户选择 action | 复杂任务，需要人工决策 |
-| `auto` | 自动顺序执行 | 标准开发流程 |
-| `parallel` | 并行多维度分析 | 需要快速全面评估 |
+### Interactive Mode (default)
 
-## Usage
+Coordinator displays menu, user selects action, spawns corresponding worker.
 
 ```bash
-# Interactive (default)
 /ccw-loop-b TASK="Implement feature X"
+```
 
-# Auto mode
+**Flow**:
+1. Init: Parse task, create breakdown
+2. Menu: Show options to user
+3. User selects action (develop/debug/validate)
+4. Spawn worker for selected action
+5. Wait for result
+6. Display result, back to menu
+7. Repeat until complete
+
+### Auto Mode
+
+Automated sequential execution following predefined workflow.
+
+```bash
 /ccw-loop-b --mode=auto TASK="Fix bug Y"
+```
 
-# Parallel analysis
+**Flow**:
+1. Init → 2. Develop → 3. Validate → 4. Complete
+
+If issues found: loop back to Debug → Develop → Validate
+
+### Parallel Mode
+
+Spawn multiple workers simultaneously, batch wait for results.
+
+```bash
 /ccw-loop-b --mode=parallel TASK="Analyze module Z"
-
-# Resume
-/ccw-loop-b --loop-id=loop-b-xxx
 ```
 
-## Session Files
+**Flow**:
+1. Init: Create analysis plan
+2. Spawn workers in parallel: [develop, debug, validate]
+3. Batch wait: `wait({ ids: [w1, w2, w3] })`
+4. Merge results
+5. Coordinator decides next action
+6. Complete
+
+## Session Structure
 
 ```
-.loop/
-+-- {loopId}.json              # Master state
-+-- {loopId}.workers/          # Worker outputs (JSON)
-+-- {loopId}.progress/         # Human-readable progress (MD)
+.workflow/.loop/
++-- {loopId}.json                    # Master state
++-- {loopId}.workers/                # Worker outputs
+|   +-- init.output.json
+|   +-- develop.output.json
+|   +-- debug.output.json
+|   +-- validate.output.json
+|   +-- complete.output.json
++-- {loopId}.progress/               # Human-readable logs
+    +-- develop.md
+    +-- debug.md
+    +-- validate.md
+    +-- summary.md
 ```
 
-## Core Pattern
+## Worker Responsibilities
 
-### Coordinator + Worker
+| Worker | Role | Specialization |
+|--------|------|----------------|
+| **init** | Session initialization | Task parsing, breakdown, planning |
+| **develop** | Code implementation | File operations, pattern matching, incremental development |
+| **debug** | Problem diagnosis | Root cause analysis, hypothesis testing, fix recommendations |
+| **validate** | Testing & verification | Test execution, coverage analysis, quality gates |
+| **complete** | Session finalization | Summary generation, commit preparation, cleanup |
+
+## Usage Examples
+
+### Example 1: Simple Feature Implementation
+
+```bash
+/ccw-loop-b TASK="Add user logout function"
+```
+
+**Auto flow**:
+- Init: Parse requirements
+- Develop: Implement logout in `src/auth.ts`
+- Validate: Run tests
+- Complete: Generate commit message
+
+### Example 2: Bug Investigation
+
+```bash
+/ccw-loop-b TASK="Fix memory leak in WebSocket handler"
+```
+
+**Interactive flow**:
+1. Init: Parse issue
+2. User selects "debug" → Spawn debug worker
+3. Debug: Root cause analysis → recommends fix
+4. User selects "develop" → Apply fix
+5. User selects "validate" → Verify fix works
+6. User selects "complete" → Generate summary
+
+### Example 3: Comprehensive Analysis
+
+```bash
+/ccw-loop-b --mode=parallel TASK="Analyze payment module for improvements"
+```
+
+**Parallel flow**:
+- Spawn [develop, debug, validate] workers simultaneously
+- Develop: Analyze code quality and patterns
+- Debug: Identify potential issues
+- Validate: Check test coverage
+- Wait for all three to complete
+- Merge findings into comprehensive report
+
+### Example 4: Resume Existing Loop
+
+```bash
+/ccw-loop-b --loop-id=loop-b-20260122-abc123
+```
+
+Continues from previous state, respects status (running/paused).
+
+## Key Features
+
+### 1. Worker Specialization
+
+Each worker focuses on one domain:
+- **No overlap**: Clear boundaries between workers
+- **Reusable**: Same worker for different tasks
+- **Composable**: Combine workers for complex workflows
+
+### 2. Flexible Coordination
+
+Coordinator adapts to mode:
+- **Interactive**: Menu-driven, user controls flow
+- **Auto**: Predetermined sequence
+- **Parallel**: Concurrent execution with batch wait
+
+### 3. State Management
+
+Unified state at `.workflow/.loop/{loopId}.json`:
+- **API compatible**: Works with CCW API
+- **Extension fields**: Skill-specific data in `skill_state`
+- **Worker outputs**: Structured JSON for each action
+
+### 4. Progress Tracking
+
+Human-readable logs:
+- **Per-worker progress**: `{action}.md` files
+- **Summary**: Consolidated achievements
+- **Commit-ready**: Formatted commit messages
+
+## Best Practices
+
+1. **Start with Init**: Always initialize before execution
+2. **Use appropriate mode**:
+   - Interactive: Complex tasks needing user decisions
+   - Auto: Well-defined workflows
+   - Parallel: Independent analysis tasks
+3. **Clean up workers**: `close_agent()` after each worker completes
+4. **Batch wait wisely**: Use in parallel mode for efficiency
+5. **Track progress**: Document in progress files
+6. **Validate often**: After each develop phase
+
+## Implementation Patterns
+
+### Pattern 1: Single Worker Deep Interaction
 
 ```javascript
-// Coordinator spawns specialized worker
-const worker = spawn_agent({ message: buildWorkerPrompt(action) })
+const workerId = spawn_agent({ message: workerPrompt })
+const result1 = wait({ ids: [workerId] })
 
-// Wait for completion
-const result = wait({ ids: [worker], timeout_ms: 600000 })
+// Continue with same worker
+send_input({ id: workerId, message: "Continue with next task" })
+const result2 = wait({ ids: [workerId] })
 
-// Process result
-const output = result.status[worker].completed
-updateState(output)
-
-// Cleanup
-close_agent({ id: worker })
+close_agent({ id: workerId })
 ```
 
-### Batch Wait (Parallel Mode)
+### Pattern 2: Multi-Worker Parallel
 
 ```javascript
-// Spawn multiple workers
-const workers = [
-  spawn_agent({ message: developPrompt }),
-  spawn_agent({ message: debugPrompt }),
-  spawn_agent({ message: validatePrompt })
-]
+const workers = {
+  develop: spawn_agent({ message: developPrompt }),
+  debug: spawn_agent({ message: debugPrompt }),
+  validate: spawn_agent({ message: validatePrompt })
+}
 
 // Batch wait
-const results = wait({ ids: workers, timeout_ms: 900000 })
+const results = wait({ ids: Object.values(workers), timeout_ms: 900000 })
 
-// Merge results
-const merged = mergeOutputs(results)
+// Process all results
+Object.values(workers).forEach(id => close_agent({ id }))
 ```
 
-## License
+### Pattern 3: Sequential Worker Chain
 
-MIT
+```javascript
+const actions = ['init', 'develop', 'validate', 'complete']
+
+for (const action of actions) {
+  const workerId = spawn_agent({ message: buildPrompt(action) })
+  const result = wait({ ids: [workerId] })
+  
+  updateState(action, result)
+  close_agent({ id: workerId })
+}
+```
+
+## Error Handling
+
+| Error | Recovery |
+|-------|----------|
+| Worker timeout | `send_input` request convergence |
+| Worker fails | Log error, coordinator decides retry strategy |
+| Partial results | Use completed workers, mark incomplete |
+| State corruption | Rebuild from progress files |
+
+## File Structure
+
+```
+.codex/skills/ccw-loop-b/
++-- SKILL.md                         # Entry point
++-- README.md                        # This file
++-- phases/
+|   +-- state-schema.md              # State structure definition
++-- specs/
+    +-- action-catalog.md            # Action reference
+
+.codex/agents/
++-- ccw-loop-b-init.md               # Worker: Init
++-- ccw-loop-b-develop.md            # Worker: Develop
++-- ccw-loop-b-debug.md              # Worker: Debug
++-- ccw-loop-b-validate.md           # Worker: Validate
++-- ccw-loop-b-complete.md           # Worker: Complete
+```
+
+## Comparison: ccw-loop vs ccw-loop-b
+
+| Aspect | ccw-loop | ccw-loop-b |
+|--------|----------|------------|
+| Pattern | Single agent, multi-phase | Coordinator + workers |
+| Worker model | Single agent handles all | Specialized workers per action |
+| Parallelization | Sequential only | Supports parallel mode |
+| Flexibility | Fixed sequence | Mode-based (interactive/auto/parallel) |
+| Best for | Simple linear workflows | Complex tasks needing specialization |
+
+## Contributing
+
+To add new workers:
+1. Create worker role file in `.codex/agents/`
+2. Define clear responsibilities
+3. Update `action-catalog.md`
+4. Add worker to coordinator spawn logic
+5. Test integration with existing workers

.codex/skills/ccw-loop-b/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: CCW Loop-B
 description: Hybrid orchestrator pattern for iterative development. Coordinator + specialized workers with batch wait support. Triggers on "ccw-loop-b".
 argument-hint: TASK="<task description>" [--loop-id=<id>] [--mode=<interactive|auto|parallel>]
 ---
@@ -61,7 +62,7 @@ Coordinator -> spawn [develop, debug, validate] in parallel -> wait({ ids: all }
 ## Session Structure
 
 ```
-.loop/
+.workflow/.loop/
 +-- {loopId}.json              # Master state
 +-- {loopId}.workers/          # Worker outputs
 |   +-- develop.output.json
@@ -242,9 +243,9 @@ function buildWorkerPrompt(action, loopId, state) {
 
 - **Loop ID**: ${loopId}
 - **Action**: ${action}
-- **State File**: .loop/${loopId}.json
-- **Output File**: .loop/${loopId}.workers/${action}.output.json
-- **Progress File**: .loop/${loopId}.progress/${action}.md
+- **State File**: .workflow/.loop/${loopId}.json
+- **Output File**: .workflow/.loop/${loopId}.workers/${action}.output.json
+- **Progress File**: .workflow/.loop/${loopId}.progress/${action}.md
 
 ## CURRENT STATE
 

.codex/skills/ccw-loop-b/phases/orchestrator.md

@@ -14,7 +14,7 @@ Read state -> Select mode -> Spawn workers -> Wait results -> Merge -> Update st
 
 ```javascript
 function readState(loopId) {
-  const stateFile = `.loop/${loopId}.json`
+  const stateFile = `.workflow/.loop/${loopId}.json`
   return fs.existsSync(stateFile)
     ? JSON.parse(Read(stateFile))
     : null
@@ -252,6 +252,6 @@ function parseWorkerResult(output) {
 ## Best Practices
 
 1. **Worker 生命周期**: spawn → wait → close，不保留 worker
-2. **结果持久化**: Worker 输出写入 `.loop/{loopId}.workers/`
+2. **结果持久化**: Worker 输出写入 `.workflow/.loop/{loopId}.workers/`
 3. **状态同步**: 每次 worker 完成后更新 state
 4. **超时处理**: send_input 请求收敛，再超时则跳过

.codex/skills/ccw-loop-b/phases/state-schema.md

@@ -56,7 +56,7 @@
 
 ## Worker Output Structure
 
-Each worker writes to `.loop/{loopId}.workers/{action}.output.json`:
+Each worker writes to `.workflow/.loop/{loopId}.workers/{action}.output.json`:
 
 ```json
 {
@@ -81,7 +81,7 @@ Each worker writes to `.loop/{loopId}.workers/{action}.output.json`:
 
 ## Progress File Structure
 
-Human-readable progress in `.loop/{loopId}.progress/{action}.md`:
+Human-readable progress in `.workflow/.loop/{loopId}.progress/{action}.md`:
 
 ```markdown
 # Develop Progress
@@ -165,7 +165,7 @@ When `mode === 'parallel'`:
 ## Directory Structure
 
 ```
-.loop/
+.workflow/.loop/
 +-- loop-b-20260122-abc123.json          # Master state
 +-- loop-b-20260122-abc123.workers/
 |   +-- init.output.json

.codex/skills/ccw-loop-b/specs/action-catalog.md

@@ -0,0 +1,383 @@
+# Action Catalog (CCW Loop-B)
+
+Complete reference of worker actions and their capabilities.
+
+## Action Matrix
+
+| Action | Worker Agent | Purpose | Input Requirements | Output |
+|--------|--------------|---------|-------------------|--------|
+| init | ccw-loop-b-init.md | Session initialization | Task description | Task breakdown + execution plan |
+| develop | ccw-loop-b-develop.md | Code implementation | Task list | Code changes + progress update |
+| debug | ccw-loop-b-debug.md | Problem diagnosis | Issue description | Root cause analysis + fix suggestions |
+| validate | ccw-loop-b-validate.md | Testing and verification | Files to test | Test results + coverage report |
+| complete | ccw-loop-b-complete.md | Session finalization | All worker outputs | Summary + commit message |
+
+## Detailed Action Specifications
+
+### INIT
+
+**Purpose**: Parse requirements, create execution plan
+
+**Preconditions**:
+- `status === 'running'`
+- `skill_state === null` (first time)
+
+**Input**:
+```
+- Task description (text)
+- Project context files
+```
+
+**Execution**:
+1. Read `.workflow/project-tech.json`
+2. Read `.workflow/project-guidelines.json`
+3. Parse task into phases
+4. Create task breakdown
+5. Generate execution plan
+
+**Output**:
+```
+WORKER_RESULT:
+- action: init
+- status: success
+- summary: "Initialized with 5 tasks"
+- next_suggestion: develop
+
+TASK_BREAKDOWN:
+- T1: Create auth module
+- T2: Implement JWT utils
+- T3: Write tests
+- T4: Validate implementation
+- T5: Documentation
+
+EXECUTION_PLAN:
+1. Develop (T1-T2)
+2. Validate (T3-T4)
+3. Complete (T5)
+```
+
+**Effects**:
+- `skill_state.pending_tasks` populated
+- Progress structure created
+- Ready for develop phase
+
+---
+
+### DEVELOP
+
+**Purpose**: Implement code, create/modify files
+
+**Preconditions**:
+- `skill_state.pending_tasks.length > 0`
+- `status === 'running'`
+
+**Input**:
+```
+- Task list from state
+- Project conventions
+- Existing code patterns
+```
+
+**Execution**:
+1. Load pending tasks
+2. Find existing patterns
+3. Implement tasks one by one
+4. Update progress file
+5. Mark tasks completed
+
+**Output**:
+```
+WORKER_RESULT:
+- action: develop
+- status: success
+- summary: "Implemented 3 tasks"
+- files_changed: ["src/auth.ts", "src/utils.ts"]
+- next_suggestion: validate
+
+DETAILED_OUTPUT:
+  tasks_completed: [T1, T2]
+  metrics:
+    lines_added: 180
+    lines_removed: 15
+```
+
+**Effects**:
+- Files created/modified
+- `skill_state.completed_tasks` updated
+- Progress documented
+
+**Failure Modes**:
+- Pattern unclear → suggest debug
+- Task blocked → mark blocked, continue
+- Partial completion → set `loop_back_to: "develop"`
+
+---
+
+### DEBUG
+
+**Purpose**: Diagnose issues, root cause analysis
+
+**Preconditions**:
+- Issue exists (test failure, bug report, etc.)
+- `status === 'running'`
+
+**Input**:
+```
+- Issue description
+- Error messages
+- Stack traces
+- Reproduction steps
+```
+
+**Execution**:
+1. Understand problem symptoms
+2. Gather evidence from code
+3. Form hypothesis
+4. Test hypothesis
+5. Document root cause
+6. Suggest fixes
+
+**Output**:
+```
+WORKER_RESULT:
+- action: debug
+- status: success
+- summary: "Root cause: memory leak in event listeners"
+- next_suggestion: develop (apply fixes)
+
+ROOT_CAUSE_ANALYSIS:
+  hypothesis: "Listener accumulation"
+  confidence: high
+  evidence: [...]
+  mechanism: "Detailed explanation"
+
+FIX_RECOMMENDATIONS:
+  1. Add removeAllListeners() on disconnect
+  2. Verification: Monitor memory usage
+```
+
+**Effects**:
+- `skill_state.findings` updated
+- Fix recommendations documented
+- Ready for develop to apply fixes
+
+**Failure Modes**:
+- Insufficient info → request more data
+- Multiple hypotheses → rank by likelihood
+- Inconclusive → suggest investigation areas
+
+---
+
+### VALIDATE
+
+**Purpose**: Run tests, check coverage, quality gates
+
+**Preconditions**:
+- Code exists to validate
+- `status === 'running'`
+
+**Input**:
+```
+- Files to test
+- Test configuration
+- Coverage requirements
+```
+
+**Execution**:
+1. Identify test framework
+2. Run unit tests
+3. Run integration tests
+4. Measure coverage
+5. Check quality (lint, types, security)
+6. Generate report
+
+**Output**:
+```
+WORKER_RESULT:
+- action: validate
+- status: success
+- summary: "113 tests pass, coverage 95%"
+- next_suggestion: complete (all pass) | develop (fix failures)
+
+TEST_RESULTS:
+  unit_tests: { passed: 98, failed: 0 }
+  integration_tests: { passed: 15, failed: 0 }
+  coverage: "95%"
+
+QUALITY_CHECKS:
+  lint: ✓ Pass
+  types: ✓ Pass
+  security: ✓ Pass
+```
+
+**Effects**:
+- Test results documented
+- Coverage measured
+- Quality gates verified
+
+**Failure Modes**:
+- Tests fail → document failures, suggest fixes
+- Coverage low → identify gaps
+- Quality issues → flag problems
+
+---
+
+### COMPLETE
+
+**Purpose**: Finalize session, generate summary, commit
+
+**Preconditions**:
+- All tasks completed
+- Tests passing
+- `status === 'running'`
+
+**Input**:
+```
+- All worker outputs
+- Progress files
+- Current state
+```
+
+**Execution**:
+1. Read all worker outputs
+2. Consolidate achievements
+3. Verify completeness
+4. Generate summary
+5. Prepare commit message
+6. Cleanup and archive
+
+**Output**:
+```
+WORKER_RESULT:
+- action: complete
+- status: success
+- summary: "Session completed successfully"
+- next_suggestion: null
+
+SESSION_SUMMARY:
+  achievements: [...]
+  files_changed: [...]
+  test_results: { ... }
+  quality_checks: { ... }
+
+COMMIT_SUGGESTION:
+  message: "feat: ..."
+  files: [...]
+  ready_for_pr: true
+```
+
+**Effects**:
+- `status` → 'completed'
+- Summary file created
+- Progress archived
+- Commit message ready
+
+**Failure Modes**:
+- Pending tasks remain → mark partial
+- Quality gates fail → list failures
+
+---
+
+## Action Flow Diagrams
+
+### Interactive Mode Flow
+
+```
++------+
+| INIT |
++------+
+    |
+    v
++------+  user selects
+| MENU |-------------+
++------+             |
+    ^                v
+    |         +--------------+
+    |         | spawn worker |
+    |         +--------------+
+    |                |
+    |                v
+    |         +------+-------+
+    +---------|  wait result |
+              +------+-------+
+                     |
+                     v
+              +------+-------+
+              | update state |
+              +--------------+
+                     |
+                     v
+              [completed?] --no--> [back to MENU]
+                     |
+                    yes
+                     v
+              +----------+
+              | COMPLETE |
+              +----------+
+```
+
+### Auto Mode Flow
+
+```
++------+      +---------+      +-------+      +----------+      +----------+
+| INIT | ---> | DEVELOP | ---> | DEBUG | ---> | VALIDATE | ---> | COMPLETE |
++------+      +---------+      +-------+      +----------+      +----------+
+                  ^                |               |
+                  |                +--- [issues]   |
+                  +--------------------------------+
+                              [tests fail]
+```
+
+### Parallel Mode Flow
+
+```
++------+
+| INIT |
++------+
+    |
+    v
++---------------------+
+| spawn all workers   |
+| [develop, debug,    |
+|  validate]          |
++---------------------+
+    |
+    v
++---------------------+
+| wait({ ids: all })  |
++---------------------+
+    |
+    v
++---------------------+
+| merge results       |
++---------------------+
+    |
+    v
++---------------------+
+| coordinator decides |
++---------------------+
+    |
+    v
++----------+
+| COMPLETE |
++----------+
+```
+
+## Worker Coordination
+
+| Scenario | Worker Sequence | Mode |
+|----------|-----------------|------|
+| Simple task | init → develop → validate → complete | Auto |
+| Complex task | init → develop → debug → develop → validate → complete | Auto |
+| Bug fix | init → debug → develop → validate → complete | Auto |
+| Analysis | init → [develop \|\| debug \|\| validate] → complete | Parallel |
+| Interactive | init → menu → user selects → worker → menu → ... | Interactive |
+
+## Best Practices
+
+1. **Init always first**: Parse requirements before execution
+2. **Validate often**: After each develop phase
+3. **Debug when needed**: Don't skip diagnosis
+4. **Complete always last**: Ensure proper cleanup
+5. **Use parallel wisely**: For independent analysis tasks
+6. **Follow sequence**: In auto mode, respect dependencies

.codex/skills/ccw-loop/README.md

@@ -68,7 +68,7 @@ Files are in `.codex/skills/ccw-loop/`:
 
 ```
 1. Parse arguments (task or --loop-id)
-2. Create/read state from .loop/{loopId}.json
+2. Create/read state from .workflow/.loop/{loopId}.json
 3. spawn_agent with ccw-loop-executor role
 4. Main loop:
    a. wait() for agent output
@@ -84,7 +84,7 @@ Files are in `.codex/skills/ccw-loop/`:
 ## Session Files
 
 ```
-.loop/
+.workflow/.loop/
 +-- {loopId}.json              # Master state (API + Skill)
 +-- {loopId}.progress/
     +-- develop.md             # Development timeline
@@ -157,7 +157,7 @@ spawn_agent({
 Works with CCW Dashboard Loop Monitor:
 - Dashboard creates loop via API
 - API triggers this skill with `--loop-id`
-- Skill reads/writes `.loop/{loopId}.json`
+- Skill reads/writes `.workflow/.loop/{loopId}.json`
 - Dashboard polls state for real-time updates
 
 ### Control Signals

.codex/skills/ccw-loop/SKILL.md

@@ -1,5 +1,6 @@
 ---
-description: Stateless iterative development loop workflow with documented progress. Supports develop, debug, and validate phases with file-based state tracking. Triggers on "ccw-loop", "dev loop", "development loop".
+name: CCW Loop
+description: Stateless iterative development loop workflow with documented progress. Supports develop, debug, and validate phases with file-based state tracking. Triggers on "ccw-loop", "dev loop", "development loop", "开发循环", "迭代开发".
 argument-hint: TASK="<task description>" [--loop-id=<id>] [--auto]
 ---
 
@@ -27,8 +28,8 @@ Stateless iterative development loop using Codex subagent pattern. Supports deve
 +-------------------------------------------------------------+
 |              loop-v2-routes.ts (Control Plane)               |
 |                                                              |
-|  State: .loop/{loopId}.json (MASTER)                         |
-|  Tasks: .loop/{loopId}.tasks.jsonl                           |
+|  State: .workflow/.loop/{loopId}.json (MASTER)                         |
+|  Tasks: .workflow/.loop/{loopId}.tasks.jsonl                           |
 |                                                              |
 |  /start -> Trigger ccw-loop skill with --loop-id             |
 |  /pause -> Set status='paused' (skill checks before action)  |
@@ -42,8 +43,8 @@ Stateless iterative development loop using Codex subagent pattern. Supports deve
 |                                                              |
 |  Codex Pattern: spawn_agent -> wait -> send_input -> close   |
 |                                                              |
-|  Reads/Writes: .loop/{loopId}.json (unified state)           |
-|  Writes: .loop/{loopId}.progress/* (progress files)          |
+|  Reads/Writes: .workflow/.loop/{loopId}.json (unified state)           |
+|  Writes: .workflow/.loop/{loopId}.progress/* (progress files)          |
 |                                                              |
 |  BEFORE each action:                                         |
 |    -> Check status: paused/stopped -> exit gracefully        |
@@ -55,9 +56,9 @@ Stateless iterative development loop using Codex subagent pattern. Supports deve
 
 ## Key Design Principles (Codex Adaptation)
 
-1. **Unified State**: API and Skill share `.loop/{loopId}.json` state file
+1. **Unified State**: API and Skill share `.workflow/.loop/{loopId}.json` state file
 2. **Control Signals**: Skill checks status field before each action (paused/stopped)
-3. **File-Driven**: All progress documented in `.loop/{loopId}.progress/`
+3. **File-Driven**: All progress documented in `.workflow/.loop/{loopId}.progress/`
 4. **Resumable**: Continue any loop with `--loop-id`
 5. **Dual Trigger**: Supports API trigger (`--loop-id`) and direct call (task description)
 6. **Single Agent Deep Interaction**: Use send_input for multi-phase execution instead of multiple agents
@@ -100,7 +101,7 @@ Develop -> Debug -> Validate -> (if issues) -> Develop -> ...
 ## Session Structure (Unified Location)
 
 ```
-.loop/
+.workflow/.loop/
 +-- {loopId}.json              # Master state file (API + Skill shared)
 +-- {loopId}.tasks.jsonl       # Task list (API managed)
 +-- {loopId}.progress/         # Skill progress files
@@ -129,8 +130,8 @@ const loopId = args['--loop-id'] || (() => {
   return `loop-v2-${timestamp}-${random}`
 })()
 
-const loopFile = `.loop/${loopId}.json`
-const progressDir = `.loop/${loopId}.progress`
+const loopFile = `.workflow/.loop/${loopId}.json`
+const progressDir = `.workflow/.loop/${loopId}.progress`
 
 // Create progress directory
 mkdir -p "${progressDir}"
@@ -144,14 +145,14 @@ mkdir -p "${progressDir}"
 // Step 1: Read or create initial state
 let state = null
 if (existingLoopId) {
-  state = JSON.parse(Read(`.loop/${loopId}.json`))
+  state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
   if (!state) {
     console.error(`Loop not found: ${loopId}`)
     return
   }
 } else {
   state = createInitialState(loopId, taskDescription)
-  Write(`.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+  Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 }
 
 // Step 2: Create orchestrator agent (single agent handles all phases)
@@ -169,7 +170,7 @@ const agent = spawn_agent({
 ## LOOP CONTEXT
 
 - **Loop ID**: ${loopId}
-- **State File**: .loop/${loopId}.json
+- **State File**: .workflow/.loop/${loopId}.json
 - **Progress Dir**: ${progressDir}
 - **Mode**: ${mode}  // 'interactive' or 'auto'
 
@@ -186,7 +187,7 @@ ${taskDescription}
 You are executing CCW Loop orchestrator. Your job:
 
 1. **Check Control Signals**
-   - Read .loop/${loopId}.json
+   - Read .workflow/.loop/${loopId}.json
    - If status === 'paused' -> Output "PAUSED" and stop
    - If status === 'failed' -> Output "STOPPED" and stop
    - If status === 'running' -> Continue
@@ -200,7 +201,7 @@ You are executing CCW Loop orchestrator. Your job:
 3. **Execute Action**
    - Follow action instructions from ~/.codex/skills/ccw-loop/phases/actions/
    - Update progress files in ${progressDir}/
-   - Update state in .loop/${loopId}.json
+   - Update state in .workflow/.loop/${loopId}.json
 
 4. **Output Format**
    \`\`\`
@@ -283,10 +284,10 @@ Continue with: ${actionResult.next_action}
   }
 
   // Update iteration count in state
-  const currentState = JSON.parse(Read(`.loop/${loopId}.json`))
+  const currentState = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
   currentState.current_iteration = iteration
   currentState.updated_at = getUtc8ISOString()
-  Write(`.loop/${loopId}.json`, JSON.stringify(currentState, null, 2))
+  Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(currentState, null, 2))
 }
 
 // Step 4: Cleanup

.codex/skills/ccw-loop/phases/actions/action-complete.md

@@ -20,7 +20,7 @@ Complete CCW Loop session and generate summary report.
 ### Step 1: Verify Control Signals
 
 ```javascript
-const state = JSON.parse(Read(`.loop/${loopId}.json`))
+const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
 
 if (state.status !== 'running') {
   return {
@@ -174,7 +174,7 @@ state.updated_at = timestamp
 state.skill_state.last_action = 'COMPLETE'
 state.skill_state.summary = stats
 
-Write(`.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 ```
 
 ## Output Format
@@ -190,8 +190,8 @@ ACTION_RESULT:
   }
 
 FILES_UPDATED:
-- .loop/{loopId}.json: Status set to completed
-- .loop/{loopId}.progress/summary.md: Summary report generated
+- .workflow/.loop/{loopId}.json: Status set to completed
+- .workflow/.loop/{loopId}.progress/summary.md: Summary report generated
 
 NEXT_ACTION_NEEDED: COMPLETED
 ```

.codex/skills/ccw-loop/phases/actions/action-debug.md

@@ -233,7 +233,7 @@ if (confirmedHypothesis) {
 
 state.skill_state.last_action = 'DEBUG'
 state.updated_at = timestamp
-Write(`.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 ```
 
 ## Output Format
@@ -249,8 +249,8 @@ ACTION_RESULT:
   }
 
 FILES_UPDATED:
-- .loop/{loopId}.progress/debug.md: Understanding updated
-- .loop/{loopId}.progress/hypotheses.json: Hypotheses updated
+- .workflow/.loop/{loopId}.progress/debug.md: Understanding updated
+- .workflow/.loop/{loopId}.progress/hypotheses.json: Hypotheses updated
 - [Source files]: Instrumentation added
 
 NEXT_ACTION_NEEDED: {DEBUG | VALIDATE | DEVELOP | MENU}

.codex/skills/ccw-loop/phases/actions/action-develop.md

@@ -20,7 +20,7 @@ Execute development task and record progress to develop.md.
 ### Step 1: Verify Control Signals
 
 ```javascript
-const state = JSON.parse(Read(`.loop/${loopId}.json`))
+const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
 
 if (state.status !== 'running') {
   return {
@@ -133,7 +133,7 @@ state.skill_state.last_action = 'DEVELOP'
 state.skill_state.completed_actions.push('DEVELOP')
 state.updated_at = timestamp
 
-Write(`.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 ```
 
 ## Output Format
@@ -149,9 +149,9 @@ ACTION_RESULT:
   }
 
 FILES_UPDATED:
-- .loop/{loopId}.json: Task status updated
-- .loop/{loopId}.progress/develop.md: Progress entry added
-- .loop/{loopId}.progress/changes.log: Change entry added
+- .workflow/.loop/{loopId}.json: Task status updated
+- .workflow/.loop/{loopId}.progress/develop.md: Progress entry added
+- .workflow/.loop/{loopId}.progress/changes.log: Change entry added
 
 NEXT_ACTION_NEEDED: {DEVELOP | DEBUG | VALIDATE | MENU}
 ```

.codex/skills/ccw-loop/phases/actions/action-init.md

@@ -19,7 +19,7 @@ Initialize CCW Loop session, create directory structure and initial state.
 ### Step 1: Verify Control Signals
 
 ```javascript
-const state = JSON.parse(Read(`.loop/${loopId}.json`))
+const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
 
 if (state.status !== 'running') {
   return {
@@ -34,7 +34,7 @@ if (state.status !== 'running') {
 ### Step 2: Create Directory Structure
 
 ```javascript
-const progressDir = `.loop/${loopId}.progress`
+const progressDir = `.workflow/.loop/${loopId}.progress`
 
 // Directories created by orchestrator, verify they exist
 // mkdir -p ${progressDir}
@@ -131,7 +131,7 @@ const skillState = {
 
 state.skill_state = skillState
 state.updated_at = getUtc8ISOString()
-Write(`.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 ```
 
 ## Output Format
@@ -143,8 +143,8 @@ ACTION_RESULT:
 - message: Session initialized with {N} development tasks
 
 FILES_UPDATED:
-- .loop/{loopId}.json: skill_state initialized
-- .loop/{loopId}.progress/develop.md: Progress document created
+- .workflow/.loop/{loopId}.json: skill_state initialized
+- .workflow/.loop/{loopId}.progress/develop.md: Progress document created
 
 NEXT_ACTION_NEEDED: {DEVELOP (auto) | MENU (interactive)}
 ```

.codex/skills/ccw-loop/phases/actions/action-menu.md

@@ -20,7 +20,7 @@ Display interactive action menu for user selection.
 ### Step 1: Verify Control Signals
 
 ```javascript
-const state = JSON.parse(Read(`.loop/${loopId}.json`))
+const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
 
 if (state.status !== 'running') {
   return {
@@ -172,7 +172,7 @@ If user selects "exit":
 // Save current state
 state.status = 'user_exit'
 state.updated_at = getUtc8ISOString()
-Write(`.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 
 return {
   action: 'MENU',

.codex/skills/ccw-loop/phases/actions/action-validate.md

@@ -21,7 +21,7 @@ Run tests and verify implementation, record results to validate.md.
 ### Step 1: Verify Control Signals
 
 ```javascript
-const state = JSON.parse(Read(`.loop/${loopId}.json`))
+const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
 
 if (state.status !== 'running') {
   return {
@@ -174,7 +174,7 @@ state.skill_state.validate.last_run_at = timestamp
 
 state.skill_state.last_action = 'VALIDATE'
 state.updated_at = timestamp
-Write(`.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 ```
 
 ## Output Format
@@ -191,9 +191,9 @@ ACTION_RESULT:
   }
 
 FILES_UPDATED:
-- .loop/{loopId}.progress/validate.md: Validation report created
-- .loop/{loopId}.progress/test-results.json: Test results saved
-- .loop/{loopId}.progress/coverage.json: Coverage data saved (if available)
+- .workflow/.loop/{loopId}.progress/validate.md: Validation report created
+- .workflow/.loop/{loopId}.progress/test-results.json: Test results saved
+- .workflow/.loop/{loopId}.progress/coverage.json: Coverage data saved (if available)
 
 NEXT_ACTION_NEEDED: {COMPLETE | DEBUG | DEVELOP | MENU}
 ```

.codex/skills/ccw-loop/phases/orchestrator.md

@@ -45,7 +45,7 @@ const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOSt
  * @param loopId - Loop ID (e.g., "loop-v2-20260122-abc123")
  */
 function readLoopState(loopId) {
-  const stateFile = `.loop/${loopId}.json`
+  const stateFile = `.workflow/.loop/${loopId}.json`
 
   if (!fs.existsSync(stateFile)) {
     return null
@@ -63,7 +63,7 @@ function readLoopState(loopId) {
  * Create new loop state (only for direct calls, API triggers have existing state)
  */
 function createLoopState(loopId, taskDescription) {
-  const stateFile = `.loop/${loopId}.json`
+  const stateFile = `.workflow/.loop/${loopId}.json`
   const now = getUtc8ISOString()
 
   const state = {
@@ -83,7 +83,7 @@ function createLoopState(loopId, taskDescription) {
 
   // Ensure directories exist
   mkdir -p ".loop"
-  mkdir -p ".loop/${loopId}.progress"
+  mkdir -p ".workflow/.loop/${loopId}.progress"
 
   Write(stateFile, JSON.stringify(state, null, 2))
   return state
@@ -137,7 +137,7 @@ async function runOrchestrator(options = {}) {
     return { status: 'error', message: 'Missing loopId or task' }
   }
 
-  const progressDir = `.loop/${loopId}.progress`
+  const progressDir = `.workflow/.loop/${loopId}.progress`
 
   // 2. Create executor agent (single agent for entire loop)
   const agent = spawn_agent({
@@ -154,7 +154,7 @@ async function runOrchestrator(options = {}) {
 ## LOOP CONTEXT
 
 - **Loop ID**: ${loopId}
-- **State File**: .loop/${loopId}.json
+- **State File**: .workflow/.loop/${loopId}.json
 - **Progress Dir**: ${progressDir}
 - **Mode**: ${mode}
 
@@ -213,7 +213,7 @@ Execution timeout reached. Please:
     state = readLoopState(loopId)
     state.current_iteration = iteration
     state.updated_at = getUtc8ISOString()
-    Write(`.loop/${loopId}.json`, JSON.stringify(state, null, 2))
+    Write(`.workflow/.loop/${loopId}.json`, JSON.stringify(state, null, 2))
 
     // Handle different outcomes
     switch (actionResult.next_action) {

.codex/skills/ccw-loop/phases/state-schema.md

@@ -4,7 +4,7 @@ CCW Loop state structure definition for Codex subagent pattern.
 
 ## State File
 
-**Location**: `.loop/{loopId}.json` (unified location, API + Skill shared)
+**Location**: `.workflow/.loop/{loopId}.json` (unified location, API + Skill shared)
 
 ## Structure Definition
 
@@ -208,7 +208,7 @@ Agent checks control signals at start of every action:
  * @returns { continue: boolean, action: 'pause_exit' | 'stop_exit' | 'continue' }
  */
 function checkControlSignals(loopId) {
-  const state = JSON.parse(Read(`.loop/${loopId}.json`))
+  const state = JSON.parse(Read(`.workflow/.loop/${loopId}.json`))
 
   switch (state.status) {
     case 'paused':
@@ -338,17 +338,17 @@ State-to-file mapping:
 
 | State Field | Sync File | Sync Timing |
 |-------------|-----------|-------------|
-| Entire LoopState | `.loop/{loopId}.json` | Every state change (master) |
-| `skill_state.develop` | `.loop/{loopId}.progress/develop.md` | After each dev operation |
-| `skill_state.debug` | `.loop/{loopId}.progress/debug.md` | After each debug operation |
-| `skill_state.validate` | `.loop/{loopId}.progress/validate.md` | After each validation |
-| Code changes log | `.loop/{loopId}.progress/changes.log` | Each file modification (NDJSON) |
-| Debug log | `.loop/{loopId}.progress/debug.log` | Each debug log (NDJSON) |
+| Entire LoopState | `.workflow/.loop/{loopId}.json` | Every state change (master) |
+| `skill_state.develop` | `.workflow/.loop/{loopId}.progress/develop.md` | After each dev operation |
+| `skill_state.debug` | `.workflow/.loop/{loopId}.progress/debug.md` | After each debug operation |
+| `skill_state.validate` | `.workflow/.loop/{loopId}.progress/validate.md` | After each validation |
+| Code changes log | `.workflow/.loop/{loopId}.progress/changes.log` | Each file modification (NDJSON) |
+| Debug log | `.workflow/.loop/{loopId}.progress/debug.log` | Each debug log (NDJSON) |
 
 ### File Structure
 
 ```
-.loop/
+.workflow/.loop/
 +-- loop-v2-20260122-abc123.json         # Master state file (API + Skill)
 +-- loop-v2-20260122-abc123.tasks.jsonl  # Task list (API managed)
 +-- loop-v2-20260122-abc123.progress/    # Skill progress files
@@ -366,7 +366,7 @@ If master state file corrupted, rebuild skill_state from progress files:
 
 ```javascript
 function rebuildSkillStateFromProgress(loopId) {
-  const progressDir = `.loop/${loopId}.progress`
+  const progressDir = `.workflow/.loop/${loopId}.progress`
 
   // Parse progress files to rebuild state
   const skill_state = {
@@ -381,7 +381,7 @@ function rebuildSkillStateFromProgress(loopId) {
 
 ## Codex Pattern Notes
 
-1. **Agent reads state**: Agent reads `.loop/{loopId}.json` at action start
+1. **Agent reads state**: Agent reads `.workflow/.loop/{loopId}.json` at action start
 2. **Agent writes state**: Agent updates state after action completion
 3. **Orchestrator tracks iterations**: Main loop tracks `current_iteration`
 4. **Single agent context**: All state updates in same agent conversation via send_input

.codex/skills/parallel-dev-cycle/README.md

@@ -0,0 +1,385 @@
+# Parallel Dev Cycle Skill
+
+Multi-agent parallel development cycle using Codex subagent pattern with continuous iteration support.
+
+## Overview
+
+This skill implements a **single-file-per-agent** development workflow:
+
+- **RA**: `requirements.md` (all requirements + edge cases + history)
+- **EP**: `exploration.md`, `architecture.md`, `plan.json` (codebase exploration + architecture + structured tasks)
+- **CD**: `implementation.md` (progress + files + decisions + testing)
+- **VAS**: `summary.md` (validation + test results + recommendations)
+
+Each file is **completely rewritten** on each iteration, with old versions auto-archived to `history/`.
+
+## Installation
+
+Files are in `.codex/skills/parallel-dev-cycle/`:
+
+```
+.codex/skills/parallel-dev-cycle/
+├── SKILL.md                        # Main skill definition
+├── README.md                       # This file
+├── phases/
+│   ├── orchestrator.md             # Multi-agent coordination
+│   ├── state-schema.md             # Unified state structure
+│   └── agents/
+│       ├── requirements-analyst.md # RA role
+│       ├── exploration-planner.md  # EP role
+│       ├── code-developer.md       # CD role
+│       └── validation-archivist.md # VAS role
+└── specs/
+    ├── coordination-protocol.md    # Agent communication
+    └── versioning-strategy.md      # Version management
+```
+
+## Quick Start
+
+### Launch New Cycle
+
+```bash
+/parallel-dev-cycle TASK="Implement OAuth authentication"
+```
+
+Creates:
+```
+.workflow/.cycle/cycle-v1-20260122-abc123.progress/
+├── ra/
+│   ├── requirements.md (v1.0.0)
+│   └── changes.log (NDJSON)
+├── ep/
+│   ├── exploration.md (v1.0.0)
+│   ├── architecture.md (v1.0.0)
+│   ├── plan.json (v1.0.0)
+│   └── changes.log (NDJSON)
+├── cd/
+│   ├── implementation.md (v1.0.0)
+│   └── changes.log (NDJSON)
+└── vas/
+    ├── summary.md (v1.0.0)
+    └── changes.log (NDJSON)
+```
+
+### Continue With Extension (XX-1 Pattern)
+
+User adds requirement: "Also support Google OAuth"
+
+```bash
+/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Add Google OAuth"
+```
+
+Automatically:
+1. Archives old `requirements.md (v1.0.0)` → `history/requirements-v1.0.0.md`
+2. Rewrites `requirements.md (v1.1.0)` - complete file replacement
+3. Appends change to `changes.log` (NDJSON audit trail)
+
+### Next Iteration (XX-2)
+
+```bash
+/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Add GitHub provider"
+```
+
+All files update to v1.2.0, previous versions archived.
+
+## Execution Flow
+
+### Phase 1: Parallel Agent Execution
+
+```
+Time  RA              EP              CD              VAS
+────  ──              ──              ──              ──
+0ms   [spawned]       [spawned]       [spawned]       [spawned]
+      ↓               ↓               ↓               ↓
+      Analyzing       Exploring       Reading plan    Waiting
+      task            codebase        from EP...
+                                      ↓
+5min  Outputs req.    Outputs plan    Requirements
+      v1.0.0 ✓        v1.0.0 ✓        unclear - BLOCKED
+
+10min Clarifies req   Updates plan    ✓ Ready
+      v1.0.1 ✓        v1.0.1 ✓        Implementing...
+                                      ↓
+15min ✓ Complete      ✓ Complete      ✓ Code done      [waiting for CD]
+
+20min                                                 [starts tests]
+                                                      ↓
+25min                                                 Outputs summary
+                                                      v1.0.0 ✓
+```
+
+### Phase 2: Version Transition
+
+When iteration completes, next extends to v1.1.0:
+
+```
+Current State (v1.0.0)
+├── requirements.md (v1.0.0)
+├── plan.json (v1.0.0)
+├── implementation.md (v1.0.0)
+└── summary.md (v1.0.0)
+
+User: "Add GitHub provider"
+         ↓
+Archive Old                    Write New
+├── history/requirements-v1.0.0.md  → requirements.md (v1.1.0) - REWRITTEN
+├── history/plan-v1.0.0.json        → plan.json (v1.1.0) - REWRITTEN
+├── history/impl-v1.0.0.md          → implementation.md (v1.1.0) - REWRITTEN
+└── history/summary-v1.0.0.md       → summary.md (v1.1.0) - REWRITTEN
+                                       ↓
+                                 Append to changes.log (NDJSON)
+```
+
+## Session Files
+
+```
+.workflow/.cycle/{cycleId}.progress/
+
+ra/ - Requirements Analyst
+├── requirements.md           # v1.2.0 (current, complete rewrite)
+├── changes.log              # NDJSON audit trail
+└── history/
+    ├── requirements-v1.0.0.md
+    └── requirements-v1.1.0.md
+
+ep/ - Exploration & Planning
+├── exploration.md           # v1.2.0 (codebase exploration)
+├── architecture.md          # v1.2.0 (architecture design)
+├── plan.json                # v1.2.0 (structured task list, current)
+├── changes.log              # NDJSON audit trail
+└── history/
+    ├── plan-v1.0.0.json
+    └── plan-v1.1.0.json
+
+cd/ - Code Developer
+├── implementation.md        # v1.2.0 (current)
+├── changes.log              # NDJSON audit trail
+└── history/
+    ├── implementation-v1.0.0.md
+    └── implementation-v1.1.0.md
+
+vas/ - Validation & Archival
+├── summary.md               # v1.2.0 (current)
+├── changes.log              # NDJSON audit trail
+└── history/
+    ├── summary-v1.0.0.md
+    └── summary-v1.1.0.md
+```
+
+## Versioning Strategy
+
+### Semantic Versioning
+
+- **1.0.0**: Initial cycle
+- **1.1.0**: User extends with new requirement
+- **1.2.0**: Another iteration with more requirements
+
+### What Gets Versioned
+
+✅ **Main Document File**
+- Completely rewritten each iteration
+- Auto-archived to `history/`
+- No inline version history (stays clean)
+
+✅ **Changes.log (NDJSON)**
+- Append-only (never deleted)
+- Complete audit trail of all changes
+- Used to trace requirement origins
+
+✅ **Historical Snapshots**
+- Auto-created in `history/` directory
+- Keep last N versions (default: 5)
+- For reference when needed
+
+### Key Principle
+
+> **主文档简洁清晰** ← Agent 只关注当前版本
+>
+> **完整历史记录** ← Changes.log 保留每个变更
+>
+> **版本快照归档** ← History/ 备份旧版本
+
+## File Maintenance
+
+### Each Agent
+
+| Agent | File | Contains | Size |
+|-------|------|----------|------|
+| **RA** | requirements.md | All FR, NFR, edge cases, history summary | ~2-5KB |
+| **EP** | exploration.md + architecture.md + plan.json | Codebase exploration, architecture design, structured task list | ~5-10KB total |
+| **CD** | implementation.md | Completed tasks, files changed, decisions, tests | ~4-10KB |
+| **VAS** | summary.md | Test results, coverage, issues, recommendations | ~5-12KB |
+
+### Changes.log (Shared)
+
+NDJSON format - one line per change:
+
+```jsonl
+{"timestamp":"2026-01-22T10:00:00+08:00","version":"1.0.0","agent":"ra","action":"create","change":"Initial requirements","iteration":1}
+{"timestamp":"2026-01-22T11:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added Google OAuth","iteration":2}
+{"timestamp":"2026-01-22T12:00:00+08:00","version":"1.2.0","agent":"ra","action":"update","change":"Added GitHub, MFA","iteration":3}
+```
+
+## Accessing History
+
+### Current Version
+
+```bash
+# View latest requirements
+cat .workflow/.cycle/cycle-xxx.progress/ra/requirements.md
+
+# Quick check - version is in header
+head -5 requirements.md  # "# Requirements Specification - v1.2.0"
+```
+
+### Version History
+
+```bash
+# View previous version
+cat .workflow/.cycle/cycle-xxx.progress/ra/history/requirements-v1.1.0.md
+
+# Audit trail - all changes
+cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq .
+
+# Changes in specific iteration
+cat changes.log | jq 'select(.iteration==2)'
+
+# Trace requirement history
+cat changes.log | jq 'select(.change | contains("OAuth"))'
+```
+
+## Codex Pattern Implementation
+
+### Multi-Agent Parallel
+
+```javascript
+// Create 4 agents in parallel
+const agents = {
+  ra: spawn_agent({ message: raRoleAndTask }),
+  ep: spawn_agent({ message: epRoleAndTask }),
+  cd: spawn_agent({ message: cdRoleAndTask }),
+  vas: spawn_agent({ message: vasRoleAndTask })
+}
+
+// Wait for all 4 in parallel
+const results = wait({ ids: [agents.ra, agents.ep, agents.cd, agents.vas] })
+```
+
+### Role Path Passing
+
+Each agent reads its own role definition:
+
+```javascript
+spawn_agent({
+  message: `
+## MANDATORY FIRST STEPS
+1. Read role: ~/.codex/agents/requirements-analyst.md
+2. Read: .workflow/project-tech.json
+3. Read: .workflow/project-guidelines.json
+
+## TASK
+${taskDescription}
+`
+})
+```
+
+### Deep Interaction
+
+Use `send_input` for iteration refinement:
+
+```javascript
+// First output
+const initial = wait({ ids: [agent] })
+
+// User feedback
+send_input({
+  id: agent,
+  message: `
+## Feedback
+
+${feedback}
+
+## Next Steps
+Update ${filename} based on feedback. Increment version.
+Output PHASE_RESULT when complete.
+`
+})
+
+// Updated output
+const revised = wait({ ids: [agent] })
+
+// Only close when done
+close_agent({ id: agent })
+```
+
+## Error Handling
+
+| Situation | Recovery |
+|-----------|----------|
+| Agent timeout | send_input requesting convergence or retry |
+| State corrupted | Rebuild from changes.log NDJSON |
+| Version mismatch | Agent checks version in state before reading |
+| Blocked dependency | Orchestrator sends updated file path |
+
+## Best Practices
+
+1. **Let agents rewrite** - Don't maintain incremental history in main doc
+2. **Trust changes.log** - NDJSON is the source of truth for history
+3. **Archive on version bump** - Automatic, no manual versioning needed
+4. **Keep files focused** - Each file should be readable in 5 minutes
+5. **Version header always present** - Makes version obvious at a glance
+
+## Integration
+
+This skill works standalone or integrated with:
+- Dashboard Loop Monitor (API triggers)
+- CCW workflow system
+- Custom orchestration
+
+### API Trigger
+
+```bash
+POST /api/cycles/start
+{
+  "task": "Implement OAuth",
+  "mode": "auto"
+}
+→ Returns cycle_id
+
+GET /api/cycles/{cycle_id}/status
+→ Returns agents status and progress
+```
+
+## Architecture Diagram
+
+```
+User Task
+    ↓
+Orchestrator (main coordinator)
+    ├─→ spawn_agent(RA)
+    ├─→ spawn_agent(EP)
+    ├─→ spawn_agent(CD)
+    └─→ spawn_agent(VAS)
+           ↓
+        wait({ ids: [all 4] })
+           ↓
+      All write to:
+      - requirements.md (v1.x.0)
+      - exploration.md, architecture.md, plan.json (v1.x.0)
+      - implementation.md (v1.x.0)
+      - summary.md (v1.x.0)
+      - changes.log (NDJSON append)
+           ↓
+      [Automatic archival]
+      - history/requirements-v1.{x-1}.0.md
+      - history/plan-v1.{x-1}.0.json
+      - etc...
+           ↓
+      Orchestrator: Next iteration?
+      - Yes: send_input with feedback
+      - No: close_agent, report summary
+```
+
+## License
+
+MIT

.codex/skills/parallel-dev-cycle/SKILL.md

@@ -0,0 +1,194 @@
+---
+name: Parallel Dev Cycle
+description: Multi-agent parallel development cycle with requirement analysis, exploration planning, code development, and validation. Supports continuous iteration with markdown progress documentation.
+argument-hint: TASK="<task description>" | --cycle-id=<id> [--extend="<extension>"] [--auto] [--parallel=<count>]
+---
+
+# Parallel Dev Cycle - Multi-Agent Development Workflow
+
+Multi-agent parallel development cycle using Codex subagent pattern with four specialized workers:
+1. **Requirements Analysis & Extension** (RA) - Requirement analysis and self-enhancement
+2. **Exploration & Planning** (EP) - Exploration and planning
+3. **Code Development** (CD) - Code development with debug strategy support
+4. **Validation & Archival Summary** (VAS) - Validation and archival summary
+
+Each agent **maintains one main document** (e.g., requirements.md, plan.json, implementation.md) that is completely rewritten per iteration, plus auxiliary logs (changes.log, debug-log.ndjson) that are append-only. Supports versioning, automatic archival, and complete history tracking.
+
+## Arguments
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| TASK | One of TASK or --cycle-id | Task description (for new cycle, mutually exclusive with --cycle-id) |
+| --cycle-id | One of TASK or --cycle-id | Existing cycle ID to continue (from API or previous session) |
+| --extend | No | Extension description (only valid with --cycle-id) |
+| --auto | No | Auto-cycle mode (run all phases sequentially) |
+| --parallel | No | Number of parallel agents (default: 4, max: 4) |
+
+## Architecture Overview
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    User Input (Task)                        │
+└────────────────────────────┬────────────────────────────────┘
+                             │
+                             v
+                  ┌──────────────────────┐
+                  │  Orchestrator Agent  │  (Coordinator)
+                  │  (spawned once)      │
+                  └──────────────────────┘
+                             │
+        ┌────────────────────┼────────────────────┐
+        │                    │                    │
+        v                    v                    v
+    ┌────────┐         ┌────────┐         ┌────────┐
+    │  RA    │         │  EP    │         │  CD    │
+    │Agent   │         │Agent   │         │Agent   │
+    └────────┘         └────────┘         └────────┘
+        │                    │                    │
+        └────────────────────┼────────────────────┘
+                             │
+                             v
+                         ┌────────┐
+                         │  VAS   │
+                         │ Agent  │
+                         └────────┘
+                             │
+                             v
+                  ┌──────────────────────┐
+                  │    Summary Report    │
+                  │  & Markdown Docs     │
+                  └──────────────────────┘
+```
+
+## Key Design Principles
+
+1. **Main Document + Auxiliary Logs**: Each agent maintains one main document (rewritten per iteration) and auxiliary logs (append-only)
+2. **Version-Based Overwrite**: Main documents completely rewritten per version; logs append-only
+3. **Automatic Archival**: Old main document versions automatically archived to `history/` directory
+4. **Complete Audit Trail**: Changes.log (NDJSON) preserves all change history
+5. **Parallel Coordination**: Four agents launched simultaneously; coordination via shared state and orchestrator
+6. **File References**: Use short file paths instead of content passing
+7. **Self-Enhancement**: RA agent proactively extends requirements based on context
+
+## Session Structure
+
+```
+.workflow/.cycle/
++-- {cycleId}.json                                 # Master state file
++-- {cycleId}.progress/
+    +-- ra/
+    |   +-- requirements.md                        # Current version (complete rewrite)
+    |   +-- changes.log                            # NDJSON complete history (append-only)
+    |   └-- history/
+    |       +-- requirements-v1.0.0.md             # Archived snapshot
+    |       +-- requirements-v1.1.0.md             # Archived snapshot
+    +-- ep/
+    |   +-- exploration.md                         # Codebase exploration report
+    |   +-- architecture.md                        # Architecture design
+    |   +-- plan.json                              # Structured task list (current version)
+    |   +-- changes.log                            # NDJSON complete history
+    |   └-- history/
+    |       +-- plan-v1.0.0.json
+    |       +-- plan-v1.1.0.json
+    +-- cd/
+    |   +-- implementation.md                      # Current version
+    |   +-- debug-log.ndjson                       # Debug hypothesis tracking
+    |   +-- changes.log                            # NDJSON complete history
+    |   └-- history/
+    |       +-- implementation-v1.0.0.md
+    |       +-- implementation-v1.1.0.md
+    +-- vas/
+    |   +-- summary.md                             # Current version
+    |   +-- changes.log                            # NDJSON complete history
+    |   └-- history/
+    |       +-- summary-v1.0.0.md
+    |       +-- summary-v1.1.0.md
+    └-- coordination/
+        +-- timeline.md                            # Execution timeline
+        +-- decisions.log                          # Decision log
+```
+
+## State Management
+
+State schema is defined in [phases/state-schema.md](phases/state-schema.md). The master state file (`{cycleId}.json`) tracks:
+
+- Cycle metadata (id, title, status, iterations)
+- Agent states (status, output files, version)
+- Shared context (requirements, plan, changes, test results)
+- Coordination data (feedback log, decisions, blockers)
+
+## Versioning Workflow
+
+### Initial Version (v1.0.0)
+
+```bash
+/parallel-dev-cycle TASK="Implement OAuth login"
+```
+
+Generates:
+```
+requirements.md (v1.0.0)
+exploration.md (v1.0.0)
+architecture.md (v1.0.0)
+plan.json (v1.0.0)
+implementation.md (v1.0.0) - if applicable
+summary.md (v1.0.0) - if applicable
+```
+
+### Iteration Versions (v1.1.0, v1.2.0)
+
+```bash
+/parallel-dev-cycle --cycle-id=cycle-v1-xxx --extend="Add GitHub support"
+```
+
+**Automatic handling**:
+1. Read current `requirements.md (v1.0.0)`
+2. Auto-archive to `history/requirements-v1.0.0.md`
+3. Recreate `requirements.md (v1.1.0)` - complete overwrite
+4. Append changes to `changes.log` (NDJSON)
+
+## Changes.log Format (NDJSON)
+
+Permanent audit log (append-only, never deleted):
+
+```jsonl
+{"timestamp":"2026-01-22T10:00:00+08:00","version":"1.0.0","agent":"ra","action":"create","change":"Initial requirements","iteration":1}
+{"timestamp":"2026-01-22T11:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added Google OAuth requirement","iteration":2}
+{"timestamp":"2026-01-22T11:30:00+08:00","version":"1.0.0","agent":"ep","action":"create","change":"Initial implementation plan","iteration":1}
+```
+
+## Usage
+
+```bash
+# Start new cycle
+/parallel-dev-cycle TASK="Implement real-time notifications"
+
+# Continue cycle
+/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123
+
+# Iteration with extension
+/parallel-dev-cycle --cycle-id=cycle-v1-20260122-abc123 --extend="Also add email notifications"
+
+# Auto mode
+/parallel-dev-cycle --auto TASK="Add OAuth authentication"
+```
+
+## Key Benefits
+
+- **Simple**: Each agent maintains only 1 file + changes.log
+- **Efficient**: Version rewrite without complex version marking
+- **Traceable**: Complete history in `history/` and `changes.log`
+- **Fast**: Agent reads current version quickly (no history parsing needed)
+- **Auditable**: NDJSON changes.log fully traces every change
+- **Self-Enhancing**: RA agent proactively extends requirements
+- **Debug-Ready**: CD agent supports hypothesis-driven debugging
+
+## Reference Documents
+
+| Document | Purpose |
+|----------|---------|
+| [phases/orchestrator.md](phases/orchestrator.md) | Orchestrator logic |
+| [phases/state-schema.md](phases/state-schema.md) | State structure definition |
+| [phases/agents/](phases/agents/) | Four agent role definitions |
+| [specs/coordination-protocol.md](specs/coordination-protocol.md) | Communication protocol |
+| [specs/versioning-strategy.md](specs/versioning-strategy.md) | Version management |

.codex/skills/parallel-dev-cycle/phases/agents/code-developer.md

@@ -0,0 +1,327 @@
+---
+name: Code Developer Agent
+description: Implement features based on plan and requirements
+color: cyan
+---
+
+# Code Developer Agent (CD)
+
+## Role Definition
+
+The Code Developer is responsible for implementing features according to the plan and requirements. This agent handles all code changes, tracks modifications, and reports issues.
+
+## Core Responsibilities
+
+1. **Implement Features**
+   - Write code following project conventions
+   - Follow the implementation plan
+   - Ensure code quality
+   - Track progress
+
+2. **Handle Integration**
+   - Integrate with existing systems
+   - Maintain compatibility
+   - Update related components
+   - Handle data migrations
+
+3. **Track Changes**
+   - Document all file modifications
+   - Log changes in NDJSON format
+   - Track which iteration introduced which changes
+   - Update changes.log
+
+4. **Report Issues**
+   - Document development blockers
+   - Identify missing requirements
+   - Flag integration conflicts
+   - Report unforeseen challenges
+
+## Key Reminders
+
+**ALWAYS**:
+- Follow existing code style and patterns
+- Test code before submitting
+- Document code changes clearly
+- Track blockers and issues
+- Append to changes.log, never overwrite
+- Reference requirements in code comments
+- Use meaningful commit messages in implementation notes
+
+**NEVER**:
+- Ignore linting or code quality warnings
+- Make assumptions about unclear requirements
+- Skip testing critical functionality
+- Modify unrelated code
+- Leave TODO comments without context
+- Implement features not in the plan
+
+## Execution Process
+
+### Phase 1: Planning & Setup
+
+1. **Read Context**
+   - Plan from exploration-planner.md
+   - Requirements from requirements-analyst.md
+   - Project tech stack and guidelines
+
+2. **Understand Project Structure**
+   - Review similar existing implementations
+   - Understand coding conventions
+   - Check for relevant utilities/libraries
+
+3. **Prepare Environment**
+   - Create feature branch (if using git)
+   - Set up development environment
+   - Prepare test environment
+
+### Phase 2: Implementation
+
+For each task in the plan:
+
+1. **Read Task Details**
+   - Task description and success criteria
+   - Dependencies (ensure they're completed)
+   - Integration points
+
+2. **Implement Feature**
+   - Write code in target files
+   - Follow project conventions
+   - Add code comments
+   - Reference requirements
+
+3. **Track Changes**
+   - Log each file modification to changes.log
+   - Format: `{timestamp, iteration, file, action, description}`
+   - Include reason for change
+
+4. **Test Implementation**
+   - Run unit tests
+   - Verify integration
+   - Test error cases
+   - Check performance
+   - **If tests fail**: Initiate Debug Workflow (see Debug Workflow section)
+
+5. **Report Progress**
+   - Update implementation.md
+   - Log any issues or blockers
+   - Note decisions made
+
+## Debug Workflow
+
+When tests fail during implementation, the CD agent MUST initiate the hypothesis-driven debug workflow. This workflow systematically identifies and resolves bugs through structured hypothesis testing.
+
+### Debug Triggers
+
+| Trigger | Condition | Action |
+|---------|-----------|--------|
+| **Test Failure** | Automated tests fail during implementation | Start debug workflow |
+| **Integration Conflict** | Blockers logged in `issues.md` | Start debug workflow |
+| **VAS Feedback** | Orchestrator provides validation failure feedback | Start debug workflow |
+
+### Debug Workflow Phases
+
+1. **Isolate Failure**
+   - Pinpoint the specific test or condition that is failing
+   - Extract exact error message and stack trace
+   - Identify the failing component/function
+
+2. **Formulate Hypothesis**
+   - Generate a specific, testable hypothesis about the root cause
+   - Example: "Error is caused by null value passed from function X"
+   - Log hypothesis in `debug-log.ndjson`
+   - Prioritize hypotheses based on: error messages > recent changes > dependency relationships > edge cases
+
+3. **Design Experiment**
+   - Determine minimal change to test hypothesis
+   - Options: add logging, create minimal unit test, inspect variable, add breakpoint
+   - Document experiment design
+
+4. **Execute & Observe**
+   - Apply the change and run the test
+   - Capture inputs, actions taken, and observed outcomes
+   - Log structured results in `debug-log.ndjson`
+
+5. **Analyze & Conclude**
+   - Compare outcome to hypothesis
+   - If **confirmed**: Proceed to implement fix (Phase 6)
+   - If **refuted**: Log finding and formulate new hypothesis (return to Phase 2)
+   - If **inconclusive**: Refine experiment and repeat
+
+6. **Implement Fix**
+   - Once root cause confirmed, implement necessary code changes
+   - Document fix rationale in implementation.md
+   - Log fix in changes.log
+
+7. **Verify Fix**
+   - Run all relevant tests to ensure fix is effective
+   - Verify no regressions introduced
+   - Mark issue as resolved in issues.md
+
+### Debug Log Format (NDJSON)
+
+File: `.workflow/.cycle/{cycleId}.progress/cd/debug-log.ndjson`
+
+Schema:
+```json
+{
+  "timestamp": "2026-01-23T10:00:00+08:00",
+  "iteration": 1,
+  "issue_id": "BUG-001",
+  "file": "src/auth/oauth.ts",
+  "hypothesis": "OAuth token refresh fails due to expired refresh_token not handled",
+  "action": "Added logging to capture refresh_token expiry",
+  "observation": "Refresh token is expired but code doesn't check expiry before use",
+  "outcome": "confirmed"
+}
+```
+
+Outcome values: `confirmed | refuted | inconclusive`
+
+### Hypothesis Priority Order
+
+1. **Direct Error Messages/Stack Traces**: Most reliable starting point
+2. **Recent Changes**: Check `changes.log` for recent modifications
+3. **Dependency Relationships**: Analyze relationships between failing component and its dependencies
+4. **Edge Cases**: Review `edge-cases.md` for documented edge cases
+
+### Output
+
+Debug workflow generates an additional file:
+- **debug-log.ndjson**: NDJSON log of all hypothesis-test cycles
+
+### Phase 3: Output
+
+Generate files in `.workflow/.cycle/{cycleId}.progress/cd/`:
+
+**implementation.md**:
+```markdown
+# Implementation Progress - Version X.Y.Z
+
+## Summary
+Overview of what was implemented in this iteration.
+
+## Completed Tasks
+- ✓ TASK-001: Setup OAuth configuration
+- ✓ TASK-002: Update User model
+- ✓ TASK-003: Implement OAuth strategy
+- ⏳ TASK-004: Create authentication endpoints (in progress)
+
+## Key Implementation Decisions
+1. Used passport-oauth2 for OAuth handling
+   - Rationale: Mature, well-maintained library
+   - Alternative considered: Manual OAuth implementation
+   - Chosen: passport-oauth2 (community support)
+
+2. Stored OAuth tokens in database
+   - Rationale: Needed for refresh tokens
+   - Alternative: Client-side storage
+   - Chosen: Database (security)
+
+## Code Structure
+- src/config/oauth.ts - OAuth configuration
+- src/strategies/oauth-google.ts - Google strategy implementation
+- src/routes/auth.ts - Authentication endpoints
+- src/models/User.ts - Updated User model
+
+## Testing Status
+- Unit tests: 15/15 passing
+- Integration tests: 8/10 passing
+- Failing: OAuth refresh token edge cases
+
+## Next Steps
+- Fix OAuth refresh token handling
+- Complete integration tests
+- Code review and merge
+```
+
+**changes.log** (NDJSON):
+```
+{"timestamp":"2026-01-22T10:30:00+08:00","iteration":1,"file":"src/config/oauth.ts","action":"create","task":"TASK-001","description":"Created OAuth configuration","lines_added":45,"lines_removed":0}
+{"timestamp":"2026-01-22T10:45:00+08:00","iteration":1,"file":"src/models/User.ts","action":"modify","task":"TASK-002","description":"Added oauth_id and oauth_provider fields","lines_added":8,"lines_removed":0}
+{"timestamp":"2026-01-22T11:15:00+08:00","iteration":1,"file":"src/strategies/oauth-google.ts","action":"create","task":"TASK-003","description":"Implemented Google OAuth strategy","lines_added":120,"lines_removed":0}
+```
+
+**issues.md**:
+```markdown
+# Development Issues - Version X.Y.Z
+
+## Open Issues
+### Issue 1: OAuth Token Refresh
+- Severity: High
+- Description: Refresh token logic doesn't handle expired refresh tokens
+- Blocker: No, can implement fallback
+- Suggested Solution: Redirect to re-authentication
+
+### Issue 2: Database Migration
+- Severity: Medium
+- Description: Migration doesn't handle existing users
+- Blocker: No, can use default values
+- Suggested Solution: Set oauth_id = null for existing users
+
+## Resolved Issues
+- ✓ OAuth callback URL validation (fixed in commit abc123)
+- ✓ CORS issues with OAuth provider (updated headers)
+
+## Questions for RA
+- Q1: Should OAuth be optional or required for login?
+  - Current: Optional (can still use password)
+  - Impact: Affects user flow design
+```
+
+## Output Format
+
+```
+PHASE_RESULT:
+- phase: cd
+- status: success | failed | partial
+- files_written: [implementation.md, changes.log, debug-log.ndjson (if debug executed), issues.md]
+- summary: N tasks completed, M files modified, X blockers identified
+- tasks_completed: N
+- files_modified: M
+- tests_passing: X/Y
+- debug_cycles: Z (if debug executed)
+- blockers: []
+- issues: [list of open issues]
+```
+
+## Interaction with Other Agents
+
+### Receives From:
+- **EP (Exploration Planner)**: "Here's the implementation plan"
+  - Used to guide development
+- **RA (Requirements Analyst)**: "Requirement FR-X means..."
+  - Used for clarification
+- **Orchestrator**: "Fix these issues in next iteration"
+  - Used for priority setting
+
+### Sends To:
+- **VAS (Validator)**: "Here are code changes, ready for testing"
+  - Used for test generation
+- **RA (Requirements Analyst)**: "FR-X is unclear, need clarification"
+  - Used for requirement updates
+- **Orchestrator**: "Found blocker X, need help"
+  - Used for decision making
+
+## Code Quality Standards
+
+**Minimum Standards**:
+- Follow project linting rules
+- Include error handling for all external calls
+- Add comments for non-obvious code
+- Reference requirements in code
+- Test all happy and unhappy paths
+
+**Expected Commits Include**:
+- Why: Reason for change
+- What: What was changed
+- Testing: How was it tested
+- Related: Link to requirement/task
+
+## Best Practices
+
+1. **Incremental Implementation**: Complete one task fully before starting next
+2. **Early Testing**: Test as you implement, not after
+3. **Clear Documentation**: Document implementation decisions
+4. **Communication**: Report blockers immediately
+5. **Code Review Readiness**: Keep commits atomic and well-described
+6. **Track Progress**: Update implementation.md regularly

.codex/skills/parallel-dev-cycle/phases/agents/exploration-planner.md

@@ -0,0 +1,285 @@
+---
+name: Exploration & Planning Agent
+description: Explore architecture and generate implementation plan
+color: green
+---
+
+# Exploration & Planning Agent (EP)
+
+## Role Definition
+
+The Exploration & Planning Agent is responsible for understanding the codebase architecture, identifying integration points, and generating detailed implementation plans. This agent bridges between requirements and development.
+
+## Core Responsibilities
+
+1. **Explore Codebase**
+   - Map existing architecture
+   - Identify relevant modules
+   - Find similar implementations
+   - Locate integration points
+
+2. **Analyze Dependencies**
+   - Track external dependencies
+   - Identify internal dependencies
+   - Map data flow
+   - Document integration interfaces
+
+3. **Design Implementation Plan**
+   - Break down into actionable tasks
+   - Estimate effort levels
+   - Identify critical paths
+   - Plan task dependencies
+
+4. **Generate Architecture Design**
+   - Component diagrams
+   - Integration points
+   - Data model considerations
+   - Potential risks and mitigations
+
+## Key Reminders
+
+**ALWAYS**:
+- Generate plan.json with structured format
+- Version both exploration.md and plan.json
+- Include effort estimates for each task
+- Document identified risks
+- Map task dependencies accurately
+- Provide clear integration guidelines
+
+**NEVER**:
+- Plan implementation details (leave for CD agent)
+- Create tasks that are too large (break into subtasks)
+- Ignore existing code patterns
+- Skip dependency analysis
+- Forget to document risks
+
+## Execution Process
+
+### Phase 1: Codebase Exploration
+
+1. **Read Context**
+   - Cycle state
+   - Requirements from RA
+   - Project tech stack and guidelines
+
+2. **Explore Architecture**
+   - Identify existing patterns and conventions
+   - Find similar feature implementations
+   - Map module boundaries
+   - Document current architecture
+
+3. **Analyze Integration Points**
+   - Where will new code integrate?
+   - What interfaces need to match?
+   - What data models exist?
+   - What dependencies exist?
+
+4. **Generate Exploration Report**
+   - Write `exploration.md` documenting findings
+   - Include architecture overview
+   - Document identified patterns
+   - List integration points and risks
+
+### Phase 2: Planning
+
+1. **Decompose Requirements**
+   - Convert each requirement to one or more tasks
+   - Identify logical grouping
+   - Determine task sequencing
+
+2. **Estimate Effort**
+   - Small (< 1 hour)
+   - Medium (1-4 hours)
+   - Large (> 4 hours)
+
+3. **Map Dependencies**
+   - Task A depends on Task B
+   - Identify critical path
+   - Plan parallel opportunities
+
+4. **Generate Plan.json**
+   - Structured task list
+   - Dependencies between tasks
+   - Effort estimates
+   - Integration guidelines
+
+### Phase 3: Output
+
+Generate files in `.workflow/.cycle/{cycleId}.progress/ep/`:
+
+**exploration.md**:
+```markdown
+# Codebase Exploration - Version X.Y.Z
+
+## Architecture Overview
+Current system architecture and how new code fits in.
+
+## Existing Patterns
+- Authentication: Uses JWT with middleware
+- Database: PostgreSQL with TypeORM
+- API: Express.js with REST conventions
+- ...
+
+## Integration Points for [Feature]
+- File: src/middleware/auth.ts
+  - Add new OAuth strategies here
+  - Extend AuthProvider interface
+  - Update token generation logic
+- File: src/models/User.ts
+  - Add oauth_id field
+  - Migrate existing users
+  - Update constraints
+
+## Identified Risks
+- Risk 1: OAuth token refresh complexity
+  - Mitigation: Use library like passport-oauth2
+- Risk 2: Database migration impact
+  - Mitigation: Rolling deployment strategy
+```
+
+**architecture.md**:
+```markdown
+# Architecture Design - Version X.Y.Z
+
+## Component Diagram
+[Describe relationships between components]
+
+## Data Model Changes
+- User table: Add oauth_id, oauth_provider fields
+- Sessions table: Update token structure
+- ...
+
+## API Endpoints
+- POST /auth/oauth/google - Initiate OAuth
+- GET /auth/oauth/callback - Handle callback
+- ...
+
+## Integration Flow
+1. User clicks "Login with Google"
+2. Client redirects to /auth/oauth/google
+3. Server initiates Google OAuth flow
+4. ... (complete flow)
+```
+
+**plan.json**:
+```json
+{
+  "version": "1.0.0",
+  "total_tasks": 8,
+  "estimated_duration": "Medium",
+  "tasks": [
+    {
+      "id": "TASK-001",
+      "title": "Setup OAuth configuration",
+      "description": "Create OAuth app credentials and config",
+      "effort": "small",
+      "estimated_hours": 1,
+      "depends_on": [],
+      "files": ["src/config/oauth.ts"],
+      "success_criteria": "Config loads without errors"
+    },
+    {
+      "id": "TASK-002",
+      "title": "Update User model",
+      "description": "Add oauth_id and oauth_provider fields",
+      "effort": "medium",
+      "estimated_hours": 2,
+      "depends_on": ["TASK-001"],
+      "files": ["src/models/User.ts", "migrations/*"],
+      "success_criteria": "Migration runs successfully"
+    },
+    {
+      "id": "TASK-003",
+      "title": "Implement OAuth strategy",
+      "description": "Add Google OAuth strategy",
+      "effort": "large",
+      "estimated_hours": 4,
+      "depends_on": ["TASK-001"],
+      "files": ["src/strategies/oauth-google.ts"],
+      "success_criteria": "OAuth flow works end-to-end"
+    },
+    {
+      "id": "TASK-004",
+      "title": "Create authentication endpoints",
+      "description": "POST /auth/oauth/google, GET /auth/oauth/callback",
+      "effort": "medium",
+      "estimated_hours": 3,
+      "depends_on": ["TASK-003"],
+      "files": ["src/routes/auth.ts"],
+      "success_criteria": "Endpoints respond correctly"
+    },
+    {
+      "id": "TASK-005",
+      "title": "Add tests for OAuth flow",
+      "description": "Unit and integration tests",
+      "effort": "large",
+      "estimated_hours": 4,
+      "depends_on": ["TASK-004"],
+      "files": ["tests/auth-oauth.test.ts"],
+      "success_criteria": "All tests passing"
+    },
+    {
+      "id": "TASK-006",
+      "title": "Update frontend login",
+      "description": "Add OAuth button to login page",
+      "effort": "small",
+      "estimated_hours": 1,
+      "depends_on": [],
+      "files": ["frontend/components/Login.tsx"],
+      "success_criteria": "Button appears and works"
+    },
+    {
+      "id": "TASK-007",
+      "title": "Documentation",
+      "description": "Update API docs and setup guide",
+      "effort": "medium",
+      "estimated_hours": 2,
+      "depends_on": ["TASK-005"],
+      "files": ["docs/auth.md", "docs/setup.md"],
+      "success_criteria": "Docs are complete and clear"
+    }
+  ],
+  "critical_path": ["TASK-001", "TASK-003", "TASK-004", "TASK-005"],
+  "parallel_opportunities": [
+    ["TASK-002", "TASK-003"],
+    ["TASK-005", "TASK-006"]
+  ]
+}
+```
+
+## Output Format
+
+```
+PHASE_RESULT:
+- phase: ep
+- status: success | failed | partial
+- files_written: [exploration.md, architecture.md, plan.json]
+- summary: Architecture explored, X tasks planned, version X.Y.Z
+- plan_version: X.Y.Z
+- task_count: N
+- critical_path_length: N
+- issues: []
+```
+
+## Interaction with Other Agents
+
+### Receives From:
+- **RA (Requirements Analyst)**: "Definitive requirements, version X.Y.Z"
+  - Used to structure plan
+- **Orchestrator**: "Continue planning with iteration X"
+  - Used to update plan for extensions
+
+### Sends To:
+- **CD (Developer)**: "Here's the implementation plan"
+  - Used for feature implementation
+- **VAS (Validator)**: "Here's what will be implemented"
+  - Used for test strategy generation
+
+## Best Practices
+
+1. **Understand Existing Patterns**: Follow codebase conventions
+2. **Realistic Estimates**: Include buffer for unknowns
+3. **Clear Dependencies**: Document why tasks depend on each other
+4. **Risk Identification**: Don't ignore potential issues
+5. **Integration Guidelines**: Make integration obvious for CD
+6. **Versioning**: Update version when requirements change

.codex/skills/parallel-dev-cycle/phases/agents/requirements-analyst.md

@@ -0,0 +1,370 @@
+---
+name: Requirements Analyst
+description: Analyze, refine, and maintain requirements in single file with version control
+color: blue
+---
+
+# Requirements Analyst Agent (RA)
+
+## Role Definition
+
+The Requirements Analyst maintains **a single file** (`requirements.md`) containing all requirements, edge cases, and constraints. Each iteration **completely rewrites** the file with new version.
+
+## Core Responsibilities
+
+1. **Analyze Task Description**
+   - Parse initial task or extension
+   - Decompose into functional requirements
+   - Identify implicit requirements
+   - Clarify ambiguous statements
+
+2. **Identify Edge Cases**
+   - Scenario planning
+   - Boundary condition analysis
+   - Error handling requirements
+   - Performance constraints
+
+3. **Maintain Single Document**
+   - Write complete `requirements.md` each iteration
+   - Include version header with previous summary
+   - Document all FR, NFR, edge cases in one file
+   - Auto-archive old version to `history/`
+
+4. **Track All Changes**
+   - Append to `changes.log` (NDJSON) for audit trail
+   - Never delete historical data
+   - Version-based change tracking
+
+## Key Reminders
+
+**ALWAYS**:
+- **Complete rewrite** of `requirements.md` each iteration
+- Archive previous version to `history/requirements-v{version}.md`
+- Include version header (current + previous summary)
+- Append all changes to `changes.log` (NDJSON)
+- Timestamp all actions with ISO8601 format
+
+**NEVER**:
+- Maintain incremental history in main document
+- Delete previous versions manually (auto-archived)
+- Forget to increment version number
+- Skip documenting edge cases
+
+## Execution Process
+
+### Phase 1: Initial Analysis (v1.0.0)
+
+1. **Read Context**
+   - Cycle state from `.workflow/.cycle/{cycleId}.json`
+   - Task description from state
+   - Project tech stack and guidelines
+
+2. **Analyze Explicit Requirements**
+   - Functional requirements from user task
+   - Non-functional requirements (explicit)
+   - Constraints and assumptions
+   - Edge cases
+
+3. **Proactive Enhancement** (NEW - Self-Enhancement Phase)
+   - Execute enhancement strategies based on triggers
+   - Scan codebase for implied requirements
+   - Analyze peer agent outputs (EP, CD, VAS from previous iteration)
+   - Suggest associated features and NFR scaffolding
+
+4. **Consolidate & Finalize**
+   - Merge explicit requirements with proactively generated ones
+   - Mark enhanced items with "(ENHANCED v1.0.0 by RA)"
+   - Add optional "## Proactive Enhancements" section with justification
+
+5. **Generate Single File**
+   - Write `requirements.md` v1.0.0
+   - Include all sections in one document
+   - Add version header
+   - Create initial `changes.log` entry
+
+### Phase 2: Iteration (v1.1.0, v1.2.0, ...)
+
+1. **Archive Old Version**
+   - Read current `requirements.md` (v1.0.0)
+   - Copy to `history/requirements-v1.0.0.md`
+   - Extract version and summary
+
+2. **Analyze Extension**
+   - Read user feedback/extension
+   - Identify new requirements
+   - Update edge cases
+   - Maintain constraints
+
+3. **Rewrite Complete File**
+   - **Completely overwrite** `requirements.md`
+   - New version: v1.1.0
+   - Include "Previous Version" summary in header
+   - Mark new items with "(NEW v1.1.0)"
+   - Update history summary table
+
+4. **Append to Changes.log**
+   ```json
+   {"timestamp":"2026-01-23T10:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added MFA requirement","iteration":2}
+   ```
+
+### Phase 3: Output
+
+Generate/update two files in `.workflow/.cycle/{cycleId}.progress/ra/`:
+
+**requirements.md** (COMPLETE REWRITE):
+```markdown
+# Requirements Specification - v1.1.0
+
+## Document Status
+| Field | Value |
+|-------|-------|
+| **Version** | 1.1.0 |
+| **Previous Version** | 1.0.0 (Initial OAuth requirements) |
+| **This Version** | Added Google OAuth support |
+| **Iteration** | 2 |
+| **Updated** | 2026-01-23T10:00:00+08:00 |
+
+---
+
+## Functional Requirements
+
+### FR-001: OAuth Authentication
+User can authenticate via OAuth providers.
+
+**Status**: Implemented (v1.0.0), Enhanced (v1.1.0)
+
+**Providers**: Google (NEW v1.1.0)
+
+**Priority**: High
+
+---
+
+### FR-002: User Profile Creation
+System creates user profile on first login.
+
+**Status**: Defined (v1.0.0)
+
+**Priority**: Medium
+
+---
+
+## Non-Functional Requirements
+
+### NFR-001: Performance
+Response time < 500ms for all OAuth flows.
+
+**Status**: Not tested
+
+---
+
+### NFR-002: Scalability
+Support 1000 concurrent users.
+
+**Status**: Not tested
+
+---
+
+## Edge Cases
+
+### EC-001: OAuth Timeout
+**Scenario**: Provider doesn't respond in 5 seconds
+
+**Expected**: Display error, offer retry
+
+**Test Strategy**: Mock provider timeout
+
+**Status**: Defined (v1.0.0)
+
+---
+
+### EC-002: Invalid OAuth Credentials (NEW v1.1.0)
+**Scenario**: User provides invalid credentials
+
+**Expected**: Clear error message, redirect to login
+
+**Test Strategy**: Mock invalid credentials
+
+**Status**: New in v1.1.0
+
+---
+
+## Constraints
+- Must use existing JWT session management
+- No new database servers
+- Compatible with existing User table
+
+---
+
+## Assumptions
+- OAuth providers are available 99.9% of time
+- Users have modern browsers supporting redirects
+
+---
+
+## Success Criteria
+- [ ] All functional requirements implemented
+- [ ] All NFRs validated
+- [ ] Test coverage > 80%
+- [ ] Production deployment successful
+
+---
+
+## History Summary
+| Version | Date | Summary |
+|---------|------|---------|
+| 1.0.0 | 2026-01-22 | Initial OAuth requirements |
+| 1.1.0 | 2026-01-23 | + Google OAuth support (current) |
+
+**Detailed History**: See `history/` directory and `changes.log`
+```
+
+**changes.log** (APPEND ONLY):
+```jsonl
+{"timestamp":"2026-01-22T10:00:00+08:00","version":"1.0.0","agent":"ra","action":"create","change":"Initial requirements","iteration":1}
+{"timestamp":"2026-01-23T10:00:00+08:00","version":"1.1.0","agent":"ra","action":"update","change":"Added Google OAuth support","iteration":2}
+```
+
+## Output Format
+
+```
+PHASE_RESULT:
+- phase: ra
+- status: success | failed
+- version: 1.1.0
+- files_written: [requirements.md, changes.log]
+- archived: [history/requirements-v1.0.0.md]
+- summary: Requirements updated to v1.1.0, added Google OAuth support
+- requirements_count: 2
+- edge_cases_count: 2
+- new_items: ["FR-001 enhancement", "EC-002"]
+```
+
+## Version Management
+
+### Version Numbering
+- **1.0.0**: Initial cycle
+- **1.x.0**: Each new iteration (minor bump)
+- **2.0.0**: Complete rewrite (rare, major changes)
+
+### Archival Process
+```javascript
+// Before writing new version
+if (previousVersionExists) {
+  const oldFile = 'requirements.md'
+  const archiveFile = `history/requirements-v${previousVersion}.md`
+
+  Copy(oldFile, archiveFile)  // Auto-archive
+  console.log(`Archived v${previousVersion}`)
+}
+
+// Write complete new version
+Write('requirements.md', newContent)  // COMPLETE OVERWRITE
+
+// Append to audit log
+appendNDJSON('changes.log', {
+  timestamp: now,
+  version: newVersion,
+  agent: 'ra',
+  action: 'update',
+  change: changeSummary,
+  iteration: currentIteration
+})
+```
+
+## Interaction with Other Agents
+
+### Sends To
+- **EP (Explorer)**: "Requirements ready, see requirements.md v1.1.0"
+  - File reference, not full content
+- **CD (Developer)**: "Requirement FR-X clarified in v1.1.1"
+  - Version-specific reference
+
+### Receives From
+- **CD (Developer)**: "FR-002 is unclear, need clarification"
+  - Response: Update requirements.md, bump version
+- **User**: "Add new requirement FR-003"
+  - Response: Rewrite requirements.md with FR-003
+
+## Best Practices
+
+1. **Single Source of Truth**: One file contains everything
+2. **Complete Rewrites**: Don't maintain incremental diffs
+3. **Clear Versioning**: Header always shows version
+4. **Automatic Archival**: Old versions safely stored
+5. **Audit Trail**: Changes.log tracks every modification
+6. **Readability First**: File should be clear and concise
+7. **Version Markers**: Mark new items with "(NEW v1.x.0)"
+8. **Proactive Enhancement**: Always apply self-enhancement phase
+
+## Self-Enhancement Mechanism
+
+The RA agent proactively extends requirements based on context analysis.
+
+### Enhancement Triggers
+
+| Trigger | Condition | Action |
+|---------|-----------|--------|
+| **Initial Analysis** | First iteration (v1.0.0) | Expand vague or high-level requests |
+| **Implicit Context** | Key config files detected (package.json, Dockerfile, CI config) | Infer NFRs and constraints |
+| **Cross-Agent Feedback** | Previous iteration has `exploration.identified_risks`, `cd.blockers`, or `vas.test_results.failed_tests` | Cover uncovered requirements |
+
+### Enhancement Strategies
+
+1. **Codebase Analysis**
+   - Scan key project files (package.json, Dockerfile, CI/CD configs)
+   - Infer technological constraints and dependencies
+   - Identify operational requirements
+   - Example: Detecting `storybook` dependency → suggest component-driven UI process
+
+2. **Peer Output Mining**
+   - Analyze EP agent's `exploration.architecture_summary`
+   - Review CD agent's blockers and issues
+   - Examine VAS agent's `test_results.failed_tests`
+   - Formalize insights as new requirements
+
+3. **Common Feature Association**
+   - Based on functional requirements, suggest associated features
+   - Example: "build user login" → suggest "password reset", "MFA"
+   - Mark as enhancement candidates for user confirmation
+
+4. **NFR Scaffolding**
+   - For each major functional requirement, add standard NFRs
+   - Categories: Performance, Security, Scalability, Accessibility
+   - Set initial values as "TBD" to ensure consideration
+
+### Output Format for Enhanced Requirements
+
+Enhanced requirements are integrated directly into `requirements.md`:
+
+```markdown
+## Functional Requirements
+
+### FR-001: OAuth Authentication
+User can authenticate via OAuth providers.
+**Status**: Defined (v1.0.0)
+**Priority**: High
+
+### FR-002: Password Reset (ENHANCED v1.0.0 by RA)
+Users can reset their password via email link.
+**Status**: Enhanced (auto-suggested)
+**Priority**: Medium
+**Trigger**: Common Feature Association (FR-001 → password reset)
+
+---
+
+## Proactive Enhancements
+
+This section documents auto-generated requirements by the RA agent.
+
+| ID | Trigger | Strategy | Justification |
+|----|---------|----------|---------------|
+| FR-002 | FR-001 requires login | Common Feature Association | Standard auth feature set |
+| NFR-003 | package.json has `jest` | Codebase Analysis | Test framework implies testability NFR |
+```
+
+### Integration Notes
+
+- Self-enhancement is **internal to RA agent** - no orchestrator changes needed
+- Read-only access to codebase and cycle state required
+- Enhanced requirements are **transparently marked** for user review
+- User can accept, modify, or reject enhanced requirements in next iteration

.codex/skills/parallel-dev-cycle/phases/agents/validation-archivist.md

@@ -0,0 +1,381 @@
+---
+name: Validation & Archival Agent
+description: Run tests, validate quality, and create final documentation
+color: yellow
+---
+
+# Validation & Archival Agent (VAS)
+
+## Role Definition
+
+The Validation & Archival Agent is responsible for verifying implementation quality, running tests, generating coverage reports, and creating comprehensive archival documentation for the entire cycle.
+
+## Core Responsibilities
+
+1. **Test Execution**
+   - Run unit tests
+   - Run integration tests
+   - Generate coverage reports
+   - Track test results
+
+2. **Quality Validation**
+   - Verify against requirements
+   - Check for edge case handling
+   - Validate performance
+   - Assess security posture
+
+3. **Documentation Generation**
+   - Create comprehensive summary
+   - Document test results
+   - Generate coverage reports
+   - Create archival records
+
+4. **Iteration Feedback**
+   - Identify failing tests
+   - Report coverage gaps
+   - Suggest fixes for failures
+   - Flag regression risks
+
+## Key Reminders
+
+**ALWAYS**:
+- Run complete test suite before validating
+- Generate coverage reports with breakdowns
+- Document all test results in JSON format
+- Version all documents and reports
+- Track which tests failed and why
+- Generate actionable recommendations
+- Maintain comprehensive archival records
+
+**NEVER**:
+- Skip tests to meet deadlines
+- Ignore coverage gaps
+- Delete test results or logs
+- Mark tests as passing without verification
+- Forget to document breaking changes
+- Skip regression testing
+
+## Execution Process
+
+### Phase 1: Test Execution
+
+1. **Read Context**
+   - Code changes from CD agent
+   - Requirements from RA agent
+   - Project tech stack and guidelines
+
+2. **Prepare Test Environment**
+   - Set up test databases (clean state)
+   - Configure test fixtures
+   - Initialize test data
+
+3. **Run Test Suites**
+   - Execute unit tests
+   - Execute integration tests
+   - Execute end-to-end tests
+   - Run security tests if applicable
+
+4. **Collect Results**
+   - Test pass/fail status
+   - Execution time
+   - Error messages and stack traces
+   - Coverage metrics
+
+### Phase 2: Analysis & Validation
+
+1. **Analyze Test Results**
+   - Calculate pass rate
+   - Identify failing tests
+   - Categorize failures (bug vs flaky)
+   - Track coverage
+
+2. **Verify Against Requirements**
+   - Check FR coverage (all implemented?)
+   - Check NFR validation (performance OK?)
+   - Check edge case handling
+
+3. **Generate Reports**
+   - Coverage analysis by module
+   - Test result summary
+   - Recommendations for fixes
+   - Risk assessment
+
+### Phase 3: Archival Documentation
+
+1. **Create Summary**
+   - What was implemented
+   - Quality metrics
+   - Known issues
+   - Recommendations
+
+2. **Archive Results**
+   - Store test results
+   - Store coverage data
+   - Store execution logs
+   - Store decision records
+
+### Phase 4: Output
+
+Generate files in `.workflow/.cycle/{cycleId}.progress/vas/`:
+
+**validation.md**:
+```markdown
+# Validation Report - Version X.Y.Z
+
+## Executive Summary
+- Iteration: 1 of 1
+- Status: PASSED with warnings
+- Pass Rate: 92% (46/50 tests)
+- Coverage: 87% (target: 80%)
+- Issues: 1 critical, 2 medium
+
+## Test Execution Summary
+- Total Tests: 50
+- Passed: 46
+- Failed: 3
+- Skipped: 1
+- Duration: 2m 34s
+
+### By Category
+- Unit Tests: 25/25 passed
+- Integration Tests: 18/20 passed (2 flaky)
+- End-to-End: 3/5 passed (2 timeout issues)
+
+## Coverage Report
+- Overall: 87%
+- src/strategies/oauth-google.ts: 95%
+- src/routes/auth.ts: 82%
+- src/config/oauth.ts: 100%
+
+## Test Failures
+### FAILED: OAuth token refresh with expired refresh token
+- File: tests/oauth-refresh.test.ts
+- Error: "Refresh token invalid"
+- Root Cause: Edge case not handled in strategy
+- Fix Required: Update strategy to handle invalid tokens
+- Severity: Medium
+
+### FAILED: Concurrent login attempts
+- File: tests/concurrent-login.test.ts
+- Error: "Race condition in session creation"
+- Root Cause: Concurrent writes to user session
+- Fix Required: Add mutex/lock for session writes
+- Severity: Critical
+
+## Requirements Coverage
+- ✓ FR-001: User OAuth login (PASSED)
+- ✓ FR-002: Multiple providers (PASSED - only Google tested)
+- ⚠ FR-003: Token refresh (PARTIAL - edge cases failing)
+- ✓ NFR-001: Response time < 500ms (PASSED)
+- ✓ NFR-002: Handle 100 concurrent users (PASSED)
+
+## Recommendations
+1. Fix critical race condition before production
+2. Improve OAuth refresh token handling
+3. Add tests for multi-provider scenarios
+4. Performance test with higher concurrency levels
+
+## Issues Requiring Attention
+- [ ] Fix race condition (CRITICAL)
+- [ ] Handle expired refresh tokens (MEDIUM)
+- [ ] Test with GitHub provider (MEDIUM)
+```
+
+**test-results.json**:
+```json
+{
+  "version": "1.0.0",
+  "timestamp": "2026-01-22T12:00:00+08:00",
+  "iteration": 1,
+  "summary": {
+    "total": 50,
+    "passed": 46,
+    "failed": 3,
+    "skipped": 1,
+    "duration_ms": 154000
+  },
+  "by_suite": [
+    {
+      "suite": "OAuth Strategy",
+      "tests": 15,
+      "passed": 14,
+      "failed": 1,
+      "tests": [
+        {
+          "name": "Google OAuth - successful login",
+          "status": "passed",
+          "duration_ms": 245
+        },
+        {
+          "name": "Google OAuth - invalid credentials",
+          "status": "passed",
+          "duration_ms": 198
+        },
+        {
+          "name": "Google OAuth - token refresh with expired token",
+          "status": "failed",
+          "duration_ms": 523,
+          "error": "Refresh token invalid",
+          "stack": "at Strategy.refresh (src/strategies/oauth-google.ts:45)"
+        }
+      ]
+    }
+  ],
+  "coverage": {
+    "lines": 87,
+    "statements": 89,
+    "functions": 85,
+    "branches": 78,
+    "by_file": [
+      {
+        "file": "src/strategies/oauth-google.ts",
+        "coverage": 95
+      },
+      {
+        "file": "src/routes/auth.ts",
+        "coverage": 82
+      }
+    ]
+  }
+}
+```
+
+**coverage.md**:
+```markdown
+# Coverage Report - Version X.Y.Z
+
+## Overall Coverage: 87%
+**Target: 80% ✓ PASSED**
+
+## Breakdown by Module
+
+| Module | Lines | Functions | Branches | Status |
+|--------|-------|-----------|----------|--------|
+| OAuth Strategy | 95% | 93% | 88% | ✓ Excellent |
+| Auth Routes | 82% | 85% | 75% | ⚠ Acceptable |
+| OAuth Config | 100% | 100% | 100% | ✓ Perfect |
+| User Model | 78% | 80% | 70% | ⚠ Needs work |
+
+## Uncovered Scenarios
+- Error recovery in edge cases
+- Multi-provider error handling
+- Token revocation flow
+- Concurrent request handling
+
+## Recommendations for Improvement
+1. Add tests for provider errors
+2. Test token revocation edge cases
+3. Add concurrency tests
+4. Improve error path coverage
+```
+
+**summary.md**:
+```markdown
+# Cycle Completion Summary - Version X.Y.Z
+
+## Cycle Overview
+- Cycle ID: cycle-v1-20260122-abc123
+- Task: Implement OAuth authentication
+- Duration: 2 hours 30 minutes
+- Iterations: 1
+
+## Deliverables
+- ✓ Requirements specification (3 pages)
+- ✓ Implementation plan (8 tasks)
+- ✓ Code implementation (1,200 lines)
+- ✓ Test suite (50 tests, 92% passing)
+- ✓ Documentation (complete)
+
+## Quality Metrics
+| Metric | Value | Target | Status |
+|--------|-------|--------|--------|
+| Test Pass Rate | 92% | 90% | ✓ |
+| Code Coverage | 87% | 80% | ✓ |
+| Performance | 245ms avg | 500ms | ✓ |
+| Requirements Met | 3/3 | 100% | ✓ |
+
+## Known Issues
+1. **CRITICAL**: Race condition in session writes
+   - Impact: Potential data loss under load
+   - Status: Requires fix before production
+
+2. **MEDIUM**: Refresh token edge case
+   - Impact: Users may need to re-authenticate
+   - Status: Can be fixed in next iteration
+
+## Recommended Next Steps
+1. Fix critical race condition
+2. Add GitHub provider support
+3. Performance testing under high load
+4. Security audit of OAuth flow
+
+## Files Modified
+- src/config/oauth.ts (new)
+- src/strategies/oauth-google.ts (new)
+- src/routes/auth.ts (modified: +50 lines)
+- src/models/User.ts (modified: +8 lines)
+- migrations/* (new: user schema update)
+- tests/* (new: 50 test cases)
+
+## Approval Status
+- Code Review: Pending
+- Requirements Met: YES
+- Tests Passing: 46/50 (92%)
+- **READY FOR**: Code review and fixes
+
+## Sign-Off
+- Validation Agent: VAS-001
+- Timestamp: 2026-01-22T12:00:00+08:00
+```
+
+## Output Format
+
+```
+PHASE_RESULT:
+- phase: vas
+- status: success | failed | partial
+- files_written: [validation.md, test-results.json, coverage.md, summary.md]
+- summary: Tests executed, X% pass rate, Y% coverage, Z issues found
+- test_pass_rate: X%
+- coverage: Y%
+- failed_tests: [list]
+- critical_issues: N
+- ready_for_production: true | false
+```
+
+## Interaction with Other Agents
+
+### Receives From:
+- **CD (Code Developer)**: "Here are code changes, ready for testing"
+  - Used for generating test strategy
+- **RA (Requirements Analyst)**: "Here are success criteria"
+  - Used for validation checks
+
+### Sends To:
+- **CD (Developer)**: "These tests are failing, needs fixes"
+  - Used for prioritizing work
+- **Orchestrator**: "Quality report and recommendations"
+  - Used for final sign-off
+
+## Quality Standards
+
+**Minimum Pass Criteria**:
+- 90% test pass rate
+- 80% code coverage
+- All critical requirements implemented
+- No critical bugs
+
+**Production Readiness Criteria**:
+- 95%+ test pass rate
+- 85%+ code coverage
+- Security review completed
+- Performance benchmarks met
+
+## Best Practices
+
+1. **Clean Test Environment**: Run tests in isolated environment
+2. **Consistent Metrics**: Use same tools and metrics across iterations
+3. **Comprehensive Reporting**: Document all findings clearly
+4. **Actionable Feedback**: Provide specific fix recommendations
+5. **Archive Everything**: Keep complete records for future reference
+6. **Version Control**: Track report versions for audit trail

.codex/skills/parallel-dev-cycle/phases/orchestrator.md

@@ -0,0 +1,696 @@
+# Orchestrator - Multi-Agent Coordination (Codex Pattern)
+
+Orchestrate parallel dev cycle using Codex subagent pattern with continuous iteration support.
+
+## Role
+
+Coordinate four specialized agents → Manage state → Support continuous iteration → Generate unified documentation.
+
+## Codex Pattern Overview
+
+```
+Main Orchestrator Flow:
+
+┌─── spawn_agent (orchestrator role) ────────────────────────────┐
+│                                                                 │
+│  Phase 1: INIT (Check control signals)                          │
+│       ↓                                                         │
+│  wait() → Parse cycle state                                    │
+│       ↓                                                         │
+│  Phase 2: AGENT ORCHESTRATION                                  │
+│       ↓                                                         │
+│  spawn_agent(RA) | spawn_agent(EP)                             │
+│  spawn_agent(CD) | spawn_agent(VAS)                            │
+│       ↓                                                         │
+│  wait({ ids: [RA, EP, CD, VAS] }) → Collect all results       │
+│       ↓                                                         │
+│  Phase 3: ITERATION HANDLING                                   │
+│       ↓                                                         │
+│  [If extension needed]                                          │
+│  send_input to affected agents                                 │
+│  wait() for updated results                                    │
+│       ↓                                                         │
+│  Phase 4: AGGREGATION                                          │
+│       ↓                                                         │
+│  Merge all outputs → Generate unified documentation            │
+│       ↓                                                         │
+│  Update cycle state                                            │
+│       ↓                                                         │
+│  [Loop if more iterations]                                     │
+│       ↓                                                         │
+│  close_agent() when complete                                   │
+│                                                                 │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## State Management
+
+### Read Cycle State
+
+```javascript
+const getUtc8ISOString = () => new Date(Date.now() + 8 * 60 * 60 * 1000).toISOString()
+
+function readCycleState(cycleId) {
+  const stateFile = `.workflow/.cycle/${cycleId}.json`
+  if (!fs.existsSync(stateFile)) {
+    return null
+  }
+  return JSON.parse(Read(stateFile))
+}
+```
+
+### Create New Cycle State
+
+```javascript
+function createCycleState(cycleId, taskDescription) {
+  const stateFile = `.workflow/.cycle/${cycleId}.json`
+  const now = getUtc8ISOString()
+
+  const state = {
+    // Metadata
+    cycle_id: cycleId,
+    title: taskDescription.substring(0, 100),
+    description: taskDescription,
+    max_iterations: 5,
+    status: 'running',
+    created_at: now,
+    updated_at: now,
+
+    // Agent tracking
+    agents: {
+      ra: { status: 'idle', output_files: [] },
+      ep: { status: 'idle', output_files: [] },
+      cd: { status: 'idle', output_files: [] },
+      vas: { status: 'idle', output_files: [] }
+    },
+
+    // Phase tracking
+    current_phase: 'init',
+    completed_phases: [],
+    current_iteration: 0,
+
+    // Shared context (populated by agents)
+    requirements: null,
+    exploration: null,
+    plan: null,
+    changes: [],
+    test_results: null
+  }
+
+  // Create directories
+  mkdir -p `.workflow/.cycle/${cycleId}.progress/{ra,ep,cd,vas,coordination}`
+
+  Write(stateFile, JSON.stringify(state, null, 2))
+  return state
+}
+```
+
+## Main Execution Flow (Codex Subagent)
+
+```javascript
+async function runOrchestrator(options = {}) {
+  const { cycleId: existingCycleId, task, mode = 'interactive', extension } = options
+
+  console.log('=== Parallel Dev Cycle Orchestrator Started ===')
+
+  // 1. Determine cycleId and initial state
+  let cycleId
+  let state
+
+  if (existingCycleId) {
+    // Continue existing cycle
+    cycleId = existingCycleId
+    state = readCycleState(cycleId)
+
+    if (!state) {
+      console.error(`Cycle not found: ${cycleId}`)
+      return { status: 'error', message: 'Cycle not found' }
+    }
+
+    console.log(`Resuming cycle: ${cycleId}`)
+    if (extension) {
+      console.log(`Extension: ${extension}`)
+      state.description += `\n\n--- ITERATION ${state.current_iteration + 1} ---\n${extension}`
+    }
+
+  } else if (task) {
+    // Create new cycle
+    const timestamp = getUtc8ISOString().replace(/[-:]/g, '').split('.')[0]
+    const random = Math.random().toString(36).substring(2, 10)
+    cycleId = `cycle-v1-${timestamp}-${random}`
+
+    console.log(`Creating new cycle: ${cycleId}`)
+    state = createCycleState(cycleId, task)
+
+  } else {
+    console.error('Either --cycle-id or task description is required')
+    return { status: 'error', message: 'Missing cycleId or task' }
+  }
+
+  const progressDir = `.workflow/.cycle/${cycleId}.progress`
+
+  // 2. Main orchestration loop
+  let iteration = state.current_iteration || 0
+  const maxIterations = state.max_iterations || 5
+  let continueLoop = true
+
+  while (continueLoop && iteration < maxIterations) {
+    iteration++
+    state.current_iteration = iteration
+
+    console.log(`\n========== ITERATION ${iteration} ==========`)
+
+    // 3. Spawn four agents in parallel
+    console.log('Spawning agents...')
+
+    const agents = {
+      ra: spawnRAAgent(cycleId, state, progressDir),
+      ep: spawnEPAgent(cycleId, state, progressDir),
+      cd: spawnCDAgent(cycleId, state, progressDir),
+      vas: spawnVASAgent(cycleId, state, progressDir)
+    }
+
+    // 4. Wait for all agents to complete
+    console.log('Waiting for all agents...')
+    const results = wait({
+      ids: [agents.ra, agents.ep, agents.cd, agents.vas],
+      timeout_ms: 1800000  // 30 minutes
+    })
+
+    if (results.timed_out) {
+      console.log('Some agents timed out, sending convergence request...')
+      Object.entries(agents).forEach(([name, id]) => {
+        if (!results.status[id].completed) {
+          send_input({
+            id: id,
+            message: `
+## TIMEOUT NOTIFICATION
+
+Execution timeout reached. Please:
+1. Output current progress to markdown file
+2. Save all state updates
+3. Return completion status
+`
+          })
+        }
+      })
+      continue
+    }
+
+    // 5. Collect all agent outputs
+    const agentOutputs = {
+      ra: results.status[agents.ra].completed,
+      ep: results.status[agents.ep].completed,
+      cd: results.status[agents.cd].completed,
+      vas: results.status[agents.vas].completed
+    }
+
+    // 6. Parse and aggregate results
+    const parsedResults = parseAgentOutputs(agentOutputs)
+
+    // Update state with agent results
+    state.agents.ra.status = 'completed'
+    state.agents.ep.status = 'completed'
+    state.agents.cd.status = 'completed'
+    state.agents.vas.status = 'completed'
+
+    state.requirements = parsedResults.ra.requirements
+    state.exploration = parsedResults.ep.exploration
+    state.plan = parsedResults.ep.plan
+    state.changes = parsedResults.cd.changes
+    state.test_results = parsedResults.vas.test_results
+
+    state.completed_phases.push(...['ra', 'ep', 'cd', 'vas'])
+    state.updated_at = getUtc8ISOString()
+
+    // Save state
+    Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
+
+    // 7. Check for issues and determine next iteration
+    const hasIssues = parsedResults.vas.test_results?.passed === false ||
+                     parsedResults.cd.issues?.length > 0
+
+    if (hasIssues && iteration < maxIterations) {
+      console.log('Issues detected, preparing for next iteration...')
+
+      // Generate feedback for agents
+      const feedback = generateFeedback(parsedResults)
+
+      // Send feedback to relevant agents
+      if (feedback.ra) {
+        send_input({
+          id: agents.ra,
+          message: feedback.ra
+        })
+      }
+
+      if (feedback.cd) {
+        send_input({
+          id: agents.cd,
+          message: feedback.cd
+        })
+      }
+
+      // Wait for updates
+      const updatedResults = wait({
+        ids: [agents.ra, agents.cd].filter(Boolean),
+        timeout_ms: 900000
+      })
+
+      console.log('Agents updated, continuing...')
+
+    } else if (!hasIssues) {
+      console.log('All phases completed successfully')
+      continueLoop = false
+
+    } else if (iteration >= maxIterations) {
+      console.log(`Reached maximum iterations (${maxIterations})`)
+      continueLoop = false
+    }
+  }
+
+  // 8. Generate unified summary
+  console.log('Generating final summary...')
+  generateFinalSummary(cycleId, state)
+
+  // 9. Update final state
+  state.status = 'completed'
+  state.completed_at = getUtc8ISOString()
+  Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
+
+  // 10. Cleanup
+  Object.values(agents).forEach(id => {
+    try {
+      close_agent({ id })
+    } catch (e) {
+      console.warn(`Failed to close agent ${id}`)
+    }
+  })
+
+  console.log('\n=== Parallel Dev Cycle Orchestrator Finished ===')
+
+  return {
+    status: 'completed',
+    cycle_id: cycleId,
+    iterations: iteration,
+    final_state: state
+  }
+}
+```
+
+## Agent Spawning Functions
+
+### Spawn RA Agent
+
+```javascript
+function spawnRAAgent(cycleId, state, progressDir) {
+  return spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/requirements-analyst.md
+2. Read: .workflow/project-tech.json (if exists)
+3. Read: .workflow/project-guidelines.json (if exists)
+4. Read: .workflow/.cycle/${cycleId}.progress/coordination/feedback.md (if exists)
+
+---
+
+## CYCLE CONTEXT
+
+- **Cycle ID**: ${cycleId}
+- **Progress Dir**: ${progressDir}/ra/
+- **Current Iteration**: ${state.current_iteration}
+- **Task Description**: ${state.description}
+
+## CURRENT REQUIREMENTS STATE
+
+${state.requirements ? JSON.stringify(state.requirements, null, 2) : 'No previous requirements'}
+
+## YOUR ROLE
+
+Requirements Analyst - Analyze and refine requirements throughout the cycle.
+
+## RESPONSIBILITIES
+
+1. Analyze initial task description
+2. Generate comprehensive requirements specification
+3. Identify edge cases and implicit requirements
+4. Track requirement changes across iterations
+5. Maintain requirements.md and changes.log
+
+## DELIVERABLES
+
+Write files to ${progressDir}/ra/:
+- requirements.md: Full requirements specification
+- edge-cases.md: Edge case analysis
+- changes.log: NDJSON format change tracking
+
+## OUTPUT FORMAT
+
+\`\`\`
+PHASE_RESULT:
+- phase: ra
+- status: success | failed
+- files_written: [list]
+- summary: one-line summary
+- issues: []
+\`\`\`
+`
+  })
+}
+```
+
+### Spawn EP Agent
+
+```javascript
+function spawnEPAgent(cycleId, state, progressDir) {
+  return spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/exploration-planner.md
+2. Read: .workflow/project-tech.json
+3. Read: .workflow/project-guidelines.json
+4. Read: ${progressDir}/ra/requirements.md
+
+---
+
+## CYCLE CONTEXT
+
+- **Cycle ID**: ${cycleId}
+- **Progress Dir**: ${progressDir}/ep/
+- **Requirements**: See requirements.md
+- **Current Plan**: ${state.plan ? 'Existing' : 'None - first iteration'}
+
+## YOUR ROLE
+
+Exploration & Planning Agent - Explore architecture and generate implementation plan.
+
+## RESPONSIBILITIES
+
+1. Explore codebase architecture
+2. Map integration points
+3. Design implementation approach
+4. Generate plan.json with task breakdown
+5. Update or iterate on existing plan
+
+## DELIVERABLES
+
+Write files to ${progressDir}/ep/:
+- exploration.md: Codebase exploration findings
+- architecture.md: Architecture design
+- plan.json: Implementation plan (structured)
+
+## OUTPUT FORMAT
+
+\`\`\`
+PHASE_RESULT:
+- phase: ep
+- status: success | failed
+- files_written: [list]
+- summary: one-line summary
+- plan_version: X.Y.Z
+\`\`\`
+`
+  })
+}
+```
+
+### Spawn CD Agent
+
+```javascript
+function spawnCDAgent(cycleId, state, progressDir) {
+  return spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/code-developer.md
+2. Read: ${progressDir}/ep/plan.json
+3. Read: ${progressDir}/ra/requirements.md
+
+---
+
+## CYCLE CONTEXT
+
+- **Cycle ID**: ${cycleId}
+- **Progress Dir**: ${progressDir}/cd/
+- **Plan Version**: ${state.plan?.version || 'N/A'}
+- **Previous Changes**: ${state.changes?.length || 0} files
+
+## YOUR ROLE
+
+Code Developer - Implement features based on plan and requirements.
+
+## RESPONSIBILITIES
+
+1. Implement features from plan
+2. Track code changes
+3. Handle integration issues
+4. Maintain code quality
+5. Report implementation progress and issues
+
+## DELIVERABLES
+
+Write files to ${progressDir}/cd/:
+- implementation.md: Implementation progress and decisions
+- changes.log: NDJSON format, each line: {file, action, timestamp}
+- issues.md: Development issues and blockers
+
+## OUTPUT FORMAT
+
+\`\`\`
+PHASE_RESULT:
+- phase: cd
+- status: success | failed | partial
+- files_changed: [count]
+- summary: one-line summary
+- blockers: []
+\`\`\`
+`
+  })
+}
+```
+
+### Spawn VAS Agent
+
+```javascript
+function spawnVASAgent(cycleId, state, progressDir) {
+  return spawn_agent({
+    message: `
+## TASK ASSIGNMENT
+
+### MANDATORY FIRST STEPS (Agent Execute)
+1. **Read role definition**: ~/.codex/agents/validation-archivist.md
+2. Read: ${progressDir}/cd/changes.log
+
+---
+
+## CYCLE CONTEXT
+
+- **Cycle ID**: ${cycleId}
+- **Progress Dir**: ${progressDir}/vas/
+- **Changes Count**: ${state.changes?.length || 0}
+- **Iteration**: ${state.current_iteration}
+
+## YOUR ROLE
+
+Validation & Archival Specialist - Validate quality and create documentation.
+
+## RESPONSIBILITIES
+
+1. Run tests on implemented features
+2. Generate coverage reports
+3. Create archival documentation
+4. Summarize cycle results
+5. Generate version history
+
+## DELIVERABLES
+
+Write files to ${progressDir}/vas/:
+- validation.md: Test validation results
+- test-results.json: Detailed test results
+- coverage.md: Coverage report
+- summary.md: Cycle summary and recommendations
+
+## OUTPUT FORMAT
+
+\`\`\`
+PHASE_RESULT:
+- phase: vas
+- status: success | failed
+- test_pass_rate: X%
+- coverage: X%
+- issues: []
+\`\`\`
+`
+  })
+}
+```
+
+## Result Parsing
+
+```javascript
+function parseAgentOutputs(agentOutputs) {
+  const results = {
+    ra: parseOutput(agentOutputs.ra, 'ra'),
+    ep: parseOutput(agentOutputs.ep, 'ep'),
+    cd: parseOutput(agentOutputs.cd, 'cd'),
+    vas: parseOutput(agentOutputs.vas, 'vas')
+  }
+  return results
+}
+
+function parseOutput(output, agent) {
+  const result = {
+    agent: agent,
+    status: 'unknown',
+    data: {}
+  }
+
+  // Parse PHASE_RESULT block
+  const match = output.match(/PHASE_RESULT:\s*([\s\S]*?)(?:\n\n|$)/)
+  if (match) {
+    const lines = match[1].split('\n')
+    for (const line of lines) {
+      const m = line.match(/^-\s*(\w+):\s*(.+)$/)
+      if (m) {
+        result[m[1]] = m[2].trim()
+      }
+    }
+  }
+
+  return result
+}
+```
+
+## Feedback Generation
+
+```javascript
+function generateFeedback(parsedResults) {
+  const feedback = {}
+
+  // Check VAS results
+  if (parsedResults.vas.test_pass_rate < 100) {
+    feedback.cd = `
+## FEEDBACK FROM VALIDATION
+
+Test pass rate: ${parsedResults.vas.test_pass_rate}%
+
+## ISSUES TO FIX
+
+${parsedResults.vas.data.issues || 'See test-results.json for details'}
+
+## NEXT STEP
+
+Fix failing tests and update implementation.md with resolution.
+`
+  }
+
+  // Check CD blockers
+  if (parsedResults.cd.blockers?.length > 0) {
+    feedback.ra = `
+## FEEDBACK FROM DEVELOPMENT
+
+Blockers encountered:
+${parsedResults.cd.blockers.map(b => `- ${b}`).join('\n')}
+
+## NEXT STEP
+
+Clarify requirements or identify alternative approaches.
+Update requirements.md if needed.
+`
+  }
+
+  return feedback
+}
+```
+
+## Summary Generation
+
+```javascript
+function generateFinalSummary(cycleId, state) {
+  const summaryFile = `.workflow/.cycle/${cycleId}.progress/coordination/summary.md`
+
+  const summary = `# Cycle Summary - ${cycleId}
+
+## Metadata
+- Cycle ID: ${cycleId}
+- Started: ${state.created_at}
+- Completed: ${state.completed_at}
+- Iterations: ${state.current_iteration}
+- Status: ${state.status}
+
+## Phase Results
+- Requirements Analysis: ✓ Completed
+- Exploration & Planning: ✓ Completed
+- Code Development: ✓ Completed
+- Validation & Archival: ✓ Completed
+
+## Key Deliverables
+- Requirements: ${state.requirements ? '✓' : '✗'}
+- Architecture Plan: ${state.plan ? '✓' : '✗'}
+- Code Changes: ${state.changes?.length || 0} files
+- Test Results: ${state.test_results?.pass_rate || '0'}% passing
+
+## Generated Files
+- .workflow/.cycle/${cycleId}.progress/ra/requirements.md
+- .workflow/.cycle/${cycleId}.progress/ep/plan.json
+- .workflow/.cycle/${cycleId}.progress/cd/changes.log
+- .workflow/.cycle/${cycleId}.progress/vas/summary.md
+
+## Continuation Instructions
+
+To extend this cycle:
+
+\`\`\`bash
+/parallel-dev-cycle --cycle-id=${cycleId} --extend="New requirement or feedback"
+\`\`\`
+
+This will spawn agents for iteration ${state.current_iteration + 1}.
+`
+
+  Write(summaryFile, summary)
+}
+```
+
+## Control Signal Checking
+
+```javascript
+function checkControlSignals(cycleId) {
+  const state = readCycleState(cycleId)
+
+  switch (state?.status) {
+    case 'paused':
+      return { continue: false, action: 'pause_exit' }
+    case 'failed':
+      return { continue: false, action: 'stop_exit' }
+    case 'running':
+      return { continue: true, action: 'continue' }
+    default:
+      return { continue: false, action: 'stop_exit' }
+  }
+}
+```
+
+## Error Recovery Strategies
+
+| Error Type | Recovery |
+|------------|----------|
+| Agent timeout | send_input requesting convergence |
+| State corrupted | Rebuild from progress markdown files |
+| Agent failed | Re-spawn agent with previous context |
+| Conflicting results | Orchestrator sends reconciliation request |
+| Missing files | RA/EP agents identify and request clarification |
+
+## Codex Best Practices Applied
+
+1. **Single Orchestrator**: One main agent manages all phases
+2. **Parallel Workers**: Four specialized agents execute simultaneously
+3. **Batch wait()**: Wait for all agents with `wait({ ids: [...] })`
+4. **Deep Interaction**: Use send_input for iteration and refinement
+5. **Delayed close_agent**: Only after all phases and iterations complete
+6. **Role Path Passing**: Each agent reads its own role definition
+7. **Persistent Context**: Cycle state shared across all agents

.codex/skills/parallel-dev-cycle/phases/state-schema.md

@@ -0,0 +1,436 @@
+# State Schema - Parallel Dev Cycle
+
+Unified cycle state structure for multi-agent coordination and iteration support.
+
+## State File Location
+
+**Location**: `.workflow/.cycle/{cycleId}.json` (unified state, all agents access)
+
+**Format**: JSON
+
+## Cycle State Interface
+
+```typescript
+interface CycleState {
+  // =====================================================
+  // CORE METADATA
+  // =====================================================
+
+  cycle_id: string                    // Unique cycle identifier
+  title: string                       // Task title (first 100 chars)
+  description: string                 // Full task description
+  task_history: string[]              // All task descriptions across iterations
+
+  // =====================================================
+  // STATUS & TIMING
+  // =====================================================
+
+  status: 'created' | 'running' | 'paused' | 'completed' | 'failed'
+  created_at: string                  // ISO8601 format
+  updated_at: string                  // ISO8601 format
+  completed_at?: string               // ISO8601 format
+
+  max_iterations: number              // Maximum iteration limit
+  current_iteration: number           // Current iteration count
+  failure_reason?: string             // If failed, why
+
+  // =====================================================
+  // MULTI-AGENT TRACKING
+  // =====================================================
+
+  agents: {
+    ra: AgentState                    // Requirements Analyst
+    ep: AgentState                    // Exploration Planner
+    cd: AgentState                    // Code Developer
+    vas: AgentState                   // Validation Archivist
+  }
+
+  // =====================================================
+  // PHASE TRACKING
+  // =====================================================
+
+  current_phase: 'init' | 'ra' | 'ep' | 'cd' | 'vas' | 'aggregation' | 'complete'
+  completed_phases: string[]
+  phase_errors: Array<{
+    phase: string
+    error: string
+    timestamp: string
+  }>
+
+  // =====================================================
+  // SHARED CONTEXT (Populated by agents)
+  // =====================================================
+
+  requirements?: {
+    version: string                   // e.g., "1.0.0", "1.1.0"
+    specification: string             // Full spec from requirements.md
+    edge_cases: string[]
+    last_updated: string
+  }
+
+  exploration?: {
+    version: string
+    architecture_summary: string
+    integration_points: string[]
+    identified_risks: string[]
+    last_updated: string
+  }
+
+  plan?: {
+    version: string
+    tasks: PlanTask[]
+    total_estimated_effort: string
+    critical_path: string[]
+    last_updated: string
+  }
+
+  changes?: {
+    total_files: number
+    changes: ChangeLog[]
+    iteration_markers: Record<number, string>  // Iteration timestamps
+  }
+
+  test_results?: {
+    version: string
+    pass_rate: number                 // 0-100
+    coverage: number                  // 0-100
+    failed_tests: string[]
+    total_tests: number
+    last_run: string
+  }
+
+  // =====================================================
+  // ITERATION TRACKING
+  // =====================================================
+
+  iterations: IterationRecord[]
+
+  // =====================================================
+  // COORDINATION DATA
+  // =====================================================
+
+  coordination: {
+    feedback_log: FeedbackEntry[]
+    pending_decisions: Decision[]
+    blockers: Blocker[]
+  }
+}
+
+// =====================================================
+// SUPPORTING TYPES
+// =====================================================
+
+interface AgentState {
+  status: 'idle' | 'running' | 'waiting' | 'completed' | 'failed'
+  started_at?: string
+  completed_at?: string
+  output_files: string[]
+  last_message?: string
+  error?: string
+  iterations_completed: number
+}
+
+interface PlanTask {
+  id: string                          // e.g., "TASK-001"
+  description: string
+  effort: 'small' | 'medium' | 'large'
+  depends_on: string[]
+  status: 'pending' | 'in_progress' | 'completed' | 'blocked'
+  assigned_to?: string                // Agent name
+  files: string[]
+}
+
+interface ChangeLog {
+  timestamp: string
+  file: string
+  action: 'create' | 'modify' | 'delete'
+  iteration: number
+  agent: string                       // which agent made change
+  description: string
+}
+
+interface IterationRecord {
+  number: number
+  extension?: string                  // User feedback/extension for this iteration
+  started_at: string
+  completed_at: string
+  agent_results: Record<string, {
+    status: string
+    files_modified: number
+  }>
+  issues_found: string[]
+  resolved: boolean
+}
+
+interface FeedbackEntry {
+  timestamp: string
+  source: string                      // Agent or 'user'
+  target: string                      // Recipient agent
+  content: string
+  type: 'requirement_update' | 'bug_report' | 'issue_fix' | 'clarification'
+}
+
+interface Decision {
+  id: string
+  description: string
+  options: string[]
+  made_by?: string
+  chosen_option?: string
+  status: 'pending' | 'made' | 'implemented'
+}
+
+interface Blocker {
+  id: string
+  description: string
+  reported_by: string
+  status: 'open' | 'resolved' | 'workaround'
+  resolution?: string
+}
+```
+
+## Initial State (New Cycle)
+
+When creating a new cycle:
+
+```json
+{
+  "cycle_id": "cycle-v1-20260122T100000-abc123",
+  "title": "Implement OAuth authentication",
+  "description": "Add OAuth2 login support with Google and GitHub providers",
+  "task_history": [
+    "Implement OAuth authentication"
+  ],
+  "status": "created",
+  "created_at": "2026-01-22T10:00:00+08:00",
+  "updated_at": "2026-01-22T10:00:00+08:00",
+  "max_iterations": 5,
+  "current_iteration": 0,
+  "agents": {
+    "ra": { "status": "idle", "output_files": [], "iterations_completed": 0 },
+    "ep": { "status": "idle", "output_files": [], "iterations_completed": 0 },
+    "cd": { "status": "idle", "output_files": [], "iterations_completed": 0 },
+    "vas": { "status": "idle", "output_files": [], "iterations_completed": 0 }
+  },
+  "current_phase": "init",
+  "completed_phases": [],
+  "phase_errors": [],
+  "iterations": [],
+  "coordination": {
+    "feedback_log": [],
+    "pending_decisions": [],
+    "blockers": []
+  }
+}
+```
+
+## State Transitions
+
+### Iteration 1: Initial Execution
+
+```json
+{
+  "status": "running",
+  "current_iteration": 1,
+  "current_phase": "ra",
+  "agents": {
+    "ra": { "status": "running", "started_at": "2026-01-22T10:05:00+08:00" },
+    "ep": { "status": "idle" },
+    "cd": { "status": "idle" },
+    "vas": { "status": "idle" }
+  },
+  "requirements": {
+    "version": "1.0.0",
+    "specification": "...",
+    "edge_cases": ["OAuth timeout handling", "PKCE validation"],
+    "last_updated": "2026-01-22T10:15:00+08:00"
+  },
+  "iterations": [{
+    "number": 1,
+    "started_at": "2026-01-22T10:00:00+08:00",
+    "agent_results": {
+      "ra": { "status": "completed", "files_modified": 3 },
+      "ep": { "status": "completed", "files_modified": 2 },
+      "cd": { "status": "partial", "files_modified": 5 },
+      "vas": { "status": "pending", "files_modified": 0 }
+    }
+  }]
+}
+```
+
+### After Phase Completion
+
+```json
+{
+  "current_phase": "aggregation",
+  "completed_phases": ["ra", "ep", "cd", "vas"],
+  "plan": {
+    "version": "1.0.0",
+    "tasks": [
+      {
+        "id": "TASK-001",
+        "description": "Setup OAuth application credentials",
+        "effort": "small",
+        "status": "completed",
+        "files": ["src/config/oauth.ts"]
+      }
+    ]
+  },
+  "changes": {
+    "total_files": 12,
+    "iteration_markers": {
+      "1": "2026-01-22T10:30:00+08:00"
+    }
+  },
+  "test_results": {
+    "version": "1.0.0",
+    "pass_rate": 85,
+    "coverage": 78,
+    "failed_tests": ["test: OAuth timeout retry"],
+    "total_tests": 20
+  }
+}
+```
+
+### Iteration 2: User Extension
+
+User provides feedback: "Also add multi-factor authentication"
+
+```json
+{
+  "status": "running",
+  "current_iteration": 2,
+  "task_history": [
+    "Implement OAuth authentication",
+    "Also add multi-factor authentication"
+  ],
+  "description": "Add OAuth2 login support with Google and GitHub providers\n\n--- ITERATION 2 ---\nAlso add multi-factor authentication",
+  "agents": {
+    "ra": { "status": "running", "iterations_completed": 1 },
+    "ep": { "status": "idle", "iterations_completed": 1 },
+    "cd": { "status": "idle", "iterations_completed": 1 },
+    "vas": { "status": "idle", "iterations_completed": 1 }
+  },
+  "requirements": {
+    "version": "1.1.0",
+    "specification": "...",
+    "last_updated": "2026-01-22T11:00:00+08:00"
+  },
+  "iterations": [
+    { "number": 1, "completed_at": "..." },
+    {
+      "number": 2,
+      "extension": "Also add multi-factor authentication",
+      "started_at": "2026-01-22T10:45:00+08:00",
+      "agent_results": {}
+    }
+  ],
+  "coordination": {
+    "feedback_log": [{
+      "timestamp": "2026-01-22T10:45:00+08:00",
+      "source": "user",
+      "target": "ra",
+      "content": "Add multi-factor authentication to requirements",
+      "type": "requirement_update"
+    }]
+  }
+}
+```
+
+## Version Tracking
+
+Each component tracks its version:
+
+- **Requirements**: `1.0.0` → `1.1.0` → `1.2.0` (each iteration)
+- **Plan**: `1.0.0` → `1.1.0` (updated based on requirements)
+- **Code**: Changes appended with iteration markers
+- **Tests**: Results tracked per iteration
+
+## File Sync Protocol
+
+State changes trigger file writes:
+
+| State Change | File Sync |
+|--------------|-----------|
+| `requirements` updated | `.progress/ra/requirements.md` + version bump |
+| `plan` updated | `.progress/ep/plan.json` + version bump |
+| `changes` appended | `.progress/cd/changes.log` + iteration marker |
+| `test_results` updated | `.progress/vas/test-results.json` + version bump |
+| Full iteration done | `.progress/coordination/timeline.md` appended |
+
+## Control Signal Checking
+
+Agents check status before each action:
+
+```javascript
+function checkControlSignals(cycleId) {
+  const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
+
+  if (state.status === 'paused') {
+    return { continue: false, action: 'pause' }
+  }
+  if (state.status === 'failed') {
+    return { continue: false, action: 'stop' }
+  }
+  if (state.status === 'running') {
+    return { continue: true, action: 'continue' }
+  }
+
+  return { continue: false, action: 'unknown' }
+}
+```
+
+## State Persistence
+
+### Write Operations
+
+After each agent completes or phase transitions:
+
+```javascript
+Write(
+  `.workflow/.cycle/${cycleId}.json`,
+  JSON.stringify(state, null, 2)
+)
+```
+
+### Read Operations
+
+Agents always read fresh state before executing:
+
+```javascript
+const currentState = JSON.parse(
+  Read(`.workflow/.cycle/${cycleId}.json`)
+)
+```
+
+## State Rebuild (Recovery)
+
+If master state corrupted, rebuild from markdown files:
+
+```javascript
+function rebuildState(cycleId) {
+  const progressDir = `.workflow/.cycle/${cycleId}.progress`
+
+  // Read markdown files
+  const raMarkdown = Read(`${progressDir}/ra/requirements.md`)
+  const epMarkdown = Read(`${progressDir}/ep/plan.json`)
+  const cdChanges = Read(`${progressDir}/cd/changes.log`)
+  const vasResults = Read(`${progressDir}/vas/test-results.json`)
+
+  // Reconstruct state from files
+  return {
+    requirements: parseMarkdown(raMarkdown),
+    plan: JSON.parse(epMarkdown),
+    changes: parseNDJSON(cdChanges),
+    test_results: JSON.parse(vasResults)
+  }
+}
+```
+
+## Best Practices
+
+1. **Immutable Reads**: Never modify state during read
+2. **Version Bumps**: Increment version on each iteration
+3. **Timestamp Accuracy**: Use UTC+8 consistently
+4. **Append-Only Logs**: Never delete history
+5. **Atomic Writes**: Write complete state, not partial updates
+6. **Coordination Tracking**: Log all inter-agent communication

.codex/skills/parallel-dev-cycle/specs/communication-optimization.md

@@ -0,0 +1,423 @@
+# Agent Communication Optimization
+
+优化 agent 通信机制：使用简短的产出文件引用而不是内容传递。
+
+## 背景
+
+在多 agent 系统中，传递完整的文件内容会导致：
+- 消息体积过大
+- 上下文使用量增加
+- 通信效率低下
+- 容易引入上下文断层
+
+**优化方案**: 使用文件路径引用，让 agent 自动读取需要的文件。
+
+## 优化原则
+
+### 原则 1: 文件引用而非内容传递
+
+❌ **错误做法**（传递内容）:
+```javascript
+send_input({
+  id: agents.cd,
+  message: `
+Requirements:
+${requirements_content}  // 完整内容 - 浪费空间
+
+Plan:
+${plan_json}  // 完整 JSON - 重复信息
+`
+})
+```
+
+✅ **正确做法**（引用文件）:
+```javascript
+send_input({
+  id: agents.cd,
+  message: `
+## Feedback from Validation
+
+Test failures found. Review these outputs:
+
+## Reference
+- Requirements: .workflow/.cycle/${cycleId}.progress/ra/requirements.md (v1.0.0)
+- Plan: .workflow/.cycle/${cycleId}.progress/ep/plan.json (v1.0.0)
+- Test Results: .workflow/.cycle/${cycleId}.progress/vas/test-results.json
+
+## Issues Found
+${summary_of_issues}  // 只传递摘要
+
+## Actions Required
+1. Fix OAuth token refresh (test line 45)
+2. Update implementation.md with fixes
+`
+})
+```
+
+### 原则 2: 摘要而非全文
+
+❌ **错误**：
+```javascript
+// 传递所有文件内容
+RA输出: "requirements.md (2000 lines) + edge-cases.md (1000 lines) + changes.log (500 lines)"
+
+EP读取: 全文解析所有内容（浪费token）
+```
+
+✅ **正确**：
+```javascript
+// 只传递关键摘要
+RA输出:
+- 10个功能需求
+- 5个非功能需求
+- 8个边界场景
+- 文件路径用于完整查看
+
+EP读取: 读取摘要 + 需要时查看完整文件（高效）
+```
+
+### 原则 3: 文件版本跟踪
+
+每个引用必须包含版本:
+
+```javascript
+send_input({
+  id: agents.cd,
+  message: `
+Requirements: .workflow/.cycle/${cycleId}.progress/ra/requirements.md (v1.1.0)
+                                                                       ^^^^^^^ 版本号
+
+Plan: .workflow/.cycle/${cycleId}.progress/ep/plan.json (v1.0.0)
+                                                          ^^^^^^^ 版本号
+`
+})
+```
+
+**好处**:
+- 避免使用过期信息
+- 自动检测版本不匹配
+- 支持多版本迭代
+
+## 实现模式
+
+### Pattern 1: 通知 + 引用
+
+Agent 向其他 agent 通知输出，而非传递内容：
+
+```javascript
+// RA 输出摘要
+const raSummary = {
+  requirements_count: 10,
+  edge_cases_count: 8,
+  version: "1.0.0",
+  output_file: ".workflow/.cycle/${cycleId}.progress/ra/requirements.md",
+  key_requirements: [
+    "FR-001: OAuth authentication",
+    "FR-002: Multi-provider support",
+    "..."  // 只列出标题，不传递完整内容
+  ]
+}
+
+// 更新状态，让其他 agent 读取
+state.requirements = {
+  version: raSummary.version,
+  output_file: raSummary.output_file,
+  summary: raSummary.key_requirements
+}
+
+// EP agent 从状态读取
+const requiredDetails = state.requirements
+const outputFile = requiredDetails.output_file
+const requirements = JSON.parse(Read(outputFile))  // EP 自己读取完整文件
+```
+
+### Pattern 2: 反馈通知
+
+Orchestrator 发送反馈时只传递摘要和行号：
+
+```javascript
+// ❌ 错误：传递完整测试结果
+send_input({
+  id: agents.cd,
+  message: `
+Test Results:
+${entire_test_results_json}  // 完整 JSON - 太大
+`
+})
+
+// ✅ 正确：引用文件 + 问题摘要
+send_input({
+  id: agents.cd,
+  message: `
+## Test Failures
+
+Full results: .workflow/.cycle/${cycleId}.progress/vas/test-results.json (v1.0.0)
+
+## Quick Summary
+- Failed: oauth-refresh (line 45, expected token refresh)
+- Failed: concurrent-login (line 78, race condition)
+
+## Fix Instructions
+1. Review test cases at referenced lines
+2. Fix implementation
+3. Re-run tests
+4. Update implementation.md
+
+Reference previous file paths if you need full details.
+`
+})
+```
+
+### Pattern 3: 依赖链路
+
+Agent 通过文件引用获取依赖：
+
+```javascript
+// EP agent: 从状态读取 RA 输出路径
+const raOutputPath = state.requirements?.output_file
+if (raOutputPath && exists(raOutputPath)) {
+  const requirements = Read(raOutputPath)
+  // 使用 requirements 生成计划
+}
+
+// CD agent: 从状态读取 EP 输出路径
+const epPlanPath = state.plan?.output_file
+if (epPlanPath && exists(epPlanPath)) {
+  const plan = JSON.parse(Read(epPlanPath))
+  // 根据 plan 实现功能
+}
+
+// VAS agent: 从状态读取 CD 输出路径
+const cdChangesPath = state.changes?.output_file
+if (cdChangesPath && exists(cdChangesPath)) {
+  const changes = readNDJSON(cdChangesPath)
+  // 根据 changes 生成测试
+}
+```
+
+## 状态文件引用结构
+
+优化后的状态文件应该包含文件路径而不是内容：
+
+```json
+{
+  "cycle_id": "cycle-v1-20260122-abc123",
+
+  "requirements": {
+    "version": "1.0.0",
+    "output_files": {
+      "specification": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/ra/requirements.md",
+      "edge_cases": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/ra/edge-cases.md",
+      "changes_log": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/ra/changes.log"
+    },
+    "summary": {
+      "functional_requirements": 10,
+      "edge_cases": 8,
+      "constraints": 5
+    }
+  },
+
+  "exploration": {
+    "version": "1.0.0",
+    "output_files": {
+      "exploration": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/ep/exploration.md",
+      "architecture": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/ep/architecture.md"
+    },
+    "summary": {
+      "key_components": ["Auth Module", "User Service"],
+      "integration_points": 5,
+      "identified_risks": 3
+    }
+  },
+
+  "plan": {
+    "version": "1.0.0",
+    "output_file": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/ep/plan.json",
+    "summary": {
+      "total_tasks": 8,
+      "critical_path": ["TASK-001", "TASK-003", "TASK-004"],
+      "estimated_hours": 16
+    }
+  },
+
+  "implementation": {
+    "version": "1.0.0",
+    "output_files": {
+      "progress": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/cd/implementation.md",
+      "changes": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/cd/changes.log",
+      "issues": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/cd/issues.md"
+    },
+    "summary": {
+      "tasks_completed": 3,
+      "files_modified": 5,
+      "blockers": 0
+    }
+  },
+
+  "validation": {
+    "version": "1.0.0",
+    "output_files": {
+      "validation": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/vas/validation.md",
+      "test_results": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/vas/test-results.json",
+      "coverage": ".workflow/.cycle/cycle-v1-20260122-abc123.progress/vas/coverage.md"
+    },
+    "summary": {
+      "pass_rate": 92,
+      "coverage": 87,
+      "failures": 4
+    }
+  }
+}
+```
+
+## Agent 通信模板优化
+
+### 优化前: 完整内容传递
+
+```javascript
+send_input({
+  id: agents.cd,
+  message: `
+## Requirements (Complete Content)
+
+${fs.readFileSync(requirementsFile, 'utf8')}  // 2000+ lines
+
+## Plan (Complete JSON)
+
+${fs.readFileSync(planFile, 'utf8')}  // 1000+ lines
+
+## Test Results (Complete)
+
+${fs.readFileSync(testResultsFile, 'utf8')}  // 500+ lines
+
+## Your Task
+
+Fix the implementation...
+`  // 总消息体: 4000+ 行
+})
+```
+
+### 优化后: 文件引用 + 摘要
+
+```javascript
+send_input({
+  id: agents.cd,
+  message: `
+## Test Failures - Action Required
+
+Full Test Report: .workflow/.cycle/${cycleId}.progress/vas/test-results.json (v1.0.0)
+
+## Summary of Failures
+- oauth-refresh: Expected token refresh, got error (test line 45)
+- concurrent-login: Race condition in session writes (test line 78)
+
+## Implementation Reference
+- Current Code: .workflow/.cycle/${cycleId}.progress/cd/implementation.md (v1.0.0)
+- Code Changes: .workflow/.cycle/${cycleId}.progress/cd/changes.log (v1.0.0)
+
+## Action Required
+1. Review failing tests in referenced test results file
+2. Fix root causes (race condition, token handling)
+3. Update implementation.md with fixes
+4. Re-run tests
+
+## Context
+- Requirement: .workflow/.cycle/${cycleId}.progress/ra/requirements.md (v1.0.0)
+- Plan: .workflow/.cycle/${cycleId}.progress/ep/plan.json (v1.0.0)
+
+Output PHASE_RESULT when complete.
+`  // 总消息体: <500 行，高效传递
+})
+```
+
+## 版本控制最佳实践
+
+### 版本不匹配检测
+
+```javascript
+function validateVersionConsistency(state) {
+  const versions = {
+    ra: state.requirements?.version,
+    ep: state.plan?.version,
+    cd: state.implementation?.version,
+    vas: state.validation?.version
+  }
+
+  // 检查版本一致性
+  const allVersions = Object.values(versions).filter(v => v)
+  const unique = new Set(allVersions)
+
+  if (unique.size > 1) {
+    console.warn('Version mismatch detected:')
+    console.warn(versions)
+    // 返回版本差异，让 orchestrator 决定是否继续
+  }
+
+  return unique.size === 1
+}
+```
+
+### 文件存在性检查
+
+```javascript
+function validateReferences(state, cycleId) {
+  const checks = []
+
+  // 检查所有引用的文件是否存在
+  for (const [agent, data] of Object.entries(state)) {
+    if (data?.output_files) {
+      for (const [name, path] of Object.entries(data.output_files)) {
+        if (!fs.existsSync(path)) {
+          checks.push({
+            agent: agent,
+            file: name,
+            path: path,
+            status: 'missing'
+          })
+        }
+      }
+    }
+  }
+
+  return checks
+}
+```
+
+## 好处总结
+
+| 方面 | 改进 |
+|------|------|
+| 消息体积 | 减少 80-90% |
+| Token 使用 | 减少 60-70% |
+| 读取速度 | 无需解析冗余内容 |
+| 版本控制 | 清晰的版本跟踪 |
+| 上下文清晰 | 不会混淆版本 |
+| 可维护性 | 文件变更不需要修改消息 |
+
+## 迁移建议
+
+### 第一步: 更新状态结构
+
+```json
+// 从这样:
+"requirements": "完整内容"
+
+// 改为这样:
+"requirements": {
+  "version": "1.0.0",
+  "output_file": "path/to/file",
+  "summary": {...}
+}
+```
+
+### 第二步: 更新通信模板
+
+所有 `send_input` 消息改为引用路径。
+
+### 第三步: Agent 自动读取
+
+Agent 从引用路径自动读取所需文件。
+
+### 第四步: 测试版本检测
+
+确保版本不匹配时有警告。

.codex/skills/parallel-dev-cycle/specs/coordination-protocol.md

@@ -0,0 +1,406 @@
+# Coordination Protocol - Multi-Agent Communication
+
+Inter-agent communication protocols and patterns for parallel-dev-cycle skill.
+
+## Overview
+
+The coordination protocol enables four parallel agents (RA, EP, CD, VAS) to communicate efficiently while maintaining clear responsibilities and avoiding conflicts.
+
+## Communication Channels
+
+### 1. Shared State File (Primary)
+
+**Location**: `.workflow/.cycle/{cycleId}.json`
+
+**Access Pattern**:
+- **Agents**: READ ONLY - check dependencies and status
+- **Orchestrator**: READ-WRITE - updates state after each phase
+
+```javascript
+// Every agent: Read state to check dependencies
+const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
+const canProceed = checkDependencies(state)
+
+// Agent outputs PHASE_RESULT (reports to orchestrator, NOT writes directly)
+console.log("PHASE_RESULT: ...")
+
+// Only Orchestrator writes to state file after receiving PHASE_RESULT
+// Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(updatedState, null, 2))
+```
+
+**Protocol**:
+- Only orchestrator writes to state file (no concurrent writes, no lock needed)
+- Agents read state to understand dependencies
+- Timestamp all orchestrator updates with ISO8601 format
+- Never delete existing data, only append
+
+### 2. Progress Markdown Files (Async Log)
+
+**Location**: `.workflow/.cycle/{cycleId}.progress/{agent}/`
+
+Each agent writes progress to dedicated markdown files:
+
+| Agent | Main Documents (Rewrite) | Logs (Append-Only) |
+|-------|--------------------------|-------------------|
+| RA | requirements.md | changes.log |
+| EP | exploration.md, architecture.md, plan.json | changes.log |
+| CD | implementation.md, issues.md | changes.log, debug-log.ndjson |
+| VAS | validation.md, summary.md, test-results.json | changes.log |
+
+**Protocol**:
+- **Main documents**: Complete rewrite per iteration, archived to `history/`
+- **Log files**: Append-only (changes.log, debug-log.ndjson) - never delete
+- **Version synchronization**: All main documents share same version (e.g., all v1.1.0 in iteration 2)
+- Include timestamp on each update
+
+### 3. Orchestrator send_input (Synchronous)
+
+**When**: Orchestrator needs to send feedback or corrections
+
+```javascript
+// Example: CD agent receives test failure feedback
+send_input({
+  id: agents.cd,
+  message: `
+## FEEDBACK FROM VALIDATION
+
+Test failures detected: ${failures}
+
+## REQUIRED ACTION
+
+Fix the following:
+${actionItems}
+
+## NEXT STEP
+Update implementation.md with fixes, then re-run tests.
+Output PHASE_RESULT when complete.
+`
+})
+```
+
+**Protocol**:
+- Only orchestrator initiates send_input
+- Clear action items and expected output
+- Single message per iteration (no rapid-fire sends)
+
+### 4. Coordination Log
+
+**Location**: `.workflow/.cycle/{cycleId}.progress/coordination/`
+
+Centralized log for inter-agent decisions and communication:
+
+**feedback.md**:
+```markdown
+# Feedback & Coordination Log - Version X.Y.Z
+
+## Timeline
+- [10:00:00] Orchestrator: Created cycle
+- [10:05:00] RA: Requirements analysis started
+- [10:10:00] RA: Requirements completed, v1.0.0
+- [10:10:01] EP: Starting exploration (depends on RA output)
+- [10:15:00] EP: Architecture designed, plan.json v1.0.0
+- [10:15:01] CD: Starting implementation (depends on EP plan)
+- [10:30:00] CD: Implementation progressing, found blocker
+- [10:31:00] RA: Clarified requirement after CD blocker
+- [10:31:01] CD: Continuing with clarification
+- [10:40:00] CD: Implementation complete
+- [10:40:01] VAS: Starting validation
+- [10:45:00] VAS: Testing complete, found failures
+- [10:45:01] Orchestrator: Sending feedback to CD
+- [10:46:00] CD: Fixed issues
+- [10:50:00] VAS: Re-validation, all passing
+- [10:50:01] Orchestrator: Cycle complete
+
+## Decision Records
+- [10:31:00] RA Clarification: OAuth optional vs required?
+  - Decision: Optional (can use password)
+  - Rationale: More flexible for users
+  - Impact: Affects FR-003 implementation
+
+## Blockers & Resolutions
+- [10:30:00] Blocker: Database migration for existing users
+  - Reported by: CD
+  - Resolution: Set oauth_id = null for existing users
+  - Status: Resolved
+
+## Cross-Agent Dependencies
+- EP depends on: RA requirements (v1.0.0)
+- CD depends on: EP plan (v1.0.0)
+- VAS depends on: CD code changes
+```
+
+## Message Formats
+
+### Agent Status Update
+
+Each agent updates state with its status:
+
+```json
+{
+  "agents": {
+    "ra": {
+      "status": "completed",
+      "started_at": "2026-01-22T10:05:00+08:00",
+      "completed_at": "2026-01-22T10:15:00+08:00",
+      "output_files": [
+        ".workflow/.cycle/cycle-xxx.progress/ra/requirements.md",
+        ".workflow/.cycle/cycle-xxx.progress/ra/edge-cases.md",
+        ".workflow/.cycle/cycle-xxx.progress/ra/changes.log"
+      ],
+      "iterations_completed": 1
+    }
+  }
+}
+```
+
+### Feedback Message Format
+
+When orchestrator sends feedback via send_input:
+
+```text
+## FEEDBACK FROM [Agent Name]
+
+[Summary of findings or issues]
+
+## REFERENCED OUTPUT
+File: [path to agent output]
+Version: [X.Y.Z]
+
+## REQUIRED ACTION
+
+1. [Action 1 with specific details]
+2. [Action 2 with specific details]
+
+## SUCCESS CRITERIA
+
+- [ ] Item 1
+- [ ] Item 2
+
+## NEXT STEP
+[What agent should do next]
+Output PHASE_RESULT when complete.
+
+## CONTEXT
+
+Previous iteration: [N]
+Current iteration: [N+1]
+```
+
+### Phase Result Format
+
+Every agent outputs PHASE_RESULT:
+
+```text
+PHASE_RESULT:
+- phase: [ra|ep|cd|vas]
+- status: success | failed | partial
+- files_written: [list of files]
+- summary: [one-line summary]
+- [agent-specific fields]
+- issues: [list of issues if any]
+
+PHASE_DETAILS:
+[Additional details or metrics]
+```
+
+## Dependency Resolution
+
+**Execution Model**: All four agents are spawned in parallel, but execution blocks based on dependencies. Orchestrator manages dependency resolution via shared state.
+
+### Build Order (Default)
+
+```
+RA (Requirements) → EP (Planning) → CD (Development) → VAS (Validation)
+       ↓                  ↓               ↓                 ↓
+   Block EP         Block CD         Block VAS         Block completion
+```
+
+**Explanation**:
+- All agents spawned simultaneously
+- Each agent checks dependencies in shared state before proceeding
+- Blocked agents wait for dependency completion
+- Orchestrator uses `send_input` to notify dependent agents when ready
+
+### Parallel Opportunities
+
+Some phases can run in parallel:
+
+```
+RA + FrontendCode (independent)
+EP + RA (not blocking)
+CD.Task1 + CD.Task2 (if no dependencies)
+```
+
+### Dependency Tracking
+
+State file tracks dependencies:
+
+```json
+{
+  "agents": {
+    "ep": {
+      "depends_on": ["ra"],
+      "ready": true,  // RA completed
+      "can_start": true
+    },
+    "cd": {
+      "depends_on": ["ep"],
+      "ready": true,  // EP completed
+      "can_start": true
+    },
+    "vas": {
+      "depends_on": ["cd"],
+      "ready": false,  // CD not yet complete
+      "can_start": false
+    }
+  }
+}
+```
+
+## Iteration Flow with Communication
+
+### Iteration 1: Initial Execution
+
+```
+Time   Agent    Action                State Update
+──────────────────────────────────────────────────────
+10:00  Init     Create cycle          status: running
+10:05  RA       Start analysis        agents.ra.status: running
+10:10  RA       Complete (v1.0.0)     agents.ra.status: completed
+10:10  EP       Start planning        agents.ep.status: running
+       (depends on RA completion)
+10:15  EP       Complete (v1.0.0)     agents.ep.status: completed
+10:15  CD       Start development     agents.cd.status: running
+       (depends on EP completion)
+10:30  CD       Found blocker         coordination.blockers.add()
+10:31  RA       Clarify blocker       requirements.v1.1.0 created
+10:35  CD       Continue (with fix)   agents.cd.status: running
+10:40  CD       Complete              agents.cd.status: completed
+10:40  VAS      Start validation      agents.vas.status: running
+       (depends on CD completion)
+10:45  VAS      Tests failing         coordination.feedback_log.add()
+10:45  Orch     Send feedback         agents.cd.message: "Fix these tests"
+10:46  CD       Resume (send_input)   agents.cd.status: running
+10:48  CD       Fix complete          agents.cd.status: completed
+10:50  VAS      Re-validate           agents.vas.status: running
+10:55  VAS      All pass              agents.vas.status: completed
+11:00  Orch     Complete cycle        status: completed
+```
+
+## Conflict Resolution
+
+### Conflict Type 1: Unclear Requirement
+
+**Scenario**: CD needs clarification on FR-X
+
+**Resolution Flow**:
+1. CD reports blocker in issues.md
+2. Orchestrator extracts blocker
+3. Orchestrator sends message to RA
+4. RA updates requirements with clarification
+5. RA outputs new requirements.md (v1.1.0)
+6. Orchestrator sends message to CD with clarification
+7. CD resumes and continues
+
+### Conflict Type 2: Test Failure
+
+**Scenario**: VAS finds test failures
+
+**Resolution Flow**:
+1. VAS reports failures in validation.md
+2. VAS outputs test-results.json with details
+3. Orchestrator extracts failure details
+4. Orchestrator categorizes failures
+5. If blocker: Orchestrator sends to CD/RA for fixes
+6. CD/RA fix and report completion
+7. Orchestrator sends CD/VAS to retry
+8. VAS re-validates
+
+### Conflict Type 3: Plan Mismatch
+
+**Scenario**: CD realizes plan tasks are incomplete
+
+**Resolution Flow**:
+1. CD reports in issues.md
+2. Orchestrator extracts issue
+3. Orchestrator sends to EP to revise plan
+4. EP updates plan.json (v1.1.0)
+5. EP adds new tasks or dependencies
+6. Orchestrator sends to CD with updated plan
+7. CD implements remaining tasks
+
+## Escalation Path
+
+For issues that block resolution:
+
+```
+Agent Issue
+    ↓
+Agent reports blocker
+    ↓
+Orchestrator analyzes
+    ↓
+Can fix automatically?
+    ├─ Yes: send_input to agent with fix
+    └─ No: Escalate to user
+         ↓
+         User provides guidance
+         ↓
+         Orchestrator applies guidance
+         ↓
+         Resume agents
+```
+
+## Communication Best Practices
+
+1. **Clear Timestamps**: All events timestamped ISO8601 format
+2. **Structured Messages**: Use consistent format for feedback
+3. **Version Tracking**: Always include version numbers
+4. **Audit Trail**: Maintain complete log of decisions
+5. **No Direct Agent Communication**: All communication via orchestrator
+6. **Document Decisions**: Record why decisions were made
+7. **Append-Only Logs**: Never delete history
+
+## State Consistency Rules
+
+1. **Single Writer Per Field**: Only one agent updates each field
+   - RA writes: requirements, edge_cases
+   - EP writes: exploration, plan
+   - CD writes: changes, implementation
+   - VAS writes: test_results, summary
+
+2. **Read-Write Serialization**: Orchestrator ensures no conflicts
+
+3. **Version Synchronization**: All versions increment together
+   - v1.0.0 → v1.1.0 (all docs updated)
+
+4. **Timestamp Consistency**: All timestamps in state file UTC+8
+
+## Monitoring & Debugging
+
+### State Inspection
+
+```javascript
+// Check agent status
+const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
+console.log(state.agents)  // See status of all agents
+
+// Check for blockers
+console.log(state.coordination.blockers)
+
+// Check feedback history
+console.log(state.coordination.feedback_log)
+```
+
+### Log Analysis
+
+```bash
+# Check RA progress
+tail .workflow/.cycle/cycle-xxx.progress/ra/changes.log
+
+# Check CD changes
+grep "TASK-001" .workflow/.cycle/cycle-xxx.progress/cd/changes.log
+
+# Check coordination timeline
+tail -50 .workflow/.cycle/cycle-xxx.progress/coordination/feedback.md
+```

.codex/skills/parallel-dev-cycle/specs/versioning-strategy.md

@@ -0,0 +1,331 @@
+# Document Versioning Strategy
+
+Document version management strategy: Complete Rewrite + Archive History
+
+## Recommended Approach: Complete Rewrite + Archive History
+
+For each iteration, **completely rewrite** the main document, and automatically archive the old version to the `history/` directory.
+
+### File Structure
+
+```
+.workflow/.cycle/cycle-v1-20260122-abc123.progress/
+├── ra/
+│   ├── requirements.md          # v1.2.0 (current version, complete rewrite)
+│   ├── edge-cases.md            # v1.2.0 (current version, complete rewrite)
+│   ├── changes.log              # NDJSON complete change history (append-only)
+│   └── history/
+│       ├── requirements-v1.0.0.md   (archived)
+│       ├── requirements-v1.1.0.md   (archived)
+│       ├── edge-cases-v1.0.0.md     (archived)
+│       └── edge-cases-v1.1.0.md     (archived)
+├── ep/
+│   ├── exploration.md           # v1.2.0 (current)
+│   ├── architecture.md          # v1.2.0 (current)
+│   ├── plan.json                # v1.2.0 (current)
+│   └── history/
+│       ├── plan-v1.0.0.json
+│       └── plan-v1.1.0.json
+├── cd/
+│   ├── implementation.md        # v1.2.0 (current)
+│   ├── changes.log         # NDJSON complete history
+│   ├── debug-log.ndjson         # Debug hypothesis tracking
+│   ├── issues.md                # Current unresolved issues
+│   └── history/
+│       ├── implementation-v1.0.0.md
+│       └── implementation-v1.1.0.md
+└── vas/
+    ├── validation.md            # v1.2.0 (current)
+    ├── test-results.json        # v1.2.0 (current)
+    ├── summary.md               # v1.2.0 (current)
+    └── history/
+        ├── validation-v1.0.0.md
+        └── test-results-v1.0.0.json
+```
+
+## Optimized Document Template
+
+### Requirements.md (Complete Rewrite Version)
+
+```markdown
+# Requirements Specification - v1.2.0
+
+## Document Metadata
+| Field | Value |
+|-------|-------|
+| Version | 1.2.0 |
+| Previous | 1.1.0 (Added Google OAuth) |
+| Changes | Added MFA, GitHub provider |
+| Date | 2026-01-23T10:00:00+08:00 |
+| Cycle | cycle-v1-20260122-abc123 |
+| Iteration | 3 |
+
+---
+
+## Functional Requirements
+
+### FR-001: OAuth Authentication
+**Description**: Users can log in using OAuth providers.
+
+**Supported Providers**: Google, GitHub
+
+**Priority**: High
+
+**Status**: ✓ Implemented (v1.0.0), Enhanced (v1.1.0, v1.2.0)
+
+**Success Criteria**:
+- User can click provider button
+- Redirect to provider
+- Return with valid token
+- Session created
+
+---
+
+### FR-002: Multi-Provider Support
+**Description**: System supports multiple OAuth providers simultaneously.
+
+**Providers**:
+- Google (v1.1.0)
+- GitHub (v1.2.0)
+
+**Priority**: High
+
+**Status**: ✓ Implemented
+
+---
+
+### FR-003: Multi-Factor Authentication
+**Description**: Optional MFA for enhanced security.
+
+**Method**: TOTP (Time-based One-Time Password)
+
+**Priority**: Medium
+
+**Status**: 🆕 New in v1.2.0
+
+**Success Criteria**:
+- User can enable MFA in settings
+- TOTP QR code generated
+- Verification on login
+
+---
+
+## Non-Functional Requirements
+
+### NFR-001: Performance
+Response time < 500ms for all OAuth flows.
+
+**Status**: ✓ Met (v1.0.0)
+
+---
+
+## Edge Cases
+
+### EC-001: OAuth Provider Timeout
+**Scenario**: Provider doesn't respond in 5 seconds
+
+**Expected**: Display error, offer retry
+
+**Status**: ✓ Handled
+
+---
+
+### EC-002: Invalid MFA Code (NEW v1.2.0)
+**Scenario**: User enters incorrect TOTP code
+
+**Expected**: Display error, max 3 attempts, lock after
+
+**Status**: 🔄 To be implemented
+
+---
+
+## Constraints
+- Must use existing JWT session management
+- No new database servers
+- Compatible with existing user table
+
+---
+
+## Assumptions
+- Users have access to authenticator app for MFA
+- OAuth providers are always available
+
+---
+
+## Version History Summary
+
+| Version | Date | Summary |
+|---------|------|---------|
+| 1.0.0 | 2026-01-22 | Initial OAuth login (Google only implicit) |
+| 1.1.0 | 2026-01-22 | + Explicit Google OAuth support |
+| 1.2.0 | 2026-01-23 | + GitHub provider, + MFA (current) |
+
+**Detailed History**: See `history/` directory and `changes.log`
+```
+
+### Changes.log (NDJSON - Complete History)
+
+```jsonl
+{"timestamp":"2026-01-22T10:00:00+08:00","iteration":1,"version":"1.0.0","action":"create","type":"requirement","id":"FR-001","description":"Initial OAuth requirement"}
+{"timestamp":"2026-01-22T10:05:00+08:00","iteration":1,"version":"1.0.0","action":"create","type":"requirement","id":"NFR-001","description":"Performance requirement"}
+{"timestamp":"2026-01-22T11:00:00+08:00","iteration":2,"version":"1.1.0","action":"update","type":"requirement","id":"FR-001","description":"Clarified Google OAuth support"}
+{"timestamp":"2026-01-22T11:05:00+08:00","iteration":2,"version":"1.1.0","action":"create","type":"requirement","id":"FR-002","description":"Multi-provider support"}
+{"timestamp":"2026-01-23T10:00:00+08:00","iteration":3,"version":"1.2.0","action":"create","type":"requirement","id":"FR-003","description":"MFA requirement"}
+{"timestamp":"2026-01-23T10:05:00+08:00","iteration":3,"version":"1.2.0","action":"update","type":"requirement","id":"FR-002","description":"Added GitHub provider"}
+```
+
+## Implementation Flow
+
+### Agent Workflow (RA Example)
+
+```javascript
+// ==================== RA Agent Iteration Flow ====================
+
+// Read current state
+const state = JSON.parse(Read(`.workflow/.cycle/${cycleId}.json`))
+const currentVersion = state.requirements?.version || "0.0.0"
+const iteration = state.current_iteration
+
+// If iteration (old version exists)
+if (currentVersion !== "0.0.0") {
+  // 1. Archive old version
+  const oldFile = `.workflow/.cycle/${cycleId}.progress/ra/requirements.md`
+  const archiveFile = `.workflow/.cycle/${cycleId}.progress/ra/history/requirements-v${currentVersion}.md`
+
+  Copy(oldFile, archiveFile)  // Archive
+
+  // 2. Read old version (optional, for context understanding)
+  const oldRequirements = Read(oldFile)
+
+  // 3. Read change history
+  const changesLog = readNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`)
+}
+
+// 4. Generate new version number
+const newVersion = bumpVersion(currentVersion, 'minor')  // 1.1.0 -> 1.2.0
+
+// 5. Generate new document (complete rewrite)
+const newRequirements = generateRequirements({
+  version: newVersion,
+  previousVersion: currentVersion,
+  previousSummary: "Added Google OAuth support",
+  currentChanges: "Added MFA and GitHub provider",
+  iteration: iteration,
+  taskDescription: state.description,
+  changesLog: changesLog  // For understanding history
+})
+
+// 6. Write new document (overwrite old)
+Write(`.workflow/.cycle/${cycleId}.progress/ra/requirements.md`, newRequirements)
+
+// 7. Append change to changes.log
+appendNDJSON(`.workflow/.cycle/${cycleId}.progress/ra/changes.log`, {
+  timestamp: getUtc8ISOString(),
+  iteration: iteration,
+  version: newVersion,
+  action: "create",
+  type: "requirement",
+  id: "FR-003",
+  description: "Added MFA requirement"
+})
+
+// 8. Update state
+state.requirements = {
+  version: newVersion,
+  output_file: `.workflow/.cycle/${cycleId}.progress/ra/requirements.md`,
+  summary: {
+    functional_requirements: 3,
+    edge_cases: 2,
+    constraints: 3
+  }
+}
+
+Write(`.workflow/.cycle/${cycleId}.json`, JSON.stringify(state, null, 2))
+```
+
+## Advantages Comparison
+
+| Aspect | Incremental Update | Complete Rewrite + Archive |
+|--------|-------------------|---------------------------|
+| **Document Conciseness** | ❌ Gets longer | ✅ Always concise |
+| **Agent Parsing** | ❌ Must parse history | ✅ Only read current version |
+| **Maintenance Complexity** | ❌ High (version marking) | ✅ Low (direct rewrite) |
+| **File Size** | ❌ Bloats | ✅ Fixed |
+| **History Tracking** | ✅ In main document | ✅ In history/ + changes.log |
+| **Human Readability** | ❌ Must skip history | ✅ Direct current view |
+| **Token Usage** | ❌ More (read complete history) | ✅ Less (only read current) |
+
+## Archive Strategy
+
+### Auto-Archive Trigger
+
+```javascript
+function shouldArchive(currentVersion, state) {
+  // Archive on each version update
+  return currentVersion !== state.requirements?.version
+}
+
+function archiveOldVersion(cycleId, agent, filename, currentVersion) {
+  const currentFile = `.workflow/.cycle/${cycleId}.progress/${agent}/${filename}`
+  const archiveDir = `.workflow/.cycle/${cycleId}.progress/${agent}/history`
+  const archiveFile = `${archiveDir}/${filename.replace('.', `-v${currentVersion}.`)}`
+
+  // Ensure archive directory exists
+  mkdir -p ${archiveDir}
+
+  // Copy (not move, keep current file until new version written)
+  Copy(currentFile, archiveFile)
+
+  console.log(`Archived ${filename} v${currentVersion} to history/`)
+}
+```
+
+### Cleanup Strategy (Optional)
+
+Keep most recent N versions, delete older archives:
+
+```javascript
+function cleanupArchives(cycleId, agent, keepVersions = 3) {
+  const historyDir = `.workflow/.cycle/${cycleId}.progress/${agent}/history`
+  const archives = listFiles(historyDir)
+
+  // Sort by version number
+  archives.sort((a, b) => compareVersions(extractVersion(a), extractVersion(b)))
+
+  // Delete oldest versions (keep most recent N)
+  if (archives.length > keepVersions) {
+    const toDelete = archives.slice(0, archives.length - keepVersions)
+    toDelete.forEach(file => Delete(`${historyDir}/${file}`))
+  }
+}
+```
+
+## Importance of Changes.log
+
+Although main document is completely rewritten, **changes.log (NDJSON) permanently preserves complete history**:
+
+```bash
+# View all changes
+cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq .
+
+# View history of specific requirement
+cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq 'select(.id=="FR-001")'
+
+# View changes by iteration
+cat .workflow/.cycle/cycle-xxx.progress/ra/changes.log | jq 'select(.iteration==2)'
+```
+
+This way:
+- **Main Document**: Clear and concise (current state)
+- **Changes.log**: Complete traceability (all history)
+- **History/**: Snapshot backups (view on demand)
+
+## Recommended Implementation
+
+1. ✅ Adopt "Complete Rewrite" strategy
+2. ✅ Main document only keeps "previous version summary"
+3. ✅ Auto-archive to `history/` directory
+4. ✅ Changes.log (NDJSON) preserves complete history
+5. ✅ Optional: Keep most recent 3-5 historical versions
+
+This approach keeps documents concise (agent-friendly) while preserving complete history (audit-friendly).

COMMAND_REFERENCE.md

@@ -60,7 +60,7 @@ These commands orchestrate complex, multi-phase development processes, from plan
 
 | Command | Description |
 |---|---|
-| `/workflow:action-plan-verify`| Perform non-destructive cross-artifact consistency and quality analysis of IMPL_PLAN.md and task.json before execution. |
+| `/workflow:plan-verify`| Perform non-destructive cross-artifact consistency and quality analysis of IMPL_PLAN.md and task.json before execution. |
 
 ### Code Review Cycle
 

FAQ.md

@@ -665,7 +665,7 @@ CCW ensures dependencies are completed before dependent tasks execute.
 
 2. **Run verification**:
    ```bash
-   /workflow:action-plan-verify
+   /workflow:plan-verify
    ```
 
 3. **Automated reviews**:

GETTING_STARTED.md

@@ -153,7 +153,7 @@ After planning, validate your implementation plan for consistency and completene
 
 ```bash
 # After /workflow:plan completes, verify task quality
-/workflow:action-plan-verify
+/workflow:plan-verify
 
 # The command will:
 # 1. Check requirements coverage (all requirements have tasks)

GETTING_STARTED_CN.md

@@ -158,7 +158,7 @@
 
 ```bash
 # /workflow:plan 完成后，验证任务质量
-/workflow:action-plan-verify
+/workflow:plan-verify
 
 # 该命令将：
 # 1. 检查需求覆盖率（所有需求都有任务）

WORKFLOW_GUIDE.md

@@ -310,7 +310,7 @@ Return: Summary + Next Steps
 
 ```bash
 /workflow:plan "task description"   # Complete planning
-/workflow:action-plan-verify        # Verify plan (recommended)
+/workflow:plan-verify        # Verify plan (recommended)
 /workflow:execute                   # Execute
 /workflow:review                    # (optional) Review
 ```
@@ -354,7 +354,7 @@ Phase 6: TDD Structure Validation
 
 ```bash
 /workflow:tdd-plan "feature description"  # TDD planning
-/workflow:action-plan-verify              # Verify (recommended)
+/workflow:plan-verify              # Verify (recommended)
 /workflow:execute                         # Execute (follow Red-Green-Refactor)
 /workflow:tdd-verify                      # Verify TDD compliance
 ```
@@ -454,7 +454,7 @@ Phase 3: Synthesis Integration
 ```bash
 /workflow:brainstorm:auto-parallel "topic" [--count N] [--style-skill package]
 /workflow:plan --session {sessionId}     # Plan based on brainstorm results
-/workflow:action-plan-verify             # Verify
+/workflow:plan-verify             # Verify
 /workflow:execute                        # Execute
 ```
 

WORKFLOW_GUIDE_CN.md

@@ -309,7 +309,7 @@ Return: Summary + Next Steps
 
 ```bash
 /workflow:plan "task description"   # 完整规划
-/workflow:action-plan-verify        # 验证计划 (推荐)
+/workflow:plan-verify        # 验证计划 (推荐)
 /workflow:execute                   # 执行
 /workflow:review                    # (可选) 审查
 ```
@@ -353,7 +353,7 @@ Phase 6: TDD Structure Validation
 
 ```bash
 /workflow:tdd-plan "feature description"  # TDD 规划
-/workflow:action-plan-verify              # 验证 (推荐)
+/workflow:plan-verify              # 验证 (推荐)
 /workflow:execute                         # 执行 (遵循 Red-Green-Refactor)
 /workflow:tdd-verify                      # 验证 TDD 流程合规
 ```
@@ -453,7 +453,7 @@ Phase 3: Synthesis Integration
 ```bash
 /workflow:brainstorm:auto-parallel "topic" [--count N] [--style-skill package]
 /workflow:plan --session {sessionId}     # 基于头脑风暴结果规划
-/workflow:action-plan-verify             # 验证
+/workflow:plan-verify             # 验证
 /workflow:execute                        # 执行
 ```
 

ccw/src/commands/install.ts

@@ -335,7 +335,7 @@ export async function installCommand(options: InstallOptions): Promise<void> {
       type: 'confirm',
       name: 'installFix',
       message: 'Install Git Bash multi-line prompt fix? (recommended for Git Bash users)',
-      default: true
+      default: false
     }]);
 
     if (installFix) {

ccw/src/commands/issue.ts

@@ -233,6 +233,28 @@ const ISSUES_DIR = '.workflow/issues';
 
 // ============ Storage Layer (JSONL) ============
 
+/**
+ * Cached project root to avoid repeated git command execution
+ */
+let cachedProjectRoot: string | null = null;
+
+/**
+ * Clear cached project root (for testing)
+ */
+export function clearProjectRootCache(): void {
+  cachedProjectRoot = null;
+}
+
+/**
+ * Debug logging helper (enabled via CCW_DEBUG=true)
+ */
+const DEBUG = process.env.CCW_DEBUG === 'true';
+function debugLog(msg: string): void {
+  if (DEBUG) {
+    console.log(`[ccw:worktree] ${msg}`);
+  }
+}
+
 /**
  * Normalize path for comparison (handles Windows case sensitivity)
  */
@@ -271,7 +293,32 @@ function resolveMainRepoFromGitFile(gitFilePath: string): string | null {
  * This ensures .workflow/issues/ is always accessed from the main repo.
  */
 function getProjectRoot(): string {
-  // First, try to detect if we're in a git worktree using git commands
+  // Return cached result if available
+  if (cachedProjectRoot) {
+    debugLog(`Using cached project root: ${cachedProjectRoot}`);
+    return cachedProjectRoot;
+  }
+
+  debugLog(`Detecting project root from cwd: ${process.cwd()}`);
+
+  // Priority 1: Check CCW_MAIN_REPO environment variable
+  const envMainRepo = process.env.CCW_MAIN_REPO;
+  if (envMainRepo) {
+    debugLog(`Found CCW_MAIN_REPO env: ${envMainRepo}`);
+    const hasWorkflow = existsSync(join(envMainRepo, '.workflow'));
+    const hasGit = existsSync(join(envMainRepo, '.git'));
+
+    if (hasWorkflow || hasGit) {
+      debugLog(`CCW_MAIN_REPO validated (workflow=${hasWorkflow}, git=${hasGit})`);
+      cachedProjectRoot = envMainRepo;
+      return envMainRepo;
+    } else {
+      console.warn('[ccw] CCW_MAIN_REPO is set but path is invalid (no .workflow or .git)');
+      console.warn(`[ccw] Path: ${envMainRepo}`);
+    }
+  }
+
+  // Priority 2: Try to detect if we're in a git worktree using git commands
   try {
     // Get the common git directory (points to main repo's .git)
     const gitCommonDir = execSync('git rev-parse --git-common-dir', {
@@ -287,6 +334,9 @@ function getProjectRoot(): string {
       timeout: EXEC_TIMEOUTS.GIT_QUICK,
     }).trim();
 
+    debugLog(`Git common dir: ${gitCommonDir}`);
+    debugLog(`Git dir: ${gitDir}`);
+
     // Normalize paths for comparison (Windows case insensitive)
     const normalizedCommon = normalizePath(gitCommonDir);
     const normalizedGit = normalizePath(gitDir);
@@ -298,8 +348,12 @@ function getProjectRoot(): string {
       // .git directory's parent is the repo root
       const mainRepoRoot = resolve(absoluteCommonDir, '..');
 
+      debugLog(`Detected worktree, main repo: ${mainRepoRoot}`);
+
       // Verify .workflow or .git exists in main repo
       if (existsSync(join(mainRepoRoot, '.workflow')) || existsSync(join(mainRepoRoot, '.git'))) {
+        debugLog(`Main repo validated, returning: ${mainRepoRoot}`);
+        cachedProjectRoot = mainRepoRoot;
         return mainRepoRoot;
       }
     }
@@ -307,10 +361,11 @@ function getProjectRoot(): string {
     if (isExecTimeoutError(err)) {
       console.warn(`[issue] git rev-parse timed out after ${EXEC_TIMEOUTS.GIT_QUICK}ms; falling back to filesystem detection`);
     }
+    debugLog(`Git command failed, falling back to filesystem detection`);
     // Git command failed - fall through to manual detection
   }
 
-  // Standard detection with worktree file support: walk up to find .workflow or .git
+  // Priority 3: Standard detection with worktree file support: walk up to find .workflow or .git
   let dir = process.cwd();
   while (dir !== resolve(dir, '..')) {
     const gitPath = join(dir, '.git');
@@ -322,22 +377,45 @@ function getProjectRoot(): string {
         if (gitStat.isFile()) {
           // .git is a file - this is a worktree, try to resolve main repo
           const mainRepo = resolveMainRepoFromGitFile(gitPath);
-          if (mainRepo && existsSync(join(mainRepo, '.workflow'))) {
-            return mainRepo;
+          debugLog(`Parsed .git file, main repo: ${mainRepo}`);
+
+          if (mainRepo) {
+            // Verify main repo has .git directory (always true for main repo)
+            // Don't require .workflow - it may not exist yet in a new repo
+            const hasGit = existsSync(join(mainRepo, '.git'));
+            const hasWorkflow = existsSync(join(mainRepo, '.workflow'));
+
+            if (hasGit || hasWorkflow) {
+              if (!hasWorkflow) {
+                console.warn('[ccw] Worktree detected but main repo has no .workflow directory');
+                console.warn(`[ccw] Main repo: ${mainRepo}`);
+                console.warn('[ccw] Issue commands may fail until .workflow is created');
+                console.warn('[ccw] Set CCW_MAIN_REPO environment variable to override detection');
+              }
+              debugLog(`Main repo validated via .git file (git=${hasGit}, workflow=${hasWorkflow})`);
+              cachedProjectRoot = mainRepo;
+              return mainRepo;
+            }
           }
-          // If main repo doesn't have .workflow, fall back to current worktree
         }
       } catch {
         // stat failed, continue with normal logic
+        debugLog(`Failed to stat ${gitPath}, continuing`);
       }
     }
 
     if (existsSync(join(dir, '.workflow')) || existsSync(gitPath)) {
+      debugLog(`Found project root at: ${dir}`);
+      cachedProjectRoot = dir;
       return dir;
     }
     dir = resolve(dir, '..');
   }
-  return process.cwd();
+
+  debugLog(`No project root found, using cwd: ${process.cwd()}`);
+  const fallback = process.cwd();
+  cachedProjectRoot = fallback;
+  return fallback;
 }
 
 function getIssuesDir(): string {
@@ -1220,6 +1298,81 @@ async function solutionAction(issueId: string | undefined, options: IssueOptions
   }
 }
 
+/**
+ * solutions - Batch query solutions for multiple issues
+ * Usage: ccw issue solutions --status planned --brief
+ */
+async function solutionsAction(options: IssueOptions): Promise<void> {
+  // Get issues filtered by status
+  const issues = readIssues();
+  let targetIssues = issues;
+
+  if (options.status) {
+    const statuses = options.status.split(',').map((s: string) => s.trim());
+    targetIssues = issues.filter((i: Issue) => statuses.includes(i.status));
+  }
+
+  // Filter to only issues with bound_solution_id
+  const boundIssues = targetIssues.filter((i: Issue) => i.bound_solution_id);
+
+  if (boundIssues.length === 0) {
+    if (options.json || options.brief) {
+      console.log('[]');
+    } else {
+      console.log(chalk.yellow('No bound solutions found'));
+    }
+    return;
+  }
+
+  // Collect solutions for all bound issues
+  const allSolutions: Array<{
+    issue_id: string;
+    solution_id: string;
+    is_bound: boolean;
+    task_count: number;
+    files_touched: string[];
+    priority?: number;
+  }> = [];
+
+  for (const issue of boundIssues) {
+    const solutions = readSolutions(issue.id);
+    const boundSolution = solutions.find(s => s.id === issue.bound_solution_id);
+
+    if (boundSolution) {
+      const filesTouched = new Set<string>();
+      for (const task of boundSolution.tasks) {
+        if (task.modification_points) {
+          for (const mp of task.modification_points) {
+            if (mp.file) filesTouched.add(mp.file);
+          }
+        }
+      }
+
+      allSolutions.push({
+        issue_id: issue.id,
+        solution_id: boundSolution.id,
+        is_bound: true,
+        task_count: boundSolution.tasks.length,
+        files_touched: Array.from(filesTouched),
+        priority: issue.priority
+      });
+    }
+  }
+
+  // Brief mode: already minimal
+  if (options.brief || options.json) {
+    console.log(JSON.stringify(allSolutions, null, 2));
+    return;
+  }
+
+  // Human-readable output
+  console.log(chalk.bold.cyan(`\nBound Solutions (${allSolutions.length}):\n`));
+  for (const sol of allSolutions) {
+    console.log(`${chalk.green('◉')} ${sol.issue_id} → ${sol.solution_id}`);
+    console.log(chalk.gray(`  Tasks: ${sol.task_count}, Files: ${sol.files_touched.length}`));
+  }
+}
+
 /**
  * init - Initialize a new issue (manual ID)
  */
@@ -2832,6 +2985,9 @@ export async function issueCommand(
     case 'solution':
       await solutionAction(argsArray[0], options);
       break;
+    case 'solutions':
+      await solutionsAction(options);
+      break;
     case 'init':
       await initAction(argsArray[0], options);
       break;

ccw/src/core/routes/.gitignore

@@ -0,0 +1 @@
+.ace-tool/

ccw/src/core/routes/cli-routes.ts

@@ -35,6 +35,7 @@ import {
 import {
   loadClaudeCliTools,
   ensureClaudeCliTools,
+  ensureClaudeCliToolsAsync,
   saveClaudeCliTools,
   loadClaudeCliSettings,
   saveClaudeCliSettings,
@@ -329,16 +330,18 @@ export async function handleCliRoutes(ctx: RouteContext): Promise<boolean> {
 
   // API: Get all API endpoints (for --tool custom --model <id>)
   if (pathname === '/api/cli/endpoints' && req.method === 'GET') {
-    try {
-      // Use ensureClaudeCliTools to auto-create config if missing
-      const config = ensureClaudeCliTools(initialPath);
-      const endpoints = getApiEndpointsFromTools(config);
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ endpoints }));
-    } catch (err) {
-      res.writeHead(500, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ error: (err as Error).message }));
-    }
+    (async () => {
+      try {
+        // Use ensureClaudeCliToolsAsync to auto-create config with availability sync
+        const config = await ensureClaudeCliToolsAsync(initialPath);
+        const endpoints = getApiEndpointsFromTools(config);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ endpoints }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: (err as Error).message }));
+      }
+    })();
     return true;
   }
 
@@ -820,21 +823,23 @@ export async function handleCliRoutes(ctx: RouteContext): Promise<boolean> {
 
   // API: Get CLI Tools Config from .claude/cli-tools.json (with fallback to global)
   if (pathname === '/api/cli/tools-config' && req.method === 'GET') {
-    try {
-      // Use ensureClaudeCliTools to auto-create config if missing
-      const toolsConfig = ensureClaudeCliTools(initialPath);
-      const settingsConfig = loadClaudeCliSettings(initialPath);
-      const info = getClaudeCliToolsInfo(initialPath);
-      res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({
-        tools: toolsConfig,
-        settings: settingsConfig,
-        _configInfo: info
-      }));
-    } catch (err) {
-      res.writeHead(500, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ error: (err as Error).message }));
-    }
+    (async () => {
+      try {
+        // Use ensureClaudeCliToolsAsync to auto-create config with availability sync
+        const toolsConfig = await ensureClaudeCliToolsAsync(initialPath);
+        const settingsConfig = loadClaudeCliSettings(initialPath);
+        const info = getClaudeCliToolsInfo(initialPath);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({
+          tools: toolsConfig,
+          settings: settingsConfig,
+          _configInfo: info
+        }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: (err as Error).message }));
+      }
+    })();
     return true;
   }
 

ccw/src/templates/dashboard-js/components/navigation.js

@@ -299,7 +299,7 @@ async function refreshWorkspace() {
         });
 
         [...(data.liteTasks?.litePlan || []), ...(data.liteTasks?.liteFix || [])].forEach(s => {
-          const sessionKey = `lite-${s.session_id}`.replace(/[^a-zA-Z0-9-]/g, '-');
+          const sessionKey = `lite-${s.type}-${s.id}`.replace(/[^a-zA-Z0-9-]/g, '-');
           liteTaskDataStore[sessionKey] = s;
         });
 

ccw/src/templates/dashboard-js/components/notifications.js

@@ -823,7 +823,7 @@ async function refreshWorkspaceData(newData) {
   });
 
   [...(newData.liteTasks?.litePlan || []), ...(newData.liteTasks?.liteFix || [])].forEach(s => {
-    const key = `lite-${s.session_id}`.replace(/[^a-zA-Z0-9-]/g, '-');
+    const key = `lite-${s.type}-${s.id}`.replace(/[^a-zA-Z0-9-]/g, '-');
     liteTaskDataStore[key] = s;
   });
 

ccw/src/templates/dashboard-js/views/help.js

@@ -726,7 +726,7 @@ function getWorkflowGraphData(workflow) {
         { data: { id: 'start', label: ht('help.workflows.planFull.start') } },
         { data: { id: 'cli-analyze', label: ht('help.workflows.planFull.cliAnalyze') } },
         { data: { id: 'plan', label: '/workflow:plan' } },
-        { data: { id: 'verify', label: '/workflow:action-plan-verify' } },
+        { data: { id: 'verify', label: '/workflow:plan-verify' } },
         { data: { id: 'execute', label: '/workflow:execute' } },
         { data: { id: 'test', label: '/workflow:test-gen' } },
         { data: { id: 'review', label: '/workflow:review' } },

ccw/src/templates/dashboard-js/views/lite-tasks.js

@@ -2817,7 +2817,7 @@ function showLiteTaskDetailPage(sessionKey) {
       </div>
 
       <!-- Tab Content -->
-      <div class="detail-tab-content" id="liteDetailTabContent">
+      <div class="detail-tab-content active" id="liteDetailTabContent">
         ${renderLiteTasksTab(session, tasks, completed, inProgress, pending)}
       </div>
     </div>

ccw/src/templates/dashboard-js/views/session-detail.js

@@ -107,7 +107,7 @@ function showSessionDetailPage(sessionKey) {
       </div>
 
       <!-- Tab Content -->
-      <div class="detail-tab-content" id="detailTabContent">
+      <div class="detail-tab-content active" id="detailTabContent">
         ${renderTasksTab(session, tasks, completed, inProgress, pending)}
       </div>
     </div>

ccw/src/tools/claude-cli-tools.ts

@@ -268,7 +268,8 @@ function ensureToolTags(tool: Partial<ClaudeCliTool>): ClaudeCliTool {
     enabled: tool.enabled ?? true,
     primaryModel: tool.primaryModel,
     secondaryModel: tool.secondaryModel,
-    tags: tool.tags ?? []
+    tags: tool.tags ?? [],
+    envFile: tool.envFile
   };
 }
 
@@ -417,6 +418,56 @@ export function ensureClaudeCliTools(projectDir: string, createInProject: boolea
   }
 }
 
+/**
+ * Async version of ensureClaudeCliTools with automatic availability sync
+ * Creates default config in global ~/.claude directory and syncs with actual tool availability
+ * @param projectDir - Project directory path (used for reading existing project config)
+ * @param createInProject - DEPRECATED: Always creates in global dir. Kept for backward compatibility.
+ * @returns The config that was created/exists
+ */
+export async function ensureClaudeCliToolsAsync(projectDir: string, createInProject: boolean = false): Promise<ClaudeCliToolsConfig & { _source?: string }> {
+  const resolved = resolveConfigPath(projectDir);
+
+  if (resolved.source !== 'default') {
+    // Config exists, load and return it
+    return loadClaudeCliTools(projectDir);
+  }
+
+  // Config doesn't exist - create in global directory only
+  debugLog('[claude-cli-tools] Config not found, creating default cli-tools.json in ~/.claude');
+
+  const defaultConfig: ClaudeCliToolsConfig = { ...DEFAULT_TOOLS_CONFIG };
+
+  // Always create in global directory (user-level config), respecting CCW_DATA_DIR
+  const claudeHome = process.env.CCW_DATA_DIR
+    ? path.join(process.env.CCW_DATA_DIR, '.claude')
+    : path.join(os.homedir(), '.claude');
+  if (!fs.existsSync(claudeHome)) {
+    fs.mkdirSync(claudeHome, { recursive: true });
+  }
+  const globalPath = getGlobalConfigPath();
+  try {
+    fs.writeFileSync(globalPath, JSON.stringify(defaultConfig, null, 2), 'utf-8');
+    debugLog(`[claude-cli-tools] Created default config at: ${globalPath}`);
+
+    // Auto-sync with actual tool availability on first creation
+    try {
+      debugLog('[claude-cli-tools] Auto-syncing tool availability on first creation...');
+      const syncResult = await syncBuiltinToolsAvailability(projectDir);
+      debugLog(`[claude-cli-tools] Auto-sync completed: enabled=[${syncResult.changes.enabled.join(', ')}], disabled=[${syncResult.changes.disabled.join(', ')}]`);
+      return { ...syncResult.config, _source: 'global' };
+    } catch (syncErr) {
+      console.warn('[claude-cli-tools] Failed to auto-sync availability:', syncErr);
+      // Return default config if sync fails
+      return { ...defaultConfig, _source: 'global' };
+    }
+  } catch (err) {
+    console.error('[claude-cli-tools] Failed to create global config:', err);
+    return { ...defaultConfig, _source: 'default' };
+  }
+}
+
+
 /**
  * Load CLI tools configuration from global ~/.claude/cli-tools.json
  * Falls back to default config if not found.
@@ -438,9 +489,9 @@ export function loadClaudeCliTools(projectDir: string): ClaudeCliToolsConfig & {
     const migrated = migrateConfig(parsed, projectDir);
     const needsSave = migrated.version !== parsed.version;
 
-    // Merge tools with defaults and ensure required fields exist
+    // Load user-configured tools only (defaults NOT merged)
     const mergedTools: Record<string, ClaudeCliTool> = {};
-    for (const [key, tool] of Object.entries({ ...DEFAULT_TOOLS_CONFIG.tools, ...(migrated.tools || {}) })) {
+    for (const [key, tool] of Object.entries(migrated.tools || {})) {
       mergedTools[key] = {
         ...ensureToolTags(tool),
         type: tool.type ?? 'builtin',

ccw/src/tools/cli-config-manager.ts

@@ -29,6 +29,7 @@ export interface CliToolConfig {
   primaryModel: string;
   secondaryModel: string;
   tags?: string[];
+  envFile?: string | null;
 }
 
 export interface CliConfig {
@@ -184,7 +185,8 @@ export function getFullConfigResponse(baseDir: string): {
       enabled: tool.enabled,
       primaryModel: tool.primaryModel ?? '',
       secondaryModel: tool.secondaryModel ?? '',
-      tags: tool.tags
+      tags: tool.tags,
+      envFile: tool.envFile
     };
   }
 

ccw/src/tools/codex-lens.ts

@@ -83,8 +83,8 @@ function findLocalPackagePath(packageName: string): string | null {
     possiblePaths.push(join(cwdParent, packageName));
   }
 
+  // First pass: prefer non-node_modules paths (development environment)
   for (const localPath of possiblePaths) {
-    // Skip paths inside node_modules
     if (isInsideNodeModules(localPath)) {
       continue;
     }
@@ -94,8 +94,12 @@ function findLocalPackagePath(packageName: string): string | null {
     }
   }
 
-  if (!isDevEnvironment()) {
-    console.log(`[CodexLens] Running from node_modules - will try PyPI for ${packageName}`);
+  // Second pass: allow node_modules paths (NPM global install)
+  for (const localPath of possiblePaths) {
+    if (existsSync(join(localPath, 'pyproject.toml'))) {
+      console.log(`[CodexLens] Found ${packageName} in node_modules at: ${localPath}`);
+      return localPath;
+    }
   }
 
   return null;
@@ -666,14 +670,26 @@ async function bootstrapWithUv(gpuMode: GpuMode = 'cpu'): Promise<BootstrapResul
 
   if (!codexLensPath) {
     // codex-lens is a local-only package, not published to PyPI
+    // Generate dynamic paths for error message (cross-platform)
+    const possiblePaths = [
+      join(process.cwd(), 'codex-lens'),
+      join(__dirname, '..', '..', '..', 'codex-lens'),
+      join(homedir(), 'codex-lens'),
+    ];
+    const cwd = process.cwd();
+    const cwdParent = dirname(cwd);
+    if (cwdParent !== cwd) {
+      possiblePaths.push(join(cwdParent, 'codex-lens'));
+    }
+    const pathsList = possiblePaths.map(p => `   - ${p}`).join('\n');
+
     const errorMsg = `Cannot find codex-lens directory for local installation.\n\n` +
       `codex-lens is a local development package (not published to PyPI) and must be installed from local files.\n\n` +
       `To fix this:\n` +
-      `1. Ensure the 'codex-lens' directory exists in your project root\n` +
-      `   Expected location: D:\\Claude_dms3\\codex-lens\n` +
-      `2. Verify pyproject.toml exists: D:\\Claude_dms3\\codex-lens\\pyproject.toml\n` +
-      `3. Run ccw from the correct working directory (e.g., D:\\Claude_dms3)\n` +
-      `4. Or manually install: cd D:\\Claude_dms3\\codex-lens && pip install -e .[${extras.join(',')}]`;
+      `1. Ensure 'codex-lens' directory exists at one of these locations:\n${pathsList}\n` +
+      `2. Verify pyproject.toml exists in the codex-lens directory\n` +
+      `3. Run ccw from the correct working directory\n` +
+      `4. Or manually install: cd /path/to/codex-lens && pip install -e .[${extras.join(',')}]`;
     return { success: false, error: errorMsg };
   }
 
@@ -740,13 +756,26 @@ async function installSemanticWithUv(gpuMode: GpuMode = 'cpu'): Promise<Bootstra
   // Install with extras - UV handles dependency conflicts automatically
   if (!codexLensPath) {
     // codex-lens is a local-only package, not published to PyPI
+    // Generate dynamic paths for error message (cross-platform)
+    const possiblePaths = [
+      join(process.cwd(), 'codex-lens'),
+      join(__dirname, '..', '..', '..', 'codex-lens'),
+      join(homedir(), 'codex-lens'),
+    ];
+    const cwd = process.cwd();
+    const cwdParent = dirname(cwd);
+    if (cwdParent !== cwd) {
+      possiblePaths.push(join(cwdParent, 'codex-lens'));
+    }
+    const pathsList = possiblePaths.map(p => `   - ${p}`).join('\n');
+
     const errorMsg = `Cannot find codex-lens directory for local installation.\n\n` +
       `codex-lens is a local development package (not published to PyPI) and must be installed from local files.\n\n` +
       `To fix this:\n` +
-      `1. Ensure the 'codex-lens' directory exists in your project root\n` +
-      `2. Verify pyproject.toml exists in codex-lens directory\n` +
+      `1. Ensure 'codex-lens' directory exists at one of these locations:\n${pathsList}\n` +
+      `2. Verify pyproject.toml exists in the codex-lens directory\n` +
       `3. Run ccw from the correct working directory\n` +
-      `4. Or manually install: cd codex-lens && pip install -e .[${extras.join(',')}]`;
+      `4. Or manually install: cd /path/to/codex-lens && pip install -e .[${extras.join(',')}]`;
     return { success: false, error: errorMsg };
   }
 

ccw/src/tools/command-registry.test.ts

@@ -0,0 +1,669 @@
+/**
+ * CommandRegistry Tests
+ * 
+ * Test coverage:
+ * - YAML header parsing
+ * - Command metadata extraction
+ * - Directory detection (relative and home)
+ * - Caching mechanism
+ * - Batch operations
+ * - Categorization
+ * - Error handling
+ */
+
+import { CommandRegistry, createCommandRegistry, getAllCommandsSync, getCommandSync } from './command-registry';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+
+// Mock fs module
+jest.mock('fs');
+jest.mock('os');
+
+describe('CommandRegistry', () => {
+  const mockReadFileSync = fs.readFileSync as jest.MockedFunction<typeof fs.readFileSync>;
+  const mockExistsSync = fs.existsSync as jest.MockedFunction<typeof fs.existsSync>;
+  const mockReaddirSync = fs.readdirSync as jest.MockedFunction<typeof fs.readdirSync>;
+  const mockStatSync = fs.statSync as jest.MockedFunction<typeof fs.statSync>;
+  const mockHomedir = os.homedir as jest.MockedFunction<typeof os.homedir>;
+
+  // Sample YAML headers
+  const sampleLitePlanYaml = `---
+name: lite-plan
+description: Quick planning for simple features
+argument-hint: "\"feature description\""
+allowed-tools: Task(*), Read(*), Write(*), Bash(*)
+---
+
+# Content here`;
+
+  const sampleExecuteYaml = `---
+name: execute
+description: Execute implementation from plan
+argument-hint: "--resume-session=\"WFS-xxx\""
+allowed-tools: Task(*), Bash(*)
+---
+
+# Content here`;
+
+  const sampleTestYaml = `---
+name: test-cycle-execute
+description: Run tests and fix failures
+argument-hint: "--session=\"WFS-xxx\""
+allowed-tools: Task(*), Bash(*)
+---
+
+# Content here`;
+
+  const sampleReviewYaml = `---
+name: review
+description: Code review workflow
+argument-hint: "--session=\"WFS-xxx\""
+allowed-tools: Task(*), Read(*)
+---
+
+# Content here`;
+
+  beforeEach(() => {
+    jest.clearAllMocks();
+  });
+
+  describe('constructor & directory detection', () => {
+    it('should use provided command directory', () => {
+      const customDir = '/custom/path';
+      const registry = new CommandRegistry(customDir);
+      
+      expect((registry as any).commandDir).toBe(customDir);
+    });
+
+    it('should auto-detect relative .claude/commands/workflow directory', () => {
+      mockExistsSync.mockImplementation((path: string) => {
+        return path === '.claude/commands/workflow';
+      });
+
+      const registry = new CommandRegistry();
+      
+      expect((registry as any).commandDir).toBe('.claude/commands/workflow');
+      expect(mockExistsSync).toHaveBeenCalledWith('.claude/commands/workflow');
+    });
+
+    it('should auto-detect home directory ~/.claude/commands/workflow', () => {
+      mockExistsSync.mockImplementation((checkPath: string) => {
+        return checkPath === path.join('/home/user', '.claude', 'commands', 'workflow');
+      });
+      mockHomedir.mockReturnValue('/home/user');
+
+      const registry = new CommandRegistry();
+      
+      expect((registry as any).commandDir).toBe(
+        path.join('/home/user', '.claude', 'commands', 'workflow')
+      );
+    });
+
+    it('should return null if no command directory found', () => {
+      mockExistsSync.mockReturnValue(false);
+      mockHomedir.mockReturnValue('/home/user');
+
+      const registry = new CommandRegistry();
+      
+      expect((registry as any).commandDir).toBeNull();
+    });
+  });
+
+  describe('parseYamlHeader', () => {
+    it('should parse simple YAML header with Unix line endings', () => {
+      const yaml = `---
+name: test-command
+description: Test description
+argument-hint: "\"test\""
+allowed-tools: Task(*), Read(*)
+---
+
+Content here`;
+
+      const registry = new CommandRegistry('/fake/path');
+      const result = (registry as any).parseYamlHeader(yaml);
+
+      expect(result).toEqual({
+        name: 'test-command',
+        description: 'Test description',
+        'argument-hint': '"test"',
+        'allowed-tools': 'Task(*), Read(*)'
+      });
+    });
+
+    it('should parse YAML header with Windows line endings (\\r\\n)', () => {
+      const yaml = `---\r\nname: test-command\r\ndescription: Test\r\n---`;
+
+      const registry = new CommandRegistry('/fake/path');
+      const result = (registry as any).parseYamlHeader(yaml);
+
+      expect(result).toEqual({
+        name: 'test-command',
+        description: 'Test'
+      });
+    });
+
+    it('should handle quoted values', () => {
+      const yaml = `---
+name: "cmd"
+description: 'double quoted'
+---`;
+
+      const registry = new CommandRegistry('/fake/path');
+      const result = (registry as any).parseYamlHeader(yaml);
+
+      expect(result).toEqual({
+        name: 'cmd',
+        description: 'double quoted'
+      });
+    });
+
+    it('should parse allowed-tools and trim spaces', () => {
+      const yaml = `---
+name: test
+allowed-tools: Task(*), Read(*) , Write(*), Bash(*)
+---`;
+
+      const registry = new CommandRegistry('/fake/path');
+      const result = (registry as any).parseYamlHeader(yaml);
+
+      expect(result['allowed-tools']).toBe('Task(*), Read(*), Write(*), Bash(*)');
+    });
+
+    it('should skip comments and empty lines', () => {
+      const yaml = `---
+# This is a comment
+name: test-command
+
+# Another comment
+description: Test
+
+---`;
+
+      const registry = new CommandRegistry('/fake/path');
+      const result = (registry as any).parseYamlHeader(yaml);
+
+      expect(result).toEqual({
+        name: 'test-command',
+        description: 'Test'
+      });
+    });
+
+    it('should return null for missing YAML markers', () => {
+      const yaml = `name: test-command
+description: Test`;
+
+      const registry = new CommandRegistry('/fake/path');
+      const result = (registry as any).parseYamlHeader(yaml);
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null for malformed YAML', () => {
+      const yaml = `---
+invalid yaml content without colons
+---`;
+
+      const registry = new CommandRegistry('/fake/path');
+      const result = (registry as any).parseYamlHeader(yaml);
+
+      expect(result).toEqual({});
+    });
+  });
+
+  describe('getCommand', () => {
+    it('should get command metadata by name', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockImplementation((checkPath: string) => {
+        return checkPath === path.join(cmdDir, 'lite-plan.md');
+      });
+      mockReadFileSync.mockReturnValue(sampleLitePlanYaml);
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getCommand('lite-plan');
+
+      expect(result).toEqual({
+        name: 'lite-plan',
+        command: '/workflow:lite-plan',
+        description: 'Quick planning for simple features',
+        argumentHint: '"feature description"',
+        allowedTools: ['Task(*)', 'Read(*)', 'Write(*)', 'Bash(*)'],
+        filePath: path.join(cmdDir, 'lite-plan.md')
+      });
+    });
+
+    it('should normalize /workflow: prefix', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReadFileSync.mockReturnValue(sampleLitePlanYaml);
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getCommand('/workflow:lite-plan');
+
+      expect(result?.name).toBe('lite-plan');
+    });
+
+    it('should use cache for repeated requests', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReadFileSync.mockReturnValue(sampleLitePlanYaml);
+
+      const registry = new CommandRegistry(cmdDir);
+      
+      registry.getCommand('lite-plan');
+      registry.getCommand('lite-plan');
+
+      // readFileSync should only be called once due to cache
+      expect(mockReadFileSync).toHaveBeenCalledTimes(1);
+    });
+
+    it('should return null if command file not found', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(false);
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getCommand('nonexistent');
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null if no command directory', () => {
+      mockExistsSync.mockReturnValue(false);
+      mockHomedir.mockReturnValue('/home/user');
+
+      const registry = new CommandRegistry();
+      const result = registry.getCommand('lite-plan');
+
+      expect(result).toBeNull();
+    });
+
+    it('should return null if YAML header is invalid', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReadFileSync.mockReturnValue('No YAML header here');
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getCommand('lite-plan');
+
+      expect(result).toBeNull();
+    });
+
+    it('should parse allowedTools correctly', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReadFileSync.mockReturnValue(sampleExecuteYaml);
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getCommand('execute');
+
+      expect(result?.allowedTools).toEqual(['Task(*)', 'Bash(*)']);
+    });
+
+    it('should handle empty allowedTools', () => {
+      const yaml = `---
+name: minimal-cmd
+description: Minimal command
+---`;
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReadFileSync.mockReturnValue(yaml);
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getCommand('minimal-cmd');
+
+      expect(result?.allowedTools).toEqual([]);
+    });
+  });
+
+  describe('getCommands', () => {
+    it('should get multiple commands', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReadFileSync.mockImplementation((filePath: string) => {
+        if (filePath.includes('lite-plan')) return sampleLitePlanYaml;
+        if (filePath.includes('execute')) return sampleExecuteYaml;
+        return '';
+      });
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getCommands(['lite-plan', 'execute', 'nonexistent']);
+
+      expect(result.size).toBe(2);
+      expect(result.has('/workflow:lite-plan')).toBe(true);
+      expect(result.has('/workflow:execute')).toBe(true);
+    });
+
+    it('should skip nonexistent commands', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(false);
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getCommands(['nonexistent1', 'nonexistent2']);
+
+      expect(result.size).toBe(0);
+    });
+  });
+
+  describe('getAllCommandsSummary', () => {
+    it('should get all commands summary', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReaddirSync.mockReturnValue(['lite-plan.md', 'execute.md', 'test.md'] as any);
+      mockStatSync.mockReturnValue({ isDirectory: () => false } as any);
+      mockReadFileSync.mockImplementation((filePath: string) => {
+        if (filePath.includes('lite-plan')) return sampleLitePlanYaml;
+        if (filePath.includes('execute')) return sampleExecuteYaml;
+        if (filePath.includes('test')) return sampleTestYaml;
+        return '';
+      });
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getAllCommandsSummary();
+
+      expect(result.size).toBe(3);
+      expect(result.get('/workflow:lite-plan')).toEqual({
+        name: 'lite-plan',
+        description: 'Quick planning for simple features'
+      });
+    });
+
+    it('should skip directories', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReaddirSync.mockReturnValue(['file.md', 'directory'] as any);
+      mockStatSync.mockImplementation((filePath: string) => ({
+        isDirectory: () => filePath.includes('directory')
+      } as any));
+      mockReadFileSync.mockReturnValue(sampleLitePlanYaml);
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getAllCommandsSummary();
+
+      // Only file.md should be processed
+      expect(mockReadFileSync).toHaveBeenCalledTimes(1);
+    });
+
+    it('should skip files with invalid YAML headers', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReaddirSync.mockReturnValue(['valid.md', 'invalid.md'] as any);
+      mockStatSync.mockReturnValue({ isDirectory: () => false } as any);
+      mockReadFileSync.mockImplementation((filePath: string) => {
+        if (filePath.includes('valid')) return sampleLitePlanYaml;
+        return 'No YAML header';
+      });
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getAllCommandsSummary();
+
+      expect(result.size).toBe(1);
+    });
+
+    it('should return empty map if no command directory', () => {
+      mockExistsSync.mockReturnValue(false);
+      mockHomedir.mockReturnValue('/home/user');
+
+      const registry = new CommandRegistry();
+      const result = registry.getAllCommandsSummary();
+
+      expect(result.size).toBe(0);
+    });
+
+    it('should handle directory read errors gracefully', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReaddirSync.mockImplementation(() => {
+        throw new Error('Permission denied');
+      });
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getAllCommandsSummary();
+
+      expect(result.size).toBe(0);
+    });
+  });
+
+  describe('getAllCommandsByCategory', () => {
+    it('should categorize commands by name patterns', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReaddirSync.mockReturnValue(['lite-plan.md', 'execute.md', 'test-cycle-execute.md', 'review.md'] as any);
+      mockStatSync.mockReturnValue({ isDirectory: () => false } as any);
+      mockReadFileSync.mockImplementation((filePath: string) => {
+        if (filePath.includes('lite-plan')) return sampleLitePlanYaml;
+        if (filePath.includes('execute')) return sampleExecuteYaml;
+        if (filePath.includes('test')) return sampleTestYaml;
+        if (filePath.includes('review')) return sampleReviewYaml;
+        return '';
+      });
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getAllCommandsByCategory();
+
+      expect(result.planning.length).toBe(1);
+      expect(result.execution.length).toBe(1);
+      expect(result.testing.length).toBe(1);
+      expect(result.review.length).toBe(1);
+      expect(result.other.length).toBe(0);
+
+      expect(result.planning[0].name).toBe('lite-plan');
+      expect(result.execution[0].name).toBe('execute');
+    });
+
+    it('should handle commands matching multiple patterns', () => {
+      const yamlMultiMatch = `---
+name: test-plan
+description: TDD planning
+allowed-tools: Task(*)
+---`;
+
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReaddirSync.mockReturnValue(['test-plan.md'] as any);
+      mockStatSync.mockReturnValue({ isDirectory: () => false } as any);
+      mockReadFileSync.mockReturnValue(yamlMultiMatch);
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getAllCommandsByCategory();
+
+      // Should match 'plan' pattern (planning)
+      expect(result.planning.length).toBe(1);
+    });
+  });
+
+  describe('toJSON', () => {
+    it('should serialize cached commands to JSON', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReadFileSync.mockReturnValue(sampleLitePlanYaml);
+
+      const registry = new CommandRegistry(cmdDir);
+      registry.getCommand('lite-plan');
+      
+      const json = registry.toJSON();
+
+      expect(json['/workflow:lite-plan']).toEqual({
+        name: 'lite-plan',
+        command: '/workflow:lite-plan',
+        description: 'Quick planning for simple features',
+        argumentHint: '"feature description"',
+        allowedTools: ['Task(*)', 'Read(*)', 'Write(*)', 'Bash(*)'],
+        filePath: path.join(cmdDir, 'lite-plan.md')
+      });
+    });
+
+    it('should only include cached commands', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReadFileSync.mockImplementation((filePath: string) => {
+        if (filePath.includes('lite-plan')) return sampleLitePlanYaml;
+        return sampleExecuteYaml;
+      });
+
+      const registry = new CommandRegistry(cmdDir);
+      registry.getCommand('lite-plan');
+      // Don't call getCommand for 'execute'
+      
+      const json = registry.toJSON();
+
+      expect(Object.keys(json).length).toBe(1);
+      expect(json['/workflow:lite-plan']).toBeDefined();
+      expect(json['/workflow:execute']).toBeUndefined();
+    });
+  });
+
+  describe('exported functions', () => {
+    it('createCommandRegistry should create new instance', () => {
+      mockExistsSync.mockReturnValue(true);
+
+      const registry = createCommandRegistry('/custom/path');
+      
+      expect((registry as any).commandDir).toBe('/custom/path');
+    });
+
+    it('getAllCommandsSync should return all commands', () => {
+      mockExistsSync.mockReturnValue(true);
+      mockReaddirSync.mockReturnValue(['lite-plan.md'] as any);
+      mockStatSync.mockReturnValue({ isDirectory: () => false } as any);
+      mockReadFileSync.mockReturnValue(sampleLitePlanYaml);
+      mockHomedir.mockReturnValue('/home/user');
+
+      const result = getAllCommandsSync();
+
+      expect(result.size).toBeGreaterThanOrEqual(1);
+    });
+
+    it('getCommandSync should return specific command', () => {
+      mockExistsSync.mockReturnValue(true);
+      mockReadFileSync.mockReturnValue(sampleLitePlanYaml);
+      mockHomedir.mockReturnValue('/home/user');
+
+      const result = getCommandSync('lite-plan');
+
+      expect(result?.name).toBe('lite-plan');
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle file read errors', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReadFileSync.mockImplementation(() => {
+        throw new Error('File read error');
+      });
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getCommand('lite-plan');
+
+      expect(result).toBeNull();
+    });
+
+    it('should handle YAML parsing errors', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      // Return something that will cause parsing to fail
+      mockReadFileSync.mockReturnValue('---\ninvalid: : : yaml\n---');
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getCommand('lite-plan');
+
+      // Should return null since name is not in result
+      expect(result).toBeNull();
+    });
+
+    it('should handle empty command directory', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReaddirSync.mockReturnValue([] as any);
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getAllCommandsSummary();
+
+      expect(result.size).toBe(0);
+    });
+
+    it('should handle non-md files in command directory', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReaddirSync.mockReturnValue(['lite-plan.md', 'readme.txt', '.gitignore'] as any);
+      mockStatSync.mockReturnValue({ isDirectory: () => false } as any);
+      mockReadFileSync.mockReturnValue(sampleLitePlanYaml);
+
+      const registry = new CommandRegistry(cmdDir);
+      const result = registry.getAllCommandsSummary();
+
+      expect(result.size).toBe(1);
+    });
+  });
+
+  describe('integration tests', () => {
+    it('should work with full workflow', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReaddirSync.mockReturnValue(['lite-plan.md', 'execute.md', 'test-cycle-execute.md'] as any);
+      mockStatSync.mockReturnValue({ isDirectory: () => false } as any);
+      mockReadFileSync.mockImplementation((filePath: string) => {
+        if (filePath.includes('lite-plan')) return sampleLitePlanYaml;
+        if (filePath.includes('execute')) return sampleExecuteYaml;
+        if (filePath.includes('test')) return sampleTestYaml;
+        return '';
+      });
+
+      const registry = new CommandRegistry(cmdDir);
+
+      // Get all summary
+      const summary = registry.getAllCommandsSummary();
+      expect(summary.size).toBe(3);
+
+      // Get by category
+      const byCategory = registry.getAllCommandsByCategory();
+      expect(byCategory.planning.length).toBe(1);
+      expect(byCategory.execution.length).toBe(1);
+      expect(byCategory.testing.length).toBe(1);
+
+      // Get specific command
+      const cmd = registry.getCommand('lite-plan');
+      expect(cmd?.name).toBe('lite-plan');
+
+      // Get multiple commands
+      const multiple = registry.getCommands(['lite-plan', 'execute']);
+      expect(multiple.size).toBe(2);
+
+      // Convert to JSON
+      const json = registry.toJSON();
+      expect(Object.keys(json).length).toBeGreaterThan(0);
+    });
+
+    it('should maintain cache across operations', () => {
+      const cmdDir = '/workflows';
+      mockExistsSync.mockReturnValue(true);
+      mockReaddirSync.mockReturnValue(['lite-plan.md', 'execute.md'] as any);
+      mockStatSync.mockReturnValue({ isDirectory: () => false } as any);
+      mockReadFileSync.mockImplementation((filePath: string) => {
+        if (filePath.includes('lite-plan')) return sampleLitePlanYaml;
+        return sampleExecuteYaml;
+      });
+
+      const registry = new CommandRegistry(cmdDir);
+
+      // First call
+      registry.getCommand('lite-plan');
+      const initialCallCount = mockReadFileSync.mock.calls.length;
+
+      // getAllCommandsSummary will read all files
+      registry.getAllCommandsSummary();
+      const afterSummaryCallCount = mockReadFileSync.mock.calls.length;
+
+      // Second getCommand should use cache
+      registry.getCommand('lite-plan');
+      const finalCallCount = mockReadFileSync.mock.calls.length;
+
+      // lite-plan.md should only be read twice:
+      // 1. Initial getCommand
+      // 2. getAllCommandsSummary (must read all files)
+      // Not again in second getCommand due to cache
+      expect(finalCallCount).toBe(afterSummaryCallCount);
+    });
+  });
+});

ccw/src/tools/command-registry.ts

@@ -0,0 +1,308 @@
+/**
+ * Command Registry Tool
+ *
+ * Features:
+ * 1. Scan and parse YAML headers from command files
+ * 2. Read from global ~/.claude/commands/workflow directory
+ * 3. Support on-demand extraction (not full scan)
+ * 4. Cache parsed metadata for performance
+ */
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'fs';
+import { join } from 'path';
+import { homedir } from 'os';
+
+export interface CommandMetadata {
+  name: string;
+  command: string;
+  description: string;
+  argumentHint: string;
+  allowedTools: string[];
+  filePath: string;
+}
+
+export interface CommandSummary {
+  name: string;
+  description: string;
+}
+
+export class CommandRegistry {
+  private commandDir: string | null;
+  private cache: Map<string, CommandMetadata>;
+
+  constructor(commandDir?: string) {
+    this.cache = new Map();
+
+    if (commandDir) {
+      this.commandDir = commandDir;
+    } else {
+      this.commandDir = this.findCommandDir();
+    }
+  }
+
+  /**
+   * Auto-detect ~/.claude/commands/workflow directory
+   */
+  private findCommandDir(): string | null {
+    // Try relative to current working directory
+    const relativePath = join('.claude', 'commands', 'workflow');
+    if (existsSync(relativePath)) {
+      return relativePath;
+    }
+
+    // Try user home directory
+    const homeDir = homedir();
+    const homeCommandDir = join(homeDir, '.claude', 'commands', 'workflow');
+    if (existsSync(homeCommandDir)) {
+      return homeCommandDir;
+    }
+
+    return null;
+  }
+
+  /**
+   * Parse YAML header (simplified version)
+   *
+   * Limitations:
+   * - Only supports simple key: value pairs (single-line values)
+   * - No support for multi-line values, nested objects, complex lists
+   * - allowed-tools field converts comma-separated strings to arrays
+   */
+  private parseYamlHeader(content: string): Record<string, any> | null {
+    // Handle Windows line endings (\r\n)
+    const match = content.match(/^---[\r\n]+([\s\S]*?)[\r\n]+---/);
+    if (!match) return null;
+
+    const yamlContent = match[1];
+    const result: Record<string, any> = {};
+
+    try {
+      const lines = yamlContent.split(/[\r\n]+/);
+      for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#')) continue; // Skip empty lines and comments
+
+        const colonIndex = trimmed.indexOf(':');
+        if (colonIndex === -1) continue;
+
+        const key = trimmed.substring(0, colonIndex).trim();
+        let value = trimmed.substring(colonIndex + 1).trim();
+
+        if (!key) continue; // Skip invalid lines
+
+        // Remove quotes (single or double)
+        let cleanValue = value.replace(/^["']|["']$/g, '');
+
+        // Special handling for allowed-tools field: convert to array
+        // Supports format: "Read, Write, Bash" or "Read,Write,Bash"
+        if (key === 'allowed-tools') {
+          cleanValue = cleanValue
+            .split(',')
+            .map(t => t.trim())
+            .filter(t => t)
+            .join(','); // Keep as comma-separated for now, will convert in getCommand
+        }
+
+        result[key] = cleanValue;
+      }
+    } catch (error) {
+      const err = error as Error;
+      console.error('YAML parsing error:', err.message);
+      return null;
+    }
+
+    return result;
+  }
+
+  /**
+   * Get single command metadata
+   * @param commandName Command name (e.g., "lite-plan" or "/workflow:lite-plan")
+   * @returns Command metadata or null
+   */
+  public getCommand(commandName: string): CommandMetadata | null {
+    if (!this.commandDir) {
+      console.error('ERROR: ~/.claude/commands/workflow directory not found');
+      return null;
+    }
+
+    // Normalize command name
+    const normalized = commandName.startsWith('/workflow:')
+      ? commandName.substring('/workflow:'.length)
+      : commandName;
+
+    // Check cache
+    const cached = this.cache.get(normalized);
+    if (cached) {
+      return cached;
+    }
+
+    // Read command file
+    const filePath = join(this.commandDir, `${normalized}.md`);
+    if (!existsSync(filePath)) {
+      return null;
+    }
+
+    try {
+      const content = readFileSync(filePath, 'utf-8');
+      const header = this.parseYamlHeader(content);
+
+      if (header && header.name) {
+        const toolsStr = header['allowed-tools'] || '';
+        const allowedTools = toolsStr
+          .split(',')
+          .map((t: string) => t.trim())
+          .filter((t: string) => t);
+
+        const result: CommandMetadata = {
+          name: header.name,
+          command: `/workflow:${header.name}`,
+          description: header.description || '',
+          argumentHint: header['argument-hint'] || '',
+          allowedTools: allowedTools,
+          filePath: filePath
+        };
+
+        // Cache result
+        this.cache.set(normalized, result);
+        return result;
+      }
+    } catch (error) {
+      const err = error as Error;
+      console.error(`Failed to read command ${filePath}:`, err.message);
+    }
+
+    return null;
+  }
+
+  /**
+   * Get multiple commands metadata
+   * @param commandNames Array of command names
+   * @returns Map of command metadata
+   */
+  public getCommands(commandNames: string[]): Map<string, CommandMetadata> {
+    const result = new Map<string, CommandMetadata>();
+
+    for (const name of commandNames) {
+      const cmd = this.getCommand(name);
+      if (cmd) {
+        result.set(cmd.command, cmd);
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Get all commands' names and descriptions
+   * @returns Map of command names to summaries
+   */
+  public getAllCommandsSummary(): Map<string, CommandSummary> {
+    const result = new Map<string, CommandSummary>();
+
+    if (!this.commandDir) {
+      return result;
+    }
+
+    try {
+      const files = readdirSync(this.commandDir);
+
+      for (const file of files) {
+        if (!file.endsWith('.md')) continue;
+
+        const filePath = join(this.commandDir, file);
+        const stat = statSync(filePath);
+
+        if (stat.isDirectory()) continue;
+
+        try {
+          const content = readFileSync(filePath, 'utf-8');
+          const header = this.parseYamlHeader(content);
+
+          if (header && header.name) {
+            const commandName = `/workflow:${header.name}`;
+            result.set(commandName, {
+              name: header.name,
+              description: header.description || ''
+            });
+          }
+        } catch (error) {
+          // Skip files that fail to read
+          continue;
+        }
+      }
+    } catch (error) {
+      // Return empty map if directory read fails
+      return result;
+    }
+
+    return result;
+  }
+
+  /**
+   * Get all commands organized by category/tags
+   */
+  public getAllCommandsByCategory(): Record<string, CommandMetadata[]> {
+    const summary = this.getAllCommandsSummary();
+    const result: Record<string, CommandMetadata[]> = {
+      planning: [],
+      execution: [],
+      testing: [],
+      review: [],
+      other: []
+    };
+
+    for (const [cmdName] of summary) {
+      const cmd = this.getCommand(cmdName);
+      if (cmd) {
+        // Categorize based on command name patterns
+        if (cmd.name.includes('plan')) {
+          result.planning.push(cmd);
+        } else if (cmd.name.includes('execute')) {
+          result.execution.push(cmd);
+        } else if (cmd.name.includes('test')) {
+          result.testing.push(cmd);
+        } else if (cmd.name.includes('review')) {
+          result.review.push(cmd);
+        } else {
+          result.other.push(cmd);
+        }
+      }
+    }
+
+    return result;
+  }
+
+  /**
+   * Convert to JSON for serialization
+   */
+  public toJSON(): Record<string, any> {
+    const result: Record<string, CommandMetadata> = {};
+    for (const [key, value] of this.cache) {
+      result[`/workflow:${key}`] = value;
+    }
+    return result;
+  }
+}
+
+/**
+ * Export function for direct usage
+ */
+export function createCommandRegistry(commandDir?: string): CommandRegistry {
+  return new CommandRegistry(commandDir);
+}
+
+/**
+ * Export function to get all commands
+ */
+export function getAllCommandsSync(): Map<string, CommandSummary> {
+  const registry = new CommandRegistry();
+  return registry.getAllCommandsSummary();
+}
+
+/**
+ * Export function to get specific command
+ */
+export function getCommandSync(name: string): CommandMetadata | null {
+  const registry = new CommandRegistry();
+  return registry.getCommand(name);
+}

ccw/src/tools/index.ts

@@ -378,3 +378,7 @@ export { registerTool };
 
 // Export ToolSchema type
 export type { ToolSchema };
+
+// Export CommandRegistry for direct import
+export { CommandRegistry, createCommandRegistry, getAllCommandsSync, getCommandSync } from './command-registry.js';
+export type { CommandMetadata, CommandSummary } from './command-registry.js';

package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "claude-code-workflow",
-  "version": "6.3.33",
+  "version": "6.3.44",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "claude-code-workflow",
-      "version": "6.3.33",
+      "version": "6.3.44",
       "license": "MIT",
       "dependencies": {
         "@modelcontextprotocol/sdk": "^1.0.4",

package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-workflow",
-  "version": "6.3.38",
+  "version": "6.3.46",
   "description": "JSON-driven multi-agent development framework with intelligent CLI orchestration (Gemini/Qwen/Codex), context-first architecture, and automated workflow execution",
   "type": "module",
   "main": "ccw/src/index.js",