@skitterbyte/skitterspec-linear 10.7.0 → 11.0.0

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

@@ -110,6 +110,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
@@ -105,8 +105,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:**
@@ -157,7 +160,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
@@ -200,6 +203,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** —
@@ -210,7 +225,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
@@ -230,6 +245,12 @@ worktree and branch are being kept, and go straight to sub-step 4. Mention
    finish completing anyway — never block the spec on it. Skip when Docker isn't
    in use (the command self-reports "no orphaned volumes").
 
+**Report from where you now are.** After a teardown you relocated for, the
+worktree path in the report is a directory that no longer exists and the landed
+work is on the base branch in the primary checkout — say both, so nobody goes
+looking for a tree that is gone. A session that was a worktree tab has finished
+its job at that point; its shell is the operator's own to close.
+
 **Say what you reclaimed.** With no confirmation step the user never saw this
 coming, so the final report must name the worktree path removed and the branch
 deleted (or, under `--keep-env`, that both were kept). A teardown nobody

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

@@ -1,6 +1,6 @@
 ---
 name: spec-hotfix
-description: Fix a production bug on the exact released version — fork a worktree from a release tag, drive it red→green like /spec-bug, then land it by tagging a new patch (for CI/CD to deploy) and cherry-picking the fix back onto main. ALWAYS starts from a base tag and works on the hotfix's own branch, never on main. Can start from a tracker issue when a provider is installed (`/spec-hotfix <tag> <ISSUE-REF>`), adopting it as the hotfix's issue. Creates specs/in-progress/hotfix-<name>/00-overview.md. Use when the user says "/spec-hotfix", "hotfix <tag>", "prod is broken on <version>", "patch the released version", or needs a fix shipped against a tagged release rather than main.
+description: Fix a production bug on the exact released version — fork a worktree from a release tag, drive it red→green, then land it by tagging a new patch for CI/CD and cherry-picking the fix onto main. ALWAYS starts from a base tag and works on the hotfix's own branch, never on main. Use when the user says "/spec-hotfix", "hotfix <tag>", "prod is broken on <version>", "patch the released version", or needs a fix shipped against a tagged release rather than main.
 ---
 
 # /spec-hotfix — fix a released version, tag it, cherry-pick back to main
@@ -97,7 +97,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.
@@ -173,7 +173,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
@@ -206,7 +206,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>
@@ -243,8 +243,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 |
 |---------|--------|--------|
@@ -306,7 +308,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
@@ -323,6 +325,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.
+
 ## 6. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix on the branch. Match surrounding code;
@@ -334,7 +368,7 @@ message.
 
 **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

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

package/assets/skills/spec-linear-setup/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: spec-linear-setup
-description: Configure Linear sync for this repo by interview rather than by hand. Discovers the workspace over MCP (teams, projects, labels, issue workflow states), asks how the work is organised — which team this repo files into, whether products are split by team or by project, which labels drive intake — then hands the answers to `skitterspec spec-sync init-config`, which validates them and writes specs/.core/linear.config.json. Checks the configured workflow-state names against the workspace, so a renamed state is caught now instead of silently producing a mirror that never moves. Safe to re-run: an existing config is reviewed, never overwritten without consent. Use when the user says "/spec-linear-setup", "set up Linear sync", "connect this repo to Linear", "configure linear.config.json", or "check my Linear setup".
+description: Configure Linear sync for this repo by interview rather than by hand — discovers the workspace, asks how the work is organised, then validates the answers and writes specs/.core/linear.config.json. Safe to re-run; an existing config is reviewed, never overwritten without consent. Use when the user says "/spec-linear-setup", "set up Linear sync", "connect this repo to Linear", "configure linear.config.json", or "check my Linear setup".
 ---
 
 # /spec-linear-setup — configure Linear sync by interview

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

