@benjaminthomas/spec-driven-dev 1.6.0 → 1.7.0

package/README.md

@@ -93,6 +93,23 @@ words in quotes.
 /spec-ship                         "ship it"
 ```
 
+**The right model for each task.** `spec-create` rates every task **light**, **standard**, or
+**deep**, based on how much it touches and how risky it is (data, security, concurrency, public
+contracts, unclear requirements). `spec-implement` then runs each task on the model for its tier:
+
+| Tier | Typical task | Claude Code default |
+|---|---|---|
+| light | copy change, config value, small UI tweak following an existing pattern | `haiku` |
+| standard | a normal feature slice: route + service + tests | `sonnet` |
+| deep | migrations with backfills, auth/permissions, concurrency, cross-repo contracts | `opus` |
+
+- **Reviews:** each batch's review runs on at least `standard`, and on the batch's highest tier.
+- **Escalation:** a task that still fails after a fix round is retried one tier up.
+- **Tools that run one model per session** (Cursor, Codex) don't switch silently. Before a heavier
+  batch, they pause and tell you which model to switch to.
+- **Changing the models:** edit the `models:` section of `.spec-driven.yml`, for example to use a
+  newer model for `deep`.
+
 **Fewer stops:** after reviewing the spec, say **"approved, run it through"**. The workflow then
 implements, verifies, and commits in one go. It stops at the first failure, and it always asks
 before pushing or opening a PR. To make this the default after approval, choose `run-through` during
@@ -139,6 +156,7 @@ straight away, so you can fix it before moving on. Press Enter on an empty line
 | Lint / typecheck / test / build / dev commands | `package.json` scripts and lockfile (per repo or package) | `pnpm run lint` |
 | Where specs go | (you choose) | `specs/` |
 | After you approve a spec | (you choose) | `stop` (wait at each stage) or `run-through` |
+| Model per task tier | written with defaults: Claude Code `haiku`/`sonnet`/`opus`, others `default` | edit `models:` later |
 
 **Where the file lives, by layout:**
 
@@ -542,15 +560,15 @@ skips that step rather than failing.
 
 | Skill | Stage | SKILL.md lines | Words | Supporting files |
 |---|---|---:|---:|---:|
-| `spec-setup` | 0 · configure | 114 | 1,022 | 1 |
-| `spec-investigate` | 1 · understand | 325 | 2,741 | 1 |
-| `spec-create` | 2 · plan | 157 | 1,415 | 4 |
-| `spec-implement` | 3 · build | 273 | 2,109 | 3 |
+| `spec-setup` | 0 · configure | 117 | 1,068 | 1 |
+| `spec-investigate` | 1 · understand | 330 | 2,794 | 1 |
+| `spec-create` | 2 · plan | 166 | 1,503 | 5 |
+| `spec-implement` | 3 · build | 298 | 2,375 | 3 |
 | `spec-verify` | 4 · prove | 155 | 1,492 | 1 |
 | `spec-checkpoint` | 5 · commit | 108 | 795 | 0 |
 | `spec-ship` | 6 · PR | 220 | 1,268 | 0 |
 | `generative-seo` | standalone | 255 | 2,209 | 7 |
-| **Total** | | **1,607** | **13,051** | **17** |
+| **Total** | | **1,649** | **13,504** | **18** |
 
 - **8** skills: **1** setup + **6** workflow stages + **1** standalone
 - **4** tools supported natively (Claude Code, Codex CLI, Cursor, Antigravity), plus an MCP fallback

package/bin/cli.mjs

@@ -235,11 +235,22 @@ function toYaml(c) {
   out += `tracker:\n  type: ${c.tracker.type}\n  key: ${y(c.tracker.key)}\n  url: ${y(c.tracker.url)}\n`;
   out += `git:\n${cmds(c.git, "  ")}\n`;
   out += `commands:\n${cmds(c.commands, "  ")}\n  dev_url: ${y(c.devUrl)}\n`;
+  out += "models:   # model per task tier (light / standard / deep); \"default\" = the session's model\n" + Object.entries(MODEL_DEFAULTS)
+    .map(([tool, m]) => `  ${tool}:\n` + TIERS.map((t) => `    ${t}: ${m[t]}\n`).join("")).join("");
   out += `pipeline:\n  after_approval: ${c.afterApproval || "stop"}   # stop | run-through (implement → verify → checkpoint; ship always asks)\n`;
   return out + `specs_dir: ${y(c.specsDir)}\n`;
 }
 
 const LAYOUTS = ["single", "monorepo", "multi-repo"];
