@skitterbyte/skitterspec-linear 10.8.0 → 12.0.0

package/MIGRATION.md

@@ -1,5 +1,93 @@
 # Migration guide
 
+## `@skitterbyte/skitterspec` v17 → v18 (a spec is built in its own worktree)
+
+### Breaking change
+
+**`/spec-start` no longer moves the branch into your checkout.** In `worktree`
+mode it provisions the spec's worktree, does the housekeeping there, opens a
+session in it, and stops. The spec is built where it was provisioned — which is
+what worktrees are for, and why `main` stays free.
+
+This **supersedes the "one checkout holds one spec in flight" rule** described
+under v16 → v17 below. That rule was a consequence of moving the branch into the
+primary checkout; with the move gone, so is the restriction:
+
+| v17 | v18 |
+|-----|-----|
+| `/spec-start` refused while another spec held your checkout | In `worktree` mode it only requires a **clean tree**. Several specs in flight is what the mode is for. |
+| Starting a spec took two invocations, with a `/spec-live <name>` you typed in between | **One invocation.** No hand-off command, no re-run. |
+| `/spec-live main` was one of the ways out of the gate | The ways out are `/spec-complete` and `/spec-cancel`. Parking to free a workbench is a one-workbench answer, and only `checkout` mode holds one spec now. |
+
+**`/spec-live` is for testing only** — reusing your running dev server to reach a
+spec at the canonical URL. It was never meant to be how work gets started, and no
+lifecycle skill calls it.
+
+`checkout` mode is unchanged: the branch is built in the primary checkout, the
+gate still requires the workbench free, and `/spec-start` carries straight on
+into phase 1 in the same session.
+
+### What to do
+
+1. **Upgrade** — `npx @skitterbyte/skitterspec update`.
+2. **Expect a session, not a swap.** After `/spec-start` in `worktree` mode, run
+   `/spec-next` from the session it opens in the worktree. `/spec-next` builds
+   the spec it is *standing in* and refuses to build one from elsewhere.
+3. **Nothing to configure.** `spec.companionPaths` in `env.config.json` is new
+   and optional — it names paths that belong to a spec alongside its own folder
+   (a tracker's per-spec snapshot), so `/spec-start` can commit them together.
+   Empty by default; `/spec-linear-setup` sets it for you.
+
+## `@skitterbyte/skitterspec-linear` v11 → v12 (a spec is built in its own worktree)
+
+The same change as `@skitterbyte/skitterspec` v17 → v18 above — this
+distribution composes the same lifecycle skills. Read that entry; nothing here
+is Linear-specific.
+
+## `@skitterbyte/skitterspec` v16 → v17 (`/spec-go` splits in two)
+
+### Breaking change
+
+**`/spec-go` is removed.** It did two jobs — set an environment up, and build a
+phase — and the seam between them is where the worktree hand-off hurt: you ran
+the same command twice, once to provision and once, from another session, to
+build. They are now two commands with one job each:
+
+| Removed | Use instead |
+|---------|-------------|
+| `/spec-go <name>` (first run — start a spec) | **`/spec-start <name>`** — puts the spec in flight on this checkout, moves it to `in-progress`, then builds phase 1. |
+| `/spec-go` (later runs — build the next phase) | **`/spec-next`** — builds the next phase of whichever spec is in flight. Re-run it per phase. |
+| `/spec-go --here` | **Nothing — `/spec-start` *is* here.** It puts the branch in the checkout you are in, which is what the flag was reaching for. |
+
+**One checkout holds one spec in flight.** `/spec-start` refuses while another
+spec holds your checkout, naming it and the three ways to free the workbench
+(`/spec-complete`, `/spec-cancel`, or `/spec-live main` to park it). It will not
+stash, commit or switch on your behalf — moving unfinished work is a decision,
+not a side effect.
+
+**`/spec-next` refuses when nothing is in flight** rather than guessing a spec
+from the conversation. It writes real code; a wrong guess produces commits on a
+branch nobody asked for.
+
+### What to do
+
+1. **Upgrade** — `npx @skitterbyte/skitterspec update` removes the retired
+   `/spec-go` skill and installs the two replacements. A `/spec-go` you edited
+   yourself is kept with a warning rather than deleted; remove it by hand.
+2. **Retrain the muscle memory** — `/spec-start <name>` to begin, `/spec-next` to
+   carry on, unchanged `/spec-complete` to finish.
+3. **Providers**: the `spec-go-start` seam is now **`spec-next-start`**. A
+   provider distribution must rename its fragment file to match, or the build
+   fails on an orphaned seam.
+
+## `@skitterbyte/skitterspec-linear` v10 → v11 (`/spec-go` splits in two)
+
+The same change as `@skitterbyte/skitterspec` v16 → v17 above — this
+distribution composes the same lifecycle skills, so `/spec-go` is removed here
+too and replaced by `/spec-start` + `/spec-next`. Read that entry; nothing here
+is Linear-specific. (Backfilled: the base entry was written when the change
+landed and this one was missed.)
+
 ## `@skitterbyte/skitterspec-linear` v9 → v10 (`push` validates your issue states)
 
 **`spec-sync push` now refuses to run until the configured `states` names have

package/README.md

@@ -72,7 +72,7 @@ them. Your `specs/` content and live `.core` config are never touched.
 
 ## What the superset adds
 
-On top of the base skills (`/spec`, `/spec-go`, isolation, …):
+On top of the base skills (`/spec`, `/spec-start`, `/spec-next`, isolation, …):
 
 - **`/spec-status`** — read-only drift report: what the next push would create /
   update, any workflow-state drift, and any phase whose status signals disagree
@@ -108,7 +108,7 @@ On top of the base skills (`/spec`, `/spec-go`, isolation, …):
 Linear steps filled in, so the mirror keeps up without anyone remembering to
 push: `/spec`, `/spec-bug` and `/spec-hotfix` link the spec they create (asking
 which **Project** it belongs to, and minting a sub-issue per phase);
-`/spec-go` refreshes it as work starts; `/spec-complete`, `/spec-cancel` and
+`/spec-next` refreshes it as work starts; `/spec-complete`, `/spec-cancel` and
 `/spec-review` refresh it after they change it. All three creating skills can
 also start **from** an existing issue — `/spec SKI-123`,
 `/spec-hotfix v33.16.4 SKI-123`, or `--from-issue` to browse the ones your web
@@ -155,7 +155,7 @@ whole repo *or* one per lifecycle bucket:
   so agents can be assigned one each.
 - `"deferred"` — unlinked phases wait until the work starts. A spec sitting in
   `specs/backlog/` mirrors as **the issue alone**, keeping its phase list in the
-  description; the sub-issues arrive with the push that follows `/spec-go`. Worth
+  description; the sub-issues arrive with the push that follows `/spec-start`. Worth
   it when adopting sync on a backlog of dozens of specs, where the default
   front-loads hundreds of calls for work nobody has started.
 - `"inline"` — phases become **sections of the spec issue's own description**,

package/assets/claude-md-section.md

@@ -1,53 +1,25 @@
 ## Spec workflow
 
-Spec-driven development runs through the lifecycle **skills** below — use them so
-structure and lifecycle stay consistent (see `.claude/rules/spec-planning.md`).
-The everyday loop is **`spec → go → commit → complete`**, with `/spec-connect`
-in the middle when you want to test the spec in a browser.
+Spec-driven development runs through the lifecycle **skills** — use them so
+structure and lifecycle stay consistent. The everyday loop is
+**`spec → start → next → commit → complete`**, with `/spec-connect` when you want to test
+the spec in a browser.
 
-| Skill | Action | Status | Folder |
-|-------|--------|--------|--------|
-| `/spec` | (Feature) Grill to a shared understanding, then write a groomed spec | `Ready` (or `Draft`) | `specs/backlog/` |
-| `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
-| `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
-| `/spec-go` | Provision the env, bring dev servers up, implement the next phase | `In Progress` | `specs/in-progress/` |
-| `/spec-complete` | Verify all phases done + tests green; land + tear down | `Complete` | `specs/complete/` |
-| `/spec-cancel` | Record progress, stamp a reason; tear down | `Cancelled` | `specs/cancelled/` |
-| `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag | `In Progress` | `specs/in-progress/` |
-| `/spec-to-main` | Land the branch on the base mid-spec, without finishing | (unchanged) | (unchanged) |
-| `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
+**Skills vs commands.** The lifecycle skills are read by Claude, which exercises
+judgment. `/spec-connect` and `/spec-live` are **slash commands** instead — each
+pre-executes one `spec-env` verb and relays it, so only you can run them; a
+skill that wants one will tell you to type it.
 
-**Skills vs commands.** The table is skills — Claude reads them and exercises
-judgment. `/spec-connect` and `/spec-live` are **slash commands** instead: each
-pre-executes one `spec-env` verb and relays it, so only you can run them. A skill
-that wants one will tell you to type it.
+The skill table, the spec type/folder conventions and the per-spec isolation
+model all live in **`.claude/rules/spec-planning.md`**, the canonical reference
+every spec skill points at. Tailor its per-phase test commands to this stack.
 
-Every spec has a **type** (`> **Type:** Feature\|Bug`) and a filename prefix
-(`feat-<name>` / `bug-<name>`) — never `[BUG]` brackets (glob hazard). Specs use
-markdown checkboxes (`- [ ]`) for task tracking and are the single source of
-truth for progress. Every spec is a folder: `00-overview.md` is the dashboard
-(problem, decisions, solution, **phase index**, logs) and **each phase is its own
-file** (`01-<slug>.md`, `02-…`) holding that phase's tasks — never a bare file,
-never phases lumped into the overview. **Every phase ends with creating and
-running tests**; decisions go in the spec's Changelog, state transitions in its
-State log.
-
-> Tailor the per-phase test commands and project conventions referenced by the
-> spec skills to this project's stack (see `.claude/rules/spec-planning.md`).
-
-**Per-spec isolation (adopt once, then default):** with isolation adopted
-(`skitterspec init --isolation`, or `specs/.core/env.config.json` present),
-**`/spec-go`** gives every in-progress spec its own git worktree automatically —
-parallel specs, no stashing, `main` left free — and brings up the project's host
-**dev servers** (`env.config` → `dev`) on the spec's ports. The **`/spec-connect <name>`** command then exposes that spec on your canonical
-`localhost` ports so you can test it at the normal URL (`/spec-connect main`
-hands them back); for a code-only spec, **`/spec-live <name>`** reuses the dev
-server you already have running instead. Docker is a
-**per-spec escalation**: `/spec` sets `> **Stack:** worktree` (default) or
-`worktree + docker` when the spec touches the DB / stateful services, and only
-the latter gets a namespaced stack. Teardown is folded into **`/spec-complete`** ·
-**`/spec-cancel`**; beneath the skills, `skitterspec spec-env` is the CLI engine — `up`, `down`,
-`prune`, `dev`, `connect`, `integrate`, `hotfix`, `live`, `status` and `resolve`.
-Most are planners the skills run; omit the spec name and it uses the worktree you
-are standing in. Independent of lifecycle
-status; inactive when `env.config.json` is absent.
+**Release gating** *(only when `specs/.core/gating.config.json` exists)* — each
+spec records whether it ships behind a feature flag, as
+`> **Gating:** <flag name>` or `> **Gating:** none: <one-line reason>`. `/spec`,
+`/spec-bug` and `/spec-hotfix` ask; `/spec-review`, `/spec-start` and
+`/spec-complete` report a spec that has no answer, and never block over it.
+`skitterspec gating check` lists them and always exits 0. The point is that the
+question is **on the record**: a missing line is an oversight, a reason is a
+decision. Skitterspec never reads your flag system — it asks and cites the doc
+you point it at. Without that config, none of this appears.

package/assets/core/SETUP.md

@@ -168,7 +168,7 @@ field:
 
 Everything else (state names, field ownership) has sensible defaults — see
 `linear.config.md` to customise. The moment this file exists, the Linear steps in
-`/spec` and `/spec-go` and the three sync skills switch on.
+`/spec` and `/spec-start` and the three sync skills switch on.
 
 > Editing by hand skips the state-name check described above. If you go this
 > route and your workspace renamed any state, `/spec-push` catches it at your

package/assets/core/env.config.json.example

@@ -1,4 +1,5 @@
 {
+  "mode": "worktree",
   "worktree": {
     "root": "../{repo}-wt",
     "folderPattern": "{slug}"
@@ -14,7 +15,9 @@
   },
   "seedFiles": {
     "mode": "symlink",
-    "files": [".env"]
+    "files": [
+      ".env"
+    ]
   },
   "setup": [],
   "dev": [],
@@ -30,6 +33,9 @@
     "pattern": "{type}/{slug}",
     "identifierField": ""
   },
+  "spec": {
+    "companionPaths": []
+  },
   "baseBranch": "",
   "guards": {
     "refuseTeardownIfDirty": true,

package/assets/core/env.config.md

@@ -2,17 +2,17 @@
 
 Opt-in config for per-spec isolation (git worktree + optional namespaced Docker
 stack + host dev servers + a front-door proxy + an optional opener per
-in-progress spec). Provisioning is folded into `/spec-go`, teardown into
+in-progress spec). Provisioning is folded into `/spec-start`, teardown into
 `/spec-complete` · `/spec-cancel`, and traffic diversion is `/spec-connect`; the
 `skitterspec spec-env <up|down|prune|dev|connect|integrate>` CLI is the engine
 beneath them.
 
-**Once this file is present, isolation is the default policy:** `/spec-go` gives
-**every** in-progress spec its own git worktree automatically. Docker is a **per-
-spec escalation** — a spec brings up a stack only when its `> **Stack:**` header
-is `worktree + docker` (set at `/spec` when it touches the DB / stateful
-services). A `worktree`-only spec takes no registry slot, no port block, and no
-`.env`.
+**Once this file is present, isolation is the default policy:** `/spec-start` gives
+**every** in-progress spec its own git worktree automatically. Docker is a
+**per- spec escalation** — a spec brings up a stack only when its
+`> **Stack:**` header is `worktree + docker` (set at `/spec` when it touches
+the DB / stateful services). A `worktree`-only spec takes no registry slot, no
+port block, and no `.env`.
 
 **Adopt it** with `skitterspec init --isolation` (or copy
 `env.config.json.example` → `env.config.json` here) and edit the values. While
@@ -28,6 +28,22 @@ no live `env.config.json` was found.
 ```jsonc
 {
   // Where sibling worktrees are created and how their dirs are named.
+  // Where a spec's branch gets built.
+  //
+  //   "worktree"  (default) — every spec gets its own git worktree. Several
+  //               specs run side by side and `main` stays free, at the cost of
+  //               one terminal session per spec (`/spec-start` sets it up for you).
+  //   "checkout"  — the branch is built in the primary checkout instead. One
+  //               spec at a time, but no second session and no hand-off: the
+  //               terminal you are already in follows the work.
+  //
+  // Pick it for how you work, not for what this repo contains — a project with
+  // no dev servers may still want several specs in flight. An unrecognised
+  // value falls back to "worktree" rather than erroring.
+  //
+  // Not to be confused with `seedFiles.mode`, which is "symlink" | "copy".
+  "mode": "worktree",
+
   "worktree": {
     "root": "../{repo}-wt",   // dir that holds all spec worktrees; sibling of
                               // the primary checkout, never nested inside it.
@@ -108,9 +124,18 @@ no live `env.config.json` was found.
     "host": "127.0.0.1"     // bind host for the canonical ports
   },
 
-  // Optional, editor/terminal-agnostic opener run after `spec-env up`. The
-  // template is expanded with {worktreePath}, {slug}, {branch}, {projectName},
-  // {portOffset}. Empty = nothing is opened (the path is just printed).
+  // Optional, editor/terminal-agnostic opener — the FALLBACK for reaching a
+  // worktree. `/spec-start` normally moves the session you typed into into the
+  // worktree, and then there is nothing to open: it runs this only when it
+  // could not switch in place (the session is already inside another worktree,
+  // or the harness cannot move it). Run after provisioning and bootstrap, so
+  // the session opens onto a tree that is ready to work in. The template is
+  // expanded with {worktreePath}, {slug}, {branch}, {projectName},
+  // {portOffset}.
+  // Empty = nothing is opened (the path is just printed), which is how you turn
+  // the auto-open off, and the right value unless you actually want a second
+  // window on the fallback path. A non-interactive run skips it either way — an
+  // opened window nobody is sitting at helps no one.
   // Examples: "code {worktreePath}", "tmux new-window -c {worktreePath}",
   // or a "warp://..." deeplink for Warp users.
   "open": {
@@ -133,6 +158,26 @@ no live `env.config.json` was found.
     "identifierField": ""
   },
 
+  // Paths that belong to a spec ALONGSIDE its own `specs/<bucket>/<name>/`
+  // folder. `/spec-start` uses this to tell "the spec you just wrote, not yet
+  // committed" apart from someone else's uncommitted work: if every dirty path
+  // belongs to the spec being started it is committed for you, and if a single
+  // path does not, the start is refused as before.
+  //
+  // Provider-neutral by design — the base engine must not know that any
+  // particular tracker exists — so you declare the shape here. `{slug}` and
+  // `{identifier}` expand exactly as in `branch.pattern` above, `{identifier}`
+  // via `branch.identifierField`.
+  //
+  // A pattern using {identifier} matches NOTHING when no identifier resolves
+  // (no `identifierField` set, or a spec never pushed to a tracker). That is
+  // deliberate: the file it names then belongs to some other spec, and the safe
+  // failure is a refusal you clear with /commit, not a stranger's file swept
+  // into your commit. Default: none — a spec owns only its own folder.
+  "spec": {
+    "companionPaths": []
+  },
+
   // Integration base branch — the branch specs fork from and land back onto
   // (used by the teardown "merged?" guard and, later, the integrate step).
   // Empty = auto-detect: origin/HEAD → main → master. Set it when your default
@@ -148,7 +193,7 @@ no live `env.config.json` was found.
     "refuseTeardownIfUnpushed": true
   },
 
-  // What teardown cleans up beyond this machine. `/spec-go` pushes the spec
+  // What teardown cleans up beyond this machine. `/spec-start` pushes the spec
   // branch when it provisions, so without this a completed spec leaves a merged
   // branch on the remote forever. `deleteRemoteBranch`:
   //   "prompt"  (default) — plan `git push <remote> --delete <branch>` in its own

package/assets/core/gating.config.json.example

@@ -0,0 +1,4 @@
+{
+  "guidance": "",
+  "default": "none: <reason>"
+}

package/assets/core/gating.config.md

@@ -0,0 +1,81 @@
+# `gating.config.json` — release-gating config
+
+Opt-in config for **release gating**: whether each spec records a decision about
+shipping behind a feature flag.
+
+The problem it solves is not "we forgot to use a flag" — it is that
+**nobody can tell whether the question was asked**. A spec can go from `/spec`
+through
+implementation to `/spec-complete` with no flag and no mention of one, and that
+is indistinguishable from "we considered it and decided against". Prose guidance
+in a project rule has already been shown not to close that gap; a required header
+does, because its absence is visible.
+
+**Skitterspec bakes in the offer, never the mechanism.** How your project does
+flags — a resolver, an admin toggle, env precedence, a vendor SDK — is none of
+its business, and it never reads your flag code. It asks the question, cites your
+own documentation, and records the answer.
+
+**Adopt it** by copying `gating.config.json.example` → `gating.config.json` here
+(or `skitterspec init --gating`). While this file is absent the feature is
+entirely unused: no grill question, no header, nothing to check — which is read
+as "this project does not use feature flags".
+
+## Fields
+
+```jsonc
+{
+  // Where THIS project documents how its flags work — a repo-relative path,
+  // cited when the question is asked so the answer is an informed one.
+  // Skitterspec never reads the file; it only names it. Empty = say nothing.
+  "guidance": ".claude/rules/feature-flags.md",
+
+  // The value written when the user declines a flag, so a project can
+  // standardise its wording. Must keep the `none: <reason>` shape — the reason
+  // half is the whole point (see below). Empty falls back to `none: <reason>`.
+  "default": "none: <reason>"
+}
+```
+
+## The header it drives
+
+With this file present, every spec `/spec`, `/spec-bug` and `/spec-hotfix` write
+carries a `Gating:` field beside `Stack:` in `00-overview.md`:
+
+```
+> **Gating:** search-ranking-v2
+> **Gating:** none: additive, nothing to revert
+```
+
+Two valid shapes, and one that is not:
+
+| Value | Meaning |
+|-------|---------|
+| a flag name | ships behind that flag |
+| `none: <reason>` | deliberately not flagged, and why |
+| *missing, empty, or a bare `none`* | **not a decision** — nobody answered |
+
+The reason half is load-bearing. `none: additive, nothing to revert` is a
+decision a reviewer can disagree with; a bare `none` is a shrug, and a missing
+line is an oversight. Distinguishing those three is the entire feature.
+
+## What it never does
+
+- **It never blocks.** `skitterspec gating check` reports and exits 0;
+  `/spec-start` and `/spec-complete` mention a missing header and carry on.
+  Nothing here can stop a spec being started, completed or landed.
+- **It never accuses an old spec.** Only `specs/backlog/` and
+  `specs/in-progress/` are read. Specs finished or abandoned before you adopted
+  gating are out of range by construction, not by a filter someone has to
+  remember.
+- **It never learns your flag system.** `guidance` is a path it prints, nothing
+  more.
+
+## Checking
+
+```
+skitterspec gating check              # the spec in flight here
+skitterspec gating check <spec>       # one named spec
+skitterspec gating check --all        # every active spec
+skitterspec gating check --json       # for tooling
+```

package/assets/core/linear.config.md

@@ -1,7 +1,7 @@
 # `linear.config.json` — Linear one-way sync config
 
 Opt-in config for the Linear sync (`/spec-status`, `/spec-push`, and the
-Linear-aware paths of `/spec` and `/spec-go`). Sync is **one-way**: the repo is
+Linear-aware paths of `/spec` and `/spec-start`). Sync is **one-way**: the repo is
 the source of truth and the Linear **issue** is a **generated mirror**. A spec is
 a Linear issue and each phase a sub-issue; a phase's tasks ride along inside
 that sub-issue's description as a read-only checklist. Content is
@@ -11,7 +11,7 @@ is a read-only drift report. The `sync.fieldOwnership` map now just selects the
 projection field set (every field is repo-owned and pushed).
 
 **Every Linear step is gated on this file.** While `specs/.core/linear.config.json`
-is absent the feature is simply unused — `/spec`, `/spec-go`, and the CLI's
+is absent the feature is simply unused — `/spec`, `/spec-start`, and the CLI's
 `spec-sync` subcommands behave exactly as they do today (local-only). Adopt it by
 copying `linear.config.json.example` → `linear.config.json` here and filling in
 your team ID (and an optional grouping project).
@@ -365,10 +365,11 @@ default for anyone who never sets one.
   `save_issue` calls to mirror, N being its phase count.
 - `"deferred"` — only once the work starts. A spec sitting in `specs/backlog/`
   mirrors as **the issue alone**; its sub-issues are created by the push that
-  follows `/spec-go`.
-- `"inline"` — never. Each phase becomes a **section of the spec issue's own
-  description**, with its full task list, and the `## Phases` index stays as the
-  table of contents. One issue per spec, however many phases it has.
+  follows `/spec-start`.
+- `"inline"` — never. Each phase becomes a
+  **section of the spec issue's own description**, with its full task list, and
+  the `## Phases` index stays as the table of contents. One issue per spec,
+  however many phases it has.
 
 ### One mode, or one per bucket
 
@@ -405,11 +406,11 @@ that made the choice worth it.
 
 ### Switching modes is non-destructive
 
-**A phase already carrying a `linear_issue_id` keeps its sub-issue in every
-mode**, and is never *also* inlined. One-way sync has no delete op, so
-withholding a live sub-issue would not remove it from Linear — it would freeze it
-there, never updated again. So changing `mapping.phases` only ever changes what
-has yet to be minted, and a spec part-way through keeps a coherent mirror.
+**A phase already carrying a `linear_issue_id` keeps its sub-issue in every mode**,
+and is never *also* inlined. One-way sync has no delete op, so withholding a
+live sub-issue would not remove it from Linear — it would freeze it there,
+never updated again. So changing `mapping.phases` only ever changes what has
+yet to be minted, and a spec part-way through keeps a coherent mirror.
 
 **Adopting on an established repo:** set `complete: "inline"` (and `"deferred"`
 or `"inline"` for `backlog`) **before** the first backfill push. Finished specs

package/assets/rules/spec-planning.md

@@ -11,7 +11,8 @@ and lifecycle stay consistent. Each sets a status on the spec header
 | `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
 | `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag + cherry-pick | `In Progress` | `specs/in-progress/` |
 | `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
-| `/spec-go` | Provision the env, bring dev servers up, implement the next phase | `In Progress` | `specs/in-progress/` |
+| `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 | `In Progress` | `specs/in-progress/` |
+| `/spec-next` | Build the next phase of the spec this session is in (re-run per phase) | `In Progress` (unchanged) | (unchanged) |
 | `/spec-to-main` | Land the branch on the base (rebase + ff) **without** finishing — for running the work in CI / a shared env mid-spec; repeatable | `In Progress` (unchanged) | (unchanged) |
 | `/spec-complete` | Verify all phases done + tests green; land + tear down | `Complete` | `specs/complete/` |
 | `/spec-cancel` | Record progress, stamp a reason on the header; tear down | `Cancelled` | `specs/cancelled/` |
@@ -21,15 +22,15 @@ and lifecycle stay consistent. Each sets a status on the spec header
 exercises judgment. `/spec-connect` and `/spec-live` are instead **slash commands**
 (`.claude/commands/`): each pre-executes one `skitterspec spec-env` verb and
 relays its output, so there is no judgment to apply and no model turn spent
-finding one. They are marked `disable-model-invocation`, meaning **only you can
-run them** — a skill that wants one will tell you to type it rather than invoking
-it.
+finding one. They are marked `disable-model-invocation`, meaning
+**only you can run them** — a skill that wants one will tell you to type it
+rather than invoking it.
 
 `/spec-to-main`, `/spec-status` and `/spec-sync` stay **skills** — each carries
 real judgment (green tests before a land; an MCP fetch and a team-key check; ten
 subcommands) — but they are marked user-only too, since nobody reaches them
 except by typing them. Everything else in the table above stays model-invocable,
-which is what lets `/spec-go` hand off to `/spec-push` as work progresses.
+which is what lets `/spec-next` hand off to `/spec-push` as work progresses.
 
 Status flow: `Ready → In Progress → Complete` (or `Cancelled` from any state).
 `/spec` grills to a **Ready** spec directly — there is no separate grooming
@@ -41,14 +42,26 @@ mid-spec (so the work can run in CI / a shared test env) while the spec stays
 `In Progress` in `specs/in-progress/`; it's the intermediate, repeatable half of
 `/spec-complete`'s landing, without the finalise-and-tear-down.
 
+**Two workspace modes.** `specs/.core/env.config.json` → `mode` decides where a
+spec's branch is built. **`worktree`** (the default) gives each spec its own
+checkout — several specs at once and `main` left free — and `/spec-start` moves
+the session you typed into *into* that checkout, so the work carries on in the
+same terminal. **`checkout`** builds the branch in the primary checkout instead:
+one spec at a time, and nothing to move into. Neither mode costs you a second
+terminal; the difference is how many specs can be in flight at once.
+Pick it for how you work rather than for what the project contains — a repo with
+no dev servers may still want several specs in flight. In `checkout` mode
+`/spec-connect` and `/spec-live` do not apply and say so: both exist to reach
+work that lives elsewhere, which is the gap that mode removes.
+
 **Per-spec isolation (opt-in to adopt, then the default policy).** When a project
 adopts isolation (`skitterspec init --isolation`, or `specs/.core/env.config.json`
-present), `/spec-go` gives **every** in-progress spec its own git worktree
+present), `/spec-start` gives **every** in-progress spec its own git worktree
 automatically — several specs run side by side without stashing or clashing, and
 `main` stays free. Docker is a **per-spec escalation**: `/spec` records
 `> **Stack:** worktree` (default) or `worktree + docker` when the spec touches the
