@benjaminthomas/spec-driven-dev 0.0.0-stage → 1.4.1

package/skills/spec-create/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: spec-create
+description: >
+  Create a structured feature specification with self-contained task files organized into
+  parallel execution batches. Use this skill when the user says "create a spec", "plan this feature",
+  "write up an implementation plan", "break this into tasks", or after any planning conversation
+  where the user wants to capture decisions as actionable spec files. Also use when the user
+  says "/spec-create" (or their host's equivalent invocation syntax) or wants to decompose a
+  feature into work items that agents can implement independently. This skill produces local
+  spec files under specs/{feature}/ — no GitHub integration.
+license: MIT
+---
+
+# Create Feature Specification
+
+Transform a planning conversation into a structured spec folder that enables parallel agent implementation. The spec breaks a feature into self-contained task files — each one detailed enough that a coder agent can pick it up cold and implement it without reading anything else.
+
+The key insight: implementation plans that live in a single file are either too large for a context window or too shallow for independent execution. By splitting into one file per task with full context in each, we enable multiple agents to work in parallel while keeping each agent's context focused.
+
+## Project config (read first)
+
+Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
+found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+you would detect or assume. This skill uses `layout`/`repos` and `specs_dir`.
+
+**Monorepo / multi-repo:** every task names its package or repo, and its file paths are relative to that. Keep each task inside one repo. Cross-repo work becomes separate tasks, with the contract (API shape, event, schema) written into both.
+
+**No config?** If the `spec-setup` skill is available, run it first, then continue here. If it
+isn't, detect what this skill needs from the repo, ask about anything ambiguous, and offer to save
+the answers to `.spec-driven.yml` (keys: `layout`, `repos`, `tracker`, `git`, `commands`,
+`specs_dir`).
+
+## When to Use
+
+- After a planning conversation where requirements and technical details have been discussed
+- When the user asks to create a spec, plan a feature, or break work into tasks
+- When the user wants to prepare work for parallel agent implementation
+
+## Instructions
+
+### Step 1: Gather Requirements
+
+If a `{specs_dir}/*/investigation.md` (default `specs/`) from `spec-investigate` exists for this work, read it first and treat it as the evidence base: carry its VERIFIED facts, affected files, risks, and acceptance criteria into the spec, reuse its folder (`specs/{feature-slug}/`) instead of naming a new one in Step 2, and turn its open questions/UNKNOWNs into items for the user or `action-required.md` rather than guessing.
+
+If the conversation already contains planning context (requirements discussed, technical decisions made, architecture outlined), extract all of it. Review the entire conversation to ensure nothing is lost — the spec is the single source of truth, and anything not captured here disappears.
+
+If no planning conversation exists, interview the user:
+- What does this feature do and why does it matter?
+- What are the acceptance criteria?
+- What technical constraints or decisions have been made?
+- What files, APIs, schemas, or patterns are involved?
+
+### Step 2: Name the Feature
+
+Choose a kebab-case name that clearly identifies the feature (e.g., `add-user-auth`, `migrate-to-postgres`, `dashboard-redesign`). This becomes the folder name under `specs/`.
+
+### Step 3: Decompose into Tasks
+
+Break the implementation into atomic tasks. Each task should:
+- Be completable in a single coding session by one agent
+- Have a clear, specific scope (one concern per task)
+- Produce working, testable code when complete
+- Not overlap in files modified with other tasks in the same batch
+
+Think carefully about granularity. Too coarse and agents can't work in parallel. Too fine and the overhead of context-switching between tasks dominates. A good task typically creates or modifies 1-5 files around a single concern.
+
+Tests ship with the code they cover: fill in each task's **Tests** section (see the task template) instead of creating separate "write tests" tasks. Only add a standalone testing task for cross-cutting suites (e.g. a new E2E harness) or when the user asks for one.
+
+### Step 4: Build the Dependency Graph
+
+For each task, identify:
+- **What it depends on**: which tasks must complete before this one can start
+- **What depends on it**: which tasks are blocked until this one finishes
+
+Tasks with no dependencies form Batch 1. Tasks whose dependencies are all in Batch 1 form Batch 2. And so on. All tasks within a batch can execute in parallel.
+
+When assigning batches, verify that tasks within the same batch do not modify overlapping files. If two tasks in the same batch would touch the same file, move one to a later batch — parallel agents on the same branch cannot safely modify the same file.
+
+### Step 5: Create the Spec Folder
+
+Create the following structure at `specs/{feature-name}/`:
+
+```
+specs/{feature-name}/
+├── README.md
+├── requirements.md
+├── action-required.md
+└── tasks/
+    ├── task-01-{name}.md
+    ├── task-02-{name}.md
+    └── ...
+```
+
+Read the templates in `references/` before writing each file:
+- `references/readme-template.md` — for the README (dependency graph, batch table, status tracking)
+- `references/task-template.md` — for each task file (self-contained with all context)
+- `references/requirements-template.md` — for the requirements document
+- `references/action-required-template.md` — for manual human steps
+
+Task files are numbered with zero-padded two-digit prefixes in topological order: Batch 1 tasks first, then Batch 2, etc. Within a batch, order is arbitrary but stable.
+
+### Step 6: Write Self-Contained Task Files
+
+This is the most important step. Each task file is the **only thing** a coder agent will read before implementing. It must contain everything the agent needs:
+
+- **Description**: what to build and why it matters in context
+- **Dependency context**: what prior tasks produce that this task needs (summarized in prose, not just filenames). The agent should not need to read other task files.
+- **Technical details**: CLI commands, code snippets, schemas, file paths, env vars, API endpoints — every implementation-specific detail from the planning conversation
+- **Files to create/modify**: explicit list with purpose for each
+- **Acceptance criteria**: specific, verifiable conditions
+
+Review each task file with fresh eyes: could an agent who has never seen the planning conversation implement this correctly using only this file? If not, add what's missing.
+
+### Step 7: Extract Manual Actions
+
+Identify any steps that require human action (account creation, API key setup, DNS configuration, environment variables, third-party service registration, etc.). Write these to `action-required.md` grouped by timing (Before/During/After implementation). If none exist, note "No manual steps required."
+
+### Step 8: Report to User
+
+After creating the spec, display:
+
+```
+Feature specification created at specs/{feature-name}/
+
+Files created:
+- README.md (dependency graph, {N} batches, {T} tasks)
+- requirements.md
+- action-required.md
+- tasks/ ({T} task files)
+
+Batch breakdown:
+- Batch 1: {count} tasks (parallel) — {brief description}
+- Batch 2: {count} tasks (parallel) — {brief description}
+- ...
+
+Next steps:
+1. Review action-required.md for tasks you need to complete manually
+2. Review the requirements and task files
+3. Use /spec-implement to start parallel implementation
+```
+
+## Critical Rules
+
+- Every task file must be fully self-contained — this is the entire point of the spec structure. A coder agent reading only that file must know exactly what to do.
+- Capture ALL technical details from the planning conversation. The spec is the single source of truth — CLI commands, schemas, code snippets, file paths, env vars, API endpoints. Anything not captured here is lost.
+- Tasks within the same batch must not modify overlapping files. Parallel agents on the same branch cannot safely touch the same files.
+- Keep tasks atomic — one concern per task. If a task has more than 5-7 files to modify, consider splitting it.
+- Put tests in each task's Tests section, not in separate testing tasks (unless the user asks, or it's a cross-cutting suite).
+- Number task files in topological order (batch 1 first, then batch 2, etc.) for easy scanning.

