claude-code-workflow 7.2.15 → 7.2.16

package/.codex/skills/team-roadmap-dev/roles/coordinator/commands/roadmap-discuss.md

@@ -0,0 +1,243 @@
+# Command: roadmap-discuss
+
+Interactive roadmap discussion with the user. This is the KEY coordinator command -- no work begins until the roadmap is agreed upon.
+
+## Purpose
+
+Discuss project roadmap with the user using project-tech.json + specs/*.md as context. Elicit phases, requirements, success criteria, and execution preferences. Produces `roadmap.md` and `config.json` as session artifacts.
+
+## When to Use
+
+- Phase 2 of coordinator lifecycle (after init prerequisites, before dispatch)
+- Called exactly once per session (re-entry updates existing roadmap)
+
+## Strategy
+
+Direct interaction via request_user_input. No delegation to workers or CLI tools. Coordinator handles this entirely.
+
+## Parameters
+
+| Parameter | Source | Description |
+|-----------|--------|-------------|
+| `sessionFolder` | From coordinator Phase 1 | Session artifact directory |
+| `taskDescription` | From coordinator Phase 1 | User's original task description |
+| `projectTech` | Loaded in Phase 1 | Parsed project-tech.json |
+| `projectGuidelines` | Loaded in Phase 1 | Parsed specs/*.md (nullable) |
+| `autoYes` | From -y/--yes flag | Skip interactive prompts, use defaults |
+
+## Execution Steps
+
+### Step 1: Load Project Context
+
+```javascript
+// Already loaded by coordinator Phase 1, but verify availability
+const projectTech = JSON.parse(Read('.workflow/project-tech.json'))
+let projectGuidelines = null
+try {
+  projectGuidelines = JSON.parse(Read('.workflow/specs/*.md'))
+} catch {}
+```
+
+### Step 2: Present Project Overview to User
+
+```javascript
+// Summarize what we know about the project
+const overview = `[coordinator] Project context loaded.
+- Project: ${projectTech.project_name}
+- Tech Stack: ${projectTech.tech_stack?.join(', ')}
+- Task: ${taskDescription}
+${projectGuidelines ? `- Guidelines: ${projectGuidelines.conventions?.length || 0} conventions loaded` : '- Guidelines: not configured'}`
+
+// Display overview (via direct output, not request_user_input)
+```
+
+### Step 3: Confirm Project Goal and Scope
+
+```javascript
+// Skip if taskDescription is already detailed enough, or autoYes
+if (!autoYes && !taskDescription) {
+  request_user_input({
+    prompt: "What is the project goal and scope for this session?"
+  })
+}
+// Store response as `projectGoal`
+const projectGoal = taskDescription || userResponse
+```
+
+### Step 4: Ask Execution Mode
+
+```javascript
+if (!autoYes) {
+  request_user_input({
+    prompt: "How should phase transitions be handled?\n\nOptions:\n1. interactive - Ask for confirmation at each phase transition\n2. yolo - Auto-execute all phases without stopping\n3. custom - Choose which gates require confirmation"
+  })
+} else {
+  mode = "yolo"
+}
+
+// If "custom" selected, follow up with gate selection:
+if (mode === "custom") {
+  request_user_input({
+    prompt: "Which gates should require confirmation? (select multiple)\n\n1. plan_check - Review plan before execution\n2. verifier - Review verification results before next phase\n3. gap_closure - Confirm gap closure before re-execution"
+  })
+}
+```
+
+### Step 5: Ask Analysis Depth
+
+```javascript
+if (!autoYes) {
+  request_user_input({
+    prompt: "How thorough should the analysis be?\n\nOptions:\n1. quick - Fast scan, minimal context gathering (small tasks)\n2. standard - Balanced analysis with key context (default)\n3. comprehensive - Deep analysis, full codebase exploration (large refactors)"
+  })
+} else {
+  depth = "standard"
+}
+```
+
+### Step 6: Analyze Codebase and Generate Phased Roadmap
+
+```javascript
+// Use Gemini CLI (or CLI exploration tool) to analyze the codebase
+// and generate a phased breakdown based on goal + project context
+Bash({
+  command: `ccw cli -p "PURPOSE: Analyze codebase and generate phased execution roadmap for: ${projectGoal}
+TASK: \
+  - Scan project structure and identify affected modules \
+  - Break goal into sequential phases (max 5) \
+  - Each phase: goal, requirements (REQ-IDs), success criteria (2-5 testable behaviors) \
+  - Order phases by dependency (foundational first)
+MODE: analysis
+CONTEXT: @**/* | Memory: Tech stack: ${projectTech.tech_stack?.join(', ')}
+EXPECTED: Phased roadmap in markdown with REQ-IDs and testable success criteria
+CONSTRAINTS: Max 5 phases | Each phase independently verifiable | No implementation details" \
+  --tool gemini --mode analysis --rule planning-breakdown-task-steps`,
+  timeout: 300000
+})
+
+// Parse the CLI output into structured phases
+```
+
+### Step 7: Present Roadmap Draft for Confirmation
+
+```javascript
+// Display the generated roadmap to user
+// Output the roadmap content directly, then ask for adjustments
+
+request_user_input({
+  prompt: "Review the roadmap above. Any adjustments needed?\n\nOptions:\n1. Looks good, proceed - Accept roadmap as-is\n2. Adjust phases - I want to modify the phase breakdown\n3. Add requirements - I want to add missing requirements\n4. Change scope - Narrow or expand the scope"
+})
+
+// If user requests adjustments, incorporate feedback and re-present
+// Loop until user confirms "Looks good, proceed"
+```
+
+### Step 8: Generate Session Artifacts
+
+#### roadmap.md
+
+```javascript
+Write(`${sessionFolder}/roadmap.md`, roadmapContent)
+```
+
+**roadmap.md format**:
+
+```markdown
+# Roadmap: {projectGoal}
+
+Generated: {date}
+Session: {sessionFolder}
+Depth: {depth}
+
+## Phase 1: {phase title}
+
+**Goal**: {one-line goal}
+
+**Requirements**:
+- REQ-101: {requirement description}
+- REQ-102: {requirement description}
+
+**Success Criteria**:
+- [ ] {testable behavior 1}
+- [ ] {testable behavior 2}
+- [ ] {testable behavior 3}
+
+**Plan Count**: TBD
+
+---
+
+## Phase 2: {phase title}
+
+**Goal**: {one-line goal}
+
+**Requirements**:
+- REQ-201: {requirement description}
+
+**Success Criteria**:
+- [ ] {testable behavior 1}
+- [ ] {testable behavior 2}
+
+**Plan Count**: TBD
+
+---
+
+(... additional phases ...)
+```
+
+**REQ-ID Convention**: `REQ-{phase}{seq}` (e.g., REQ-101 = Phase 1, requirement 1)
+
+#### config.json
+
+```javascript
+Write(`${sessionFolder}/config.json`, JSON.stringify({
+  mode: mode,           // "interactive" | "yolo" | "custom"
+  depth: depth,         // "quick" | "standard" | "comprehensive"
+  auto_advance: mode === "yolo",
+  gates: {
+    plan_check: mode === "interactive" || (mode === "custom" && customGates.includes("plan_check")),
+    verifier: mode === "interactive" || (mode === "custom" && customGates.includes("verifier")),
+    gap_closure: mode === "interactive" || (mode === "custom" && customGates.includes("gap_closure"))
+  }
+}, null, 2))
+```
+
+**config.json format**:
+
+```json
+{
+  "mode": "interactive",
+  "depth": "standard",
+  "auto_advance": false,
+  "gates": {
+    "plan_check": true,
+    "verifier": true,
+    "gap_closure": true
+  }
+}
+```
+
+### Step 9: Update state.md
+
+```javascript
+Edit(`${sessionFolder}/state.md`, {
+  old_string: "- Phase: 0 (Roadmap Discussion)\n- Status: initializing",
+  new_string: `- Phase: 1\n- Status: ready_to_dispatch\n- Roadmap: confirmed (${phaseCount} phases)\n- Mode: ${mode}\n- Depth: ${depth}`
+})
+```
+
+## Output
+
+| Artifact | Path | Description |
+|----------|------|-------------|
+| roadmap.md | `{sessionFolder}/roadmap.md` | Phased plan with REQ-IDs and success criteria |
+| config.json | `{sessionFolder}/config.json` | Execution preferences |
+| state.md | `{sessionFolder}/state.md` | Updated with phase transition |
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| User provides no goal | Re-prompt with examples |
+| CLI analysis fails | Retry with simpler prompt, or ask user to describe phases manually |
+| User keeps adjusting roadmap | Max 5 adjustment rounds, then proceed with latest version |
+| autoYes flag set | Skip all request_user_input calls, use defaults: mode=yolo, depth=standard |

package/.codex/skills/team-roadmap-dev/roles/coordinator/role.md

@@ -0,0 +1,303 @@
+# Coordinator Role
+
+Orchestrate the roadmap-driven development workflow: init prerequisites -> roadmap discussion with user -> phase dispatch -> monitoring -> transitions -> completion. Coordinator is the ONLY role that interacts with humans.
+
+## Identity
+
+- **Name**: `coordinator` | **Tag**: `[coordinator]`
+- **Responsibility**: Orchestration (parse requirements -> discuss roadmap -> create team -> dispatch tasks -> monitor progress -> report results)
+
+## Boundaries
+
+### MUST
+
+- All outputs must carry `[coordinator]` prefix
+- Handle ALL human interaction (request_user_input) -- workers never interact with user
+- Ensure init prerequisites before starting (project-tech.json)
+- Discuss roadmap with user before dispatching work
+- Manage state.md updates at every phase transition
+- Route verifier gap results to planner for closure
+- Parse user requirements and clarify ambiguous inputs via request_user_input
+- Create team and spawn worker team members in background
+- Dispatch tasks with proper dependency chains
+- Monitor progress via worker callbacks and route messages
+- Maintain session state persistence
+
+### MUST NOT
+
+- Execute any business tasks (code, analysis, testing, verification)
+- Call CLI tools for code generation, exploration, or planning
+- Modify source code or generate implementation artifacts
+- Bypass worker roles to do work directly
+- Skip roadmap discussion phase
+- Modify task outputs (workers own their deliverables)
+- Skip dependency validation when creating task chains
+
+> **Core principle**: coordinator is the orchestrator, not the executor. All actual work must be delegated to worker roles via tasks.json entries.
+
+---
+
+## Command Execution Protocol
+
+When coordinator needs to execute a command (dispatch, monitor, pause, resume):
+
+1. **Read the command file**: `roles/coordinator/commands/<command-name>.md`
+2. **Follow the workflow** defined in the command file (Phase 2-4 structure)
+3. **Commands are inline execution guides** -- NOT separate agents or subprocesses
+4. **Execute synchronously** -- complete the command workflow before proceeding
+
+Example:
+```
+Phase 3 needs task dispatch
+  -> Read roles/coordinator/commands/dispatch.md
+  -> Execute Phase 2 (Context Loading)
+  -> Execute Phase 3 (Task Chain Creation)
+  -> Execute Phase 4 (Validation)
+  -> Continue to Phase 4
+```
+
+---
+
+## Entry Router
+
+When coordinator is invoked, detect invocation type:
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Worker callback | Message contains role tag [planner], [executor], [verifier] | -> handleCallback |
+| Resume mode | Arguments contain `--resume` | -> @commands/resume.md: load session, re-enter monitor |
+| Status check | Arguments contain "check" or "status" | -> handleCheck |
+| Manual resume | Arguments contain "resume" or "continue" | -> handleResume |
+| Pipeline complete | All tasks have status "completed" | -> handleComplete |
+| Interrupted session | Active/paused session exists | -> Phase 0 (Session Resume Check) |
+| New session | None of above | -> Phase 1 (Init Prerequisites) |
+
+For callback/check/resume/complete: load `@commands/monitor.md` and execute matched handler, then STOP.
+
+### Router Implementation
+
+1. **Load session context** (if exists):
+   - Scan `.workflow/.team/RD-*/.msg/meta.json` for active/paused sessions
+   - If found, extract session folder path, status, and pipeline mode
+
+2. **Parse $ARGUMENTS** for detection keywords:
+   - Check for role name tags in message content
+   - Check for "check", "status", "resume", "continue", "--resume" keywords
+
+3. **Route to handler**:
+   - For monitor handlers: Read `commands/monitor.md`, execute matched handler, STOP
+   - For --resume: Read `@commands/resume.md`, execute resume flow
+   - For Phase 0: Execute Session Resume Check
+   - For Phase 1: Execute Init Prerequisites below
+
+---
+
+## Toolbox
+
+### Available Commands
+
+| Command | File | Phase | Description |
+|---------|------|-------|-------------|
+| `analyze` | [commands/analyze.md](commands/analyze.md) | Phase 1 | Detect depth/phase-count/gate signals from task description |
+| `roadmap-discuss` | [commands/roadmap-discuss.md](commands/roadmap-discuss.md) | Phase 2 | Discuss roadmap with user, generate session artifacts |
+| `dispatch` | [commands/dispatch.md](commands/dispatch.md) | Phase 3 | Create task chain per phase |
+| `monitor` | [commands/monitor.md](commands/monitor.md) | Phase 4 | Stop-Wait phase execution loop |
+| `pause` | [commands/pause.md](commands/pause.md) | Any | Save state and exit cleanly |
+| `resume` | [commands/resume.md](commands/resume.md) | Any | Resume from paused session |
+
+### Tool Capabilities
+
+| Tool | Type | Used By | Purpose |
+|------|------|---------|---------|
+| `request_user_input` | Human interaction | coordinator | Clarify requirements, roadmap discussion |
+| Session folder ops | Team management | coordinator | Create roadmap-dev session folder |
+| `tasks.json` | Task dispatch | coordinator | Create PLAN-*, EXEC-*, VERIFY-* tasks in tasks.json |
+| `wait_agent` | Worker communication | coordinator | Receive worker results |
+| `report_agent_job_result` | Worker communication | workers | Report results to coordinator |
+| `mcp__ccw-tools__team_msg` | Message bus | coordinator | Log all communications |
+| `Read/Write` | File operations | coordinator | Session state management |
+
+---
+
+## Message Types
+
+| Type | Direction | Trigger | Description |
+|------|-----------|---------|-------------|
+| `phase_started` | coordinator -> workers | Phase dispatch | New phase initiated |
+| `phase_complete` | coordinator -> user | All phase tasks done | Phase results summary |
+| `gap_closure` | coordinator -> planner | Verifier found gaps | Trigger re-plan for gaps |
+| `project_complete` | coordinator -> user | All phases done | Final report |
+| `error` | coordinator -> user | Critical failure | Error report |
+
+## Message Bus
+
+Before every message exchange, log via `mcp__ccw-tools__team_msg`:
+
+```
+mcp__ccw-tools__team_msg({
+  operation: "log",
+  session_id: <session-id>,
+  from: "coordinator",
+  to: <target-role>,
+  type: <message-type>,
+  data: { ref: <artifact-path> }
+})
+```
+
+**CLI fallback** (when MCP unavailable):
+
+```
+Bash("ccw team log --session-id <session-id> --from coordinator --type <type> --json")
+```
+
+---
+
+## Execution (5-Phase)
+
+### Phase 1: Init Prerequisites + Requirement Parsing
+
+**Objective**: Ensure prerequisites and parse user requirements.
+
+**Workflow**:
+
+1. Parse arguments for flags: `--resume`, `--yes`, task description
+2. If `--resume` present -> load @commands/resume.md and execute resume flow
+3. Ensure project-tech.json exists:
+
+| Condition | Action |
+|-----------|--------|
+| `.workflow/project-tech.json` exists | Continue to step 4 |
+| File not found | Invoke `Skill(skill="workflow:init")` |
+
+4. Load project context from project-tech.json
+5. Create session directory: `.workflow/.team/RD-<slug>-<date>/`
+6. Initialize state.md with project reference, current position, task description
+
+**Success**: Session directory created, state.md initialized.
+
+### Phase 2: Roadmap Discussion (via command)
+
+**Objective**: Discuss roadmap with user and generate phase plan.
+
+Delegate to `@commands/roadmap-discuss.md`:
+
+| Step | Action |
+|------|--------|
+| 1 | Load commands/roadmap-discuss.md |
+| 2 | Execute interactive discussion with user |
+| 3 | Produce roadmap.md with phase requirements |
+| 4 | Produce config.json with session settings |
+| 5 | Update state.md with roadmap reference |
+
+**Produces**: `<session>/roadmap.md`, `<session>/config.json`
+
+**Command**: [commands/roadmap-discuss.md](commands/roadmap-discuss.md)
+
+### Phase 3: Create Team + Dispatch First Phase
+
+**Objective**: Initialize team and dispatch first phase task.
+
+**Workflow**:
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `Bash({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-roadmap-dev`
+
+2. Create session folder: `.workflow/.team/RD-<slug>-<date>/`
+
+3. Initialize meta.json with pipeline metadata:
+```typescript
+// Use team_msg to write pipeline metadata to .msg/meta.json
+mcp__ccw-tools__team_msg({
+  operation: "log",
+  session_id: "<session-id>",
+  from: "coordinator",
+  type: "state_update",
+  summary: "Session initialized",
+  data: {
+    pipeline_mode: "roadmap-driven",
+    pipeline_stages: ["planner", "executor", "verifier"],
+    roles: ["coordinator", "planner", "executor", "verifier"],
+    team_name: "roadmap-dev"
+  }
+})
+```
+
+4. Spawn worker roles (see SKILL.md Coordinator Spawn Template)
+5. Load `@commands/dispatch.md` for task chain creation
+
+| Step | Action |
+|------|--------|
+| 1 | Read roadmap.md for phase definitions |
+| 2 | Create PLAN-101 task entry in tasks.json for first phase |
+| 3 | Set proper owner and blockedBy dependencies in tasks.json |
+| 4 | Include `Session: <session-folder>` in task description |
+
+**Produces**: PLAN-101 task created, workers spawned
+
+**Command**: [commands/dispatch.md](commands/dispatch.md)
+
+### Phase 4: Coordination Loop (Stop-Wait per phase)
+
+**Objective**: Monitor phase execution, handle callbacks, advance pipeline.
+
+**Design**: Spawn-and-Stop + Callback pattern.
+- Spawn workers with `spawn_agent()` -> immediately return
+- Worker completes -> report_agent_job_result() -> coordinator receives via wait_agent() -> auto-advance
+- User can use "check" / "resume" to manually advance
+- Coordinator does one operation per invocation, then STOPS
+
+Delegate to `@commands/monitor.md`:
+
+| Step | Action |
+|------|--------|
+| 1 | Load commands/monitor.md |
+| 2 | Find tasks with: status=pending, blockedBy all resolved |
+| 3 | For each ready task -> spawn worker (see SKILL.md Spawn Template) |
+| 4 | Handle worker callbacks -> advance pipeline |
+| 5 | Phase complete -> transition to next phase or gap closure |
+| 6 | STOP after each operation |
+
+**Pipeline advancement** driven by three wake sources:
+- Worker callback (automatic) -> handleCallback
+- User "check" -> handleCheck (status only)
+- User "resume" -> handleContinue (advance)
+
+**Command**: [commands/monitor.md](commands/monitor.md)
+
+### Phase 5: Report + Persist
+
+**Objective**: Completion report and follow-up options.
+
+**Workflow**:
+
+| Step | Action |
+|------|--------|
+| 1 | Load session state -> count completed tasks, duration |
+| 2 | List deliverables with output paths |
+| 3 | Update state.md status -> "completed" |
+| 4 | Offer next steps via request_user_input |
+
+**Next step options**:
+- Submit code (git add + commit)
+- Continue next milestone (new roadmap discussion)
+- Complete (end session)
+
+---
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| project-tech.json missing | Invoke /workflow:spec:setup  automatically |
+| User cancels roadmap discussion | Save session state, exit gracefully |
+| Planner fails | Retry once, then ask user for guidance |
+| Executor fails on plan | Mark plan as failed, continue with next |
+| Verifier finds gaps (<=3 iterations) | Trigger gap closure: re-plan -> re-execute -> re-verify |
+| Verifier gaps persist (>3 iterations) | Report to user, ask for manual intervention |
+| Worker timeout | Kill worker, report partial results |
+| Task timeout | Log, mark failed, ask user to retry or skip |
+| Worker crash | Respawn worker, reassign task |
+| Dependency cycle | Detect, report to user, halt |
+| Invalid mode | Reject with error, ask to clarify |
+| Session corruption | Attempt recovery, fallback to manual reconciliation |

package/.codex/skills/team-roadmap-dev/roles/executor/role.md

@@ -0,0 +1,71 @@
+---
+role: executor
+prefix: EXEC
+inner_loop: true
+cli_tools:
+  - gemini --mode write
+message_types:
+  success: exec_complete
+  progress: exec_progress
+  error: error
+---
+
+# Executor
+
+Wave-based code implementation per phase. Reads IMPL-*.json task files, computes execution waves from the dependency graph, delegates each task to CLI tool for code generation. Produces summary-{IMPL-ID}.md per task.
+
+## Phase 2: Context Loading
+
+| Input | Source | Required |
+|-------|--------|----------|
+| Task JSONs | <session>/phase-{N}/.task/IMPL-*.json | Yes |
+| Prior summaries | <session>/phase-{1..N-1}/summary-*.md | No |
+| Wisdom | <session>/wisdom/ | No |
+
+1. Glob `<session>/phase-{N}/.task/IMPL-*.json`, error if none found
+2. Parse each task JSON: extract id, description, depends_on, files, convergence, implementation
+3. Compute execution waves from dependency graph:
+   - Wave 1: tasks with no dependencies
+   - Wave N: tasks whose all deps are in waves 1..N-1
+   - Force-assign if circular (break at lowest-numbered task)
+4. Load prior phase summaries for cross-task context
+
+## Phase 3: Wave-Based Implementation
+
+Execute waves sequentially, tasks within each wave can be parallel.
+
+**Strategy selection**:
+
+| Task Count | Strategy |
+|------------|----------|
+| <= 2 | Direct: inline Edit/Write |
+| 3-5 | Single CLI tool call for all |
+| > 5 | Batch: one CLI tool call per module group |
+
+**Per task**:
+1. Build prompt from task JSON: description, files, implementation steps, convergence criteria
+2. Include prior summaries and wisdom as context
+3. Delegate to CLI tool:
+   ```
+   Bash({
+     command: `ccw cli -p "PURPOSE: Implement task ${taskId}: ${description}
+   TASK: ${implementationSteps}
+   MODE: write
+   CONTEXT: @${files.join(' @')} | Memory: ${priorSummaries}
+   EXPECTED: Working code changes matching convergence criteria
+   CONSTRAINTS: ${convergenceCriteria}" --tool gemini --mode write`
+   })
+   ```
+4. Write `<session>/phase-{N}/summary-{IMPL-ID}.md` with: task ID, affected files, changes made, status
+
+**Between waves**: report wave progress via team_msg (type: exec_progress)
+
+## Phase 4: Self-Validation
+
+| Check | Method | Pass Criteria |
+|-------|--------|---------------|
+| Affected files exist | `test -f <path>` for each file in summary | All present |
+| TypeScript syntax | `npx tsc --noEmit` (if tsconfig.json exists) | No errors |
+| Lint | `npm run lint` (best-effort) | No critical errors |
+
+Log errors via team_msg but do NOT fix — verifier handles gap detection.

package/.codex/skills/team-roadmap-dev/roles/planner/role.md

@@ -0,0 +1,76 @@
+---
+role: planner
+prefix: PLAN
+inner_loop: true
+cli_tools:
+  - gemini --mode analysis
+message_types:
+  success: plan_ready
+  progress: plan_progress
+  error: error
+---
+
+# Planner
+
+Research and plan creation per roadmap phase. Gathers codebase context via CLI exploration, then generates wave-based execution plans with convergence criteria via CLI planning tool.
+
+## Phase 2: Context Loading + Research
+
+| Input | Source | Required |
+|-------|--------|----------|
+| roadmap.md | <session>/roadmap.md | Yes |
+| config.json | <session>/config.json | Yes |
+| Prior summaries | <session>/phase-{1..N-1}/summary-*.md | No |
+| Wisdom | <session>/wisdom/ | No |
+
+1. Read roadmap.md, extract phase goal, requirements (REQ-IDs), success criteria
+2. Read config.json for depth setting (quick/standard/comprehensive)
+3. Load prior phase summaries for dependency context
+4. Detect gap closure mode (task description contains "Gap closure")
+5. Launch CLI exploration with phase requirements as exploration query:
+   ```
+   Bash({
+     command: `ccw cli -p "PURPOSE: Explore codebase for phase requirements
+   TASK: • Identify files needing modification • Map patterns and dependencies • Assess test infrastructure • Identify risks
+   MODE: analysis
+   CONTEXT: @**/* | Memory: Phase goal: ${phaseGoal}
+   EXPECTED: Structured exploration results with file lists, patterns, risks
+   CONSTRAINTS: Read-only analysis" --tool gemini --mode analysis`
+   })
+   ```
+   - Target: files needing modification, patterns, dependencies, test infrastructure, risks
+6. If depth=comprehensive: run Gemini CLI analysis (`--mode analysis --rule analysis-analyze-code-patterns`)
+7. Write `<session>/phase-{N}/context.md` combining roadmap requirements + exploration results
+
+## Phase 3: Plan Creation
+
+1. Load context.md from Phase 2
+2. Create output directory: `<session>/phase-{N}/.task/`
+3. Delegate to CLI planning tool with:
+   ```
+   Bash({
+     command: `ccw cli -p "PURPOSE: Generate wave-based execution plan for phase ${phaseNum}
+   TASK: • Break down requirements into tasks • Define convergence criteria • Build dependency graph • Assign waves
+   MODE: write
+   CONTEXT: @${contextMd} | Memory: ${priorSummaries}
+   EXPECTED: IMPL_PLAN.md + IMPL-*.json files + TODO_LIST.md
+   CONSTRAINTS: <= 10 tasks | Valid DAG | Measurable convergence criteria" --tool gemini --mode write`
+   })
+   ```
+4. CLI tool produces: `IMPL_PLAN.md`, `.task/IMPL-*.json`, `TODO_LIST.md`
+5. If gap closure: only create tasks for gaps, starting from next available ID
+
+## Phase 4: Self-Validation
+
+| Check | Pass Criteria | Action on Failure |
+|-------|---------------|-------------------|
+| Task JSON files exist | >= 1 IMPL-*.json found | Error to coordinator |
+| Required fields | id, title, description, files, implementation, convergence | Log warning |
+| Convergence criteria | Each task has >= 1 criterion | Log warning |
+| No self-dependency | task.id not in task.depends_on | Log error, remove cycle |
+| All deps valid | Every depends_on ID exists | Log warning |
+| IMPL_PLAN.md exists | File present | Generate minimal version from task JSONs |
+
+After validation, compute wave structure from dependency graph for reporting:
+- Wave count = topological layers of DAG
+- Report: task count, wave count, file list