@skitterbyte/skitterspec 16.10.0 → 18.0.0

package/assets/skills/spec/SKILL.md

@@ -6,10 +6,10 @@ description: Create a new spec-driven-development spec. Grills the user to a cle
 # /spec — author a new spec
 
 Produce ONE concise spec in `specs/backlog/`. Do not start coding — this skill
-plans only. Implementation happens later via `/spec-go`.
+plans only. Implementation happens later via `/spec-start`.
 
 Lifecycle (the governing skills) — status in parentheses:
-`/spec` (writes **Ready** when fully groomed, else Draft; backlog) → `/spec-go`
+`/spec` (writes **Ready** when fully groomed, else Draft; backlog) → `/spec-start`
 (In Progress, in-progress; implement phase 1) → `/spec-complete` (Complete) /
 `/spec-cancel` (Cancelled). See `.claude/rules/spec-planning.md`. (There is no
 separate grooming command — `/spec` grills to a Ready spec directly.)
@@ -23,7 +23,12 @@ not write the spec until this is resolved.
 
 - Break the problem into **distinctive areas** and work them in logical order,
   resolving dependencies between decisions one at a time.
-- Ask **one question at a time**. For each, give your **recommended answer**.
+- **Batch independent questions; sequence dependent ones.** When several
+  questions do not affect each other's answers, put them to the user together
+  (up to four at once — use the harness's multi-question ask tool where it has
+  one) rather than spending a round trip on each. When an answer would change
+  what you ask next, ask that one alone and wait for it. Give your
+  **recommended answer** either way.
 - If a question can be answered by **reading the codebase, read it** instead of
   asking. Verify endpoints/models/files actually exist before relying on them.
 - Cover, at minimum, the areas that apply:
@@ -42,9 +47,19 @@ not write the spec until this is resolved.
      this spec touch the DB / stateful services (so its worktree needs a Docker
      stack), or is a plain worktree enough? Default `worktree`; escalate to
      `worktree + docker` only when it must. This sets the `> **Stack:**` header
-     that `/spec-go` acts on (it can be escalated later). Skip when isolation
+     that `/spec-start` acts on (it can be escalated later). Skip when isolation
      isn't enabled — leave the default `worktree`.
-  10. **Open questions** — anything still undecided.
+  10. **Release gating** *(only when `specs/.core/gating.config.json` exists)* —
+      should this ship behind a feature flag, or land live?
+      **Offer, don't impose**: the user decides and you raise it, so a spec
+      never reaches
+      `/spec-complete` with the question unasked. Cite the project's own
+      `guidance` path from that config when it names one — skitterspec knows
+      nothing about how this project does flags, and must not guess. Record the
+      answer **either way**: a flag name, or `none: <one-line reason>`. "No" is a
+      decision and belongs in the header; silence is not. Skip entirely when the
+      config is absent — that project does not use flags.
+  11. **Open questions** — anything still undecided.
 
 Stop grilling when there are no unresolved branches that would change the spec.
 Briefly play back the agreed understanding before writing.
@@ -95,7 +110,7 @@ the codebase, link rather than duplicate):
 # <Feature title>
 
 > **Type:** Feature
-> **Name:** feat-<kebab-name> (the spec folder name — the handle you paste into `/spec-go`)
+> **Name:** feat-<kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
 > **Status:** Ready — not started
 > **Author:** <git user.name — `git config user.name`>
 > **Developer:** —
@@ -103,6 +118,9 @@ the codebase, link rather than duplicate):
 > **Area:** <comma-separated files/modules this touches>
 > **Stack:** <worktree — or "worktree + docker" if it touches the DB/stateful
 > services; only acted on when isolation is enabled — see Phase A item 9>
+> **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
+> is configured; omit the line entirely otherwise. An empty value or a bare
+> "none" is not a valid outcome — see Phase A item 10>
 
 ## Problem
 
@@ -191,7 +209,7 @@ Keep the `00-overview.md` phase index and the phase files in sync: the index row
 is the one-line summary + status; the phase file is the detail.
 
 The **State log** is the audit trail of folder/status transitions — every
