cc-dev-template 0.1.58 → 0.1.62

package/bin/install.js

@@ -20,7 +20,7 @@ console.log('='.repeat(50));
 console.log(`Installing to ${CLAUDE_DIR}...`);
 
 // Create directories
-const dirs = ['commands', 'scripts', 'skills', 'hooks', 'mcp-servers'];
+const dirs = ['commands', 'scripts', 'skills', 'hooks', 'mcp-servers', 'agents'];
 dirs.forEach(dir => {
   fs.mkdirSync(path.join(CLAUDE_DIR, dir), { recursive: true });
 });
@@ -62,11 +62,33 @@ console.log('\nCommands:');
 const cmdCount = copyFiles('commands', 'commands', '.md');
 console.log(cmdCount ? `✓ ${cmdCount} commands installed` : '  No commands to install');
 
+// Copy agents
+console.log('\nAgents:');
+const agentCount = copyFiles('agents', 'agents', '.md');
+console.log(agentCount ? `✓ ${agentCount} agents installed` : '  No agents to install');
+
 // Copy scripts
 console.log('\nScripts:');
 const scriptCount = copyFiles('scripts', 'scripts', '.js');
 const jsonCount = copyFiles('scripts', 'scripts', '.json');
-console.log(scriptCount || jsonCount ? `✓ ${scriptCount + jsonCount} scripts installed` : '  No scripts to install');
+
+// Copy shell scripts and make executable
+const scriptsDir = path.join(SRC_DIR, 'scripts');
+let shellCount = 0;
+if (fs.existsSync(scriptsDir)) {
+  const shellScripts = fs.readdirSync(scriptsDir).filter(f => f.endsWith('.sh'));
+  shellScripts.forEach(file => {
+    const src = path.join(scriptsDir, file);
+    const dest = path.join(CLAUDE_DIR, 'scripts', file);
+    fs.copyFileSync(src, dest);
+    fs.chmodSync(dest, 0o755);
+    console.log(`  ${file}`);
+    shellCount++;
+  });
+}
+
+const totalScripts = scriptCount + jsonCount + shellCount;
+console.log(totalScripts ? `✓ ${totalScripts} scripts installed` : '  No scripts to install');
 
 // Copy skills (entire directories)
 console.log('\nSkills:');
