@skitterbyte/skitterspec-linear 10.8.0 → 12.0.0

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
@@ -198,6 +198,31 @@ project's own, so ask rather than guess.
 the workspace — that report is the evidence the setup is right, so don't
 paraphrase it into "done".
 
+## 8b. Let `/spec-start` commit the snapshot with its spec
+
+**Only when `specs/.core/env.config.json` exists** (per-spec isolation is on). If
+it is absent, skip this — there is nothing to configure.
+
+`/spec-start` commits an uncommitted spec for you, but only the paths it can
+prove belong to that spec. Its own folder always does; this repo's per-spec
+Linear snapshot (`sync.baseDir`, `specs/.core/linear-base/<ID>.base.json`) does
+not, because the base engine is deliberately tracker-free and cannot know that
+path exists. Declare it once, in `env.config.json`:
+
+```json
+"spec": {
+  "companionPaths": ["specs/.core/linear-base/{identifier}.base.json"]
+}
+```
+
+`{identifier}` resolves through `branch.identifierField`, so **set that too** if
+it is still empty — `"linear_identifier"` is the field `/spec` stamps. Without
+it the pattern expands to nothing and the snapshot is treated as another spec's
+file: `/spec-start` then refuses the tree instead of committing it, which is the
+safe failure but a needless one.
+
+Leave both alone if the user has already set them.
+
 ## 9. Report and hand off
 
 **Finish by checking, not by describing.** First write down what the MCP server
@@ -254,12 +279,12 @@ more detail if you need it. If the key is missing, tell the user to run this
 skitterspec spec-sync credentials set
 ```
 
-**Do not ask the user to paste an API key into this conversation, and do not
-offer to store one for them.** A key pasted into a chat enters the transcript,
-is sent to the model, and may be logged — moving where a key is stored is
-pointless if it travels through the conversation to get there. Your job is to
-confirm the setup is ready and name the command; the value is theirs alone. The
-key is optional: without one, pushes go over MCP.
+**Do not ask the user to paste an API key into this conversation, and do not offer to store one for them.**
+A key pasted into a chat enters the transcript, is sent to the model, and may
+be logged — moving where a key is stored is pointless if it travels through the
+conversation to get there. Your job is to confirm the setup is ready and name
+the command; the value is theirs alone. The key is optional: without one,
+pushes go over MCP.
 
 Mention what setup did **not** configure, so the defaults aren't mistaken for
 decisions: phase mapping (`mapping.phases` — sub-issue per phase by default) and

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

@@ -0,0 +1,141 @@
+---
+name: spec-next
+description: Build the next unfinished phase of the spec in flight for this session — pre-flight, implement with tests, record progress and refresh the tracker. Refuses when no spec is in flight rather than guessing one, and never builds a spec it is not standing in. 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 start one`.
+
+**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,20 +1,19 @@
 ---
 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)
 
-Repo → Linear. The repo is the **source of truth**; Linear is a **generated
-mirror**. A spec is a Linear **issue**; each phase is a **sub-issue** (a child
-issue), and the phase file is mirrored into that sub-issue's description as
-written — its prose, its sections, and its tasks as a read-only checklist, never
-as issues of their own. Only the phase's h1 and `> **Status:**` line are left
-out, because both are pushed as fields of their own (the sub-issue's title and
-state). This skill
-computes what changed since the last push and applies it — it never reads Linear
-content back or merges. A person editing the mirror in Linear will see it
-overwritten on the next push.
+Repo → Linear. The repo is the **source of truth**; Linear is a
+**generated mirror**. A spec is a Linear **issue**; each phase is a
+**sub-issue** (a child issue), and the phase file is mirrored into that
+sub-issue's description as written — its prose, its sections, and its tasks as
+a read-only checklist, never as issues of their own. Only the phase's h1 and
+`> **Status:**` line are left out, because both are pushed as fields of their
+own (the sub-issue's title and state). This skill computes what changed since
+the last push and applies it — it never reads Linear content back or merges. A
+person editing the mirror in Linear will see it overwritten on the next push.
 
 **Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
 tell the user how to enable Linear sync and stop.
@@ -90,7 +89,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.
 
@@ -190,10 +189,10 @@ skitterspec spec-sync verify <spec> --stored <file>
 
 It compares against what the engine sent, ignoring the reformatting Linear
 legitimately applies (renumbered ordered lists, `-`→`*`, collapsed table
-separators, checkbox case, whitespace) and reporting only lost or altered **word
-characters**. Relay any divergence — it prints both sides around the first
-difference. It exits 0 either way: the repo is unaffected and still correct, so
-this is a warning, not a failure.
+separators, checkbox case, whitespace) and reporting only lost or altered
+**word characters**. Relay any divergence — it prints both sides around the
+first difference. It exits 0 either way: the repo is unaffected and still
+correct, so this is a warning, not a failure.
 
 This is **not a pull**. Nothing read here is merged, stamped, or written
 anywhere; the repo remains the only source of truth. Do it before step 5 so a

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
 
