@benjaminthomas/spec-driven-dev 1.6.0 → 1.8.0

package/README.md

@@ -93,6 +93,35 @@ 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 | Codex CLI | Effort |
+|---|---|---|---|---|
+| light | copy change, config value, small UI tweak following an existing pattern | `haiku` | `gpt-6-luna` | low |
+| standard | a normal feature slice: route + service + tests | `sonnet` | `gpt-6.1-sol` | medium |
+| deep | migrations with backfills, auth/permissions, concurrency, cross-repo contracts | `opus` | `gpt-6.1-sol` | high |
+| escalate | a deep task that still fails after a fix round | `fable` (asks first, as it may use usage credits) | (session model) | xhigh |
+
+- **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. A deep task
+  that still fails goes to the `escalate` model.
+- **Fallback:** if a model isn't available on your plan or provider, that task runs on your current
+  model and the report says so.
+- **Where the defaults come from:** they were checked on 2026-11-06 against
+  [Claude Code's model docs](https://code.claude.com/docs/en/model-config) (on Bedrock, Google Cloud,
+  and Foundry, `sonnet`/`haiku` point to older versions),
+  [Anthropic's model overview](https://platform.claude.com/docs/en/about-claude/models/overview),
+  [Codex's config docs](https://developers.openai.com/codex/config-basic), and
+  [Cursor's model list](https://cursor.com/help/models-and-usage/available-models). Claude Code
+  uses family aliases, which always point to the newest model. Cursor's models depend on your plan,
+  so it uses your current model until you fill in the models you can see in its picker.
+- **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 +168,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 and effort per task tier | written with the defaults above | edit `models:` / `effort:` later |
 
 **Where the file lives, by layout:**
 
@@ -542,15 +572,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 | 303 | 2,458 | 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,654** | **13,587** | **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,30 @@ 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; \"default\" = the session's model; escalate = last resort for repeat failures\n" + Object.entries(MODEL_DEFAULTS)
+    .map(([tool, m]) => `  ${tool}:\n` + MODEL_KEYS.map((t) => `    ${t}: ${m[t]}\n`).join("")).join("");
+  out += "effort:   # effort / reasoning level per tier (Claude Code, Codex): low | medium | high | xhigh | max | default\n"
+    + MODEL_KEYS.map((t) => `  ${t}: ${EFFORT_DEFAULTS[t]}\n`).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"];
+const MODEL_KEYS = [...TIERS, "escalate"]; // escalate: optional last resort when a deep task keeps failing
+const EFFORTS = ["low", "medium", "high", "xhigh", "max", "default"];
+// Checked against the vendors' docs on 2026-11-06 (Claude Code model-config, OpenAI Codex config,
+// Cursor models page). Claude Code aliases track the newest model per family on your provider.
+// Cursor's models depend on your plan, so it defaults to the session's model.
+// shortcut: model names go stale; refresh these defaults (and the README table) when vendors ship new lines.
+const MODEL_DEFAULTS = {
+  claude: { light: "haiku", standard: "sonnet", deep: "opus", escalate: "fable" },
+  codex: { light: "gpt-6-luna", standard: "gpt-6.1-sol", deep: "gpt-6.1-sol", escalate: "default" },
+  cursor: { light: "default", standard: "default", deep: "default", escalate: "default" },
+  antigravity: { light: "default", standard: "default", deep: "default", escalate: "default" },
+};
+// Effort / reasoning level per tier, for tools that support it (Claude Code, Codex).
+const EFFORT_DEFAULTS = { light: "low", standard: "medium", deep: "high", escalate: "xhigh" };
 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 +485,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 +519,15 @@ 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 (!MODEL_KEYS.includes(k)) problems.push(`models.${tool}.${k}: unknown tier (use light, standard, deep, escalate)`);
+  }
+  for (const [k, v] of Object.entries(c.effort || {})) {
+    if (!MODEL_KEYS.includes(k)) problems.push(`effort.${k}: unknown tier (use light, standard, deep, escalate)`);
+    else if (!EFFORTS.includes(v)) problems.push(`effort.${k} "${v}" must be one of ${EFFORTS.join(", ")}`);
+  }
   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.8.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,28 @@ 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 and effort from the task's tier.** Read the task's `## Complexity` tier
+(treat a missing tier as `standard`), then look up `.spec-driven.yml` → `models.<tool>.<tier>` and
+`effort.<tier>`, where `<tool>` is the host you're running in (`claude`, `codex`, `cursor`,
+`antigravity`). Without those sections, use these defaults: Claude Code `light → haiku/low`,
+`standard → sonnet/medium`, `deep → opus/high`; other hosts use the session's model.
+
+- **Host can set a model per agent** (e.g. Claude Code's Agent tool `model` and `effort`
+  parameters): dispatch each coder with its tier's model and effort.
+- **Model not available** (not on your plan or provider, or rejected by the host): fall back to the
+  session's model, say which task fell back and why, and suggest fixing `models:`. Don't stop the
+  batch for this.
+- **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 +165,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 +185,11 @@ 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`). A `deep` task that still fails goes to `models.<tool>.escalate`
+   (e.g. `fable`) at `effort.escalate`, if it's set and not `default`. Ask first if that model can
+   bill to usage credits, as Fable can on some plans. Note every escalation in the batch report:
+   a task that needed escalating was probably under-rated, 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: (`models.<tool>.deep` at `effort.deep` if the tier is deep, or the `escalate` model for very ambiguous, long-horizon work; 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,39 @@ 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".
+# escalate = optional last resort when a deep task still fails review after a fix round.
+# Defaults checked against vendor docs on 2026-11-06 — refresh when vendors ship new models.
+models:
+  claude:            # Claude Code aliases follow the newest model per family on your provider
+    light: haiku
+    standard: sonnet
+    deep: opus
+    escalate: fable  # Fable: hardest/long-running work; may bill to usage credits on some plans
+  codex:
+    light: gpt-6-luna
+    standard: gpt-6.1-sol
+    deep: gpt-6.1-sol  # same model, higher reasoning effort (see effort:)
+    escalate: default
+  cursor:            # depends on your Cursor plan; set models you can see in the model picker
+    light: default
+    standard: default
+    deep: default
+    escalate: default
+  antigravity:
+    light: default
+    standard: default
+    deep: default
+    escalate: default
+
+# Effort / reasoning level per tier, for tools that support it (Claude Code, Codex).
+effort:
+  light: low
+  standard: medium
+  deep: high
+  escalate: xhigh
+
 pipeline:
   # stop        — every stage waits for you (default)
   # run-through — after you approve a spec: implement → verify → checkpoint in one go,