@skitterbyte/skitterspec-linear 10.7.0 → 11.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

@@ -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,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/commands/spec-live.md

@@ -1,6 +1,6 @@
 ---
-description: Put one spec live on the already-running dev server (take | release | abort | status)
-argument-hint: "[take <spec> | release | abort | status]"
+description: Put one spec live on the already-running dev server — `<spec>` takes it, a bare `take` takes the spec you are on, `main` hands the instance back
+argument-hint: "[<spec> | main | take | release | abort | status]"
 allowed-tools: Bash({{exec}} skitterspec spec-env live:*)
 disable-model-invocation: true
 ---

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

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/core/linear.config.json.example

@@ -24,7 +24,8 @@
     "overviewFile": "00-overview.md"
   },
   "release": {
-    "stages": []
+    "stages": [],
+    "ignorePaths": ["specs/"]
   },
   "branch": {
     "pattern": "{type}/{slug}"

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).
@@ -88,8 +88,12 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
   // The project's OWN deployment ladder — where a ticket goes AFTER its spec is
   // complete. Empty (the default) means no ladder is declared and every
   // stage-aware path is unused. See "The deployment ladder" below.
+  //
+  // `ignorePaths` is what `released`/`stage` treat as BOOKKEEPING rather than
+  // shipped work — see "Bookkeeping commits" below. `[]` opts out.
   "release": {
-    "stages": []
+    "stages": [],
+    "ignorePaths": ["specs/"]
   },
 
   // Git branch name derived for a linked spec. Tokens: {type}, {slug},
@@ -168,6 +172,44 @@ Run `skitterspec spec-sync states` to see the whole configured vocabulary — th
 bucket map and the ladder — against what the workspace actually has.
 
 
+## Bookkeeping commits (`release.ignorePaths`)
+
+`spec-sync released` and `spec-sync stage` answer "what did this release
+contain?" from the `Refs:` trailers in the range. Left alone, that over-answers:
+a spec's `chore(spec): complete <name>` commit carries the **same ref** as the
+code it describes, but lands **after** the tag that shipped that code — so the
+ticket turns up in two consecutive release ranges, once for its code and once
+for its paperwork. Downstream, a deployment ladder then drags an issue that had
+already reached the top back down a rung.
+
+`release.ignorePaths` names the repo-relative prefixes that are paperwork:
+
+```jsonc
+"release": {
+  "ignorePaths": ["specs/"]
+}
+```
+
+- **Paths, not subjects.** `chore(spec):` is a convention a mislabelled commit
+  escapes; what a commit changed is a fact. A commit touching an ignored path
+  **and** a source file still counts — it shipped code.
+- **Prefixes, not globs.** `specs` and `specs/` both mean the directory, and a
+  prefix matches only on a path boundary, so `specs/` never swallows
+  `specs-archive/`. Name a single file to ignore just that file.
+- **Only a commit whose paths are ALL ignored is dropped**, and only when git
+  actually listed paths for it. A merge commit (for which git lists none) counts,
+  as does every commit if the path read fails — a lookup that saw nothing knows
+  nothing, and dropping a ticket nobody notices is worse than the double-count
+  this is fixing.
+- **Every drop is disclosed.** The report says `N commit(s) ignored as
+  bookkeeping`, and `--json` carries `ignored` / `ignoredCommits`.
+- **`[]` is the opt-out**; a blank entry is a hard error, since `""` is a prefix
+  of every path and would silently empty the release.
+
+Default: `["specs/"]`. A project that keeps its paperwork elsewhere names its own
+directories instead.
+
+
 ## Spec → Issue, phases → sub-issues
 
 Push maps the spec's structure to Linear's, keyed by id so it updates rather than
@@ -323,7 +365,7 @@ 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`.
+  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.

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,21 +42,33 @@ 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
 move, header edits, the code) happens on the spec's branch in the worktree; `main`
 changes only when it merges. Teardown is folded into `/spec-complete` ·
 `/spec-cancel`. Beneath the skills, `skitterspec spec-env
-<up|down|prune|dev|connect|integrate|hotfix>` is the CLI engine. Teardown drops
+<up|down|prune|dev|connect|integrate|hotfix|live|status|resolve>` is the CLI
+engine (omit the spec name and it uses the worktree you are standing in). Teardown drops
 the finished spec's own test-DB volume; `spec-env prune` additionally reaps
 **orphaned** volumes left by declined/aborted teardowns, so `/spec-complete` and
 `/spec-cancel` also sweep orphans (confirm-first). A **hotfix** is the one