-lifecycle skill (`/spec-go`, `/spec-complete`, `/spec-cancel`) appends one row
+lifecycle skill (`/spec-start`, `/spec-complete`, `/spec-cancel`) appends one row
 when it moves the spec. The **Changelog** is for decisions and course-corrections
 only — keep the two separate.
 
@@ -206,13 +224,14 @@ Rules for the spec body:
   phase index.
 - **Honour project conventions** when writing tasks — reference the relevant
   `.claude/rules/*.md` rather than re-explaining them.
-- **The `## Impact` table is derived from Phase A items 3 (Affected areas) & 5
-  (Data/API impact)** — a structured place to record what those already surface,
-  not new grilling. It is the scannable substitute for spelling impact out in
-  prose: name the surfaces (endpoints, schemas, DB tables, domain objects,
-  routes, business rules) instead of describing them, keep `Detail` terse, and
-  let it — not paragraphs — carry the blast radius. It complements the `Area:`
-  header (files) by naming behavioural surfaces.
+-
+  **The `## Impact` table is derived from Phase A items 3 (Affected areas) & 5 (Data/API impact)**
+  — a structured place to record what those already surface, not new grilling.
+  It is the scannable substitute for spelling impact out in prose: name the
+  surfaces (endpoints, schemas, DB tables, domain objects, routes, business
+  rules) instead of describing them, keep `Detail` terse, and let it — not
+  paragraphs — carry the blast radius. It complements the `Area:` header
+  (files) by naming behavioural surfaces.
 - **Changelog** is mandatory and lives in the spec. Every later decision or
   course-correction gets a dated one-line entry. Convert relative dates to
   absolute.
@@ -223,20 +242,29 @@ Rules for the spec body:
 After writing, tell the user the path and that it's **`Ready`** in `backlog`
 (grilling in Phase A resolved the open questions). If you deliberately left open
 questions unresolved, write `Draft` instead and say what still needs deciding.
-Either way, the next step is `/spec-go` to start building.
+Either way, the next step is `/spec-start` to start building.
 
 ## Phase D — record the isolation stack (only if configured)
 
 **Only when `specs/.core/env.config.json` exists** (per-spec isolation is
 enabled), make sure the `> **Stack:**` header reflects the Phase A item 9
 decision — `worktree` (default) or `worktree + docker` when it touches the DB /
-stateful services. Nothing to provision now: `/spec-go` gives every in-progress
+stateful services. Nothing to provision now: `/spec-start` gives every in-progress
 spec its own worktree automatically, and brings up Docker only when the Stack
 says so. Mention the operator can escalate the Stack later (edit the header, or
 run `skitterspec spec-env up <name>` to add Docker to an existing worktree). If
 `env.config.json` is absent, isolation is off — leave the default `worktree` and
 finish as above.
 
+## Phase D2 — record the gating decision (only if configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Make sure the
+`> **Gating:**` header carries the Phase A item 10 answer — a flag name, or
+`none: <reason>` using the config's `default` wording if it sets one. Nothing is
+provisioned or enforced by this: the header exists so the decision is
+**on the record and reviewable**, and `skitterspec gating check` reports a spec that has
+none. It never blocks. If the config is absent, do not write the line at all.
+
 ## Phase E — link to a ticketing provider (only if one is installed)
 
 **Only when a ticketing provider is installed and configured** (it ships the

package/assets/skills/spec-bug/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-bug
-description: Investigate a bug, capture it as a Bug-type spec, and drive it red→green. When per-spec isolation is enabled it provisions a worktree first, so the failing test and fix land on the bug's own branch, never on main. ALWAYS starts by reproducing the bug with a failing test, then writes the spec and works the test to green. Creates specs/in-progress/bug-<name>/00-overview.md. Use when the user reports a bug, says "/spec-bug", "investigate this bug", "this is broken — find and fix it", or pastes an error/stack trace.
+description: Investigate a bug, capture it as a Bug-type spec, and drive it red→green. ALWAYS starts by reproducing the bug with a failing test, then writes the spec and works the test to green — on the bug's own branch, never on main. Use when the user reports a bug, says "/spec-bug", "investigate this bug", "this is broken — find and fix it", or pastes an error/stack trace.
 ---
 
 # /spec-bug — investigate a bug, prove it with a failing test, fix it
@@ -37,7 +37,7 @@ place), skip this whole section and fix on the current branch — same as when
 isolation is off. Warn that the fix will land wherever you currently are (usually
 `main`); reserve it for a trivial one-liner or an explicit request.
 
