@benjaminthomas/spec-driven-dev 1.7.0 → 1.8.0

package/README.md

@@ -97,14 +97,26 @@ words in quotes.
 **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` |
+| 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.
+- **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
@@ -156,7 +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 per task tier | written with defaults: Claude Code `haiku`/`sonnet`/`opus`, others `default` | edit `models:` later |
+| Model and effort per task tier | written with the defaults above | edit `models:` / `effort:` later |
 
 **Where the file lives, by layout:**
 
@@ -563,12 +575,12 @@ skips that step rather than failing.
 | `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-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,649** | **13,504** | **18** |
+| **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,22 +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 (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 += "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"];
-// 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_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" },
-  cursor: { light: "default", standard: "default", deep: "default" },
-  codex: { light: "default", standard: "default", deep: "default" },
-  antigravity: { light: "default", standard: "default", deep: "default" },
+  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.
@@ -514,7 +522,11 @@ function doctor() {
   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)`);
+    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}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@benjaminthomas/spec-driven-dev",
-  "version": "1.7.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-implement/SKILL.md

@@ -108,14 +108,17 @@ 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.
+**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:
@@ -183,8 +186,10 @@ If the review returns **FAIL**:
    - **{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.
+   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/references/report-template.md

@@ -51,7 +51,7 @@ Copy this structure into `specs/{feature-slug}/investigation.md`.
 ## 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)
+- 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/references/config-template.yml

@@ -44,25 +44,36 @@ commands:
 
 # 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.
+# 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:            # Claude Code aliases follow the newest model per family on your provider
     light: haiku
     standard: sonnet
     deep: opus
-  cursor:
-    light: default
-    standard: default
-    deep: default
+    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)