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

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.

package/skills/spec-investigate/SKILL.md

@@ -0,0 +1,323 @@
+---
+name: spec-investigate
+description: >
+  Deep, evidence-based technical investigation of a piece of work BEFORE any specification or
+  implementation begins — starting from a ticket (Jira, GitHub Issues, Linear), a meeting/call
+  transcript, a plain-text description, a doc/PRD file, a Slack/email thread, or an error log.
+  Use when the user says "investigate STP-123", "spec-investigate", "look into this before we
+  plan it", or hands over any of those inputs and wants the
+  system understood (current behaviour, root cause, affected repos/files, risks, open
+  questions) rather than fixed or built yet. This is the first stage of the
+  investigate → create → (human approval) → implement → verify → ship pipeline — it hands off
+  to the existing spec-create skill and does not replace, duplicate, or invoke spec-create,
+  spec-implement, spec-verify, or spec-ship itself. Ticket-agnostic: works for bugs, features,
+  refactors, security, performance, infra, or cross-repository tickets in any repo.
+license: MIT
+---
+
+# spec-investigate
+
+Discover and record the facts. Do not design the fix and do not write any code.
+
+This skill is stage 1 of:
+
+```
+spec-investigate → spec-create → human approval → spec-implement → spec-verify → spec-ship
+```
+
+`spec-create`, `spec-implement`, `spec-verify`, and `spec-ship` already exist elsewhere (e.g. the
+`spec-driven-dev` plugin, or whatever equivalent this host provides). **Never create, redesign,
+duplicate, or invoke those skills from here.** Your only output is an investigation report plus a
+ready-to-use work branch; a human decides when to run `spec-create` next.
+
+## 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` (where to look and what each repo does), `tracker`, `git.remote`, `git.base_branch`, `git.branch_name`, and `specs_dir`.
+
+**Monorepo:** name the package(s) involved. **Multi-repo:** search every listed repo whose role fits the ticket, and create the work branch, with the same name, only in the repos the investigation shows need changes.
+
+**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`).
+
+## Invocation
+
+```
+spec-investigate STP-123
+spec-investigate https://<org>.atlassian.net/browse/STP-123
+spec-investigate STP-123 --context ./notes.md
+spec-investigate #482                      # GitHub issue in the current repo
+spec-investigate https://github.com/<owner>/<repo>/issues/482
+spec-investigate https://linear.app/<team>/issue/ENG-91
+spec-investigate ./call-transcript.txt          # transcript, notes, PRD, RFC, log — any file
+spec-investigate "Checkout times out for EU users since Tuesday's deploy"   # plain text
+spec-investigate                               # with the material pasted in the same message
+```
+
+The only required input is *something that describes the work* — a ticket ID/URL, a file, or text
+pasted into the message. Below, "the ticket" means that primary input, whatever form it took. `--context` (a file path, or pasted text in the
+same message) is optional supplementary evidence — a call transcript, meeting notes, a `.md`/`.txt`
+file. Never block or stall waiting for context that doesn't exist; proceed without it.
+
+Never hardcode a specific ticket ID into your behavior. Everything below must work identically for
+any ticket key, tracker, or free-form input.
+
+## The one rule everything else serves
+
+**Do not guess when the answer can be discovered.** Every non-trivial claim in the final report
+must be traceable to something you actually read — code, config, tests, git history, the
+ticket, linked docs — not inferred from a plausible-sounding folder name or a guess at convention. Work
+the loop:
+
+```
+Question → Search → Evidence → Trace → Cross-check → Concrete answer
+```
+
+"I haven't looked yet" is not the same as "unknown." Only write UNKNOWN after you've actually
+searched and found nothing — and say what you searched.
+
+Calibrate investigation depth to the ticket. A one-line copy change doesn't need an architecture
+diagram; a cross-service auth or data-migration ticket does. Don't manufacture process for a
+trivial ticket, and don't shortcut a genuinely risky one.
+
+---
+
+## Step 0 — Resolve the input and set up the branch safely
+
+1. **Identify what kind of input this is and load all of it.** A tracker reference:
+   - `*.atlassian.net/browse/KEY-123` → Jira (Atlassian MCP tool, `jira`/`acli` CLI, or REST).
+   - `#482`, `owner/repo#482`, or a `github.com/.../issues/482` URL → GitHub Issues
+     (`gh issue view 482 --comments --json title,body,labels,comments,...`).
+   - `linear.app/.../issue/ENG-91` → Linear (Linear MCP tool or API).
+   - A bare `KEY-123` → use `tracker` from `.spec-driven.yml`; without one, the tracker the project already uses (CLAUDE.md/AGENTS.md, branch
+     names, PR links in `git log`); if that's ambiguous, try the trackers this host can reach and
+     ask if none resolves. If you can't reach the tracker at all, ask the user to paste the ticket
+     rather than guessing its contents.
+
+   Anything else is free-form input — read it in full:
+   - A file path (`.txt`/`.md`/`.vtt`/`.srt`/`.pdf`/`.docx`/log) → read the whole file.
+   - Pasted text — a transcript, Slack/email thread, PRD excerpt, stack trace, or a one-line
+     description → use it as-is.
+   - A URL to a doc, PR, Sentry/Datadog issue, or design → fetch it with whatever access the host
+     has; ask the user to paste it if you can't.
+   Free-form input has no fields, so extract them: a working title, the type of work, the stated
+   problem and desired outcome, any acceptance criteria actually stated, and who decided what.
+   Apply Step 1's classification to it (requirement vs. proposal vs. question) — a transcript is
+   not a spec. If it references a ticket, fetch that too and treat it as the scope of record.
+
+   For a ticket, pull title, type,
+   priority, labels, components, full description, comments, linked/parent/child issues, and
+   attachments. Follow meaningful links (a linked ticket that defines the actual contract, a
+   linked design doc) rather than stopping at the description.
+
+2. **Determine the repository/repositories.** If you're already inside a git working directory
+   that plausibly owns this ticket's area, use it. If the ticket is cross-repo (confirmed from its
+   content, not assumed), identify every relevant repo and investigate each one — don't silently
+   pick just the one you happen to be sitting in. If you can't tell which repo(s) are relevant
+   from the ticket alone, say so and ask, rather than guessing.
+
+3. **`git status` first, always.** If there are uncommitted changes unrelated to this ticket:
+   **stop** — do not stash, reset, clean, discard, commit, or force anything on the user's behalf.
+   Report exactly what you found and ask how to proceed.
+
+4. **Determine the correct remote and base branch.** Run `git remote -v` — don't assume `origin`
+   is the right remote if there's more than one. Pick the base branch in this order: `git.base_branch` in
+   `.spec-driven.yml` → what `CLAUDE.md`/`AGENTS.md`/memory/prior project context says for this repo → the remote's default
+   branch (`git remote show <remote>` or `gh repo view --json defaultBranchRef`). If the repo also
+   has an integration branch (`staging`, `develop`) that recent work branches were cut from, and
+   nothing says which to use, stop and ask rather than guessing. Fetch it and record its latest
+   commit SHA.
+
+5. **Name the branch by the repo's convention, then stick to it exactly.** Use, in order: `git.branch_name`
+   in `.spec-driven.yml` → an explicit rule in `CLAUDE.md`/`AGENTS.md`/memory → the pattern recent branches already follow
+   (`git branch -r --sort=-committerdate | head -20` — e.g. bare `STP-123`, or `fix/STP-123-…`) →
+   default `<type>/<TICKET-ID>-<short-slug>` with the same prefixes `spec-ship` uses (`feat/`,
+   `fix/`, `refactor/`, `chore/`, `docs/`). Don't invent a new pattern alongside an existing one.
+   With no ticket ID (free-form input), use `<type>/<short-slug>` from the working title, and ask
+   whether there's a ticket it should be linked to.
+
+6. **If the branch already exists** (locally or remotely): do not delete, reset, rebase, or
+   recreate it. Investigate first — what commit is it on, does it already have commits ahead of
+   base, uncommitted changes, an existing `specs/` folder or investigation report, signs of
+   started implementation? If continuing risks losing someone's work, **stop and report** instead
+   of proceeding. If it's clean and simply behind the latest base, that's fine to note, not fix
+   unprompted.
+
+7. **If the branch doesn't exist:** create it directly from the fetched base commit. Never modify
+   the base branch itself, never force-push.
+
+8. Record for the report: source type (ticket / transcript / text / doc / log), ticket ID +
+   tracker + URL or file path, working title, type of work, branch name, base branch, base commit
+   SHA.
+
+## Step 1 — Read the optional context, but don't crown it source of truth
+
+If `--context` or pasted material was given, read it fully. It is **supplementary evidence**, not
+automatically a requirement. For every substantive claim in it, classify what kind of statement it
+actually is: a stated requirement, a business decision, a technical decision, a constraint, a
+description of existing behaviour, a proposed (not decided) solution, a question, an assumption, or
+just an example. A sentence like "maybe we should add another endpoint" is a proposed approach to
+investigate against the existing API, not a requirement to build it.
+
+Default evidence hierarchy when sources disagree — but actually evaluate conflicts, don't apply
+this mechanically:
+
+```
+Repository / actual system behaviour
+        ↓
+Ticket scope and acceptance criteria
+        ↓
+User-provided context / meeting discussion
+        ↓
+Supporting documentation
+```
+
+When the context introduces something not in the ticket at all and it would materially affect scope,
+architecture, data, APIs, security, or effort: don't fold it in silently. Flag it as Confirmed /
+Likely / Proposed / Needs Clarification, and if sources genuinely conflict, document it as:
+
+```
+Ticket says: ...
+Additional context says: ...
+Repository currently does: ...
+Impact: ...
+Recommended clarification: ...
+```
+
+No context supplied is a completely normal case — proceed on ticket + repository evidence alone,
+don't ask for a transcript that may not exist.
+
+## Step 2 — Understand the ticket itself
+
+From the ticket: problem statement, expected behaviour, acceptance criteria, type (bug / feature /
+refactor / security / infra / perf / data / integration / UI / API / DB — whatever it actually is,
+don't force it into a category it isn't). Pull in anything linked that actually defines scope.
+
+## Step 3 — Map the relevant system before touching anything
+
+For each relevant repo, briefly note why it's relevant and which app/service/module inside it
+matters. Then trace the ACTUAL implementation — not what the folder names suggest — through
+whichever of these layers are real for this stack:
+
+```
+Client/UI → Route/Controller → Service/Business logic → Data access → Database → External integration
+```
+
+Also check, wherever relevant to the ticket (skip what plainly doesn't apply): auth/authz,
+validation, state management, feature flags, background jobs/queues/events, caching, retries,
+idempotency, error handling, logging/observability, deployment behaviour.
+
+For the specific behaviour the ticket is about, document the real execution flow with concrete
+references — file paths, function/class/component names, route handlers, DB tables/migrations,
+config keys, env vars. "The backend handles this" is not an answer; name the file and function.
+
+## Step 4 — Root cause (bug/regression tickets)
+
+Don't accept the ticket's stated cause at face value — verify it against the code. Classify your
+conclusion as `CONFIRMED ROOT CAUSE`, `LIKELY ROOT CAUSE` (explain the gap), or
+`ROOT CAUSE NOT YET CONFIRMED` (explain what more would nail it down). If the real cause differs
+from what the ticket claims, say so plainly and show the evidence.
+
+## Step 5 — Change surface, without scope-creeping it
+
+Bucket every piece of work you can see coming into exactly one of:
+
+- **Required** — needed to satisfy the ticket.
+- **Supporting** — needed to safely enable the required change (a migration, a flag, a test seam).
+- **Optional** — genuinely nice, not required; name it as optional, don't fold it into Required.
+- **Out of scope** — things you noticed along the way that should explicitly NOT be touched now.
+
+An investigation that quietly balloons into "and also we should refactor X" has failed this step.
+
+## Step 6 — Dependencies, risks, security, performance (as relevant)
+
+For each meaningful risk: what it is, why it exists, the potential impact, the evidence behind it,
+and what mitigation it implies — don't list generic risk categories with nothing backing them.
+Cover, where actually applicable to this ticket (don't manufacture relevance): internal/external
+dependencies, API/DB/schema changes, backward compatibility, data migration, concurrency/race
+conditions, retries/idempotency/duplicate processing, rollback, auth/authz/tenant isolation, input
+validation, secrets/sensitive data handling, query performance/N+1/pagination, caching, rate
+limits, timeouts. Tie every recommendation to evidence you actually found — not "this could
+theoretically be slow."
+
+## Step 7 — Testing landscape
+
+Find what already tests this area (unit/integration/API/component/E2E, fixtures, mocks, CI config)
+and what doesn't. Note existing patterns worth reusing and obvious regression risk if untested
+paths change. **Do not write or implement any tests here** — this step only maps the landscape for
+`spec-create` to plan against.
+
+## Step 8 — Completion gate
+
+Before writing the report, check you can actually answer (or have correctly marked UNKNOWN with
+real justification, or flagged as a business decision) every one of:
+
+what the ticket asks for · current vs. expected behaviour · where the current behaviour lives ·
+how that flow actually works · why it behaves that way · confirmed root cause (if a bug) ·
+affected repos/files · the real change surface · dependencies and risks · security considerations ·
+performance/reliability considerations · existing test coverage · edge cases that matter ·
+anything from optional context that changes scope · what's genuinely unknown · what needs a human
+business decision.
+
+If something on this list is still open and investigable, keep investigating — don't write the
+report yet. If it's genuinely a product/business call, name the exact question that needs an
+answer; don't invent one.
+
+## Evidence labels
+
+Tag non-obvious findings so `spec-create` knows how much weight to put on them:
+
+- **VERIFIED** — confirmed directly in code, config, DB, tests, git history, the ticket, or official docs.
+- **INFERRED** — well-supported by multiple signals but not directly confirmed; say why.
+- **ASSUMPTION** — can't currently be proven; keep this list short, never hide one inside a
+  recommendation as if it were fact.
+- **UNKNOWN** — investigated and still open; say what you searched and why it didn't resolve.
+
+## Step 9 — Write the report
+
+Write it to `{specs_dir}/{feature-slug}/investigation.md` (`specs_dir` from config, default `specs`) in the repo (create the `specs/` folder if
+needed — this mirrors where `spec-create` already keeps its own output, so the handoff reads
+naturally from the same place; don't commit this folder if the repo's convention already
+gitignores `specs/`, matching whatever this repo already does there). Use the structure in `references/report-template.md`.
+
+Every section should be specific and evidence-backed, or explicitly say "None found" /
+"Not applicable to this ticket" rather than being left looking like an oversight.
+
+**Recommended Implementation Direction** describes the technically-supported direction the
+evidence points to — reusing existing patterns the investigation actually found, not a novel
+architecture invented on the spot. It is not permission to start building; flag any business
+decision it depends on.
+
+## Step 10 — Stop, hand off, don't bleed into the next stage
+
+Report completion plainly:
+
+```
+Investigation complete.
+
+Source: <ticket ID, or file / "pasted text">
+Branch: <branch> (created from <base> @ <sha>)
+Report: specs/<feature-slug>/investigation.md
+
+Next step: run spec-create for <feature-slug> — it can read the investigation above directly rather than
+re-discovering the system.
+```
+
+Do not run `spec-create` yourself unless the user explicitly asks you to chain into it in the same
+turn. Never run `spec-implement` from here under any circumstance — that skips the human
+review/approval step this workflow depends on.
+
+## Hard boundaries (do not cross these)
+
+- No implementation: no app code, API, schema, migration, UI, config, dependency, infra, or test
+  changes. Finding an obvious one-line fix doesn't change this — document it, don't apply it.
+- No code changes get committed or pushed from this skill — the only commit this skill produces,
+  if any, is the empty ticket branch itself (creating a branch doesn't require a commit).
+- Never touch the base branch.
+- Never discard, stash, reset, or overwrite existing uncommitted work without being told to.
+- Never force-push, never delete an existing branch without explicit approval.
+- Never fabricate an answer to fill a gap — mark it UNKNOWN or as a business decision instead.
+- Never silently expand scope based on optional context the ticket itself doesn't support.

package/skills/spec-investigate/references/report-template.md

@@ -0,0 +1,53 @@
+# Investigation Report Template
+
+Copy this structure into `specs/{feature-slug}/investigation.md`.
+
+```markdown
+# Investigation
+
+## Source
+- Source Type: (ticket / transcript / plain text / doc / log / mixed)
+- Ticket ID / Tracker / URL: (or "None")
+- Source Files / Links:
+- Title:
+- Type of Work:
+- Priority:
+- Branch:
+- Base Branch:
+- Base Commit:
+
+## Business Context
+## Problem Statement
+## Expected Behaviour
+## Current Behaviour
+## Relevant Repositories
+## Relevant Files / Modules
+## Existing Architecture
+## Current Flow
+## Data Flow
+## Root Cause
+## Evidence
+### Verified
+### Inferred
+### Unknown
+### Assumptions
+## Required Change Surface
+## Supporting Changes
+## Optional Changes
+## Out of Scope
+## Dependencies
+## Risks
+## Security Considerations
+## Performance / Reliability Considerations
+## Testing Context
+## Edge Cases
+## Additional Context
+### Business Decisions
+### Technical Decisions
+### Potential Requirements
+### Proposed Solutions Discussed
+### Open Questions
+### Conflicts / Discrepancies
+## Recommended Implementation Direction
+## References
+```

package/skills/spec-setup/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: spec-setup
+description: >
+  One-time discovery that teaches the spec-driven-dev pipeline how THIS project works, and saves
+  the answers to .spec-driven.yml — project layout (single repo, monorepo, or multiple repos),
+  issue tracker, base branch, PR target, branch naming, commit style, and the lint/typecheck/test/
+  build/dev commands. Use when the user says "set up spec-driven", "configure the pipeline",
+  "spec-setup", "change our branch rules", or when any other spec-* skill finds no
+  .spec-driven.yml. Detects everything it can from the repos first and only asks about what is
+  ambiguous. Writes config only — never changes code, branches, or commits.
+license: MIT
+---
+
+# spec-setup
+
+Learn this project's rules once, save them, and let every other `spec-*` skill reuse them. Team
+rules live in a config file the team can review and change — never in the skills themselves.
+
+## Where the config lives
+
+`.spec-driven.yml`, found by walking up from the current directory (stop at the home folder). The
+first one found wins.
+
+| Layout | Put the file in | Share it? |
+|---|---|---|
+| `single` | the repo root | Commit it — the whole team gets the same rules |
+| `monorepo` | the repo root | Commit it |
+| `multi-repo` | the shared parent folder of the repos (usually not itself a git repo) | Personal by default; offer to also commit a copy into the repo the team treats as "home" |
+
+A multi-repo config only applies inside the repos it lists. If the current repo sits under that
+folder but isn't listed, treat it as having no config (ask whether to add it).
+
+## Step 1 — Detect before asking
+
+Read, don't guess. Collect a draft of every field in `references/config-template.yml`:
+
+1. **Layout.**
+   - Inside a git repo with workspace markers (`pnpm-workspace.yaml`, `workspaces` in
+     `package.json`, `turbo.json`, `nx.json`, `lerna.json`, `go.work`, `[workspace]` in
+     `Cargo.toml`, several `apps/*`/`packages/*`/`services/*` with their own manifests) →
+     `monorepo`; list the packages.
+   - Not inside a git repo, but sibling folders are git repos → candidate `multi-repo`. Group them
+     by remote owner (`git remote get-url origin`) and show the groups — the user picks which repos
+     belong together. Never assume every folder in the parent belongs. Always also ask whether
+     repos in **other folders** belong (e.g. `~/clients/billing`). Check each path is a git repo,
+     and store paths inside the workspace as relative and paths outside it as absolute.
+   - The user can override the detected layout. If they choose `multi-repo` from inside one repo,
+     the workspace folder defaults to that repo's parent, with the current repo pre-selected. If
+     they choose `monorepo`, ask for the package folders. Never write a `multi-repo` config with
+     no repos.
+   - Otherwise → `single`.
+2. **Existing written rules.** `CLAUDE.md`, `AGENTS.md`, `CONTRIBUTING.md`, PR templates,
+   `.github/workflows`. Anything stated there is a strong default — quote it back to the user.
+3. **Tracker.** Ticket keys in recent branch names and commit subjects (`STP-123`, `#45`,
+   `ENG-91`), Jira/Linear links in PR templates or docs, whether GitHub Issues are enabled
+   (`gh repo view --json hasIssuesEnabled`).
+4. **Git, per repo.** Default branch (`git symbolic-ref refs/remotes/origin/HEAD` or
+   `gh repo view --json defaultBranchRef`); integration branches (`staging`, `develop`,
+   `pre-prod`); which branch recent PRs targeted (`gh pr list --state merged --limit 20 --json
+   baseRefName`); the pattern of the last ~20 remote branch names; the commit style from
+   `git log -30 --format=%s`.
+5. **Commands, per repo/package.** `package.json` scripts plus the lockfile's package manager,
+   `Makefile`, `pyproject.toml`/`tox.ini`, `Cargo.toml`, `go.mod`, `composer.json`, CI workflow
+   steps (CI is often the most truthful source). Dev URL from the dev script, `.env.example`, or
+   framework defaults.
+
+## Step 2 — Confirm in one round
+
+Show the draft as a short table grouped by layout, tracker, git, commands, and specs location.
+Mark each value **detected** (with where it came from) or **guess**. Then ask only about guesses
+and conflicts — in one message, not a drip of questions. Typical ones:
+
+- "Your repos default to `master`, but recent PRs targeted `staging`. Cut work from `staging`?"
+- "Recent branches are bare ticket IDs (`STP-282`). Keep that, or use `fix/STP-282-short-slug`?"
+- "These 6 repos share the `acme` GitHub org. Do they form one workspace for the pipeline?"
+- "Where should specs live — this folder's `specs/`, or inside one repo so they go through PRs?"
+
+If the user says "just use the defaults", accept the detected values and the template defaults
+for the rest.
+
+## Step 3 — Write and report
+
+1. Write `.spec-driven.yml` using `references/config-template.yml` as the shape. Keep its
+   comments; drop fields that don't apply (e.g. `repos:` for `single`). Per-repo values only go
+   under `repos:` where they differ from the top level.
+2. If it's inside a repo, tell the user it's meant to be committed (so teammates get the same
+   rules) — don't commit it yourself.
+3. If `npx` is available, run `npx -y @benjaminthomas/spec-driven-dev doctor` from the config's folder. It checks
+   that every branch, folder, and `npm run` script in the file really exists. Fix anything it
+   reports before finishing.
+4. Report: the file path, a one-line summary per section, and "re-run spec-setup any time these
+   change".
+
+## Updating
+
+Re-running `spec-setup` with an existing config: load it, re-detect, and show only what changed or
+looks stale (a branch that no longer exists, a script that was renamed). Never silently overwrite
+a value the user set by hand.
+
+## Boundaries
+
+- Writes `.spec-driven.yml` and nothing else. No branches, commits, pushes, installs, or code.
+- Never put secrets, tokens, or credentials in the config.
+- A value in the config beats a detected value. If the config looks wrong mid-run (a base
+  branch that doesn't exist), the other skills stop and point back here rather than overriding it.

package/skills/spec-setup/references/config-template.yml

@@ -0,0 +1,45 @@
+# .spec-driven.yml — project rules for the spec-driven-dev skills.
+# Written by spec-setup from what it detected + what you confirmed. Edit freely, or re-run
+# spec-setup to update it. Every spec-* skill reads this before doing anything else.
+version: 1
+
+# single     — one git repo, one app
+# monorepo   — one git repo, several apps/packages (pnpm/npm/yarn workspaces, Turborepo, Nx, Go/Cargo workspaces…)
+# multi-repo — several separate git repos that change together (this file sits in their shared parent folder)
+layout: single
+
+# The repos (multi-repo) or packages (monorepo) the pipeline may touch. Omit for `single`.
+# Each entry can override the top-level git/commands settings.
+# repos:
+#   - path: api                 # relative to this file
+#     role: REST API + workers  # one line: what lives here, so investigations know where to look
+#     git:
+#       base_branch: staging
+#     commands:
+#       test: npm test
+#   - path: web
+#     role: React frontend
+
+tracker:
+  type: jira                    # jira | github | linear | none
+  key: STP                      # ticket key prefix (jira/linear); omit for github/none
+  url: https://example.atlassian.net   # site/org/repo URL, if any
+
+git:
+  remote: origin
+  base_branch: default          # branch work is cut from; "default" = the remote's default branch
+  pr_target: default            # branch PRs go into; usually the same as base_branch
+  branch_name: "{type}/{ticket}-{slug}"   # placeholders: {ticket} {slug} {type}; e.g. "{ticket}" for bare STP-123
+  commit_style: conventional    # conventional (feat: …) | ticket (STP-123: …) | freeform
+
+# Leave a command empty if the project doesn't have it; skills skip what's empty.
+commands:
+  install: ""
+  lint: ""
+  typecheck: ""
+  test: ""
+  build: ""
+  dev: ""                       # how spec-verify starts the app
+  dev_url: ""                   # where it answers, e.g. http://localhost:3000
+
+specs_dir: specs                # where specs/<feature>/ folders go (relative to this file)