@@ -0,0 +1,141 @@
+---
+name: spec-next
+description: Build the next unfinished phase of the spec currently in flight on this checkout — pre-flight, implement with tests, record progress and refresh the tracker. Refuses when no spec is in flight rather than guessing one. Use when the user says "/spec-next", "build the next phase", "continue the spec", or "carry on with this spec".
+---
+
+# /spec-next — build the next phase of the spec in flight
+
+It assumes the workbench is already set up: a spec is **in flight** on this
+checkout, and this skill implements its next unfinished phase. Putting a spec in
+flight — provisioning, moving it to `in-progress`, getting its branch here — is
+`/spec-start`'s job. Re-run this per phase until the spec is done, then
+`/spec-complete`.
+
+## 1. Identify the spec in flight
+
+Resolve **in this order**, and stop at the first that answers:
+
+1. **The live spec of this checkout** — run
+   `skitterspec spec-env live status` and read its `live:` line. `live: yes`
+   names the spec whose branch is checked out here; that is the one to build.
+2. **The worktree you are standing in** — if this session's cwd is inside a
+   spec's worktree, that spec is in flight *for this session*. This is the
+   manual-parallel path: several specs may be provisioned, and a terminal tab
+   opened in one is its own workbench.
+3. **The current branch, in `checkout` mode** — no worktrees exist, so the
+   branch the checkout is on names the spec.
+
+**If none answers, refuse and stop:**
+`no spec in flight — run /spec-start <name> to put one on this checkout`.
+
+**Never fall back to the spec "in context".** A spec discussed in conversation
+is not a spec in flight, and this skill writes real code: building the wrong
+spec's phase produces commits on a branch nobody asked for. The refusal is
+cheap; the mistake is not.
+
+A **name argument** is accepted, but it must *match* the spec in flight — it
+narrows a re-run, it does not select a different spec. A mismatch refuses,
+naming both.
+
+## 2. Pre-flight — commit prior work
+
+Before writing any code for this phase, get the workspace clean:
+
+- **Confirm the last-worked phase is committed.** Run `git status` and
+  `git log --oneline -5`. The most recently *implemented* phase (not necessarily
+  the numerically previous one) should already be committed. If prior-phase work
+  is still uncommitted, **stop and suggest committing it first** (e.g. via
+  `/commit`) so each phase lands as its own reviewable commit — don't build the
+  next phase on top of an uncommitted one. (Skip if this is the first phase —
+  there's nothing prior to commit.)
+
+## 3. Implement the phase
+
+Identify the **first unfinished phase** from the `00-overview.md` phase index,
+then open its phase file (`0N-<slug>.md`) — that file holds the tasks. Mark it
+started: set the phase-file heading to `🔄` and its `> **Status:**` to
+`In progress`, and flip the matching row in the overview phase index to `🔄`.
+
+**Then sync with the tracker (only if a provider is installed).** The phase has
+just changed state, so refresh the mirror before the build starts — that is what
+makes the phase show as in progress *while* it is being built rather than only
+once it is over. Without a provider this is a no-op and nothing below changes.
+
+**Only when `specs/.core/linear.config.json` exists** and the spec carries a
+`linear_identifier`. Otherwise skip this step — no config means zero change.
+
+- **No pull.** Linear is a generated mirror in one-way sync, so there is nothing
+  to bring down before building — the repo is already the source of truth. (A
+  workflow-state a teammate moved in Linear is advisory only; `/spec-status`
+  surfaces it. It is overwritten on the next push.)
+- **Refresh the mirror now, without asking.** Run `/spec-push`. The spec has just
+  moved to `in-progress` and its phase to `🔄` — both real state changes, and the
+  tracker is a generated mirror of them. This holds under **both**
+  `mapping.phases` modes, for different reasons:
+  - `"subissue"` (the default) — the phase sub-issues already exist, and this
+    push is what moves the current one into its in-progress state. Skip it and
+    every sub-issue sits in Backlog until the spec completes.
+  - `"deferred"` — the sub-issues do not exist yet, and this push is what mints
+    them. Skip it and a started spec stays mirrored as a phase-less issue.
+- **Never mint the spec issue.** An unlinked spec is skipped, not created —
+  `/spec-push` is how someone opts in.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **carry on with the build**. The repo is correct regardless; the mirror is
+  disposable and the next push repairs it.
+- **Expect a dirty `specs/.core/` afterwards.** The push writes a base snapshot
+  and stamps any new ids, and `/spec-next` does not commit. The next `/commit`
+  sweeps it up with the phase's own work.
+- Linear's GitHub branch/PR automation may drive status transitions off the
+  branch/PR you pushed in step 2; that's expected and the repo still wins on the
+  next `/spec-push`.
+
+Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.md`:
+
+- Work task by task through the phase file. Make focused edits that match
+  surrounding code.
+- Honour the project's conventions (see `.claude/rules/spec-planning.md` and the
+  rules it links).
+- **Tests are part of the phase, not after it.** Create/extend tests for the
+  work, then run the project's typecheck and test commands. Do not declare the
+  phase done until green.
+- Never hardcode dates in tests; never run destructive commands against a real
+  database — use the project's test database only.
+
+## 4. Record progress
+
+- In the **phase file**: tick completed tasks (`- [x]`), flip its heading to `✅`,
+  and set its `> **Status:**` to `Done`.
+- In **`00-overview.md`**: flip the matching phase-index row to `✅`.
+- If anything changed from the plan (a decision, a deviation, a discovered
+  constraint), add a dated **Changelog** entry in `00-overview.md`.
+- If new work surfaced, add it as tasks to the appropriate phase file (or add a
+  new phase file + index row) rather than doing it silently.
+
+**Then refresh the mirror (only if a provider is installed).** The phase is done
+in the repo now; leaving the tracker to catch up at `/spec-complete` is what makes
+a mirror lag a whole spec behind. Without a provider this is a no-op.
+
+**Only when `specs/.core/linear.config.json` exists** and the spec carries a
+`linear_identifier`. Either missing → **skip**, in one line
+(`not linked to Linear — /spec-push to mirror it`), and carry on.
+
+**Refresh the mirror now, without asking.** Run `/spec-push`. The repo has just
+become the truth about this phase's progress, and progress is what the mirror
+exists to show. Deferring it to `/spec-complete` is what makes every phase
+sub-issue jump from Backlog straight to Done, with nothing visible in between.
+
+- **Never mint.** An unlinked spec is skipped, not created.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **finish the operation anyway**. The phase is done in the repo regardless;
+  the mirror is disposable and the next push repairs it.
+- **Expect a dirty `specs/.core/` afterwards.** The push writes a base snapshot
+  and stamps any new ids, and these skills do not commit. The next `/commit`
+  sweeps it up with the phase's own work.
+- **Say what happened** in the skill's report: mirror updated, skipped as
+  unlinked, or failed with the reason.
+
+## 5. Report
+
+Summarise what was implemented, the test result (quote failures if any), and
+which phase is next. Do **not** `git commit` unless the user asks — finish,
+verify, and wait.

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

@@ -1,6 +1,6 @@
 ---
 name: spec-push
-description: Push a spec up to its linked Linear issue (repo → Linear, one-way). The repo is the source of truth; Linear is a generated mirror. A spec is a Linear issue and each phase a sub-issue, with the phase's tasks mirrored read-only into that sub-issue's description. Runs `skitterspec spec-sync push` to get a create/update plan, then applies it with `spec-sync apply` — straight to Linear's API when a key is set (descriptions never pass through the model), or over MCP when it isn't — stamping the returned ids back into the spec and recording the snapshot. Never merges Linear content back. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "update the Linear issue from this spec".
+description: Push a spec up to its linked Linear issue (repo → Linear, one-way). The repo is the source of truth and Linear a generated mirror, so content is never read back or merged. A spec is an issue and each phase a sub-issue. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-push", "push to Linear", "update the Linear issue from this spec".
 ---
 
 # /spec-push — send a spec up to Linear (one-way)
@@ -90,7 +90,7 @@ issue-state NAME via `config.states` at apply time.
 
 A **`phasesDeferred`** field means `mapping.phases` is `"deferred"` and this spec
 has not started, so its phases are deliberately absent from the plan — the issue
-pushes alone and the sub-issues are minted by the push that follows `/spec-go`.
+pushes alone and the sub-issues are minted by the push that follows `/spec-start`.
 Relay the count; it is not a sign the phase files failed to parse. Nothing else
 about applying the plan changes.
 

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

@@ -8,7 +8,7 @@ description: Re-validate an existing spec against the current codebase — detec
 Specs rot: the code moves on while a spec sits in the backlog or pauses
 mid-build. This skill re-validates a spec against the **current** code and
 rewrites the stale parts so it's safe to act on. It plans only — it does not
-implement anything (that's `/spec-go`).
+implement anything (that's `/spec-next`).
 
 ## 1. Identify the target spec
 
@@ -48,9 +48,9 @@ trust the spec's own wording — verify:
 
 Where the drift forces a choice (the old approach no longer fits, a referenced
 thing is gone, scope is now ambiguous), grill the user like `/spec` Phase A —
-**one question at a time, with a recommended answer** — but scoped tightly to
-the drift. Don't re-litigate decisions that still hold. If you can resolve it by
-reading the code, do that instead of asking.
+**batching independent questions, each with a recommended answer** — but scoped
+tightly to the drift. Don't re-litigate decisions that still hold. If you can
+resolve it by reading the code, do that instead of asking.
 
 ## 4. Update the spec
 
@@ -119,5 +119,5 @@ In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
 ## 5. Report
 
 Summarise the drift found, what you changed, any questions still open, and
-whether the spec is now safe to `/spec-go` (or should drop back to `Draft` until
+whether the spec is now safe to `/spec-start` (or should drop back to `Draft` until
 the open questions are resolved). Do **not** `git commit` unless the user asks.

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

@@ -0,0 +1,146 @@
+---
+name: spec-start
+description: Put a spec in flight on this checkout — provision its branch, move it to in-progress, refresh the tracker, then build phase 1. Refuses unless the checkout is on the base branch with nothing already in flight, so it never parks or swaps someone's unfinished work. Use when the user says "/spec-start", "start this spec", or "begin implementing <spec>".
+---
+
+# /spec-start — put a spec in flight
+
+One checkout, one spec in flight. This skill is how a spec gets there:
+provision, move it to `in-progress`, refresh the tracker, then hand straight on
+to `/spec-next` for phase 1. Continuing a spec afterwards is `/spec-next`;
+finishing it is `/spec-complete`.
+
+## 1. The gate — refuse unless the workbench is free
+
+**Check this first, before resolving anything or touching a file.** In
+`worktree` mode run `skitterspec spec-env live status`; in `checkout` mode read
+the current branch. The workbench must be:
+
+- **on the base branch** (`main`, or the configured `baseBranch`), and
+- **clean** — no uncommitted changes.
+
+**If it isn't, relay what is in flight and stop.** Name the spec holding the
+checkout and the three ways out, then end your turn:
+
+- **`/spec-complete`** — it's finished; land it and free the workbench.
+- **`/spec-cancel`** — it isn't wanted; record why and free the workbench.
+- **`/spec-live main`** *(worktree mode)* — park it: the branch goes back to its
+  worktree and stays exactly as it is, ready to resume later.
+
+**Never get past the gate yourself.** Do not stash, do not commit on the
+operator's behalf, do not `/spec-live main` for them, do not switch branches. An
+uncommitted tree, a half-built phase and a rebase are each a decision someone
+must make deliberately — and the cost of guessing is another spec's work moved
+without its author asking. A refusal costs one command; the alternative can cost
+an afternoon.
+
+A dirty tree is refused *with the same words whatever the cause*: the gate does
+not try to judge whether the changes look important.
+
+## 2. Identify the spec
+
+- Use the name/path argument when given.
+- Otherwise use the spec **in context** (the one just created or discussed).
+  Unlike `/spec-next`, that fallback is safe here: this skill starts nothing
+  without the gate above passing, and a wrong guess is caught by the operator
+  before any code is written.
+- Locate it under `specs/` — `specs/backlog/` first, then the other buckets. A
+  spec is a `<name>/` folder whose entry point is `00-overview.md`, with one
+  file per phase beside it (`01-<slug>.md`, `02-…`). Legacy specs may be a bare
+  `<name>.md`, or a `00-overview.md` with inline phases — handle those too.
+- A spec already in `specs/in-progress/` was started before. If its branch is
+  parked in a worktree, this skill brings it back into flight; say so rather
+  than reporting a fresh start.
+
+## 3. Put its branch in this checkout
+
+**Read `mode` from `specs/.core/env.config.json`** (default `worktree`).
+
+### `worktree` mode
+
+1. **Provision.** Run `skitterspec spec-env up <name>` — a planner, so run the
+   `to provision, run:` commands it prints and confirm they succeeded. Then run
+   its **`then, in the worktree, run:`** steps in order (file seeding, then
+   `setup`): a fresh worktree has no dependencies and none of the repo's
+   gitignored files, so hooks, typechecks and tests fail until they are there.
+2. **Bring the branch here.** Tell the user to type **`/spec-live <name>`** — it
+   rebases the branch, frees it from the worktree and checks it out in this
+   checkout, which is what makes this session the workbench. It is a user-only
+   command, so you cannot run it: print it, end your turn, and pick up at step 4
+   when they re-run `/spec-start`.
+   **Already here?** If the live check in step 1 showed this spec live, or the
+   branch is already checked out, the move is done — carry straight on.
+3. **A spec the live overlay refuses** — a hotfix, a stateful spec
+   (`Stack: worktree + docker`), or a branch touching migrations — **parks
+   instead.** Do the housekeeping in step 4 with `git -C <worktreePath>`, run
+   `open.command` if configured, print the worktree path, and say to run
+   `/spec-next` from a session there. Relay the engine's refusal reason as it
+   printed it; those guards protect a shared dev instance and are not yours to
+   weaken.
+   **Trust the worktree first.** `spec-env up` wrote the printed `trusted:` root
+   into `.claude/settings.local.json`, but that file will not hot-reload in this
+   session — run `/add-dir <trusted root>` before editing into the worktree, or
+   the first write prompts.
+
+### `checkout` mode
+
+Run `skitterspec spec-env up <name>` and the single `git switch` it prints.
+There is no worktree, no bootstrap, no live step — the checkout is already the
+workbench. Its planner enforces the same gate from the engine side, so relay any
+refusal and stop.
+
+## 4. Move the spec into development
+
+On the branch, in this checkout (or via `git -C <worktreePath>` for a parked
+spec):
+
+- `git mv "specs/backlog/<name>" "specs/in-progress/<name>"` if it isn't there
+  already (`mkdir -p specs/in-progress` first). Use `git mv` to keep history.
+- Set the **Status** header: `> **Status:** In Progress — Phase 1 (started <YYYY-MM-DD>)`.
+- Set **Developer** if it is still `—` (`git config user.name`).
+- Append a **State log** row: `| <YYYY-MM-DD> | In Progress | in-progress | <git user.name> |`.
+- **Commit it, and push the branch.** One commit, the spec's own — it records the
+  in-progress state for everyone and fires the tracker's automation. Do this
+  *before* the tracker refresh below, so the snapshot that refresh writes is
+  swept up by the phase's own commit rather than left dirty.
+
+A spec ideally arrives `Ready` from `/spec`; a `Draft` works too — sanity-check
+it is well-formed first.
+
+## 5. Bring the spec's dev servers up — confirm before heavy steps
+
+**Only when the project configures host dev servers** (`env.config.json` → a
+non-empty `dev` array). Show what will start — the commands, the ports, any
+Docker stack — and get a yes; on **`--plan`**, print it and stop. On
+confirmation run `skitterspec spec-env dev up <name>`. With none configured this
+is a clean no-op.
+
+To reach the spec at your normal `localhost` URL afterwards, the **user** types
+**`/spec-connect <name>`** (`/spec-connect main` hands the ports back). Never
+invoke it yourself.
+
+## 6. Build phase 1
+
+**Carry straight on into `/spec-next`** in this session: it marks phase 1
+started, refreshes the mirror again, builds it with tests and reports. Do not
+stop and ask the operator to run it — the workbench is set up and they asked to
+start the spec.
+
+## Opt-outs
+
+- **`--plan`** — print the provisioning and dev-server plan, change nothing.
+- **`--no-worktree`** — skip provisioning and build on the current branch. Warn
+  that the work lands wherever you are (usually the base branch); reserve it for
+  a trivial change or an explicit request.
+
+There is no `--here`: `/spec-start` **is** here. It puts the branch in the
+checkout you are in, which is what the old opt-out was reaching for.
+
+## Why there is no tracker seam here
+
+This skill creates no spec and mints no issue, so it has nothing to link — the
+intake and picker steps belong to `/spec`, `/spec-bug` and `/spec-hotfix`. The
+state change it *does* make (the spec moving to `in-progress`) is mirrored by
+the refresh `/spec-next` runs the moment it starts, which pushes the issue state
+and the phase states together. Adding a push here would send the same thing
+twice, one commit apart.

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

@@ -1,6 +1,6 @@
 ---
 name: spec-status
-description: Show a spec's one-way sync status against Linear — a read-only drift report. Reports whether the spec changed since the last push (there's something to push) and, optionally, whether Linear's issue workflow-state differs from the spec's. Fetches the Linear issue over MCP and runs `skitterspec spec-sync status`. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what would push", or "show spec sync status".
+description: Show a spec's one-way sync status against Linear — a read-only drift report naming what would push, and whether the tracker's workflow-state has drifted from the spec's. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what would push", or "show spec sync status".
 disable-model-invocation: true
 ---
 
@@ -77,4 +77,4 @@ given spec got is stated. Under **`inline`** the phases live in the spec issue's
 description rather than as sub-issues, so "0 to create" is the expected shape
 rather than a sign the phase files failed to parse; under **`deferred`** the
 `N phase(s) deferred` line above it says how many are still waiting on
-`/spec-go`. Relay both lines as printed.
+`/spec-next`. Relay both lines as printed.

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

@@ -1,6 +1,6 @@
 ---
 name: spec-sync
-description: Run the repo-wide spec-sync operations against Linear — what's linked, the workspace's states and projects, read-back verification, manual stamping, and bulk `apply --all <bucket>`. Run it bare for the repo-wide overview. Wraps the `spec-sync` CLI, which is a local devDependency and never on PATH, so this skill always states the full invocation. Defers to /spec-push and /spec-status for per-spec work. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-sync", "run spec-sync", "what's linked to Linear", "which states does the workspace have", or "mirror the whole backlog".
+description: Run the repo-wide spec-sync operations against Linear — what is linked, the workspace states and projects, read-back verification, manual stamping, and bulk apply. Run it bare for the repo-wide overview. Defers to /spec-push and /spec-status for per-spec work. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-sync", "run spec-sync", "what's linked to Linear", "which states does the workspace have", or "mirror the whole backlog".
 disable-model-invocation: true
 ---
 
@@ -156,6 +156,14 @@ Relay the **unreferenced count** even when it is zero. A chore commit
 legitimately carries no ticket and a *missed* trailer looks identical, so
 omitting the number reads as "everything is accounted for" when it may not be.
 
+**Bookkeeping commits are excluded.** A spec's `chore(spec): complete <name>`
+commit carries the same ref as the code it describes but lands *after* the tag
+that shipped it, so counting it would put the ticket in two consecutive releases.
+A commit whose changed paths are **all** under `release.ignorePaths` (default
+`specs/`) contributes nothing; one that touches an ignored path *and* a source
+file still counts. Relay the **ignored count** whenever it is non-zero — that is
+the report saying which commits it set aside.
+
 ## 8. `retarget` — after a Linear team is renamed
 
 ```