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

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.

package/skills/spec-implement/references/coder-prompt-template.md

@@ -0,0 +1,48 @@
+# Coder Agent Prompt Template
+
+Use this template when constructing prompts for coder subagents. Replace the placeholders (`{requirements}`, `{completed_tasks_summary}`, `{task_content}`) with actual content from the spec files.
+
+## Template
+
+```
+You are implementing a single task from a feature specification. Your job is to write the code described below — nothing more, nothing less.
+
+## Feature Context
+
+{requirements}
+
+## What's Already Been Built
+
+{completed_tasks_summary}
+
+## Your Task
+
+{task_content}
+
+## Instructions
+
+1. Read the relevant parts of the codebase to understand existing patterns, imports, and conventions
+2. Write the tests listed in the task's Tests section first, using the repo's existing test framework, and run them to see them fail for the right reason (skip this only where the task says "None")
+3. Implement everything described in the task's Technical Details and Implementation Steps until those tests pass
+4. Follow the project's existing code patterns and conventions
+5. Run the project's lint, typecheck, and test commands after making changes. Fix any errors before finishing — never delete, skip, or weaken a test to make it pass
+6. Do NOT commit your changes — if you're in your own git worktree, leave the changes uncommitted there too — the orchestrator handles commits after review
+6. When done, report:
+   - Files created (with paths)
+   - Files modified (with paths)
+   - Tests added and the test command's final result
+   - A one-paragraph summary of what you implemented
+```
+
+## Placeholder Details
+
+- **{requirements}**: paste the full text of `requirements.md`. This gives the agent overall feature context — the "what" and "why" — so it can make good judgment calls during implementation.
+
+- **{completed_tasks_summary}**: for each previously completed task, include a brief summary like:
+  ```
+  - task-01-setup-database: Created PostgreSQL schema with users and sessions tables. Files: src/db/schema.ts, src/db/migrations/001_initial.sql
+  - task-02-auth-config: Set up Better Auth with email/password provider. Files: src/lib/auth.ts, src/lib/auth-client.ts
+  ```
+  Keep each entry to 1-2 lines. The purpose is to give the agent awareness of what exists, not full implementation details.
+
+- **{task_content}**: paste the full text of the task file (task-{nn}-{name}.md). This is the agent's primary instruction set — it contains the description, technical details, files to create/modify, and acceptance criteria.

package/skills/spec-implement/references/fix-prompt-template.md

@@ -0,0 +1,38 @@
+# Fix Agent Prompt Template
+
+Use this template when constructing prompts for coder agents that fix issues found during code review. Replace the placeholders with actual content.
+
+## Template
+
+```
+You are fixing specific issues found during code review. Address every issue listed below — do not skip any.
+
+## Issues to Fix
+
+{issues}
+
+## Original Task Context
+
+{task_content}
+
+## Instructions
+
+1. Fix each issue listed above. The review provided file paths, line numbers, and suggested fixes — use those as your starting point.
+2. Run the project's lint and typecheck commands after making fixes. Resolve any new errors your fixes introduce.
+3. Do NOT commit your changes — the orchestrator handles commits.
+4. Do NOT make changes beyond what's needed to fix the listed issues. Stay within scope.
+5. When done, report:
+   - What you fixed (reference each issue)
+   - Any files modified
+   - If you could NOT fix an issue, explain why
+```
+
+## Placeholder Details
+
+- **{issues}**: the specific issues from the review that relate to this task. Include file paths, line numbers, descriptions, severity, and suggested fixes. Example:
+  ```
+  - Issue 1: src/api/users.ts:42 — Missing error handling for database connection failure — Severity: high — Suggested fix: wrap the query in try/catch and return a 500 response
+  - Issue 2: src/api/users.ts:15 — Unused import 'Session' — Severity: low — Suggested fix: remove the import
+  ```
+
+- **{task_content}**: the full text of the original task file for context. The fix agent may need to reference the task's technical details or acceptance criteria to understand the intended behavior.

package/skills/spec-implement/references/review-prompt-template.md

@@ -0,0 +1,50 @@
+# Review Agent Prompt Template
+
+Use this template when constructing prompts for the code review agent that runs between batches. Replace the placeholders with actual content.
+
+## Template
+
+```
+You are reviewing the combined output of Batch {batch_number} of a feature implementation. Multiple coder agents worked in parallel on separate tasks — your job is to verify everything integrates correctly and meets quality standards.
+
+## Feature Context
+
+{requirements}
+
+## Tasks Completed in This Batch
+
+{task_summaries}
+
+## Review Checklist
+
+1. **Verification**: Run `{verification_commands}` and report results. Fix nothing — just report.
+2. **Acceptance Criteria & Tests**: For each task listed above, check whether the implementation meets the acceptance criteria from its task file, and that the tests named in its Tests section exist, actually exercise that behaviour, and pass. Flag tests that were deleted, skipped, or weakened.
+3. **Integration**: Verify that files created by different tasks work together:
+   - Imports resolve correctly
+   - Types match across module boundaries
+   - No duplicate or conflicting definitions
+   - Shared state (env vars, config) is consistent
+4. **Code Quality**: Check for security issues, performance problems, and adherence to project conventions.
+5. **Scope**: Verify each task stayed within its defined scope (Files to Create/Modify). Flag any unexpected file changes.
+
+## Verdict
+
+Respond with one of:
+
+**VERDICT: PASS**
+All checks passed. Include any minor observations as notes.
+
+**VERDICT: FAIL**
+Include a structured list of issues:
+- **Issue 1**: {file:line} — {description} — Severity: {high/medium/low} — Suggested fix: {fix}
+- **Issue 2**: ...
+
+Group issues by the task they most closely relate to (based on which task's files are affected). This helps the orchestrator dispatch targeted fix agents.
+```
+
+## Placeholder Details
+
+- **{batch_number}**: the current batch number (e.g., "2")
+- **{requirements}**: full text of `requirements.md`
+- **{task_summaries}**: for each task in the batch, include the task title and the coder agent's completion summary (files created/modified + what was implemented)
+- **{verification_commands}**: the project's lint, typecheck, and test commands. Check for `package.json` scripts (or the stack's equivalent) — typically `pnpm lint && pnpm typecheck && pnpm test` or similar.