package/skills/spec-create/references/action-required-template.md

@@ -0,0 +1,53 @@
+# Action Required Template
+
+Use this structure for the action-required.md at the root of each spec folder. This file captures manual steps that require human action and cannot be automated by agents.
+
+## Template (when manual steps exist)
+
+```markdown
+# Action Required: {Feature Name}
+
+Manual steps that must be completed by a human. These cannot be automated.
+
+## Before Implementation
+
+- [ ] **{Action}** — {Brief reason why this is needed}
+- [ ] **{Action}** — {Brief reason}
+
+## During Implementation
+
+- [ ] **{Action}** — {Brief reason}
+
+## After Implementation
+
+- [ ] **{Action}** — {Brief reason}
+
+---
+
+> These tasks are also referenced in context within the relevant task files.
+```
+
+## Template (when no manual steps exist)
+
+```markdown
+# Action Required: {Feature Name}
+
+No manual steps required for this feature. All tasks can be implemented automatically.
+```
+
+## Common Manual Steps
+
+- Account creation (third-party services, OAuth apps)
+- API key generation and setup
+- Environment variable configuration
+- DNS or domain settings
+- Billing or subscription setup
+- Third-party service registration (webhooks, integrations)
+- Certificate provisioning
+- Access permissions or IAM roles
+
+## Key Points
+
+- Group actions by timing: before, during, and after implementation. This helps the user know when they need to act.
+- Keep descriptions brief — one line explaining what to do and why.
+- Also reference these manual steps in the relevant task files so agents know to pause or skip that part.

