cc-dev-template 0.1.56 → 0.1.61

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,6 +62,11 @@ 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');
@@ -348,6 +353,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.56",
+  "version": "0.1.61",
   "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,16 @@
+---
+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.
+
+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. Understand the **Criterion** section—this defines success
+4. Implement the criterion, touching only files listed in the **Files** section
+5. Write a brief summary of what you did to the **Implementation Notes** section of the task file
+6. Mark the task complete

package/src/agents/spec-validator.md

@@ -0,0 +1,42 @@
+---
+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.
+
+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
+
+## 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? Note your assessment.
+  - Missing error handling, unclear naming, other quality issues
+- Note any concerns
+
+## 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}`
+
+## Output
+
+Write findings to the **Review Notes** section of the task file:
+
+- Issues found (with severity: critical, warning, suggestion)
+- Files that may need refactoring (with reasoning)
+- E2E test results (what worked, what didn't)
+- Overall pass/fail assessment

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

@@ -0,0 +1,35 @@
+---
+allowed-tools: Read, Grep, Glob, Task, TaskCreate, TaskList, TaskUpdate, TaskGet, AskUserQuestion, Bash
+---
+
+# Execute Spec
+
+Orchestrates the implementation and validation of a spec's task breakdown.
+
+**Important**: This skill is an orchestrator. It reads task files and dispatches agents to do the work. It does NOT edit files directly - that's the job of the spec-implementer agents it spawns.
+
+## 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** - Load task files into the task system with dependencies
+2. **Build** - Dispatch spec-implementer agents for each task (parallel, respecting dependencies)
+3. **Validate** - Dispatch spec-validator agents for each completed task
+4. **Triage** - Collect feedback, dispatch fixes or escalate to user
+
+## 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,65 @@
+# Phase 1: Hydrate Tasks
+
+Load task files from the spec into the Claude Code task system.
+
+## Input
+
+Spec path argument, e.g., `docs/specs/kiosk-storefront`
+
+## Process
+
+```
+1. Validate spec structure:
+   - {spec-path}/spec.md exists
+   - {spec-path}/tasks/ directory exists
+   - tasks/ contains T*.md files
+
+2. For each task file (sorted by ID):
+   - Read file content
+   - Parse YAML frontmatter:
+     - id: T001, T002, etc.
+     - title: Human-readable title
+     - status: pending (should be pending at start)
+     - depends_on: [T001, T002] array of task IDs
+
+3. Create tasks in Claude Code task system:
+   TaskCreate(
+     subject: "{id}: {title}",
+     description: "Implement task file: {full-path-to-task-file}",
+     activeForm: "Implementing {title}"
+   )
+
+4. After all tasks created, set up dependencies:
+   For each task with depends_on:
+     TaskUpdate(
+       taskId: {claude-task-id},
+       addBlockedBy: [mapped-claude-task-ids]
+     )
+```
+
+## Mapping Task IDs
+
+The task files use IDs like T001, T002. The Claude Code task system assigns its own IDs.
+
+Maintain a mapping:
+```
+{
+  "T001": "claude-task-id-1",
+  "T002": "claude-task-id-2",
+  ...
+}
+```
+
+Use this mapping when setting up blockedBy relationships.
+
+## Output
+
+- All tasks loaded into Claude Code task system
+- Dependencies correctly configured
+- Ready for Phase 2: Build
+
+## Error Handling
+
+- If spec.md missing: Stop and report error
+- If tasks/ empty: Stop and report "No tasks to execute"
+- If task file has invalid frontmatter: Report which file and what's wrong

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,103 @@
+# Phase 4: Triage
+
+Process validation findings, fix issues, and iterate until clean.
+
+## Process
+
+```
+1. Collect all issues from validator Review Notes
+
+2. Categorize issues:
+
+   EASY FIXES (dispatch automatically):
+   - Missing import
+   - Typo in text
+   - Small styling fix
+   - Test assertion needs update
+   - File exists but missing export
+
+   COMPLEX ISSUES (ask user):
+   - Architectural concerns
+   - "Should we refactor X into Y?"
+   - Unclear requirements
+   - Trade-off decisions
+   - Performance concerns with multiple valid approaches
+
+3. For easy fixes:
+   - Dispatch fix agent with specific instructions
+   - Agent makes the fix
+   - Re-run validator for affected task
+
+4. For complex issues:
+   - Use AskUserQuestion to discuss with user
+   - Present the issue and options
+   - Implement based on user decision
+   - Or user may defer ("not now, add to backlog")
+
+5. Repeat until:
+   - No issues remain, OR
+   - All remaining issues are deferred by user
+```
+
+## Issue Severity Guide
+
+**Critical** - Must fix before considering complete
+- Feature doesn't work
+- UI is broken
+- Test failures
+
+**Warning** - Should fix, but not blocking
+- Code smells (large files, unclear naming)
+- Minor UI issues
+- Missing edge case handling
+
+**Suggestion** - Nice to have
+- Refactoring opportunities
+- Performance optimizations
+- Style improvements
+
+## Dispatching Fix Agents
+
+For easy fixes, dispatch a general-purpose agent:
+```
+Task(
+  subagent_type: "general-purpose",
+  prompt: "Fix this issue in {file}:
+    Problem: {issue description}
+    Expected: {what it should be}
+
+    Make the minimal fix needed.",
+  run_in_background: true
+)
+```
+
+## Asking User About Complex Issues
+
+```
+AskUserQuestion(
+  questions: [{
+    header: "Refactor?",
+    question: "ProductCard.tsx is 342 lines. Should we split it into smaller components?",
+    options: [
+      { label: "Yes, split it", description: "Create ProductImage, ProductInfo, ProductActions components" },
+      { label: "No, keep as-is", description: "It's complex but cohesive, splitting would add indirection" },
+      { label: "Defer", description: "Add to backlog, not blocking for this milestone" }
+    ]
+  }]
+)
+```
+
+## Re-validation Loop
+
+After fixes:
+1. Re-run validators ONLY on affected tasks
+2. Check if new issues introduced
+3. Repeat triage for new issues
+4. Continue until stable
+
+## Output
+
+- All critical issues resolved
+- Warnings addressed or deferred
+- Final validation passes
+- Spec implementation complete

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

@@ -0,0 +1,92 @@
+# Execute Spec Workflow
+
+## Overview
+
+```
+PHASE 1: HYDRATE
+  Read task files → TaskCreate with dependencies
+
+PHASE 2: BUILD
+  Loop: find unblocked tasks → dispatch spec-implementer → wait for completion
+  Continue until all tasks built
+
+PHASE 3: VALIDATE
+  Dispatch spec-validator for each task (all in parallel)
+  Collect findings
+
+PHASE 4: TRIAGE
+  Group issues: easy fixes vs complex
+  Easy → dispatch fix agents
+  Complex → AskUserQuestion, discuss with user
+  Re-validate affected tasks
+  Loop until clean or user defers
+```
+
+## Phase 1: Hydrate
+
+Read `phase-1-hydrate.md` for details.
+
+1. Parse the spec path argument to find the tasks directory
+2. Read all `T*.md` files from `{spec-path}/tasks/`
+3. For each task file:
+   - Parse YAML frontmatter (id, title, status, depends_on)
+   - Create a task in the Claude Code task system using TaskCreate
+   - Set dependencies using the `depends_on` array (map to task IDs)
+4. Output: All tasks loaded into the task system with proper dependency graph
+
+## Phase 2: Build
+
+Read `phase-2-build.md` for details.
+
+1. Call TaskList to find pending tasks with no blockers
+2. For each unblocked task:
+   - Dispatch a `spec-implementer` agent in background:
+     ```
+     Task(
+       subagent_type: "spec-implementer",
+       prompt: "{full-path-to-task-file}",
+       run_in_background: true
+     )
+     ```
+3. Monitor for completions (agents will mark tasks complete)
+4. As tasks complete, check for newly unblocked tasks
+5. Repeat until all build tasks are complete
+
+## Phase 3: Validate
+
+Read `phase-3-validate.md` for details.
+
+1. Once all build tasks complete, dispatch validators
+2. For each task:
+   - Dispatch a `spec-validator` agent in background:
+     ```
+     Task(
+       subagent_type: "spec-validator",
+       prompt: "{full-path-to-task-file}",
+       run_in_background: true
+     )
+     ```
+3. Validators run in parallel (they create isolated browser sessions)
+4. Wait for all validators to complete
+5. Collect findings from Review Notes sections
+
+## Phase 4: Triage
+
+Read `phase-4-triage.md` for details.
+
+1. Read all task files and collect Review Notes
+2. Parse issues by severity (critical, warning, suggestion)
+3. Group issues:
+   - **Easy fixes**: Clear problem, obvious solution → dispatch fix agent
+   - **Complex issues**: Ambiguous, architectural, needs discussion → AskUserQuestion
+4. After fixes, re-run validation on affected tasks
+5. Loop until:
+   - No issues remain, OR
+   - User explicitly defers remaining issues
+
+## Key Principles
+
+- **Parallelism**: Use `run_in_background: true` to maximize throughput
+- **Dependency respect**: Only dispatch tasks whose dependencies are complete
+- **Isolation**: Each validator gets its own browser session
+- **Full paths**: Always use full relative paths to task files so agents know exactly which spec they're implementing

package/src/skills/spec-interview/references/step-4-deep-dive.md

@@ -27,6 +27,19 @@ Example: To understand auth integration:
 
 No assumptions. If you don't know how something works, send an Explorer to find out.
 
+### File Landscape
+
+Once the feature is understood, identify concrete file paths. Ask an Explorer:
+
+> "To implement [this feature], what files would need to be created or modified? Give me concrete file paths."
+
+Capture:
+- **Files to create**: New files with full paths (e.g., `src/models/notification.ts`)
+- **Files to modify**: Existing files that need changes (e.g., `src/routes/index.ts`)
+- **Directory conventions**: Where each type of code lives in this project
+
+This becomes the File Landscape section of the spec, which spec-to-tasks uses directly.
+
 ### Data Model
 - Entities and relationships
 - Constraints (required fields, validations, limits)
@@ -67,6 +80,14 @@ Write to `docs/specs/<name>/spec.md` with this structure:
 - External: [APIs, services, libraries]
 - Data flows: [in/out]
 
+## File Landscape
+
+### Files to Create
+- [path/to/new-file.ts]: [purpose]
+
+### Files to Modify
+- [path/to/existing-file.ts]: [what changes]
+
 ## Data Model
 [Entities, relationships, constraints]
 
@@ -79,6 +100,7 @@ Write to `docs/specs/<name>/spec.md` with this structure:
 
 ## Acceptance Criteria
 - [ ] [Testable requirement]
+  **Verify:** [verification method]
 
 ## Blockers
 - [ ] [Blocker]: [what's needed]

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-1-identify-spec.md

@@ -19,11 +19,20 @@ If no specs found in git history, check `docs/specs/` for any spec files and ask
 ## Verify the Spec
 
 Read the spec file. Confirm it contains enough detail to generate implementation tasks:
-- Clear requirements or user stories
-- Technical approach or architecture decisions
-- Defined scope
 
-If the spec is incomplete or unclear, inform the user and ask if they want to complete the spec first.
+**Required:**
+- Acceptance Criteria with verification methods (each criterion becomes a task)
+- Clear behavior descriptions
+
+**Expected (from spec-interview):**
+- File Landscape section listing files to create/modify
+- Integration points and data model
+
+**If missing acceptance criteria or verification methods:**
+Inform the user: "This spec doesn't have acceptance criteria with verification methods. Each task needs a clear pass/fail test. Would you like to add them now, or run spec-interview to complete the spec?"
+
+**If missing file landscape:**
+Proceed to step 2 where we'll discover file paths via exploration.
 
 ## Next Step
 

package/src/skills/spec-to-tasks/references/step-2-explore.md

@@ -1,25 +1,43 @@
-# Step 2: Explore the Codebase
+# Step 2: Verify File Landscape
 
-Before generating tasks, understand the codebase structure to determine accurate file paths.
+The spec should already contain a File Landscape section from the interview process. This step verifies and supplements it.
 
-## Launch Exploration Subagent
+## Check the Spec
 
-Use a subagent to explore the codebase. The subagent should identify:
+Read the spec's File Landscape section. It should list:
+- **Files to create**: New files with paths and purposes
+- **Files to modify**: Existing files that need changes
 
-- **Existing patterns**: Where do models, services, routes, and components live?
-- **Naming conventions**: How are files and directories named?
-- **Files to modify**: Which existing files need changes for this feature?
-- **Files to create**: What new files are needed and where should they go?
+If the File Landscape section is missing or incomplete, use an Explorer to fill the gaps:
 
-Provide the subagent with the spec content so it understands what is being implemented.
+> "To implement [feature from spec], what files would need to be created or modified? Give me concrete file paths."
 
-## Capture Findings
+## Map Files to Acceptance Criteria
 
-The subagent should return:
-- A list of directories and their purposes
-- Specific file paths for each aspect of the feature
-- Any existing code that the new feature should integrate with
+For each acceptance criterion in the spec, identify which files are involved. This mapping drives task generation.
+
+Example:
+```
+"User can receive notifications"
+  → src/models/notification.ts
+  → src/services/notificationService.ts
+  → src/services/notificationService.test.ts
+
+"User can view notification list"
+  → src/routes/notifications.ts
+  → src/components/NotificationList.tsx
+```
+
+If a criterion's files aren't clear from the spec, ask an Explorer:
+
+> "What files would be involved in making this criterion pass: [criterion]?"
+
+## Output
+
+You should now have:
+1. Complete list of files to create and modify
+2. Each acceptance criterion mapped to its files
 
 ## Next Step
 
-Once exploration is complete and file paths are known, read `references/step-3-generate.md`.
+Once files are mapped to criteria, read `references/step-3-generate.md`.

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

@@ -1,31 +1,72 @@
-# Step 3: Generate Task Manifest
+# Step 3: Generate Task Files
 
-Create the task manifest based on the spec and codebase exploration.
+Create individual task files based on the spec and codebase exploration.
 
 ## Task Principles
 
-**Atomic**: Each task is a single, focused change — one model, one endpoint, one component, or one test file. A task should take an AI agent one focused session to complete.
+**Criterion-based**: Each task corresponds to one acceptance criterion from the spec. A task includes all files needed to make that criterion pass. Do NOT split by file or architectural layer.
 
-**Ordered**: Sequence tasks so each can be completed without blocking. Tasks with no dependencies can share the same `depends_on` value to signal parallel execution.
+**Verifiable**: Every task has a verification method from the spec. A coder implements, a QA agent verifies, and the loop continues until it passes.
 
-**Concrete file paths**: Use the file paths discovered in Step 2. Every task specifies which files it touches.
+**Ordered**: Name files so they sort in dependency order (T001, T002, etc.). Tasks with no dependencies on each other can be worked in parallel.
 
-**Declarative**: Tasks describe WHAT to implement, not HOW. Implementation details live in the spec.
+**Concrete file paths**: Use the file paths discovered in Step 2. Every task lists all files it touches.
 
-## Generate the Manifest
+## Deriving Tasks from Acceptance Criteria
 
-Write to `docs/specs/<name>/tasks.yaml` using the template in `templates/tasks.yaml`.
+Each acceptance criterion in the spec becomes one task.
 
-Derive tasks from the spec:
-- Break each requirement or feature section into atomic units
-- Sequence by dependency (data layer, then business logic, then API, then integration)
-- Reference specific spec sections in task descriptions where helpful
+**For each criterion, determine:**
+1. What files must exist or change for this to pass?
+2. What's the verification method from the spec?
+3. What other criteria must pass first? (dependencies)
 
-## Review with User
+**Grouping rules:**
+- If two criteria share foundational work (e.g., both need a model), the first task creates the foundation, later tasks build on it
+- If a criterion is too large (touches 10+ files), flag it — the spec may need refinement
+- Small tasks are fine; artificial splits are not
 
-Present:
-1. Number of tasks and estimated scope
-2. Task titles in dependency order
-3. Offer to show full YAML or proceed to implementation
+**Anti-patterns to avoid:**
+- "Create the User model" — no verifiable outcome
+- "Add service layer" — implementation detail, not behavior
+- "Set up database schema" — means to an end, not the end
 
-Save the manifest to `docs/specs/<name>/tasks.yaml`.
+**Good task boundaries:**
+- "User can register with email" — verifiable, coherent
+- "Duplicate emails are rejected" — verifiable, coherent
+- "Dashboard shows notification count" — verifiable, coherent
+
+## Validate Criteria Quality
+
+Before generating tasks, verify each acceptance criterion has:
+- A specific, testable condition
+- A verification method (test command, agent-browser script, or query)
+
+If criteria are vague or missing verification, stop and ask:
+> "The criterion '[X]' doesn't have a clear verification method. Should I suggest one, or would you like to refine the spec first?"
+
+## Generate Task Files
+
+Create a `tasks/` directory inside the spec folder:
+
+```
+docs/specs/<name>/
+├── spec.md
+└── tasks/
+    ├── T001-<slug>.md
+    ├── T002-<slug>.md
+    └── T003-<slug>.md
+```
+
+Use the template in `templates/task.md` for each file. Name files in dependency order so alphabetical sorting reflects execution order.
+
+## REQUIRED: Run Review Before Presenting
+
+**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

@@ -0,0 +1,46 @@
+# Step 4: Review Task Breakdown
+
+**This step is REQUIRED.** Do not present results until review is complete.
+
+## Run Task Review
+
+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)
+- File plausibility (paths make sense)
+- Verification executability (concrete commands)
+- Task scope (appropriately sized)
+- Consistency (format, frontmatter)
+
+## Handle Findings
+
+The review returns findings categorized as Critical, Warning, or Note.
+
+**Critical issues**: Fix before proceeding. Update the affected task files.
+
+**Warnings**: Present to user with your recommendation (fix or skip).
+
+**Notes**: Mention briefly, no action required.
+
+## Present to User
+
+After addressing critical issues, present:
+
+1. Number of tasks generated
+2. Task titles in dependency order
+3. Any warnings from the review (with recommendations)
+4. Offer to show task files or proceed to implementation
+
+If the user wants changes, update the task files and re-run the review.
+
+## Complete
+
+Once the user approves the task breakdown, the skill is complete. The tasks are ready for implementation.

package/src/skills/spec-to-tasks/templates/task.md

@@ -0,0 +1,30 @@
+---
+id: T00X
+title: <Short descriptive title — the acceptance criterion>
+status: pending
+depends_on: []
+---
+
+## Criterion
+
+<The acceptance criterion from the spec, verbatim or lightly edited for clarity>
+
+## Files
+
+- <path/to/file.ts>
+- <path/to/another-file.ts>
+- <path/to/test-file.test.ts>
+
+## Verification
+
+<The verification method from the spec — test command, agent-browser script, or manual steps>
+
+---
+
+## Implementation Notes
+
+<!-- Coder agent writes here after each implementation attempt -->
+
+## Review Notes
+
+<!-- QA agent writes here after each review pass -->

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

@@ -0,0 +1,18 @@
+---
+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
+
+Review the task breakdown to catch issues before implementation begins.
+
+## What To Do Now
+
+If an argument was provided, use it as the spec name. Otherwise, find the most recent spec with a `tasks/` directory.
+
+Read the spec file and all task files in the `tasks/` directory.
+
+Then read `references/checklist.md` and evaluate each item.

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

@@ -0,0 +1,135 @@
+# Task Review Checklist
+
+Evaluate each area. For each issue found, note the severity:
+- **Critical**: Must fix before implementation
+- **Warning**: Should fix, but could proceed
+- **Note**: Minor suggestion
+
+## 1. Coverage
+
+Compare acceptance criteria in the spec to tasks generated.
+
+**Check:**
+- [ ] Every acceptance criterion has exactly one corresponding task
+- [ ] No criteria were skipped or forgotten
+- [ ] No phantom tasks that don't map to a criterion
+
+**How to verify:**
+List each criterion from the spec's Acceptance Criteria section. For each, find the matching task file. Flag any orphans in either direction.
+
+## 2. Dependency Order
+
+Tasks should be sequenced so each can be completed without waiting on later tasks.
+
+**Check:**
+- [ ] Task file names sort in valid execution order (T001, T002, etc.)
+- [ ] Each task's `depends_on` references only earlier tasks
+- [ ] No circular dependencies
+- [ ] Foundation work comes before features that use it
+
+**Common issues:**
+- API route task before the service it calls
+- UI component before the API it fetches from
+- Test file before the code it tests (tests should be in same task as code)
+
+## 3. File Plausibility
+
+Files listed in each task should make sense for the project.
+
+**Check:**
+- [ ] File paths follow project conventions (use Explorer if unsure)
+- [ ] Files to modify actually exist in the codebase
+- [ ] Files to create are in appropriate directories
+- [ ] No duplicate files across tasks (each file appears in exactly one task)
+
+**How to verify:**
+For files to modify, confirm they exist. For files to create, confirm the parent directory exists and the naming follows conventions.
+
+## 4. Verification Executability
+
+Each task's verification method must be concrete and runnable.
+
+**Check:**
+- [ ] Verification is a specific command or script, not vague prose
+- [ ] Test file paths exist or will be created by the task
+- [ ] agent-browser commands reference real routes/elements
+- [ ] No "manually verify" without clear steps
+
+**Red flags:**
+- "Verify it works correctly"
+- "Check that the feature functions"
+- Test commands for files not listed in the task
+
+## 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.
+
+**Check:**
+- [ ] No task touches more than ~10 files (consider splitting)
+- [ ] No trivially small tasks that could merge with related work
+- [ ] Each task produces a verifiable outcome, not just "creates a file"
+
+## 8. Consistency
+
+Cross-check task files against each other and the spec.
+
+**Check:**
+- [ ] Task titles match or closely reflect the acceptance criterion
+- [ ] Status is `pending` for all new tasks
+- [ ] Frontmatter format is consistent across all task files
+- [ ] Implementation Notes and Review Notes sections exist (empty is fine)
+
+---
+
+## Output Format
+
+Return findings as a structured list:
+
+```
+## Critical Issues
+- [T002] Depends on T005 which comes later - wrong order
+- [T003] Missing verification method
+
+## Warnings
+- [T001] touches 12 files - consider splitting
+- Criterion "User can delete account" has no corresponding task
+
+## Notes
+- [T004] Could merge with T005 since they share the same files
+```
+
+If no issues found, state: "Task breakdown looks good. All criteria covered, dependencies valid, verification methods concrete."

package/src/skills/spec-to-tasks/templates/tasks.yaml

@@ -1,25 +0,0 @@
-spec: <name>
-spec_path: docs/specs/<name>/spec.md
-generated: <ISO timestamp>
-
-tasks:
-  - id: T001
-    title: <Short descriptive title>
-    description: |
-      <What to implement>
-      <Reference to spec section if applicable>
-    files:
-      - <path/to/file.ts>
-    depends_on: []
-    acceptance: |
-      <How to verify this task is complete>
-
-  - id: T002
-    title: <Next task>
-    description: |
-      <What to implement>
-    files:
-      - <path/to/file.ts>
-    depends_on: [T001]
-    acceptance: |
-      <Verification criteria>