@@ -348,6 +370,7 @@ console.log('='.repeat(50));
 console.log(`
 Installed to:
   Commands:    ${CLAUDE_DIR}/commands/
+  Agents:      ${CLAUDE_DIR}/agents/
   Scripts:     ${CLAUDE_DIR}/scripts/
   Skills:      ${CLAUDE_DIR}/skills/
   Hooks:       ${CLAUDE_DIR}/hooks/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.58",
+  "version": "0.1.62",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/agents/spec-implementer.md

@@ -0,0 +1,51 @@
+---
+name: spec-implementer
+description: Implements a single criterion from a spec task file. Only use when explicitly assigned a task file path from the execute-spec workflow.
+tools: Read, Grep, Glob, Edit, Write, Bash, LSP
+---
+
+You implement one task from a spec breakdown.
+
+## Process
+
+When given a task file path:
+
+1. Read the task file at that path
+2. Read the spec file in the parent directory (`../spec.md`)
+3. Check the **Review Notes** section of the task file:
+   - **If issues exist**: Address those specific issues (fix mode)
+   - **If empty**: Implement from scratch per the Criterion (initial mode)
+4. Implement the work, touching only files listed in the **Files** section
+5. Append your work summary to **Implementation Notes** (see format below)
+6. Return minimal status (see Output section)
+
+## Implementation Notes Format
+
+Append a new section with timestamp:
+
+```markdown
+### Pass N (YYYY-MM-DD HH:MM)
+
+[Brief summary of what you implemented or fixed]
+
+Files modified:
+- path/to/file.ts - [what changed]
+```
+
+Do NOT overwrite previous passes. The log provides debugging context.
+
+## Output (Critical)
+
+Return ONLY a minimal status message. All details go in the task file.
+
+**Success:**
+```
+Task complete: T005-variant-selection.md
+```
+
+**Blocked:**
+```
+Blocked: T005 - [one-line reason why you cannot proceed]
+```
+
+Do NOT return tables, code snippets, file listings, or detailed explanations. The orchestrator only needs pass/fail status. All details belong in the task file's Implementation Notes section.

package/src/agents/spec-validator.md

@@ -0,0 +1,79 @@
+---
+name: spec-validator
+description: Validates a completed task through code review and E2E testing. Only use when explicitly assigned a task file path from the execute-spec workflow.
+tools: Read, Grep, Glob, Bash
+---
+
+You are a senior QA engineer validating completed work.
+
+## Process
+
+When given a task file path:
+
+1. Read the task file and parent spec (`../spec.md`)
+2. Read the **Implementation Notes** to understand what was built
+3. Perform validation (see steps below)
+4. Append findings to **Review Notes** (see format below)
+5. Return minimal status (see Output section)
+
+## Step 1: Code Review + Automated Tests
+
+- Run automated tests if they exist (look for test files, run with appropriate test runner)
+- Check for code smells:
+  - Files over 300 lines: Can this logically split into multiple files, or does it need to be one file?
+  - Missing error handling, unclear naming, other quality issues
+- Note concerns for Review Notes
+
+## Step 2: E2E Testing with agent-browser
+
+Run `agent-browser --help` if you need to understand its capabilities.
+
+- Create your own session to avoid conflicts: `--session validator-{task-id}`
+- Dev server runs via `make dev` (check output for port if not already running)
+- Pretend you are a user testing the criterion:
+  - Use `agent-browser snapshot -i` to see interactive elements
+  - Click buttons, fill forms, navigate flows
+  - Does the UI look right? Are elements interactable?
+  - Does the feature work as a user would expect?
+- Close your session when finished: `agent-browser close --session validator-{task-id}`
+
+## Review Notes Format
+
+Append a new section with timestamp:
+
+```markdown
+### Pass N (YYYY-MM-DD HH:MM)
+
+**Result**: PASS | FAIL
+
+**Issues** (if any):
+- [critical] one-line description
+- [warning] one-line description
+- [suggestion] one-line description
+
+**E2E Tests**:
+- [pass/fail] Test description
+
+**Notes**: [Any additional context needed for fix]
+```
+
+Do NOT overwrite previous passes. The log provides debugging context.
+
+## Output (Critical)
+
+Return ONLY a minimal status message. All details go in the task file.
+
+**Pass:**
+```
+Pass: T005
+```
+
+**Issues found:**
+```
+Issues: T005
+- [critical] one-line summary
+- [warning] one-line summary
+Details in Review Notes.
+```
+
+Do NOT return tables, code snippets, detailed logs, or lengthy explanations. The orchestrator only needs pass/fail to decide next action. All details belong in the task file's Review Notes section.

package/src/scripts/block-task-files.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+
+# PreToolUse hook for execute-spec skill
+# Blocks the orchestrator from reading task files directly
+# Task files should only be read by implementer/validator agents
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+# Check if this is a task file (pattern: */tasks/T*.md)
+if [[ "$FILE_PATH" =~ /tasks/T[0-9]+.*\.md$ ]]; then
+  jq -n '{
+    "hookSpecificOutput": {
+      "hookEventName": "PreToolUse",
+      "permissionDecision": "deny",
+      "permissionDecisionReason": "Task files should be read by spec-implementer/spec-validator agents, not the orchestrator. Pass the file path to agents and let them read it."
+    }
+  }'
+  exit 0
+fi
+
+# Allow all other reads
+exit 0

package/src/scripts/parse-task-files.js

@@ -0,0 +1,120 @@
+#!/usr/bin/env node
+
+/**
+ * Parses task files from a spec directory and returns structured JSON.
+ * Used by execute-spec orchestrator to hydrate tasks without reading full file contents.
+ *
+ * Usage: node parse-task-files.js <spec-path>
+ * Example: node parse-task-files.js docs/specs/kiosk-storefront
+ *
+ * Output: JSON with task metadata (id, title, depends_on, path)
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+function parseYamlFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const yaml = match[1];
+  const result = {};
+
+  // Simple YAML parsing for our known fields
+  const lines = yaml.split('\n');
+  for (const line of lines) {
+    const idMatch = line.match(/^id:\s*(.+)/);
+    if (idMatch) result.id = idMatch[1].trim();
+
+    const titleMatch = line.match(/^title:\s*(.+)/);
+    if (titleMatch) result.title = titleMatch[1].trim();
+
+    const statusMatch = line.match(/^status:\s*(.+)/);
+    if (statusMatch) result.status = statusMatch[1].trim();
+
+    const dependsMatch = line.match(/^depends_on:\s*\[(.*)\]/);
+    if (dependsMatch) {
+      const deps = dependsMatch[1].trim();
+      result.depends_on = deps ? deps.split(',').map(d => d.trim()) : [];
+    }
+  }
+
+  // Handle multi-line depends_on
+  if (!result.depends_on) {
+    const depsSection = yaml.match(/depends_on:\s*\n((?:\s+-\s*.+\n?)*)/);
+    if (depsSection) {
+      result.depends_on = depsSection[1]
+        .split('\n')
+        .map(line => line.replace(/^\s*-\s*/, '').trim())
+        .filter(Boolean);
+    } else {
+      result.depends_on = [];
+    }
+  }
+
+  return result;
+}
+
+function main() {
+  const specPath = process.argv[2];
+
+  if (!specPath) {
+    console.error(JSON.stringify({ error: 'Usage: parse-task-files.js <spec-path>' }));
+    process.exit(1);
+  }
+
+  const tasksDir = path.join(specPath, 'tasks');
+  const specFile = path.join(specPath, 'spec.md');
+
+  // Validate spec structure
+  if (!fs.existsSync(specFile)) {
+    console.error(JSON.stringify({ error: `Spec file not found: ${specFile}` }));
+    process.exit(1);
+  }
+
+  if (!fs.existsSync(tasksDir)) {
+    console.error(JSON.stringify({ error: `Tasks directory not found: ${tasksDir}` }));
+    process.exit(1);
+  }
+
+  // Find and parse task files
+  const taskFiles = fs.readdirSync(tasksDir)
+    .filter(f => f.match(/^T\d+.*\.md$/))
+    .sort();
+
+  if (taskFiles.length === 0) {
+    console.error(JSON.stringify({ error: 'No task files found (expected T*.md)' }));
+    process.exit(1);
+  }
+
+  const tasks = [];
+
+  for (const file of taskFiles) {
+    const filePath = path.join(tasksDir, file);
+    const content = fs.readFileSync(filePath, 'utf8');
+    const frontmatter = parseYamlFrontmatter(content);
+
+    if (!frontmatter || !frontmatter.id) {
+      console.error(JSON.stringify({ error: `Invalid frontmatter in ${file}` }));
+      process.exit(1);
+    }
+
+    tasks.push({
+      id: frontmatter.id,
+      title: frontmatter.title || file.replace('.md', ''),
+      status: frontmatter.status || 'pending',
+      depends_on: frontmatter.depends_on || [],
+      path: filePath
+    });
+  }
+
+  // Output structured JSON
+  console.log(JSON.stringify({
+    specPath: specPath,
+    specFile: specFile,
+    taskCount: tasks.length,
+    tasks: tasks
+  }, null, 2));
+}
+
+main();

package/src/skills/execute-spec/SKILL.md

@@ -0,0 +1,47 @@
+---
+allowed-tools: Grep, Glob, Task, TaskCreate, TaskList, TaskUpdate, TaskGet, AskUserQuestion, Bash
+hooks:
+  PreToolUse:
+    - matcher: "Read"
+      hooks:
+        - type: command
+          command: "$HOME/.claude/scripts/block-task-files.sh"
+---
+
+# Execute Spec
+
+Orchestrates the implementation and validation of a spec's task breakdown.
+
+**Important**: This skill is an orchestrator only. It does NOT read task files or edit code directly. It dispatches agents and receives minimal status responses. All detailed work happens in the agents; all detailed findings live in the task files.
+
+## When to Use
+
+Invoke when you have a complete spec with a `tasks/` folder containing task files (T001-*.md, T002-*.md, etc.) ready for implementation.
+
+## Arguments
+
+This skill takes a spec path as an argument:
+- `docs/specs/my-feature` - path to the spec folder containing `spec.md` and `tasks/`
+
+## Workflow
+
+Read `references/workflow.md` for the full orchestration flow.
+
+## Phases
+
+1. **Hydrate** - Run parse script, create tasks with dependencies (NO file reading)
+2. **Build** - Dispatch spec-implementer agents, receive minimal status
+3. **Validate** - Dispatch spec-validator agents, receive pass/fail
+4. **Triage** - Re-dispatch implementers for failed tasks, loop until clean
+
+## Key Principles
+
+- **Never read task files** - Use the parse script for hydration, pass paths to agents
+- **Minimal context** - Agent returns are pass/fail only, details in task files
+- **Delegate everything** - Fixes go to spec-implementer, not done by orchestrator
+
+## Requirements
+
+- Spec folder must contain `spec.md` and `tasks/` directory
+- Task files must have YAML frontmatter with `id`, `title`, `status`, `depends_on`
+- The `spec-implementer` and `spec-validator` agents must be installed

package/src/skills/execute-spec/references/phase-1-hydrate.md

@@ -0,0 +1,71 @@
+# Phase 1: Hydrate Tasks
+
+Load task metadata into the Claude Code task system using the parse script.
+
+## Important: No File Reading
+
+The orchestrator does NOT read task files directly. Use the parse script.
+
+## Process
+
+```bash
+# Run the parse script
+node ~/.claude/scripts/parse-task-files.js {spec-path}
+```
+
+This outputs JSON:
+```json
+{
+  "specPath": "docs/specs/kiosk-storefront",
+  "specFile": "docs/specs/kiosk-storefront/spec.md",
+  "taskCount": 15,
+  "tasks": [
+    {
+      "id": "T001",
+      "title": "Public API endpoints",
+      "status": "pending",
+      "depends_on": [],
+      "path": "docs/specs/kiosk-storefront/tasks/T001-public-api-endpoints.md"
+    },
+    {
+      "id": "T002",
+      "title": "Kiosk routing",
+      "depends_on": ["T001"],
+      "path": "..."
+    }
+  ]
+}
+```
+
+## Create Tasks
+
+For each task in the JSON:
+
+```
+TaskCreate(
+  subject: "{id}: {title}",
+  description: "{path}",
+  activeForm: "Implementing {title}"
+)
+```
+
+The description is JUST the path. Agents read the file themselves.
+
+## Set Dependencies
+
+After creating all tasks, set up blockedBy relationships:
+
+```
+TaskUpdate(
+  taskId: {claude-task-id},
+  addBlockedBy: [mapped IDs from depends_on]
+)
+```
+
+Maintain a mapping of task IDs (T001, T002) to Claude task system IDs.
+
+## Output
+
+- All tasks in Claude Code task system
+- Dependencies configured
+- Ready for Phase 2

package/src/skills/execute-spec/references/phase-2-build.md

@@ -0,0 +1,64 @@
+# Phase 2: Build
+
+Dispatch spec-implementer agents for each task, respecting dependencies.
+
+## Process
+
+```
+Loop until all tasks complete:
+
+1. TaskList() to get current state
+
+2. Find ready tasks:
+   - status: pending
+   - blockedBy: empty (no unfinished dependencies)
+
+3. For each ready task:
+   - Extract task file path from description
+   - Mark as in_progress: TaskUpdate(taskId, status: "in_progress")
+   - Dispatch implementer:
+     Task(
+       subagent_type: "spec-implementer",
+       prompt: "{task-file-path}",
+       run_in_background: true,
+       description: "Implement {task-id}"
+     )
+
+4. Wait for completions:
+   - Agents mark tasks complete when done
+   - Poll TaskList periodically to check status
+   - As tasks complete, newly unblocked tasks become ready
+
+5. Repeat until no pending tasks remain
+```
+
+## Parallelism Strategy
+
+- Dispatch ALL ready tasks simultaneously
+- Don't wait for one to finish before starting another
+- The dependency graph controls what can run in parallel
+- Example: If T002, T003, T004 all depend only on T001, they all start when T001 completes
+
+## Monitoring Progress
+
+Report progress as tasks complete:
+```
+Build Progress:
+  [x] T001: Public API endpoints (complete)
+  [~] T002: Kiosk routing (in progress)
+  [~] T003: Entity chain validation (in progress)
+  [ ] T007: Cart persistence (blocked by T005, T006)
+  ...
+```
+
+## Error Handling
+
+- If an implementer fails: Note the error, continue with other tasks
+- If a task stays in_progress too long: May need manual intervention
+- Failed tasks block their dependents
+
+## Output
+
+- All tasks implemented (or failed with notes)
+- Implementation Notes written to each task file
+- Ready for Phase 3: Validate

package/src/skills/execute-spec/references/phase-3-validate.md

@@ -0,0 +1,76 @@
+# Phase 3: Validate
+
+Dispatch spec-validator agents for each completed task.
+
+## Prerequisites
+
+- All build tasks complete
+- Code is stable (no more modifications happening)
+
+## Process
+
+```
+1. Get list of all tasks from TaskList()
+
+2. For each completed task:
+   - Extract task file path from description
+   - Dispatch validator:
+     Task(
+       subagent_type: "spec-validator",
+       prompt: "{task-file-path}",
+       run_in_background: true,
+       description: "Validate {task-id}"
+     )
+
+3. All validators run in parallel:
+   - Each creates its own browser session
+   - No dependencies between validators
+   - They don't modify code, just read and test
+
+4. Wait for all validators to complete
+
+5. Collect results:
+   - Read Review Notes from each task file
+   - Aggregate issues by severity
+```
+
+## Validator Behavior
+
+Each validator:
+1. Reviews code changes for the task
+2. Runs automated tests if available
+3. Performs E2E testing with agent-browser
+4. Writes findings to Review Notes section
+
+## Browser Session Isolation
+
+Validators use isolated sessions:
+```
+--session validator-T001
+--session validator-T002
+...
+```
+
+This prevents conflicts when multiple validators test simultaneously.
+
+## Collecting Results
+
+After all validators complete, read each task file's Review Notes section.
+
+Structure findings:
+```
+Validation Results:
+  T001: PASS
+  T002: PASS
+  T003: FAIL
+    - [critical] Button not clickable at /kiosk/:id/product
+    - [warning] ProductCard.tsx is 342 lines, consider splitting
+  T004: PASS
+  ...
+```
+
+## Output
+
+- Validation complete for all tasks
+- Issues collected and categorized
+- Ready for Phase 4: Triage

package/src/skills/execute-spec/references/phase-4-triage.md

@@ -0,0 +1,75 @@
+# Phase 4: Triage
+
+Process validation results and iterate until all tasks pass.
+
+## Process
+
+```
+1. Collect failed task IDs from validator returns
+   (Returns are minimal: "Issues: T005 - [brief list]")
+
+2. For each failed task:
+   - Re-dispatch spec-implementer with the task path
+   - Implementer reads Review Notes and addresses issues
+   - Returns: "Task complete: T005"
+
+3. Re-run spec-validator on fixed tasks
+   - Returns: "Pass: T005" or "Issues: T005 - ..."
+
+4. Repeat until:
+   - All tasks pass, OR
+   - User defers remaining issues
+```
+
+## No Separate Fixer Agent
+
+The spec-implementer handles fixes. When it reads the task file:
+- If Review Notes has issues → fix mode (address those issues)
+- If Review Notes is empty → initial mode (implement from scratch)
+
+The task file's Review Notes section IS the feedback mechanism.
+
+## When to Escalate to User
+
+Use AskUserQuestion when:
+- Same issue persists after 2+ fix attempts
+- Issue is architectural or unclear how to resolve
+- Trade-off decision needed (performance vs simplicity, etc.)
+
+```
+AskUserQuestion(
+  questions: [{
+    header: "Fix approach",
+    question: "T005 failed twice with: [issue]. How should we proceed?",
+    options: [
+      { label: "Try approach A", description: "..." },
+      { label: "Try approach B", description: "..." },
+      { label: "Defer", description: "Skip for now, add to backlog" }
+    ]
+  }]
+)
+```
+
+## Log-Based History
+
+Each pass appends to the task file:
+- Implementer appends to Implementation Notes
+- Validator appends to Review Notes
+
+This creates a debugging trail:
+```
+Implementation Notes:
+  Pass 1: Initial implementation...
+  Pass 2: Fixed idle timer issue...
+
+Review Notes:
+  Pass 1: [critical] Timer doesn't pause...
+  Pass 2: [pass] All issues resolved
+```
+
+## Exit Conditions
+
+Phase completes when:
+1. All validators return "Pass: TXXX"
+2. User explicitly defers remaining issues
+3. Max retry limit reached (suggest user intervention)

package/src/skills/execute-spec/references/workflow.md

@@ -0,0 +1,74 @@
+# Execute Spec Workflow
+
+## Overview
+
+```
+PHASE 1: HYDRATE
+  Run parse script → TaskCreate with dependencies
+  (NO file reading by orchestrator)
+
+PHASE 2: BUILD
+  Loop: find unblocked tasks → dispatch spec-implementer → receive minimal status
+  Continue until all tasks built
+
+PHASE 3: VALIDATE
+  Dispatch spec-validator for each task (all in parallel)
+  Receive pass/fail status only
+
+PHASE 4: TRIAGE
+  For failed tasks: re-dispatch spec-implementer
+  Re-validate
+  Loop until clean or user defers
+```
+
+## Critical: Minimal Context
+
+**Agent returns are pass/fail only.** All details go in task files.
+
+- Implementer returns: `Task complete: T005` or `Blocked: T005 - reason`
+- Validator returns: `Pass: T005` or `Issues: T005 - [brief list]`
+
+The orchestrator never reads task files. It dispatches paths and receives status.
+
+## Phase 1: Hydrate
+
+Read `phase-1-hydrate.md` for details.
+
+Use the parse script to get task metadata:
+```bash
+node ~/.claude/scripts/parse-task-files.js {spec-path}
+```
+
+This returns JSON with task IDs, titles, dependencies, and paths. Create tasks from this output without reading any files.
+
+## Phase 2: Build
+
+Read `phase-2-build.md` for details.
+
+1. Find unblocked tasks via TaskList
+2. Dispatch spec-implementer with just the file path
+3. Receive minimal status (pass/fail)
+4. Repeat until all built
+
+## Phase 3: Validate
+
+Read `phase-3-validate.md` for details.
+
+1. Dispatch spec-validator for each task (parallel)
+2. Receive pass/fail status
+3. Collect list of failed task IDs
+
+## Phase 4: Triage
+
+Read `phase-4-triage.md` for details.
+
+1. For failed tasks: re-dispatch spec-implementer (it reads Review Notes and fixes)
+2. Re-run spec-validator on fixed tasks
+3. Loop until all pass or user defers remaining issues
+
+## Key Principles
+
+- **No file reading by orchestrator** - Hook blocks task file reads
+- **Minimal returns** - Agents return status only, details in task files
+- **Task file is source of truth** - Implementation Notes and Review Notes track all history
+- **Parallelism** - Use `run_in_background: true` where possible

package/src/skills/spec-to-tasks/SKILL.md

@@ -7,6 +7,17 @@ context: fork
 
 # Spec to Tasks
 
+## Workflow Overview
+
+This skill has 4 steps. **You must complete ALL steps before presenting to the user.**
+
+1. **Identify Spec** - Find and verify the spec file
+2. **Verify File Landscape** - Map files to acceptance criteria
+3. **Generate Tasks** - Create task files in `tasks/` directory
+4. **Review Tasks** - Invoke `task-review` skill to validate, fix issues
+
+Do NOT skip step 4. The review catches dependency errors and coverage gaps.
+
 ## What To Do Now
 
 Read `references/step-1-identify-spec.md` and begin.

package/src/skills/spec-to-tasks/references/step-3-generate.md

@@ -60,6 +60,13 @@ docs/specs/<name>/
 
 Use the template in `templates/task.md` for each file. Name files in dependency order so alphabetical sorting reflects execution order.
 
-## Next Step
+## REQUIRED: Run Review Before Presenting
 
-Once task files are generated, read `references/step-4-review.md` to run the review before presenting to the user.
+**Do NOT present results to the user yet.** After generating task files, you MUST:
+
+1. Read `references/step-4-review.md`
+2. Invoke the `task-review` skill to validate the breakdown
+3. Fix any critical issues found
+4. Only then present results (including any warnings)
+
+This review step catches dependency errors, coverage gaps, and verification issues. Skipping it leads to broken task breakdowns that fail during implementation.

package/src/skills/spec-to-tasks/references/step-4-review.md

@@ -1,15 +1,17 @@
 # Step 4: Review Task Breakdown
 
-Before presenting to the user, run a review to catch issues.
+**This step is REQUIRED.** Do not present results until review is complete.
 
 ## Run Task Review
 
-Invoke the `task-review` skill, specifying the spec name:
+Invoke the task-review skill NOW:
 
 ```
 Skill(skill: "task-review", args: "<spec-name>")
 ```
 
+Wait for the review to complete before proceeding.
+
 The review will check:
 - Coverage (all criteria have tasks)
 - Dependency order (tasks properly sequenced)

package/src/skills/task-review/SKILL.md

@@ -2,6 +2,7 @@
 name: task-review
 description: Reviews task breakdown for completeness, correct ordering, and implementation readiness. Use after spec-to-tasks generates task files.
 argument-hint: <spec-name>
+context: fork
 ---
 
 # Task Review

package/src/skills/task-review/references/checklist.md

@@ -60,7 +60,41 @@ Each task's verification method must be concrete and runnable.
 - "Check that the feature functions"
 - Test commands for files not listed in the task
 
-## 5. Task Scope
+## 5. Verification Completeness
+
+Each task's verification must test ALL behaviors mentioned in its criterion.
+
+**Check:**
+- [ ] Read the criterion text carefully - identify every distinct behavior or edge case mentioned
+- [ ] For each behavior, confirm there's a corresponding verification step
+- [ ] Flag any behaviors in the criterion that have no verification
+
+**How to verify:**
+For each task, extract bullet points from the criterion. For each bullet, find the matching verification step. If a behavior is mentioned but not tested, that's a Critical issue.
+
+**Common gaps:**
+- Criterion mentions "X persists across refresh" but verification doesn't test refresh
+- Criterion mentions "handles edge case Y" but verification only tests happy path
+- Criterion mentions animation/timing but verification can't test it (should note "Manual test required")
+
+## 6. Dependency Completeness
+
+Dependencies must be complete, not just valid.
+
+**Check:**
+- [ ] If task X modifies a file, check if another task creates it - that task must be in X's depends_on
+- [ ] If task X uses a component/function/route, check if another task creates it - that task must be in X's depends_on
+- [ ] If task X requires context from task Y (e.g., branding, layout, shared state), Y must be in X's depends_on
+
+**How to verify:**
+For each task, look at its Files section. For each "modify" entry, search other tasks for where that file is created. If found, verify the creating task is in depends_on. Also check the criterion for implicit dependencies (e.g., "shows branding" implies depending on the branding task).
+
+**Common gaps:**
+- Task uses a layout but doesn't depend on the task that configures the layout
+- Task modifies shared state but doesn't depend on the task that creates the context
+- Task assumes a feature exists but the feature is created by a later task
+
+## 7. Task Scope
 
 Each task should be appropriately sized for the coder→QA loop.
 
@@ -69,7 +103,7 @@ Each task should be appropriately sized for the coder→QA loop.
 - [ ] No trivially small tasks that could merge with related work
 - [ ] Each task produces a verifiable outcome, not just "creates a file"
 
-## 6. Consistency
+## 8. Consistency
 
 Cross-check task files against each other and the spec.