package/skills/spec-create/references/readme-template.md

@@ -0,0 +1,53 @@
+# README Template
+
+Use this structure for the README.md at the root of each spec folder. The README serves as the orchestration index — the `spec-implement` skill reads it to determine batch order, task assignments, and completion status.
+
+## Template
+
+```markdown
+# {Feature Name}
+
+## Overview
+
+{One paragraph summary of what the feature does and why it exists.}
+
+## Quick Links
+
+- [Requirements](./requirements.md) — full requirements and acceptance criteria
+- [Action Required](./action-required.md) — manual steps needing human action
+
+## Dependency Graph
+
+​```mermaid
+graph TD
+    task-01-name["01: Task Title"]
+    task-02-name["02: Task Title"]
+    task-03-name["03: Task Title"]
+    task-01-name --> task-03-name
+    task-02-name --> task-03-name
+​```
+
+## Batches
+
+| Batch | Tasks | Description |
+|------|-------|-------------|
+| 1 | task-01, task-02 | {Brief description of what this batch accomplishes} |
+| 2 | task-03 | {Brief description} |
+
+## Task Status
+
+### Batch 1
+- [ ] [task-01-{name}](./tasks/task-01-{name}.md) — {One-line title}
+- [ ] [task-02-{name}](./tasks/task-02-{name}.md) — {One-line title}
+
+### Batch 2
+- [ ] [task-03-{name}](./tasks/task-03-{name}.md) — {One-line title}
+```
+
+## Key Points
+
+- The **Dependency Graph** uses Mermaid syntax (widely rendered in GitHub, VS Code, etc.). Each node shows the task number and title for quick reference.
+- The **Batches** table provides a scannable overview of what runs in parallel.
+- The **Task Status** section uses markdown checkboxes that the `spec-implement` skill updates as tasks complete. The orchestrator parses these to determine which batch to resume from.
+- Links to task files use relative paths pointing into the `tasks/` subfolder.
+- Tasks without dependencies have no incoming arrows in the graph — these form Batch 1.

package/skills/spec-create/references/requirements-template.md