@@ -44,22 +44,35 @@ trust the spec's own wording — verify:
 - **Backward compatibility.** Re-confirm the planned API/schema changes are still
   additive/safe given the current code (see the project's compatibility rules).
 
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Run
+`skitterspec gating check <spec>`. A spec it names has no recorded gating
+decision — or a bare `none` that records nothing — and that is
+**drift like any other**: the question was never asked, or its answer was lost. Grill for it in
+step 3 and write the header in step 4, exactly as you would a stale file path.
+
+**This check is advisory.** It reports; it never refuses, and nothing below is
+conditional on it. A spec written before the project adopted gating has no header
+and is not broken — turning this into a gate would accuse the very specs the
+feature was designed not to disturb.
+
 ## 3. Grill only where a decision is needed
 
 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
 
-- Rewrite stale **Decisions** / **Solution overview** and refresh the **Impact
-  map** in `00-overview.md`, and stale **tasks** in the phase files, so they
-  match the current code and the resolved questions. Add/remove tasks within a phase file; add a new phase by
-  creating a `0N-<slug>.md` file **and** a matching overview index row, or drop a
-  dead phase by removing both. Keep the index and files in sync; **preserve
-  completed `[x]` history**.
+- Rewrite stale **Decisions** / **Solution overview** and refresh the
+  **Impact map** in `00-overview.md`, and stale **tasks** in the phase files,
+  so they match the current code and the resolved questions. Add/remove tasks
+  within a phase file; add a new phase by creating a `0N-<slug>.md` file
+  **and** a matching overview index row, or drop a dead phase by removing both.
+  Keep the index and files in sync; **preserve completed `[x]` history**.
 - **A phase's status is the `⬜`/`🔄`/`✅` on its H1** — `# Phase 2 — <goal> 🔄`.
   It is mirrored in that file's `> **Status:**` line and in the matching
   `00-overview.md` phase-index row, but the **heading is the authoritative one**:
@@ -119,5 +132,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,226 @@
+---
+name: spec-start
+description: Put a spec in flight — provision its branch, move it to in-progress, refresh the tracker, then build phase 1. Commits the spec itself when that is all that is uncommitted, and refuses to touch anyone else'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.** What the
+gate demands depends on the mode, because the two modes hold work in different
+places — read `mode` from `specs/.core/env.config.json` (default `worktree`).
+
+**`worktree` mode — the tree must be clean, and that is all.** The spec is built
+in its own worktree, so another spec being in flight is not a conflict; it is the
+parallelism the mode exists for. The only requirement is that this checkout has
+no uncommitted work — *except* the spec you are starting, which `spec-env up`
+commits for you (see below). Nothing is switched here and nothing is parked.
+
+**`checkout` mode — the workbench must be free**: on the base branch (`main`, or
+the configured `baseBranch`) and clean, since the branch is built right here and
+this mode holds one spec at a time. If it isn't, relay what is in flight and
+stop — name the spec holding the checkout and the two 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.
+
+**Never get past the gate yourself.** Do not stash, do not commit
+**another spec's** work, do not switch branches for them. An uncommitted tree
+and a half-built phase 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.
+
+**The one exception is the spec you are starting.** `spec-env up` classifies the
+uncommitted tree against the target spec and answers one of three ways — relay
+what it says rather than deciding for yourself:
+
+| What it found | What it does |
+|---------------|--------------|
+| clean | provisions, as always |
+| every path belongs to this spec | plans `git add` + `git commit` **first**, then the fork |
+| any path does not | refuses, naming the paths that disqualified it |
+
+That is membership in an exactly-known set — the spec's own folder plus the
+project's `spec.companionPaths` — and **not** a judgement about whether the
+changes look important. The gate still never decides that. When it plans the
+commit, the paths are printed above the commands, so run them as printed; when it
+refuses, relay the reason and stop.
+
+It also refuses a **clean** tree whose spec is not in the commit the worktree
+would fork from — otherwise you get a branch missing the very spec it is for.
+
+## 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. Its worktree
+  probably still exists, so this is a re-attach: say so rather than reporting a
+  fresh start, and skip the housekeeping that is already done.
+
+## 3. Build its branch
+
+### `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, **except**
+   the `open.command` line, which belongs to the hand-off in 3 below.
+
+2. **Enter the worktree — this session, no new window.** The spec is built in its
+   worktree; that is what the mode is for, and it is why `main` stays free and
+   several specs run at once. So put *this* session there rather than opening
+   another one: call **`EnterWorktree`** with the worktree path.
+
+   **Do it immediately after `git worktree add`, before bootstrap and before the step 4 housekeeping.**
+   Once the session is the worktree, `setup` runs in place and the housekeeping
+   is plain `git` — the `cd` and the `git -C <worktreePath>` prefix both
+   disappear. **Never `cd` into the worktree first:** `EnterWorktree` refuses a
+   path that is already the working directory
+   (`is the current working directory`), so a bootstrap `cd` does not merely
+   make the call redundant, it makes it fail.
+
+   Then run the planner's **`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. Do the step 4 housekeeping, then say to run **`/spec-next`**, here.
+
+   **Do not move the branch into this checkout**, and do not ask the operator to.
+   Entering the worktree is the opposite of moving the branch out of it — the
+   branch never leaves. `/spec-live` is for testing a finished-enough spec on the
+   already-running dev server; it is not the way work gets started, and reaching
+   for it here is what used to split a start across two invocations.
+
+3. **When you cannot enter, hand off as before.** Two cases, and
+   **decide from cwd before calling**, not by calling and catching — an error
+   surfaced mid-skill reads as a bug, and both conditions are knowable in
+   advance:
+
+   - **This session's cwd is already inside a worktree.** `EnterWorktree` only
+     allows a worktree→worktree switch when the target lives under
+     `.claude/worktrees/`, and a project's worktree root usually does not
+     (`../{repo}-wt` is the shipped shape). Do not "fix" this by relocating the
+     root: starting a spec from the base branch is the documented path anyway.
+   - **`EnterWorktree` is unavailable** — a harness without it. There is no CLI
+     counterpart to fall back on, so the skill degrades rather than fails.
+
+   On either, do exactly what this skill did before: bootstrap with
+   `cd "<worktreePath>"`, housekeep with `git -C <worktreePath>`, run
+   `open.command` if one is configured, print the worktree path, and say to run
+   **`/spec-next`** from a session in it.
+   **Trust the worktree first** on this path: `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. (Entering the worktree makes both
+   moot: the writes are then in-cwd.)
+
+   `EnterWorktree` is gated on being told to work in a worktree by the user or by
+   project instructions. A lifecycle skill directing it **is** project
+   instruction, so the call is in contract here.
+
+**`/spec-next` is unchanged by this.** Its rule 2 — "the worktree you are
+standing in" — is what answers once the session has actually moved; nothing about
+its resolution is loosened, and it must not be. The refusal exists so the wrong
+branch is never built.
+
+### `checkout` mode
+
+Run `skitterspec spec-env up <name>` and the single `git switch` it prints.
+There is no worktree, no bootstrap and no hand-off — 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
+
+**Do this before you report anything**, so no path can end with a provisioned
+worktree and a spec still reading `Ready` in `specs/backlog/`. Having entered the
+worktree (step 3.2) this is plain `git` — you are standing in it. On the hand-off
+path (step 3.3) run it against the worktree with `git -C <worktreePath>` instead;
+in `checkout` mode the branch is already here.
+
+- `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.
+
+## 4b. Note a missing gating decision (only if configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Run
+`skitterspec gating check <name>` and, if it names this spec, mention it **once**
+before phase 1 starts — the cheapest moment to decide is before any code exists.
+
+**This check is advisory.** It reports; it never refuses, and nothing below is
+conditional on it. A spec written before the project adopted gating has no header
+and is not broken — turning this into a gate would accuse the very specs the
+feature was designed not to disturb.
+
+## 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
+
+**`checkout` mode — 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 branch is here and they
+asked to start the spec.
+
+**`worktree` mode — the spec is built in its worktree**, and step 3.2 put this
+session there, so end by saying the worktree path is now the session's and to run
+**`/spec-next`** here. On the hand-off path (step 3.3) the session did not move:
+say so plainly, print the path, and tell them to run `/spec-next` from a session
+in it.
+
+`/spec-next` resolves the spec it is *standing in* — the live spec of the
+checkout, the worktree its cwd is inside, or the branch in `checkout` mode — and
+a name argument narrows a re-run rather than selecting a spec elsewhere. That
+refusal is deliberate: building the wrong spec's phase writes commits on a branch
+nobody asked for. **Do not work around it**, and do not offer to build the phase
+from here.
+
+## 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
 ---
 
@@ -142,10 +142,10 @@ pnpm exec skitterspec-linear spec-sync released [<range>] [--json]
 ```
 
 `ref` prints the ticket for the branch you are on, so a commit can carry
-`Refs: <KEY-N>` — see `.claude/rules/commit-trailers.md`. **Off a spec branch, or
-on a spec that is not linked, it prints nothing and exits non-zero.** That is the
-correct answer, not an error to work around: do not invent a ref, and never write
-`Refs: none`.
+`Refs: <KEY-N>` — see `.claude/rules/commit-trailers.md`.
+**Off a spec branch, or on a spec that is not linked, it prints nothing and exits non-zero.**
+That is the correct answer, not an error to work around: do not invent a ref,
+and never write `Refs: none`.
 
 `released` reports the tickets in a commit range — by default since the most
 recent tag, and it always prints the range it chose so a wrong default is
@@ -170,9 +170,9 @@ the report saying which commits it set aside.
 pnpm exec skitterspec-linear spec-sync retarget [--yes]
 ```
 
-Renaming a Linear team rewrites the key in every issue identifier, and **nothing
-in the repo moves**: the frontmatter stamps, the config `teamKey`, and the
-snapshot filenames and their sub-issue keys all keep the old prefix, so
+Renaming a Linear team rewrites the key in every issue identifier, and
+**nothing in the repo moves**: the frontmatter stamps, the config `teamKey`,
+and the snapshot filenames and their sub-issue keys all keep the old prefix, so
 `/spec-push` starts failing with `no Linear issue found for SKI-7`.
 
 `retarget` detects the rename (the team id survives it; the key does not) and