-A bug fix changes real source, so — exactly like `/spec-go` — it belongs on the
+A bug fix changes real source, so — exactly like `/spec-start` — it belongs on the
 bug's **own branch**, never directly on `main`. Provision the worktree **now**,
 before the failing test, so the test, the fix, and the spec all land together and
 arrive as one reviewable PR.
@@ -51,24 +51,12 @@ provision from — you'll flesh it out in §4:
 - Run `skitterspec spec-env up bug-<name>` (the `spec-env` CLI engine). It prints
   the `git worktree add … -b bug/<name>` command (a branch forked from `main`),
   the worktree path, the opener, and any `in the worktree, run:` bootstrap steps.
-- Run the printed `git worktree add`. **The worktree forks from `main`'s last
-  commit, so your uncommitted stub doesn't travel with it** — move it across so
-  `main` is left pristine. **Create the destination bucket first:**
-
-  ```
-  mkdir -p <worktreePath>/specs/in-progress
-  mv specs/in-progress/bug-<name> <worktreePath>/specs/in-progress/
-  ```
-
-  The `mkdir -p` is not belt-and-braces. Git does not store empty directories,
-  so `specs/in-progress/` is **absent** from a fresh worktree whenever that
-  bucket happens to be empty on `main` — the common case, since it empties every
-  time the last in-progress spec completes. `mv` into a missing destination
-  renames your spec folder **to** `specs/in-progress`, silently: the spec's files
-  end up one level too high, `00-overview.md` sits where the bucket should be,
-  and every later step still appears to work until something cannot find the
-  spec. Confirm the result before carrying on — you want
-  `<worktreePath>/specs/in-progress/bug-<name>/00-overview.md`.
+- Run the printed commands in order. The plan **commits the stub first** — the
+  worktree forks from `main`'s last commit, so the stub has to be in it — and
+  then adds the worktree. Nothing to move afterwards: the spec is already there.
+  The commit is planned, not silent; it appears in the printed plan above the
+  `git worktree add`, and `spec-env up` refuses outright if anything *other* than
+  this spec is uncommitted.
 - **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
   none of the repo's gitignored files (`.env`, local overrides). Run the printed
   `in the worktree, run:` steps (file seeding, then `setup`) in order, before
@@ -111,12 +99,14 @@ because work is already underway. Keep it lean:
 # Bug: <short title>
 
 > **Type:** Bug
-> **Name:** bug-<kebab-name> (the spec folder name — the handle you paste into `/spec-go`)
+> **Name:** bug-<kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
 > **Status:** In Progress — fixing (red test added)
 > **Author:** <git user.name — who reported/captured it>
 > **Developer:** <git user.name — you, since you're fixing it now>
 > **Raised:** <YYYY-MM-DD (today)>
 > **Area:** <files/modules>
+> **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
+> is configured; omit the line entirely otherwise>
 
 ## Symptom
 
@@ -147,8 +137,10 @@ Service, CLI command, Config key, Skill/rule, Business rule — or whatever fits
 this project (skitterspec itself is a CLI with no HTTP surface). Keep `Detail`
 terse — names/signatures, not sentences. List **only** surfaces that actually
 change; the heading is always present, but if nothing external changes write the
-single line below instead of an empty table. A bug fix often changes no external
-surface — that's fine, use the one-liner.>
+single line below instead of an empty table.>
+
+<A bug fix often changes no external surface — that's fine, use the
+one-liner.>
 
 | Surface | Change | Detail |
 |---------|--------|--------|
@@ -176,6 +168,19 @@ fix narrative and decisions — keep them separate.
 
 
 
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Before writing the spec,
+ask: should this fix ship behind a feature flag, or land live?
+**Offer, don't impose** — cite the project's own `guidance` path when the config
+names one, and
+record the answer either way, as a flag name or `none: <one-line reason>`.
+
+A bug fix ships in the next release exactly like a feature, so it gets the same
+question rather than an assumption. A risky rewrite of a broken path is precisely
+where a kill-switch earns its keep; a one-line null check is precisely where
+`none:` is the honest answer. Skip entirely when the config is absent.
+
 ## 5. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix. Match surrounding code; honour all