@@ -0,0 +1,54 @@
+# Requirements Template
+
+Use this structure for the requirements.md at the root of each spec folder.
+
+## Template
+
+```markdown
+# Requirements: {Feature Name}
+
+## Summary
+
+{What the feature does and why it exists — 2-3 paragraphs covering the problem, the solution, and the expected outcome.}
+
+## Goals
+
+- {Goal 1}
+- {Goal 2}
+- {Goal 3}
+
+## Non-Goals
+
+{Explicitly out of scope — things that might seem related but are not part of this feature.}
+
+- {Non-goal 1}
+- {Non-goal 2}
+
+## Acceptance Criteria
+
+{High-level criteria for the entire feature. Individual task files have their own granular criteria.}
+
+- [ ] {Criterion 1}
+- [ ] {Criterion 2}
+- [ ] {Criterion 3}
+
+## Assumptions
+
+{Things assumed to be true that could affect implementation if they turn out to be false.}
+
+- {Assumption 1}
+- {Assumption 2}
+
+## Technical Constraints
+
+{Architecture decisions, technology choices, or constraints that affect all tasks.}
+
+- {Constraint 1}
+- {Constraint 2}
+```
+
+## Key Points
+
+- The requirements doc provides **overall feature context** that each coder agent receives alongside its task file. Keep it focused on the "what" and "why" — individual task files handle the "how."
+- Non-goals are important: they prevent agents from over-building. If search functionality is out of scope, say so — otherwise a well-meaning agent might add it.
+- Acceptance criteria here are feature-level (the whole thing works end-to-end). Task-level criteria live in each task file.

package/skills/spec-create/references/task-template.md

@@ -0,0 +1,86 @@
+# Task File Template
+
+Use this structure for each task file in the `tasks/` subfolder. Each task file must be **fully self-contained** — a coder agent reading only this file should know exactly what to implement, why, and how.
+
+## Template
+
+```markdown
+# Task {nn}: {Title}
+
+## Status
+
+pending
+
+## Batch
+
+{N}
+
+## Description
+
+{2-5 sentences describing what this task accomplishes and why it matters in the context of the overall feature. Include enough context that an agent unfamiliar with the planning conversation understands the purpose.}
+
+## Dependencies
+
+**Depends on:** {Comma-separated list of task filenames, or "None (Batch 1)"}
+**Blocks:** {Comma-separated list of task filenames, or "None"}
+
+**Context from dependencies:** {Prose summary of what the dependency tasks produce that this task needs. For example: "task-01-setup-database.md creates the PostgreSQL schema with users and sessions tables. This task builds the API routes that query those tables." This is what makes each file self-contained — the agent does not need to read other task files to understand its inputs.}
+
+## Files to Create
+
+- `path/to/new-file.ts` — {Brief purpose}
+- `path/to/another-file.ts` — {Brief purpose}
+
+## Files to Modify
+
+- `path/to/existing-file.ts` — {What changes and why}
+
+## Technical Details
+
+{All implementation-specific details from the planning conversation. This section is the single source of truth. Include:}
+
+### Implementation Steps
+
+1. {Step-by-step instructions with enough detail for independent implementation}
+2. {Include CLI commands where relevant: `pnpm add package-name`}
+3. {Include code snippets for non-obvious patterns}
+
+### Code Snippets
+
+{Key type definitions, schemas, configuration blocks, or patterns that the implementer needs. Use fenced code blocks with language tags.}
+
+### Environment Variables
+
+{If applicable:}
+- `VAR_NAME` — {Purpose and example value}
+
+### API Endpoints
+
+{If applicable:}
+- `METHOD /path` — {Request/response shape}
+
+## Tests
+
+{Which tests prove this task works, following the repo's existing test framework and layout (an investigation's Testing Context is the best source). For each: file path, type (unit/integration/E2E), and the behaviour it pins down. Write "None — {reason}" only for tasks with nothing testable (pure config, docs).}
+
+- `path/to/thing.test.ts` — {behaviour under test}
+
+## Acceptance Criteria
+
+- [ ] {Criterion 1 — specific and verifiable}
+- [ ] {Criterion 2}
+- [ ] {Criterion 3}
+
+## Notes
+
+{Any additional context, edge cases, warnings, or architectural decisions relevant to this task. Omit this section if there's nothing to add.}
+```
+
+## Key Points
+
+- The **Status** field is updated by the `spec-implement` skill: `pending` → `in-progress` → `complete`.
+- The **Dependencies** section includes prose context (not just filenames) so the agent understands its inputs without reading other files. This is the most important part of making task files self-contained.
+- **Files to Create** and **Files to Modify** make the task's scope explicit. Tasks in the same batch should not overlap on these lists.
+- **Technical Details** captures everything from the planning conversation — CLI commands, schemas, code snippets, file paths, env vars, API endpoints. If it was discussed during planning and is relevant to this task, it belongs here.
+- **Tests** names the tests the coder writes alongside the code. A behavioural acceptance criterion without a matching test is a gap — add the test or explain why it can only be checked by `spec-verify`.
+- **Acceptance Criteria** should be specific enough that completion can be verified objectively (by a code review agent or a human).