+const TIERS = ["light", "standard", "deep"];
+// Aliases, not dated model IDs, so they keep pointing at the current models. Other tools default to
+// the session's own model; spec-implement then tells you when to switch.
+const MODEL_DEFAULTS = {
+  claude: { light: "haiku", standard: "sonnet", deep: "opus" },
+  cursor: { light: "default", standard: "default", deep: "default" },
+  codex: { light: "default", standard: "default", deep: "default" },
+  antigravity: { light: "default", standard: "default", deep: "default" },
+};
 const splitList = (v) => (v || "").split(",").map((x) => x.trim()).filter(Boolean);
 // Paths are stored relative to the config's folder when inside it, absolute otherwise.
 const real = (p) => { try { return fs.realpathSync(p); } catch { return p; } }; // /var vs /private/var etc.
@@ -466,7 +477,8 @@ function parseYaml(text) {
     }
     const m = line.match(/^([\w-]+):\s*(.*)$/);
     if (!m) continue;
-    const [, key, val] = m;
+    const [, key, rawVal] = m;
+    const val = rawVal.replace(/(^|\s+)#.*$/, "").trim();  // `key:   # comment` opens a block
     if (val === "") {
       const next = text.split("\n").slice(text.split("\n").indexOf(raw) + 1).find((l) => l.trim() && !l.trim().startsWith("#"));
       parent[key] = next && next.trim().startsWith("- ") ? [] : {};
@@ -499,6 +511,11 @@ function doctor() {
   if (!["single", "monorepo", "multi-repo"].includes(c.layout)) problems.push(`layout "${c.layout}" must be single, monorepo, or multi-repo`);
   if (c.tracker && !["jira", "github", "linear", "none"].includes(c.tracker.type)) problems.push(`tracker.type "${c.tracker.type}" must be jira, github, linear, or none`);
   if (c.git?.commit_style && !["conventional", "ticket", "freeform"].includes(c.git.commit_style)) problems.push(`git.commit_style "${c.git.commit_style}" must be conventional, ticket, or freeform`);
+  for (const [tool, m] of Object.entries(c.models || {})) {
+    if (typeof m !== "object") { problems.push(`models.${tool} must list light / standard / deep`); continue; }
+    for (const t of TIERS) if (!m[t]) problems.push(`models.${tool}.${t} is missing (use "default" for the session's model)`);
+    for (const k of Object.keys(m)) if (!TIERS.includes(k)) problems.push(`models.${tool}.${k}: unknown tier (use light, standard, deep)`);
+  }
   if (c.pipeline?.after_approval && !["stop", "run-through"].includes(c.pipeline.after_approval)) problems.push(`pipeline.after_approval "${c.pipeline.after_approval}" must be stop or run-through`);
   if (c.git?.branch_name && !/\{(ticket|slug)\}/.test(c.git.branch_name)) problems.push(`git.branch_name "${c.git.branch_name}" needs {ticket} or {slug}`);
   const repos = c.layout === "single" ? [{ path: "." }] : Array.isArray(c.repos) ? c.repos : [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "description": "Spec-driven AI development workflow (investigate → spec → implement → verify → ship) as Agent Skills for Claude Code, Cursor, Codex CLI and Antigravity.",
   "type": "module",
   "bin": {

package/skills/spec-create/SKILL.md

@@ -68,6 +68,11 @@ Think carefully about granularity. Too coarse and agents can't work in parallel.
 
 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.
 
+**Rate each task's complexity.** Read `references/complexity-rubric.md` and give every task a tier
+(`light`, `standard`, or `deep`) with the signals that justify it. `spec-implement` uses the tier to
+pick the model for that task, so a risky task under-rated as `light` is the costly mistake. Round up
+when unsure. If one task scores `deep` mainly because it's doing too much, split it first.
+
 ### Step 4: Build the Dependency Graph
 
 For each task, identify:
@@ -130,6 +135,10 @@ Files created:
 - action-required.md
 - tasks/ ({T} task files)
 
+Model plan: {n} light · {n} standard · {n} deep
+  (models from .spec-driven.yml → light: {model}, standard: {model}, deep: {model})
+  Deep tasks: {task-nn — main reason}
+
 Batch breakdown:
 - Batch 1: {count} tasks (parallel) — {brief description}
 - Batch 2: {count} tasks (parallel) — {brief description}

package/skills/spec-create/references/complexity-rubric.md

@@ -0,0 +1,57 @@
+# Complexity Rubric
+
+Use this to give every task a **tier**: `light`, `standard`, or `deep`. `spec-implement` runs the
+task on the model mapped to that tier in `.spec-driven.yml` (`models:`). Rate from the evidence in
+the task file and investigation, not from how long the description is.
+
+## Contents
+- Scoring
+- Tier from score
+- Overrides
+- Examples
+- What to write in the task file
+
+## Scoring
+
+Add one point for each signal that applies:
+
+| Signal | Point when… |
+|---|---|
+| Spread | the task changes more than 3 files, or files in more than one module/package/repo |
+| New design | there's no existing pattern in the repo to copy (new abstraction, algorithm, or integration) |
+| Data | it changes a schema, migration, persisted format, or data backfill |
+| Concurrency | it involves async ordering, queues, retries, locking, caching, or idempotency |
+| Security | it touches auth, permissions, tenant isolation, secrets, payments, or untrusted input |
+| Public contract | it changes an API, event, or interface that other code or other repos depend on |
+| Ambiguity | acceptance criteria rely on judgement, or the investigation left UNKNOWNs in this area |
+| Hard to verify | correctness can't be fully shown by the tests listed (timing, performance, UI feel) |
+
+## Tier from score
+
+| Score | Tier | Typical work |
+|---|---|---|
+| 0–1 | `light` | copy change, config value, small UI tweak, adding a field following an existing pattern |
+| 2–3 | `standard` | a normal feature slice: a route + service + tests following existing patterns |
+| 4+ | `deep` | cross-cutting design, migrations with backfills, auth/permission logic, concurrency fixes |
+
+## Overrides
+
+- **Security or Data alone make a task at least `standard`**, even if nothing else applies.
+- **Security + Data, or Security + Concurrency, make it `deep`**, whatever the score.
+- If the score is borderline, round up: a tier too high costs money, a tier too low costs rework.
+
+## Examples
+
+- "Rename the Export button to Download CSV" → 0 → `light`
+- "Add `exported_at` column and show it on the orders page" → Data, Spread → 2 → `standard`
+- "Make the CSV export stream rows instead of loading 10k into memory" → New design, Concurrency, Hard to verify → 3 → `standard`
+- "Enforce tenant isolation on all export endpoints and backfill missing tenant IDs" → Security + Data → `deep`
+
+## What to write in the task file
+
+```markdown
+## Complexity
+
+**Tier:** standard
+**Signals:** Data (adds `exported_at` migration), Spread (api + web)
+```

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

@@ -29,10 +29,12 @@ graph TD
 
 ## Batches
 
-| Batch | Tasks | Description |
-|------|-------|-------------|
-| 1 | task-01, task-02 | {Brief description of what this batch accomplishes} |
-| 2 | task-03 | {Brief description} |
+| Batch | Tasks | Tiers | Description |
+|------|-------|-------|-------------|
+| 1 | task-01, task-02 | light, standard | {Brief description of what this batch accomplishes} |
+| 2 | task-03 | deep | {Brief description} |
+
+**Model plan:** {n} light · {n} standard · {n} deep. Deep tasks: {task-03 — reason}.
 
 ## Task Status
 

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

@@ -15,6 +15,11 @@ pending
 
 {N}
 
+## Complexity
+
+**Tier:** {light | standard | deep}
+**Signals:** {which rubric signals applied, with the evidence — or "none"}
+
 ## 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.}
@@ -82,5 +87,6 @@ pending
 - 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.
+- **Complexity** comes from `complexity-rubric.md`. `spec-implement` picks the coder's model from this tier, so rate honestly: under-rating a risky task is the expensive mistake.
 - **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

@@ -108,6 +108,25 @@ Read `references/coder-prompt-template.md` and construct each agent's prompt by
 
 The coder agents should NOT commit their changes — the orchestrator handles commits after review.
 
+**Pick each coder's model from the task's tier.** Read the task's `## Complexity` tier (treat a
+missing tier as `standard`) and look up the model in `.spec-driven.yml` → `models.<tool>.<tier>`,
+where `<tool>` is the host you're running in (`claude`, `codex`, `cursor`, `antigravity`). Without a
+`models` section, use `models.claude` defaults: `light → haiku`, `standard → sonnet`,
+`deep → opus`.
+
+- **Host can set a model per agent** (e.g. Claude Code's Agent tool `model` parameter): dispatch
+  each coder with its tier's model.
+- **Host can't** (one model per session, as in Cursor or Codex): don't silently run deep tasks on a
+  light model. Before dispatching a batch, compare its highest tier with the model you're running
+  on. If the batch needs a stronger one, stop and say:
+  `Batch {N} has deep tasks ({task-nn: reason}). Switch to {models.<tool>.deep} for this batch, then
+  say "continue".` If the batch only has light tasks and you're on the deep model, mention that a
+  cheaper model would do, but carry on.
+- If the mapped value is `default`, use whatever model the session already runs, without
+  recommending a switch.
+
+Report the model used for each task in the batch summary.
+
 **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
@@ -143,6 +162,9 @@ Read `references/review-prompt-template.md` and construct the review prompt by f
 - **{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`)
 
+Run the reviewer on the model for the **highest tier in the batch**, and never below `standard`: the
+review is where deep mistakes get caught.
+
 The review agent should:
 1. Run lint, typecheck, and tests
 2. Verify acceptance criteria and the tests named in each task file
@@ -160,6 +182,9 @@ If the review returns **FAIL**:
    - **{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)
+5. **Escalate on repeat failure.** If a task's issues survive a fix cycle, run its next fix one tier
+   higher (`light → standard → deep`). Note the escalation in the batch report. When a task needed
+   escalating, its tier was probably wrong, which is useful feedback for future specs.
 
 **Cap at 3 review cycles per batch.** If the third review still fails, stop and report to the user:
 

package/skills/spec-investigate/SKILL.md

@@ -288,6 +288,11 @@ gitignores `specs/`, matching whatever this repo already does there). Use the st
 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.
 
+**Complexity Estimate** uses the same signals and tiers `spec-create` will apply per task: spread,
+new design, data, concurrency, security, public contract, ambiguity, hard to verify. Security plus
+data, or security plus concurrency, means `deep`. Say which model is worth planning this on, since a
+deep ticket deserves the strongest model for `spec-create` too.
+
 **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

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

@@ -48,6 +48,11 @@ Copy this structure into `specs/{feature-slug}/investigation.md`.
 ### Proposed Solutions Discussed
 ### Open Questions
 ### Conflicts / Discrepancies
+## Complexity Estimate
+- Overall tier: (light / standard / deep): the tier of the hardest part of the work
+- Signals: (which of spread, new design, data, concurrency, security, public contract, ambiguity, hard to verify apply, each with its evidence)
+- Suggested model for planning this: (the `deep` model if the tier is deep; otherwise the session's model is fine)
+
 ## Recommended Implementation Direction
 ## References
 ```

package/skills/spec-setup/SKILL.md

@@ -69,7 +69,10 @@ Read, don't guess. Collect a draft of every field in `references/config-template
    steps (CI is often the most truthful source). Dev URL from the dev script, `.env.example`, or
    framework defaults.
 
-6. **After approval.** Ask whether an approved spec should stop after each stage (`stop`), or
+6. **Models per tier.** Write the `models:` block from the template. Ask which models the user
+   has for each tool they installed, only if they want to tune it: the Claude defaults (haiku /
+   sonnet / opus) work as-is, and `default` is safe for the rest.
+7. **After approval.** Ask whether an approved spec should stop after each stage (`stop`), or
    run implement → verify → checkpoint in one go (`run-through`), stopping at any failure and never
    pushing. Store it as `pipeline.after_approval`.
 

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

@@ -42,6 +42,28 @@ commands:
   dev: ""                       # how spec-verify starts the app
   dev_url: ""                   # where it answers, e.g. http://localhost:3000
 
+# Which model runs each task tier (spec-create rates every task light / standard / deep).
+# Values are whatever your tool accepts; "default" means "whatever model the session is using".
+# Hosts that can pick a model per agent (Claude Code) switch automatically; others (Cursor, Codex)
+# tell you which model to switch to before a heavier batch.
+models:
+  claude:
+    light: haiku
+    standard: sonnet
+    deep: opus
+  cursor:
+    light: default
+    standard: default
+    deep: default
+  codex:
+    light: default
+    standard: default
+    deep: default
+  antigravity:
+    light: default
+    standard: default
+    deep: default
+
 pipeline:
   # stop        — every stage waits for you (default)
   # run-through — after you approve a spec: implement → verify → checkpoint in one go,