@skitterbyte/skitterspec 16.10.0 → 17.0.0

package/MIGRATION.md

@@ -1,5 +1,41 @@
 # Migration guide
 
+## `@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` v9 → v10 (`push` validates your issue states)
 
 **`spec-sync push` now refuses to run until the configured `states` names have

package/README.md

@@ -4,11 +4,11 @@ Spec-driven development for [Claude Code](https://claude.com/claude-code) — a
 **tracker-free** filesystem workflow. The everyday loop is five verbs:
 
 ```
-/spec  →  /spec-go  →  /spec-connect  →  /commit  →  /spec-complete
+/spec  →  /spec-start  →  /spec-next  →  /commit  →  /spec-complete
  plan      build it     test it live      save it     finish + land
 ```
 
-Ships the spec-lifecycle skills (`/spec`, `/spec-go`, `/spec-complete`,
+Ships the spec-lifecycle skills (`/spec`, `/spec-start`, `/spec-next`, `/spec-complete`,
 `/spec-cancel`, `/spec-bug`, `/spec-hotfix`, `/spec-review`, `/spec-init`) plus
 per-spec **isolation** — a git worktree per in-progress spec, Docker on demand,
 host dev servers on reserved ports, and `/spec-connect` to test a worktree at your
@@ -56,7 +56,7 @@ Install exactly one — the superset is a strict superset of this package.
 
 When your app runs from `main` on `localhost`, a worktree's changes are
 unreachable. Add a `dev` block to `specs/.core/env.config.json` listing your host
-dev servers (each `{ name, command, portVar, health?, frontPort? }`); `/spec-go`
+dev servers (each `{ name, command, portVar, health?, frontPort? }`); `/spec-start`
 starts them on the spec's reserved ports, and **`/spec-connect <name>`** points
 your canonical `localhost` ports at that spec (via a small bundled reverse proxy —
 no external install), so you test at the exact URL you always use.

package/assets/claude-md-section.md

@@ -1,53 +1,15 @@
 ## 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.
-
-| 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 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.
-
-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.
+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.
+
+**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.
+
+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.

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": [],

package/assets/core/env.config.md

@@ -2,12 +2,12 @@
 
 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
+**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
@@ -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,13 @@ 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. `/spec-start` RUNS it when it hands
+  // you into a new worktree — 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. 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": {
@@ -148,7 +168,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/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 on this checkout, then build phase 1 | `In Progress` | `specs/in-progress/` |
+| `/spec-next` | Build the next phase of the spec in flight (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/` |
@@ -29,7 +30,7 @@ it.
 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,25 @@ 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, at the cost of one
+terminal session per spec, which `/spec-start` sets up for you. **`checkout`** builds
+the branch in the primary checkout instead: one spec at a time, but no second
+session and no hand-off, so the terminal you are already in follows the work.
+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
@@ -83,6 +95,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,7 +111,7 @@ 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
@@ -135,11 +154,11 @@ 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).
 
 Every spec also has a **State log** table — the audit trail of folder/status
@@ -175,7 +194,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

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,7 +47,7 @@ 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.
 
@@ -95,7 +100,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:** —
@@ -191,7 +196,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.
 
@@ -223,14 +228,14 @@ 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

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.
@@ -111,7 +111,7 @@ 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>
@@ -147,8 +147,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 |
 |---------|--------|--------|
@@ -186,12 +188,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,18 @@ 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, `cd` to the primary checkout
+**first**, then run the teardown commands.
+
+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
@@ -73,8 +73,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 +128,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 +171,18 @@ 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, `cd` to the primary checkout
+**first**, then run the teardown commands.
+
+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** —
@@ -178,7 +193,7 @@ worktree and branch are being kept, and go straight to sub-step 4. Mention
    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
+   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
@@ -198,6 +213,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
@@ -83,7 +83,7 @@ that header — must exist **before** `spec-env up`:
   `<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,7 +116,7 @@ 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>
@@ -153,8 +153,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 |
 |---------|--------|--------|
@@ -198,7 +200,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,20 @@ 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.
 
 ## 1. Folders
 
@@ -54,7 +64,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
@@ -73,7 +83,7 @@ Ensure it exists. If missing, create it documenting:
 - 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