@@ -186,12 +191,12 @@ fix narrative and decisions — keep them separate.
 
 If the root cause is large/uncertain and can't be fixed in one pass: keep the red
 test, split the fix into phase files (`01-<slug>.md` …) with a phase index in
-`00-overview.md`, and leave the spec in `in-progress` for `/spec-go` to continue.
+`00-overview.md`, and leave the spec in `in-progress` for `/spec-next` to continue.
 Say so explicitly — don't fake green.
 
 **Then refresh the mirror (only if a provider is installed).** The Fix tasks are
 ticked, so the repo is now the truth about this fix — and this skill can take a
-bug all the way to green without `/spec-go` ever running. Without a provider this
+bug all the way to green without `/spec-next` ever running. Without a provider this
 is a no-op.
 
 

package/assets/skills/spec-cancel/SKILL.md

@@ -78,6 +78,32 @@ directly (the old `/spec-env-down` skill is gone — teardown is folded in here)
 1. If `.spec-env/connected` names this spec, run `skitterspec spec-env connect
    main` first to free the canonical ports.
 2. `skitterspec spec-env dev down <name>` — stop its host dev servers.
+**Standing in the worktree? Leave it before you tear it down.** If this
+session's cwd is inside the spec's own worktree, get out **first**, then run the
+teardown commands. How you leave depends on how you got in:
+
+- **`/spec-start` moved this session in** — the normal path in `worktree` mode.
+  Call **`ExitWorktree`** with `action: "keep"`. It restores the session to the
+  directory it started from *and* clears the caches still pointing at the
+  worktree, which a bare `cd` does not: after a `cd` the session stays registered
+  against the tree and asks you about it again when it ends.
+- **You opened the terminal yourself** — `cd` to the primary checkout, as always.
+  `ExitWorktree` is a no-op outside a session it moved, so trying it costs
+  nothing, but the `cd` is what relocates you.
+
+**Always `keep`, never `remove`.** `ExitWorktree` refuses to remove a worktree
+entered by path in any case, and the `spec-env down` plan below has to stay the
+single thing that deletes — a second deleter is how the teardown guards get
+bypassed.
+
+Not because git refuses — it does not. `git worktree remove` **succeeds** on the
+tree you are standing in, and that is the problem: the directory vanishes under
+the shell, `pwd` keeps reporting the path that no longer exists, and every
+command after it dies with `fatal: Unable to read current working directory`.
+The teardown looks fine and everything following it breaks — the report, the
+prune, any check you meant to run. Relocating first costs nothing and is the
+only ordering that survives.
+
 3. `skitterspec spec-env down <name>` — then execute the printed commands to
    remove the worktree/stack and free the slot. It respects the teardown guards
    (won't destroy a dirty/unpushed worktree without `--force`).

package/assets/skills/spec-complete/SKILL.md

@@ -25,7 +25,7 @@ Before marking complete, confirm the work is actually finished:
   originally-failing test named in the spec now passes — that test is the proof
   the fix works.
 - If genuinely incomplete work remains, **stop and tell the user** rather than
-  forcing completion. Offer to finish it (`/spec-go`) or to complete with the
+  forcing completion. Offer to finish it (`/spec-next`) or to complete with the
   remaining items explicitly listed as deferred.
 - **Check for pre-existing uncommitted changes — before you touch anything.**
   Run `git status`. Anything already uncommitted is the *user's* work (a
@@ -34,6 +34,23 @@ Before marking complete, confirm the work is actually finished:
   is its own, and step 4 commits that.
 
 
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Run
+`skitterspec gating check <spec>` and report what it says. This is the last point
+at which the question can still be answered cheaply, which is exactly why it is
+asked here — a spec that reaches `Complete` with no decision recorded is the gap
+the feature exists to close.
+
+**Never refuse to complete over it.** Say plainly that no decision was recorded,
+offer to record one now, and finish either way. The work is done; withholding the
+status flip would punish the wrong thing.
+
+**This check is advisory.** It reports; it never refuses, and nothing below is
+conditional on it. A spec written before the project adopted gating has no header
+and is not broken — turning this into a gate would accuse the very specs the
+feature was designed not to disturb.
+
 ## 3. Update the spec
 
 - Tick all completed tasks in the phase files; flip every finished phase-file
@@ -63,9 +80,10 @@ git add specs/ && git commit -m "chore(spec): complete <name>"
 ```
 
 Step 2 established the tree was otherwise clean, so this commits exactly the
-status flip and the move — nothing of yours rides along. **This is what lets step
-6 land:** `integrate` refuses a dirty worktree, so without committing here the
-skill would block on the very edits it just made. Do not `git push`.
+status flip and the move — nothing of yours rides along.
+**This is what lets step 6 land:** `integrate` refuses a dirty worktree, so
+without committing here the skill would block on the very edits it just made.
+Do not `git push`.
 
 ## 5. Report
 
@@ -73,8 +91,11 @@ Confirm the move, the commit, the final test result, and list anything deferred.
 
 ## 6. Land the branch (opt-in, only if isolated)
 
-**Only when `specs/.core/env.config.json` exists and the spec is on a worktree**
-(it was provisioned by `/spec-go` or `/spec-hotfix`). Otherwise skip this entirely
+**Only when `specs/.core/env.config.json` exists and the spec was provisioned**
+(a worktree in `worktree` mode, or its branch in the checkout in `checkout`
+mode — `spec-env integrate` and `down` pick the right plan from `mode`, so the
+commands you run differ but these steps do not)
+(it was provisioned by `/spec-start` or `/spec-hotfix`). Otherwise skip this entirely
 — a non-isolated spec has nothing to land, and `/spec-complete` behaves exactly as
 before. When it applies, offer to land the finished branch so the work reaches its
 destination in one flow. **How it lands depends on the spec type:**
@@ -125,7 +146,7 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
    work is actually landable and **aborts loudly** rather than finalize a spec
    having landed nothing. Two cases, both leaving the live session intact:
    - *stranded commits* — commits sit on the worktree's **detached HEAD** (e.g. a
-     pre-fix `/spec-go` committed there instead of on the branch). It prints the
+     pre-fix `/spec-next` committed there instead of on the branch). It prints the
      count, the sha, and a `git -C <worktree> branch <tmp> <sha>` recovery hint —
      recover those commits onto the branch, then re-run.
    - *no worktree* — the spec is live but its worktree is gone. Re-isolate it with
@@ -168,6 +189,32 @@ worktree and branch are being kept, and go straight to sub-step 4. Mention
    canonical ports go back to the primary checkout.
 2. **Stop its host dev servers:** `skitterspec spec-env dev down <name>` (a
    no-op when none are running / configured).
+**Standing in the worktree? Leave it before you tear it down.** If this
+session's cwd is inside the spec's own worktree, get out **first**, then run the
+teardown commands. How you leave depends on how you got in:
+
+- **`/spec-start` moved this session in** — the normal path in `worktree` mode.
+  Call **`ExitWorktree`** with `action: "keep"`. It restores the session to the
+  directory it started from *and* clears the caches still pointing at the
+  worktree, which a bare `cd` does not: after a `cd` the session stays registered
+  against the tree and asks you about it again when it ends.
+- **You opened the terminal yourself** — `cd` to the primary checkout, as always.
+  `ExitWorktree` is a no-op outside a session it moved, so trying it costs
+  nothing, but the `cd` is what relocates you.
+
+**Always `keep`, never `remove`.** `ExitWorktree` refuses to remove a worktree
+entered by path in any case, and the `spec-env down` plan below has to stay the
+single thing that deletes — a second deleter is how the teardown guards get
+bypassed.
+
+Not because git refuses — it does not. `git worktree remove` **succeeds** on the
+tree you are standing in, and that is the problem: the directory vanishes under
+the shell, `pwd` keeps reporting the path that no longer exists, and every
+command after it dies with `fatal: Unable to read current working directory`.
+The teardown looks fine and everything following it breaks — the report, the
+prune, any check you meant to run. Relocating first costs nothing and is the
+only ordering that survives.
+
 3. **Remove worktree + stack + slot:** run `skitterspec spec-env down <name>`
    and execute the commands it prints, in order. After a landing — merged into
    base for a **feature/bug**, captured by the deploy tag for a **hotfix** —
@@ -177,16 +224,16 @@ worktree and branch are being kept, and go straight to sub-step 4. Mention
    worktree without `--force`), so if it *does* refuse, relay that and stop
    rather than reaching for `--force`.
 
-   **If the plan prints a `remote branch — confirm with the user first:`
-   section, ask before running it.** `/spec-go` pushed this branch when it
-   provisioned, so the remote copy outlives teardown unless someone deletes it.
-   The planner only ever offers this for a branch that has **landed**, so say so
-   plainly when you ask — the commits are on the base branch (or captured by the
-   deploy tag), so deleting the remote branch loses nothing. On a yes, run the
-   printed `git push <remote> --delete <branch>`; on a no, leave it and say the
-   remote branch is still there. Never fold it into the `run these:` batch — a
-   project that wants it unattended sets `teardown.deleteRemoteBranch: "always"`
-   in `env.config.json`, and then it appears in `run these:` instead of here.
+   **If the plan prints a `remote branch — confirm with the user first:` section, ask before running it.**
+   `/spec-start` pushed this branch when it provisioned, so the remote copy
+   outlives teardown unless someone deletes it. The planner only ever offers
+   this for a branch that has **landed**, so say so plainly when you ask — the
+   commits are on the base branch (or captured by the deploy tag), so deleting
+   the remote branch loses nothing. On a yes, run the printed
+   `git push <remote> --delete <branch>`; on a no, leave it and say the remote
+   branch is still there. Never fold it into the `run these:` batch — a project
+   that wants it unattended sets `teardown.deleteRemoteBranch: "always"` in
+   `env.config.json`, and then it appears in `run these:` instead of here.
 4. **Reap orphaned test-DB volumes:** run `skitterspec spec-env prune`. It lists
    Docker volumes in the repo namespace that belong to **no live spec** (no
    worktree) — leftovers from declined/aborted teardowns, manual
@@ -198,6 +245,12 @@ worktree and branch are being kept, and go straight to sub-step 4. Mention
    finish completing anyway — never block the spec on it. Skip when Docker isn't
    in use (the command self-reports "no orphaned volumes").
 
+**Report from where you now are.** After a teardown you relocated for, the
+worktree path in the report is a directory that no longer exists and the landed
+work is on the base branch in the primary checkout — say both, so nobody goes
+looking for a tree that is gone. A session that was a worktree tab has finished
+its job at that point; its shell is the operator's own to close.
+
 **Say what you reclaimed.** With no confirmation step the user never saw this
 coming, so the final report must name the worktree path removed and the branch
 deleted (or, under `--keep-env`, that both were kept). A teardown nobody

package/assets/skills/spec-hotfix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-hotfix
-description: Fix a production bug on the exact released version — fork a worktree from a release tag, drive it red→green like /spec-bug, then land it by tagging a new patch (for CI/CD to deploy) and cherry-picking the fix back onto main. ALWAYS starts from a base tag and works on the hotfix's own branch, never on main. Can start from a tracker issue when a provider is installed (`/spec-hotfix <tag> <ISSUE-REF>`), adopting it as the hotfix's issue. Creates specs/in-progress/hotfix-<name>/00-overview.md. Use when the user says "/spec-hotfix", "hotfix <tag>", "prod is broken on <version>", "patch the released version", or needs a fix shipped against a tagged release rather than main.
+description: Fix a production bug on the exact released version — fork a worktree from a release tag, drive it red→green, then land it by tagging a new patch for CI/CD and cherry-picking the fix onto main. ALWAYS starts from a base tag and works on the hotfix's own branch, never on main. Use when the user says "/spec-hotfix", "hotfix <tag>", "prod is broken on <version>", "patch the released version", or needs a fix shipped against a tagged release rather than main.
 ---
 
 # /spec-hotfix — fix a released version, tag it, cherry-pick back to main
@@ -63,9 +63,12 @@ that header — must exist **before** `spec-env up`:
   -b hotfix/<slug> <tag>` command (the branch forks from **the tag**, not
   `main`), the worktree path, the opener, and any `in the worktree, run:`
   bootstrap steps.
-- Run the printed `git worktree add`. **The worktree is checked out at the tag,
-  so your uncommitted stub doesn't travel with it** — move it across so `main`
-  stays pristine. **Create the destination bucket first:**
+- Run the printed `git worktree add`, then **move the stub across yourself.**
+  This is where a hotfix differs from `/spec-bug`, which no longer needs the move:
+  that skill's worktree forks from `main`, so committing the stub puts it there,
+  while **this worktree is checked out at the tag** — a commit on `main` is not in
+  it and never will be. The move is not redundant here; keep it.
+  **Create the destination bucket first:**
 
   ```
   mkdir -p <worktreePath>/specs/in-progress
@@ -74,16 +77,15 @@ that header — must exist **before** `spec-env up`:
 
   The `mkdir -p` is not belt-and-braces. Git does not store empty directories, so
   `specs/in-progress/` is **absent** from the worktree whenever nothing was in
-  progress at that point in history — and here that point is an **old release
-  tag**, where it is absent more often than not. `mv` into a missing destination
-  renames your spec folder **to** `specs/in-progress`, silently: the spec's files
-  end up one level too high, `00-overview.md` sits where the bucket should be, and
-  every later step still appears to work until something cannot find the spec.
-  Confirm the result before carrying on — you want
-  `<worktreePath>/specs/in-progress/hotfix-<name>/00-overview.md`.
-- **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
+  progress at that point in history — and here that point is an
+  **old release tag**, where it is absent more often than not. `mv` into a
+  missing destination renames your spec folder **to** `specs/in-progress`,
+  silently: the spec's files end up one level too high, `00-overview.md` sits
+  where the bucket should be, and every later step still appears to work until
+  something cannot find the spec. Confirm the result before carrying on — you
+  want `<worktreePath>/specs/in-progress/hotfix-<name>/00-overview.md`. - **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
   none of the repo's gitignored files (`.env`, local overrides). Run the printed
-  `in the worktree, run:` steps (file seeding, then setup) in order, before
+  `in the worktree, run:` steps (file seeding, then `setup`) in order, before
   anything else.
 - **Trust the worktree for this session.** The engine wrote the printed
   `trusted:` root into `.claude/settings.local.json`, but it won't hot-reload now
@@ -116,13 +118,15 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
 # Hotfix: <short title>
 
 > **Type:** Hotfix
-> **Name:** hotfix-<kebab-name> (the spec folder name — the handle you paste into `/spec-go`)
+> **Name:** hotfix-<kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
 > **Status:** In Progress — fixing (red test added)
 > **Author:** <git user.name — who reported/captured it>
 > **Developer:** <git user.name — you, since you're fixing it now>
 > **Base version:** <tag prod is running, e.g. v33.16.4>
 > **Raised:** <YYYY-MM-DD (today)>
 > **Area:** <files/modules>
+> **Gating:** <pre-filled "none: hotfix — restoring released behaviour"; only
+> when release gating is configured, and overridable — see below>
 
 ## Symptom
 
@@ -153,8 +157,10 @@ Service, CLI command, Config key, Skill/rule, Business rule — or whatever fits
 this project (skitterspec itself is a CLI with no HTTP surface). Keep `Detail`
 terse — names/signatures, not sentences. List **only** surfaces that actually
 change; the heading is always present, but if nothing external changes write the
-single line below instead of an empty table. A hotfix should be minimal — often
-no external surface changes; that's fine, use the one-liner.>
+single line below instead of an empty table.>
+
+<A hotfix should be minimal — often no external surface changes; that's
+fine, use the one-liner.>
 
 | Surface | Change | Detail |
 |---------|--------|--------|
@@ -187,6 +193,21 @@ narrative and decisions).
 
 
 
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** A hotfix is the one spec
+type that does **not** ask the question cold: it writes
+`none: hotfix — restoring released behaviour` and asks only for confirmation.
+
+The default differs on purpose. A hotfix restores behaviour a release already
+had, under time pressure, and the fix is captured by a deploy tag rather than
+riding the next release — so a flag has nothing to gate and nothing to roll back
+to. Making someone answer a design question mid-incident buys nothing.
+
+It is a **default, not a rule**: say what you are writing and let the user
+override it. If they name a flag, record that instead. Skip entirely when the
+config is absent.
+
 ## 6. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix on the branch. Match surrounding code;
@@ -198,7 +219,7 @@ narrative and decisions).
 
 **Then refresh the mirror (only if a provider is installed).** The Fix tasks are
 ticked, so the repo is now the truth about this fix — and this skill can take a
-bug all the way to green without `/spec-go` ever running. Without a provider this
+bug all the way to green without `/spec-next` ever running. Without a provider this
 is a no-op.
 
 

package/assets/skills/spec-init/SKILL.md

@@ -22,10 +22,33 @@ clobber customised content. Finish with a summary of created vs already-present.
 > **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
 > `--reset` (reset needs `--yes`) drive the stronger actions.
 
-The system is **eight skills**: `spec` (feature), `spec-bug` (bug), `spec-ready`,
-`spec-review`, `spec-go`, `spec-complete`, `spec-cancel`, and this `spec-init`. The lifecycle is
-`backlog → in-progress → complete / cancelled`, with `.core` holding always-apply
-project rules.
+The system is **ten skills**: `spec` (feature), `spec-bug` (bug),
+`spec-hotfix` (a bug fixed on a released tag), `spec-review`, `spec-start`,
+`spec-next`, `spec-to-main`, `spec-complete`, `spec-cancel`, and this
+`spec-init`. The lifecycle is `backlog → in-progress → complete / cancelled`,
+with `.core` holding always-apply project rules.
+
+## 0. Workspace mode (only when adopting isolation)
+
+If this project is adopting per-spec isolation, ask which `mode` belongs in
+`specs/.core/env.config.json` — `worktree` (default; a checkout per spec, several
+at once, one terminal session each) or `checkout` (the branch is built in the
+checkout you are already in; one spec at a time, no hand-off). It is a question
+about how the operator works, not about what the repo contains, so ask rather
+than infer it from whether dev servers or Docker are configured.
+
+## 0b. Release gating (optional, and separate)
+
+Ask whether specs should record a **release-gating** decision — does this change
+ship behind a feature flag, or land live? Adopting it copies
+`specs/.core/gating.config.json.example` → `gating.config.json` and sets
+`guidance` to wherever this project documents its flags.
+
+It is **orthogonal to isolation**: a project can adopt either, both, or neither.
+Skitterspec never learns how the flags work — it asks the question, cites that
+path, and records the answer on each spec. Leave it off and nothing appears:
+no question, no header, no check. Off is a perfectly good answer for a project
+that does not use flags.
 
 ## 1. Folders
 
@@ -54,7 +77,7 @@ project wants everything tracked, remove it. Confirm with
 
 ## 3. Verify the skills are installed
 
-Check each of the eight skills resolves — `.claude/skills/<name>/SKILL.md`
+Check each of the ten skills resolves — `.claude/skills/<name>/SKILL.md`
 (project) or `~/.claude/skills/<name>/` (global). List any missing. This skill
 scaffolds the project; it does **not** regenerate skill bodies — missing skills
 must be copied in (e.g. `npx @skitterbyte/skitterspec init`) from a global install
@@ -70,10 +93,10 @@ Ensure it exists. If missing, create it documenting:
 - the **Author** / **Developer** header fields;
 - the **State log** audit table (folder/status transitions), kept separate from
   the **Changelog** (decisions);
-- the project's concrete typecheck/test commands, and the rule that **every
-  phase ends with creating + running tests**.
+- the project's concrete typecheck/test commands, and the rule that
+  **every phase ends with creating + running tests**.
 
-Read a sibling spec skill (e.g. `spec`, `spec-go`) for the canonical shapes
+Read a sibling spec skill (e.g. `spec`, `spec-next`) for the canonical shapes
 rather than inventing them. If the rule already exists, leave it unless stale.
 
 ## 5. CLAUDE.md