-DB / stateful services, and `/spec-go` brings up a namespaced stack only for the
-latter. `/spec-go` also starts the project's host **dev servers** (`env.config`
+DB / stateful services, and `/spec-start` brings up a namespaced stack only for the
+latter. `/spec-start` also starts the project's host **dev servers** (`env.config`
 → `dev`) on the spec's ports; **`/spec-connect <name>`** then exposes that spec on
 your canonical `localhost` ports so you can test it at the normal URL
 (`/spec-connect main` hands them back). All housekeeping (the backlog→in-progress
@@ -74,7 +87,8 @@ feature at the normal URL — no second stack, no proxy. The branch checked out
 the primary checkout **is** the lock: exactly one spec is live at a time, and
 `/spec-live main` hands the instance back (fixes you make while live commit
 straight onto the branch; `/spec-complete` is live-aware and lands them). Rule of
-thumb: **live overlay is the light default for code-only specs**; it *refuses*
+thumb: **live overlay is the light default for *testing* a code-only spec** — it
+is not how work gets started, and no lifecycle skill invokes it; it *refuses*
 stateful ones (`Stack: worktree + docker`, or a branch touching migrations) — keep
 `/spec-connect` + a Docker stack for those, and for genuinely parallel testing.
 Beneath it, `skitterspec spec-env live <take|release|abort|status>` is the engine.
@@ -83,6 +97,13 @@ Beneath it, `skitterspec spec-env live <take|release|abort|status>` is the engin
 tracker-free: it knows nothing about any specific ticketing system. A
 ticketing provider is installed as its own distribution that plugs into named
 **seams** in the shared skills and fulfils a skill-name + CLI contract.
+
+Part of that contract is the **binary name**: the shipped `/spec-connect` and
+`/spec-live` commands invoke `skitterspec`, so a superset that replaces the base
+must expose that name too, alongside whatever it calls itself — one entry point
+under two names. A distribution shipping only its own name leaves those commands
+failing with `command not found`, which reads as a broken install rather than a
+missing alias.
 Sync is **one-way**: the repo is the source of truth and the tracker is a
 **generated mirror**. It ships `/spec-push` (repo→tracker; computes a create/update plan
 against a committed last-pushed snapshot and applies it) and `/spec-status`
@@ -92,13 +113,28 @@ the tracker is never read back or merged.
 
 **Every skill that moves a spec through the lifecycle carries a seam**, so the
 mirror keeps up without anyone remembering to push: `/spec`, `/spec-bug` and
-`/spec-hotfix` link the spec they create; `/spec-go` refreshes it as work starts;
+`/spec-hotfix` link the spec they create; `/spec-next` refreshes it as work starts;
 `/spec-complete`, `/spec-cancel` and `/spec-review` refresh it after they change
 it. `/spec-to-main` and `/spec-live` carry none — they change no status.
 With no provider installed the seams are empty and every skill behaves as a plain
 filesystem workflow. See the provider package's own docs for its config and field
 reference.
 
+**Release gating (opt-in, config-gated).** With
+`specs/.core/gating.config.json` present, every spec `/spec`, `/spec-bug` and
+`/spec-hotfix` write carries a `> **Gating:**` header recording one decision:
+does this ship behind a feature flag, or land live? The value is a **flag name**,
+or **`none: <one-line reason>`** — and the reason half is the load-bearing part,
+because `none: additive, nothing to revert` is a decision a reviewer can argue
+with while a bare `none` is a shrug and a missing line is an oversight.
+
+Skitterspec bakes in **the offer, never the mechanism**: it asks, cites the
+project's own doc (`guidance` in that config), and records the answer. It never
+reads your flag code. `skitterspec gating check` reports specs with no decision
+and **always exits 0** — it reads only `backlog/` and `in-progress/`, so specs
+finished before you adopted gating are out of range by construction. With the
+config absent nothing appears at all: no question, no header, no check.
+
 ## Project conventions (fill this in)
 
 The spec skills tell you to run "your project's typecheck and test commands" and
@@ -135,12 +171,16 @@ status.
 Every spec header carries:
 
 - `> **Name:**` — the spec's folder name (`feat-`/`bug-`/`hotfix-<kebab-name>`).
-  It's the handle you pass to `/spec-go` and the other lifecycle skills, surfaced
+  It's the handle you pass to `/spec-start` and the other lifecycle skills, surfaced
   in the header so it's copy-pasteable without digging for the folder name.
 - `> **Author:**` — who created the spec (set at `/spec` / `/spec-bug`, defaults
   to `git config user.name`).
-- `> **Developer:**` — who implements it (`—` until `/spec-go` starts work, then
+- `> **Developer:**` — who implements it (`—` until `/spec-start` starts work, then
   set to `git config user.name`; `/spec-bug` sets it immediately).
+- `> **Gating:**` — the release-gating decision,
+  **only when `specs/.core/gating.config.json` exists**: a flag name, or
+  `none: <one-line reason>`. Absent entirely in a project that has not adopted
+  gating.
 
 Every spec also has a **State log** table — the audit trail of folder/status
 transitions. Each lifecycle skill appends exactly one row when it changes state:
@@ -175,7 +215,7 @@ When asked for a plan, implementation strategy, or feature breakdown:
 
 ```
 specs/backlog/       Ready (or Draft) specs (/spec)
-specs/in-progress/   under active implementation (/spec-go, /spec-bug)
+specs/in-progress/   under active implementation (/spec-start, /spec-bug)
 specs/complete/      finished (/spec-complete)
 specs/cancelled/     abandoned, with a reason on the header (/spec-cancel)
 specs/.core/         project rules — ALWAYS APPLY, never moved