@@ -82,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`
@@ -91,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
@@ -134,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
@@ -174,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.)
@@ -91,7 +91,7 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
 
 - **Stamp `linear_identifier` and `linear_url`** in `00-overview.md` frontmatter
   from the adopted issue. That is the whole link: every later skill
-  (`/spec-push`, `/spec-status`, `/spec-go`) keys off it being present.
+  (`/spec-push`, `/spec-status`, `/spec-start`) keys off it being present.
 - **Do not run the project picker** and never send `project`. The issue was filed
   somewhere deliberately — where it lives is Linear's business, and adoption is
   not a mint.
@@ -113,7 +113,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:
@@ -132,7 +137,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.
 
@@ -185,7 +190,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:** —
@@ -281,7 +286,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.
 
@@ -313,14 +318,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
@@ -370,7 +375,7 @@ does — you never create the issue by hand:
    `spec-sync record`. That path is fully supported — it is what anyone without
    an API key uses.
 5. **Echo the branch name** from `branch.pattern` so the user knows what
-   `/spec-go` will fork.
+   `/spec-start` will fork.
 
 **If Linear can't be reached**, say so in one line and leave the spec written and
 local — it is still a perfectly good spec, and `/spec-push` links it later. Do

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
@@ -90,7 +90,7 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
 
 - **Stamp `linear_identifier` and `linear_url`** in `00-overview.md` frontmatter
   from the adopted issue. That is the whole link: every later skill
-  (`/spec-push`, `/spec-status`, `/spec-go`) keys off it being present.
+  (`/spec-push`, `/spec-status`, `/spec-start`) keys off it being present.
 - **Do not run the project picker** and never send `project`. The issue was filed
   somewhere deliberately — where it lives is Linear's business, and adoption is
   not a mint.
@@ -127,7 +127,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.
@@ -201,7 +201,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>
@@ -237,8 +237,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 |
 |---------|--------|--------|
@@ -295,7 +297,7 @@ does — you never create the issue by hand:
    `spec-sync record`. That path is fully supported — it is what anyone without
    an API key uses.
 5. **Echo the branch name** from `branch.pattern` so the user knows what
-   `/spec-go` will fork.
+   `/spec-start` will fork.
 
 **If Linear can't be reached**, say so in one line and leave the spec written and
 local — it is still a perfectly good spec, and `/spec-push` links it later. Do
@@ -312,6 +314,38 @@ and **never auto-push git** — Linear's own automation reacts to real branch/PR
 events later. Report the Linear issue URL as part of the skill's finish-up
 message.
 
+### Picking the Linear Project
+
+Run this **only when minting a spec issue** — creating it for the first time. On
+an update the issue already has a project (or deliberately has none), and that
+placement is **Linear's to own**: never send `project` on an update, and never
+record the choice in the spec file or the snapshot. A PM re-homing a spec issue
+must not show up as drift or be overwritten on the next push.
+
+1. **List the candidates.** Ask the engine:
+   `skitterspec spec-sync projects --json`. On the API path it returns the team's
+   projects; on the MCP path it says so, and you call the discovered project-list
+   tool instead. Drop archived / completed projects — they can't take new work.
+2. **Offer them.** Show the names (most recently updated first is fine), plus an
+   explicit **None (team only)** option. Pre-select `linear.projectId` from
+   `linear.config.json` when it's set and still in the list; otherwise pre-select
+   **None**.
+3. **Narrow on request.** If the user types a fragment rather than choosing, filter
+   the list case-insensitively by name and re-offer. Don't re-fetch.
+4. **Never offer to create a project.** Projects are the PM's surface — if none
+   fits, that's **None (team only)**, and someone makes the project in Linear.
+5. **Pass it once**, to whichever thing mints the issue: `--project <chosen id>`
+   on `spec-sync apply`, or `project: <chosen id>` on the MCP issue-create call.
+   Chose None → omit it entirely (do not pass an empty string).
+
+**Degrade, never block.** If the list can't be fetched — Linear not connected, no
+project-list tool, no API key, or `spec-sync projects` reporting it couldn't ask —
+say so in one line — *"project picker unavailable"* — and carry on with
+`linear.projectId` if it's set, else no project at all. A missing picker must never fail the skill that called it.
+
+If `linear.projectId` is set but that Project is archived or missing, relay
+Linear's error and stop rather than silently minting an unparented issue.
+
 ## 5. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix. Match surrounding code; honour all
@@ -322,12 +356,12 @@ message.
 
 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.
 
 **Only when `specs/.core/linear.config.json` exists** and the spec carries a