package/skills/spec-implement/SKILL.md

@@ -0,0 +1,236 @@
+---
+name: spec-implement
+description: >
+  Orchestrate parallel implementation of a feature specification by dispatching coder agents
+  batch-by-batch with code review gates between batches. Use this skill when the user says
+  "implement this feature", "start implementing", "run the spec", "execute the plan",
+  "continue implementing", or wants to begin coding a previously planned feature from a
+  specs/{feature}/ folder. Also use when the user says "/spec-implement" (or their host's
+  equivalent invocation syntax) or drags a spec folder into the conversation and asks to
+  implement it. This skill does NOT write code itself — it orchestrates coder subagents that
+  work in parallel.
+license: MIT
+---
+
+# Implement Feature
+
+Orchestrate the parallel implementation of a feature specification by dispatching coder agents batch-by-batch. This skill reads a spec folder (created by `spec-create`), identifies the next batch of parallelizable work, spawns coder agents for each task, and runs a code review gate before moving to the next batch.
+
+The orchestrator never writes code itself. Its job is to:
+1. Parse the spec and determine what to do next
+2. Give each coder agent exactly the context it needs
+3. Verify the results via code review
+4. Manage the fix loop if review finds issues
+5. Track progress and commit completed batches
+
+## Project config (read first)
+
+Load `.spec-driven.yml`: walk up from the current directory to the home folder, and the first one
+found wins (a `multi-repo` config only applies inside the repos it lists). Its values beat anything
+you would detect or assume. This skill uses `layout`/`repos`, `commands` (lint/typecheck/test per repo or package), and `git.commit_style`.
+
+**Multi-repo:** create worktrees in each repo a task touches, run each repo's own commands in review, and make the batch commit in every repo that changed, using the same subject line.
+
+**No config?** If the `spec-setup` skill is available, run it first, then continue here. If it
+isn't, detect what this skill needs from the repo, ask about anything ambiguous, and offer to save
+the answers to `.spec-driven.yml` (keys: `layout`, `repos`, `tracker`, `git`, `commands`,
+`specs_dir`).
+
+## Orchestration Model
+
+This skill's parallelism assumes your host can run multiple independent agents at once —
+Claude Code's Agent/Task tool, Codex CLI's `spawn_agent`/`wait_agent`, Cursor's Subagents or
+Background Agents, Antigravity's `invoke_subagent`, or whatever equivalent your host provides.
+Use that mechanism throughout; give each dispatched agent only the context specified in Step 4
+below, never the full conversation history.
+
+If your host has no such mechanism, fall back to processing each batch's tasks sequentially in
+the current session — implement one task fully, then the next — rather than skipping the batch.
+The review gate (Step 6) still applies; run it as a distinct pass with a fresh, unbiased read of
+the diff, even without a separate agent to run it in.
+
+## Prerequisites
+
+A `specs/{feature}/` directory containing:
+- `README.md` with batch assignments and task status checkboxes
+- `requirements.md` with feature context
+- `tasks/task-{nn}-*.md` files (one per task, self-contained)
+
+This structure is produced by the `spec-create` skill. If the user doesn't have a spec folder, suggest they create one first.
+
+## Orchestration
+
+### Step 1: Load the Spec
+
+1. Read `specs/{feature}/README.md`
+2. Read `specs/{feature}/requirements.md`
+3. Parse the **Task Status** section in the README — look at the checkboxes:
+   - `- [x]` = completed task (skip)
+   - `- [ ]` = pending task (include)
+4. Determine the **current batch**: the first batch that has any incomplete tasks
+5. If all tasks in all batches are complete, report "All tasks complete!" and stop
+
+This makes the skill **resumable** — if invoked on a partially completed spec, it picks up exactly where it left off.
+
+### Step 2: Process Each Batch
+
+For each batch starting from the current one, execute Steps 3 through 8 below, then advance to the next batch.
+
+### Step 3: Prepare Batch Tasks
+
+1. Read all incomplete task files for this batch from the `tasks/` subfolder
+2. **Check for file overlaps**: scan the "Files to Create" and "Files to Modify" sections across all tasks in this batch. If any file appears in more than one task, warn the user:
+
+   ```
+   Warning: File overlap detected in Batch {N}:
+   - {file-path} is modified by both task-{nn} and task-{mm}
+
+   Options:
+   1. Proceed anyway (risk of conflicts)
+   2. Run these tasks sequentially instead of in parallel
+   ```
+
+   Wait for the user's decision before proceeding.
+
+### Step 4: Dispatch Coder Agents
+
+For each task in the batch, delegate the work to an independent agent using your host's
+parallel-agent mechanism (see Orchestration Model above). Dispatch every task in the batch at
+once so they run concurrently — or, without a parallel-agent mechanism, work through them one
+at a time in the current session.
+
+Read `references/coder-prompt-template.md` and construct each agent's prompt by filling in:
+- **{requirements}**: full text of `requirements.md`
+- **{completed_tasks_summary}**: for each previously completed task, a one-paragraph summary of what was implemented and what files were created/modified (extract from the task file's Description section plus any completion notes)
+- **{task_content}**: full text of the task file being assigned
+
+The coder agents should NOT commit their changes — the orchestrator handles commits after review.
+
+**Isolate parallel coders in git worktrees when the host allows it.** Coders sharing one working
+tree can clobber each other's edits and each other's lint/test runs. If your host can run an agent
+in its own worktree (e.g. Claude Code's `isolation: "worktree"`), use it for every coder in a
+batch of 2+ tasks; otherwise create them yourself — `git worktree add -b spec/{feature}/task-{nn}
+../.worktrees/{feature}-task-{nn} HEAD` — and point each coder at its path. A single-task batch, or
+a host with no way to give an agent a different working directory, runs in the main tree as before.
+
+When the batch's coders finish, bring their work back into the main tree before the review gate:
+commit inside each worktree (`wip: task-{nn}`), then `git merge --squash` each task branch into the
+feature branch in task order, leaving the result unstaged. A merge conflict means the batch's tasks
+weren't independent — stop, show the conflicting files, and ask the user how to resolve them. Remove
+the worktrees and their branches (`git worktree remove`, `git branch -D`) once merged.
+
+### Step 5: Collect Results
+
+Wait for all coder agents in the batch to complete. Each agent should report:
+- Files created
+- Files modified
+- A summary of what was implemented
+
+If any agent fails (returns an error or crashes), note the failure and continue with the remaining results. Report the failure to the user after the batch.
+
+### Step 6: Code Review Gate
+
+Dispatch a single review pass in a fresh agent/session — not one of the coder agents from
+Step 4, since the review needs an unbiased read of the diff it didn't write. Use your host's
+parallel-agent mechanism if it supports spawning a distinct reviewer agent; otherwise perform
+the review directly in the current session as its own clearly delimited pass.
+
+Read `references/review-prompt-template.md` and construct the review prompt by filling in:
+- **{batch_number}**: current batch number
+- **{requirements}**: full text of `requirements.md`
+- **{task_summaries}**: for each task in this batch, the task title and the coder agent's completion summary
+- **{verification_commands}**: `commands.lint`/`typecheck`/`test` from `.spec-driven.yml` for each repo or package touched, or the project's own commands if there's no config (e.g., `pnpm lint && pnpm typecheck && pnpm test`)
+
+The review agent should:
+1. Run lint, typecheck, and tests
+2. Verify acceptance criteria and the tests named in each task file
+3. Check that files integrate correctly (imports resolve, types match)
+4. Check for security issues and code quality
+5. Return a structured verdict: **PASS** or **FAIL** with specific issues
+
+### Step 7: Fix Loop
+
+If the review returns **FAIL**:
+
+1. Parse the issues from the review (file paths, descriptions, suggested fixes)
+2. Group issues by the task they most closely relate to (match file paths against each task's "Files to Create/Modify")
+3. For each group, dispatch a coder agent (same mechanism as Step 4) with a fix prompt. Read `references/fix-prompt-template.md` and fill in:
+   - **{issues}**: the specific issues for this task group
+   - **{task_content}**: the original task file for context
+4. After fix agents complete, re-run the review (Step 6)
+
+**Cap at 3 review cycles per batch.** If the third review still fails, stop and report to the user:
+
+```
+Batch {N} review failed after 3 cycles. Outstanding issues:
+{list of remaining issues}
+
+Options:
+1. Fix these manually and re-run /spec-implement
+2. Proceed to the next batch anyway
+3. Stop here
+```
+
+### Step 8: Complete the Batch
+
+After the batch passes review (or the user chooses to proceed):
+
+1. **Update task files**: for each completed task, change the Status field from `pending` to `complete`
+2. **Update README.md**: change `- [ ]` to `- [x]` for each completed task
+3. **Commit the batch**:
+   ```
+   git add -A
+   git commit -m "feat({feature}): complete batch {N} — {brief summary}"   # or the config's git.commit_style
+   ```
+4. **Report batch completion**:
+   ```
+   Batch {N} of {total} complete.
+
+   Tasks completed:
+   - task-{nn}-{name}: {one-line summary}
+   - task-{mm}-{name}: {one-line summary}
+
+   Review: PASS
+   Commit: {hash}
+
+   Next: Batch {N+1} has {count} tasks ready for parallel execution.
+   ```
+
+### Step 9: Final Integration Review
+
+After all batches are complete:
+
+1. Run lint and typecheck one final time
+2. Dispatch a review pass (same mechanism as Step 6) to review the full scope of changes (all files modified across all batches)
+3. Report the final status:
+
+```
+Feature "{feature}" implementation complete.
+
+Batches completed: {N}/{N}
+Total tasks: {T}
+
+Verification:
+- Lint: {PASS/FAIL}
+- Typecheck: {PASS/FAIL}
+- Integration review: {PASS/FAIL with notes}
+
+Next steps:
+- Review the changes
+- Push and create a PR when ready
+```
+
+## Error Handling
+
+- **Coder agent failure**: mark the task as failed, report to user, continue with remaining tasks in the batch. The review step will catch integration issues.
+- **Lint/typecheck failure after fix attempts**: report the specific errors and ask the user whether to commit anyway or fix manually.
+- **All tasks already complete**: report completion and stop.
+- **Missing spec folder**: ask the user to provide the feature name or suggest creating a spec with `spec-create`.
+
+## Key Principles
+
+- **The orchestrator does not write code.** Its job is dispatch, review, and progress tracking. All implementation happens in coder subagents.
+- **Each coder agent gets exactly one task.** This keeps each agent's context focused and manageable.
+- **Completed task summaries are brief.** One paragraph per task — not the full file contents. This keeps coder agent prompts from growing unbounded as batches progress.
+- **The review gate is non-negotiable.** Every batch gets reviewed before commit. This catches integration issues early rather than letting them compound across batches.
+- **Progress is tracked in the spec files.** README checkboxes and task file status fields are the source of truth. This makes the skill resumable across sessions.