@skitterbyte/skitterspec-linear 10.6.0 → 10.7.0

package/assets/claude-md-section.md

@@ -1,9 +1,9 @@
 ## Spec workflow
 
-Spec-driven development runs through seven lifecycle skills (plus `/spec-connect`
-when isolation is on) — use them so structure and lifecycle stay consistent (see
-`.claude/rules/spec-planning.md`). The everyday loop is
-**`spec → go → connect → commit → complete`**:
+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 |
 |-------|--------|--------|--------|
@@ -13,8 +13,15 @@ when isolation is on) — use them so structure and lifecycle stay consistent (s
 | `/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
@@ -32,12 +39,15 @@ State log.
 (`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. **`/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). Docker is a
+**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
-<up|down|dev|connect|integrate>` is the CLI engine. Independent of lifecycle
+**`/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.

package/assets/commands/spec-connect.md

@@ -0,0 +1,13 @@
+---
+description: Expose one spec's dev servers on the canonical localhost ports (or `main` to hand them back)
+argument-hint: "[spec|main]"
+allowed-tools: Bash({{exec}} skitterspec spec-env connect:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env connect $ARGUMENTS`
+
+Relay the engine output above verbatim. Add nothing and run nothing else.
+
+Only if it reports a **canonical port is in use**: say that the main checkout's
+dev server still holds that port, and that stopping it and re-running is the fix
+(the proxy cannot share a port main is bound to).

package/assets/commands/spec-live.md

@@ -0,0 +1,14 @@
+---
+description: Put one spec live on the already-running dev server (take | release | abort | status)
+argument-hint: "[take <spec> | release | abort | status]"
+allowed-tools: Bash({{exec}} skitterspec spec-env live:*)
+disable-model-invocation: true
+---
+!`{{exec}} skitterspec spec-env live $ARGUMENTS`
+
+Relay the engine output above verbatim. Add nothing and run nothing else.
+
+The engine enforces every refusal itself and prints why — a hotfix, a stateful
+spec (`Stack: worktree + docker`), a branch touching migrations, a dirty tree, a
+rebase conflict, or another spec already holding the instance. Do not re-explain
+or work around any of them.

package/assets/core/ci-stages.md

@@ -0,0 +1,110 @@
+# Wiring a deploy pipeline to Linear
+
+How a CI/CD pipeline moves a release's tickets along the ladder declared in
+`linear.config.json` → `release.stages`. Read `linear.config.md` → "The
+deployment ladder" first for the config itself; this page is the pipeline half.
+
+Nothing here applies until a ladder is declared. Without one, `spec-sync stage`
+refuses and every other command behaves as it always has.
+
+## The model
+
+A spec's lifecycle ends at `complete`. Everything after that is a fact about an
+**environment**, which no folder under `specs/` can derive — so the repo hands
+off. The handoff point is one-way and automatic:
+
+```
+/spec-complete          →  states.complete      (the repo's last word on state)
+CI: spec-sync stage test →  release.stages test  (the pipeline's, from here on)
+CI: spec-sync stage prod →  release.stages prod
+```
+
+Once a spec is complete, pushes stop re-asserting its workflow state, so the
+pipeline is the only writer. Editing a finished spec's prose still updates the
+mirror's description; it will not drag the ticket back out of the pipeline.
+
+## What a stage step runs
+
+```sh
+skitterspec spec-sync stage <key> <previous-tag>..<this-tag> --apply
+```
+
+- **Pass the range explicitly.** With no range it defaults to
+  `git describe --tags --abbrev=0`..HEAD, which is a developer convenience — a
+  pipeline knows exactly which tag it is deploying, and should say so. The
+  resolved range is printed on every run either way.
+- **Drop `--apply` to dry-run.** Same output, no writes. Worth running in a
+  pre-deploy job.
+- **`--json`** for a machine-readable result: the moves, the skips by category,
+  and the commit counts.
+- **Exit code is 0 unless a write failed**, so a failed move fails the stage.
+  A range with nothing to move is a success, not a failure.
+
+The tickets come from `Refs:` trailers on the commits in the range (see the
+`commit-trailers` rule). A commit with no trailer is counted and reported, never
+guessed at.
+
+## Setup
+
+1. **A ladder in `linear.config.json`** — via `/spec-linear-setup`, or
+   `spec-sync init-config --stage test="On Test" --stage prod="Done"`.
+2. **An API key as a pipeline secret**, exposed as the env var named by
+   `auth.keyEnv` (default `LINEAR_API_KEY`). The config names the *variable*,
+   never the key. `--apply` needs the API transport and refuses over MCP.
+3. **Full history for the range** (CI: `fetch-depth: 0`). Fetching tags is not
+   enough on its own: it makes the tag *resolve* without deepening the history,
+   so `git log <tag>..HEAD` would return only the commits the clone happens to
+   hold. `stage` and `released` check this and **refuse** rather than report a
+   partial range, so a shallow checkout fails the step loudly instead of
+   deploying a release that quietly leaves tickets behind.
+4. **Run `spec-sync doctor --check-remote` once** after setup. It reports the
+   ladder's rungs against the workspace and warns if the last rung never closes
+   an issue.
+
+### Azure Pipelines
+
+```yaml
+- task: Bash@3
+  displayName: Mark tickets as deployed to test
+  env:
+    LINEAR_API_KEY: $(LinearApiKey)   # a secret variable, not inline
+  inputs:
+    targetType: inline
+    script: |
+      set -euo pipefail
+      npx skitterspec spec-sync stage test "$(PreviousTag)..$(Build.SourceBranchName)" --apply
+```
+
+Repeat per environment with a different `<key>`: a post-deploy step on the test
+stage runs `stage test`, the demo approval gate runs `stage demo`, the production
+deploy runs `stage prod`.
+
+## Why not call the API directly
+
+A hand-rolled `curl` to Linear's GraphQL endpoint loses three things this command
+has, and the loss is silent in all three cases:
+
+- **State-name validation.** Linear **silently ignores** an unknown workflow
+  state: the mutation succeeds, and the issue never moves. `stage` resolves the
+  target state before its first write and refuses if the workspace lacks it.
+- **The skip rules.** A range carries refs that must not be moved — another
+  team's, ones no spec claims, and specs that have not finished. A blanket loop
+  over every ref in the log moves all of them.
+- **Retries and error classification.** The adapter retries transient failures;
+  a bare `curl` reports a 500 as success if you forget to check.
+
+## What it will not move, and why
+
+Every skipped ref is named in the output with its reason — a silent exclusion and
+a successful move look identical in a pipeline log.
+
+| Skipped | Reason |
+|---|---|
+| another team's ref | not `linear.teamKey`; writing to an unconfigured team is the worst failure available here |
+| no spec claims it | tracker-only work, or a typo in a trailer — nothing here can tell which |
+| spec not complete | it landed via `/spec-to-main`; push still owns its state and would bounce it back |
+| unreadable | Linear did not return the issue; dropped rather than guessed at |
+
+A move that runs against the declared order — backwards, or skipping a rung —
+**warns and proceeds**. A rollback from test and a hotfix going straight to prod
+are both legitimate, and refusing either would be wrong on healthy input.

package/assets/core/env.config.md

@@ -148,6 +148,24 @@ no live `env.config.json` was found.
     "refuseTeardownIfUnpushed": true
   },
 
+  // What teardown cleans up beyond this machine. `/spec-go` 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
+  //             "confirm with the user first" section; /spec-complete and
+  //             /spec-cancel ask before running it.
+  //   "never"   — omit it; clean the remote up yourself.
+  //   "always"  — fold it into `run these:` and never ask.
+  // Only ever planned for a branch that has LANDED (merged into base, or captured
+  // by a hotfix's deploy tag) and whose remote-tracking ref this clone can
+  // actually see. Until a branch lands, the remote copy is its only backup, so
+  // --force does NOT enable this. A branch pushed from another machine has no
+  // local ref here and is simply missed — teardown under-cleans rather than
+  // deleting something it cannot see. An unrecognised value means "prompt".
+  "teardown": {
+    "deleteRemoteBranch": "prompt"
+  },
+
   // Live overlay (`spec-env live` / `/spec-live`): test a spec on the already-
   // running dev server by checking its branch out in the primary checkout.
   // `migrations` is a list of globs (`**`, `*`, `?`) marking migration files; a

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

@@ -23,6 +23,9 @@
   "snapshot": {
     "overviewFile": "00-overview.md"
   },
+  "release": {
+    "stages": []
+  },
   "branch": {
     "pattern": "{type}/{slug}"
   },

package/assets/core/linear.config.md

@@ -85,6 +85,13 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
     "overviewFile": "00-overview.md"
   },
 
+  // 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.
+  "release": {
+    "stages": []
+  },
+
   // Git branch name derived for a linked spec. Tokens: {type}, {slug},
   // {identifier} (the Linear issue/project identifier, e.g. ENG-123). Shared
   // with the isolation engine's branch derivation (src/env/resolve.js).
@@ -122,6 +129,45 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
 }
 ```
 
+## The deployment ladder (`release.stages`)
+
+A spec's lifecycle stops at `complete`. Where a ticket goes **after** that —
+deployed to test, approved for demo, live in prod — is a fact about an
+**environment**, and nothing under `specs/` can derive it. `release.stages` is
+where a project declares that ladder in its own vocabulary:
+
+```jsonc
+"release": {
+  "stages": [
+    { "key": "test", "state": "On Test" },
+    { "key": "demo", "state": "Ready for Demo" },
+    { "key": "prod", "state": "Done" }
+  ]
+}
+```
+
+- **`key`** is what CI names (`spec-sync stage test …`); **`state`** is the
+  Linear issue state it moves to. Pipelines reference the *key*, never the state
+  name, so renaming a Linear column is one edit here rather than a hunt through
+  pipeline YAML.
+- **Every `state` is checked against the workspace** alongside `states`, at push
+  and setup time. Linear **silently ignores** an unknown issue state, so an
+  unchecked typo would deploy cleanly and move nothing, forever.
+- **Order is recorded, not enforced.** It drives reporting and the doctor check;
+  a rollback from test, or a hotfix going straight to prod, is legitimate and is
+  never refused.
+- **Keys must be unique**, and a malformed entry is a hard error at load — the
+  same treatment `sync.fieldOwnership` and `mapping.phases` get.
+- **Absent or empty = the opt-out.** Nothing about the ladder affects a project
+  that has not declared one.
+
+Unlike `states` and `mapping.phases`, this is **not** keyed by lifecycle bucket:
+the buckets are a closed set the repo derives, and a deployment stage never is.
+
+Run `skitterspec spec-sync states` to see the whole configured vocabulary — the
+bucket map and the ladder — against what the workspace actually has.
+
+
 ## Spec → Issue, phases → sub-issues
 
 Push maps the spec's structure to Linear's, keyed by id so it updates rather than

package/assets/rules/commit-trailers.md

@@ -6,8 +6,8 @@ installed when a ticketing provider is.
 
 ## `Refs:` — the ticket this commit belongs to
 
-A commit made on a spec's branch carries the Linear issue it belongs to, as the
-**last** trailer in the message:
+A commit carries the Linear issue **its own changes** belong to, as the **last**
+trailer in the message:
 
 ```
 fix(sync): verify no longer flags every update
@@ -26,15 +26,44 @@ Get the value from the engine rather than reading it off a spec by hand:
 pnpm exec skitterspec-linear spec-sync ref
 ```
 
+Bare, that answers **from the branch** — correct whenever you are committing
+that branch's own implementation work, which is nearly always.
+
+## When the branch and the commit disagree
+
+The branch is a proxy for "what this commit is about", and it is a good one
+right up until you commit something that is not this branch's work. The usual
+way in: part-way through a spec, a design question warrants its own spec, so
+`/spec` writes a new one into `specs/backlog/` and links it. That commit is
+**entirely the new spec's**, but you are standing on the old spec's branch, and
+the bare command answers with the old spec's ticket.
+
+Name the spec instead — still the engine, never a hand-written id:
+
+```
+pnpm exec skitterspec-linear spec-sync ref feat-distance-prescriptions
+```
+
+The branch is not consulted, so this works from `main` too. An unknown spec name
+fails rather than falling back to the branch, so a typo can't become a
+confidently wrong ref.
+
+**Better still, avoid the split:** author backlog specs from the base branch.
+A spec written inside another spec's worktree physically lives on that branch —
+it is not on `main` until that spec lands, and it is cancelled along with it.
+
 ## Rules
 
+- **The ref names the commit's subject, not your location.** If they disagree,
+  the commit's subject wins — resolve it with `spec-sync ref <spec>`.
 - **Omit the trailer entirely when there is no ref.** `spec-sync ref` exits
   non-zero and prints nothing on a commit that has no ticket — on `main`, or on
   a spec kept deliberately local. Never invent one, and never write
   `Refs: none`: the release report counts unreferenced commits, and a fabricated
   ref is worse than an honest gap.
-- **One ref per commit.** A commit belongs to one spec — the spec whose branch
-  it is on. If work genuinely spans two tickets, that is two commits.
+- **One ref per commit.** A commit belongs to one spec. If work genuinely spans
+  two tickets, that is two commits — and that is the fix when a single commit
+  would mix a branch's own work with another spec's files.
 - **Never use Linear's magic words** — `Fixes`, `Closes`, `Resolves`. Those
   close the issue the moment the commit reaches the default branch, which is
   wrong here: a ticket moves when its work is **released**, not when it merges.
@@ -49,4 +78,7 @@ pnpm exec skitterspec-linear spec-sync ref
 The repo lands specs with `merge --ff-only`, so history is linear and branch
 names never reach it. The commit message is the only artefact that survives into
 the range a release scans, which is what lets
-`spec-sync released <range>` report the tickets a release contains.
+`spec-sync released <range>` report the tickets a release contains. A ref that
+names the wrong ticket does not merely lose information — it moves a commit onto
+another ticket's release report, which is worse than the gap it was meant to
+close.

package/assets/rules/spec-planning.md

@@ -1,7 +1,7 @@
 # Spec Planning
 
-Spec-driven development is driven by nine lifecycle skills (plus `/spec-connect`
-when isolation is on) — use them rather than hand-rolling specs so the structure
+Spec-driven development is driven by nine lifecycle skills (plus the
+`/spec-connect` and `/spec-live` **commands** when isolation is on) — use them rather than hand-rolling specs so the structure
 and lifecycle stay consistent. Each sets a status on the spec header
 (`> **Status:** …`):
 
@@ -17,6 +17,20 @@ and lifecycle stay consistent. Each sets a status on the spec header
 | `/spec-cancel` | Record progress, stamp a reason on the header; tear down | `Cancelled` | `specs/cancelled/` |
 | `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
 
+**Skills vs commands.** The table above lists **skills** — Claude reads them and
+exercises judgment. `/spec-connect` and `/spec-live` are instead **slash commands**
+(`.claude/commands/`): each pre-executes one `skitterspec spec-env` verb and
+relays its output, so there is no judgment to apply and no model turn spent
+finding one. They are marked `disable-model-invocation`, meaning **only you can
+run them** — a skill that wants one will tell you to type it rather than invoking
+it.
+
+`/spec-to-main`, `/spec-status` and `/spec-sync` stay **skills** — each carries
+real judgment (green tests before a land; an MCP fetch and a team-key check; ten
+subcommands) — but they are marked user-only too, since nobody reaches them
+except by typing them. Everything else in the table above stays model-invocable,
+which is what lets `/spec-go` hand off to `/spec-push` as work progresses.
+
 Status flow: `Ready → In Progress → Complete` (or `Cancelled` from any state).
 `/spec` grills to a **Ready** spec directly — there is no separate grooming
 command; it writes `Draft` only when open questions are deliberately left.
@@ -50,7 +64,7 @@ tag and `/spec-complete` lands it via `spec-env hotfix land` (tag + cherry-pick)
 not a fast-forward. Isolation is **orthogonal to lifecycle status** and inactive
 when `env.config.json` is absent — every skill then behaves as it does today.
 
-**Live overlay (`/spec-live`) — the light way to test a spec.** `/spec-connect`
+**Live overlay (`/spec-live`, a command) — the light way to test a spec.** `/spec-connect`
 runs a spec's *own* dev stack and proxies the canonical ports to it (one stack per
 spec). **Live overlay** instead reuses the one dev server you already have running:
 `/spec-live <spec>` rebases the branch onto base, frees it from its worktree, and

package/assets/skills/spec/SKILL.md

@@ -143,6 +143,26 @@ Briefly play back the agreed understanding before writing.
 
 This skill is for **features**. For bugs, use `/spec-bug` (test-first, red→green).
 
+### Write it from the base branch
+
+**Check where you are before creating the folder.** A backlog spec belongs on
+the base branch (`main`). If you are on another spec's branch — most likely
+inside its worktree, because a design question came up part-way through
+implementing it — say so before writing, and offer to author the spec from the
+primary checkout instead.
+
+It matters for more than tidiness: a spec written inside another spec's worktree
+**physically lives on that branch**. It is not on `main` until that spec lands,
+it is invisible to anyone listing `specs/backlog/` meanwhile, and if that spec is
+cancelled the new spec is cancelled with it. Committing it there also mis-stamps
+the commit's ticket trailer, since that is resolved from the branch (see
+`.claude/rules/commit-trailers.md`, installed with a ticketing provider).
+
+**Warn, don't refuse** — doing this deliberately is legitimate, and the user may
+have a reason. If they continue, carry on exactly as normal, and mention that
+the trailer for that commit wants `spec-sync ref <new-spec-name>` rather than the
+bare form.
+
 - **Every spec is a folder** — never a bare file, even for a one-line change:
   `specs/backlog/feat-<kebab-name>/`. Create it with `mkdir -p`.
 - The entry point is **always `00-overview.md`** — the index/dashboard for the

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

@@ -143,8 +143,22 @@ provision from — you'll flesh it out in §4:
   the worktree path, the opener, and any `in the worktree, run:` bootstrap steps.
 - Run the printed `git worktree add`. **The worktree forks from `main`'s last
   commit, so your uncommitted stub doesn't travel with it** — move it across so
-  `main` is left pristine:
-  `mv specs/in-progress/bug-<name> <worktreePath>/specs/in-progress/`.
+  `main` is left pristine. **Create the destination bucket first:**
+
+  ```
+  mkdir -p <worktreePath>/specs/in-progress
+  mv specs/in-progress/bug-<name> <worktreePath>/specs/in-progress/
+  ```
+
+  The `mkdir -p` is not belt-and-braces. Git does not store empty directories,
+  so `specs/in-progress/` is **absent** from a fresh worktree whenever that
+  bucket happens to be empty on `main` — the common case, since it empties every
+  time the last in-progress spec completes. `mv` into a missing destination
+  renames your spec folder **to** `specs/in-progress`, silently: the spec's files
+  end up one level too high, `00-overview.md` sits where the bucket should be,
+  and every later step still appears to work until something cannot find the
+  spec. Confirm the result before carrying on — you want
+  `<worktreePath>/specs/in-progress/bug-<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

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

@@ -113,6 +113,15 @@ directly (the old `/spec-env-down` skill is gone — teardown is folded in here)
 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`).
+
+   If the plan prints a `remote branch — confirm with the user first:` section,
+   **ask before running that line** — it is a `git push <remote> --delete`, and
+   the branch is merged, so it loses nothing. Usually there is nothing to ask:
+   a cancelled spec is normally **unlanded**, and the planner deliberately never
+   offers the remote delete then, because the pushed branch is the only surviving
+   copy of abandoned work. Seeing no such section here is the expected case, not
+   a fault — and if the user wants the remote branch gone anyway, that is their
+   call to make explicitly, not something to tidy away on their behalf.
 4. `skitterspec spec-env prune` — reap orphaned test-DB volumes that belong to no
    live spec (leftovers from declined/aborted teardowns or manual worktree
    removal). Show the orphan list and, **only on the user's confirmation**, run

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

@@ -152,7 +152,7 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
    back to base, re-isolates it into its worktree, clears the receipt), then prints
    the normal landing plan. Commit any live fixes to the branch first; it refuses
    if the primary checkout is dirty, or if a *different* spec holds it (release that
-   one with `/spec-live main`). Teardown (step 7) is unchanged.
+   one by typing `/spec-live main`). Teardown (step 7) is unchanged.
    **Work-loss abort.** Before it ends the live session, `integrate` checks the
    work is actually landable and **aborts loudly** rather than finalize a spec
    having landed nothing. Two cases, both leaving the live session intact:
@@ -208,6 +208,17 @@ worktree and branch are being kept, and go straight to sub-step 4. Mention
    still respects the guards (won't destroy a dirty, or unpushed-and-unlanded,
    worktree without `--force`), so if it *does* refuse, relay that and stop
    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
+   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
+   deploy tag), so deleting the remote branch loses nothing. On a yes, run the
+   printed `git push <remote> --delete <branch>`; on a no, leave it and say the
+   remote branch is still there. Never fold it into the `run these:` batch — a
+   project that wants it unattended sets `teardown.deleteRemoteBranch: "always"`
+   in `env.config.json`, and then it appears in `run these:` instead of here.
 4. **Reap orphaned test-DB volumes:** run `skitterspec spec-env prune`. It lists
    Docker volumes in the repo namespace that belong to **no live spec** (no
    worktree) — leftovers from declined/aborted teardowns, manual

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

@@ -7,7 +7,8 @@ description: Promote a spec into active development and build the next phase —
 
 The "up" button: it promotes the spec, provisions its worktree, brings its host
 dev servers up on the spec's reserved ports (with your OK), then builds the phase.
-Diverting your browser to the spec is a separate explicit step — `/spec-connect`.
+Diverting your browser to the spec is a separate explicit step the **user**
+types — `/spec-connect` (a slash command, not a skill you can invoke).
 
 ## 1. Identify the target spec
 
@@ -33,8 +34,8 @@ branch. Instead skip the provisioning bullets and step 2b, leave the spec where
 it is, and go straight to **step 4**, implementing the phase **in the primary
 checkout on the branch** — edits and commits there advance the branch, and
 `/spec-complete` lands them. (`spec-env up` refuses while live and says the same.
-To return to an isolated worktree instead, run `/spec-live main` first, then
-re-run `/spec-go`.)
+To return to an isolated worktree instead, ask the user to type `/spec-live main`
+first, then re-run `/spec-go`.)
 
 **If per-spec isolation is enabled** (`specs/.core/env.config.json` exists), the
 spec **isn't already live** (the check above), and it doesn't already have a
@@ -121,11 +122,12 @@ runnable — its UI/API on the spec's reserved port block, isolated from `main`.
   dev process detached on its port, logs to `.spec-env/logs/`, and waits on each
   `health` check. With no `dev` configured it's a clean no-op; skip this step.
 - **Diverting your browser is a separate step.** To test the spec at your normal
-  `localhost` URL, run **`/spec-connect <name>`** (exclusive — it exposes this
-  spec on the canonical ports; `/spec-connect main` hands them back). `/spec-go`
-  never seizes the canonical ports on its own. For a **code-only** spec, the
-  lighter **`/spec-live <name>`** reuses your already-running dev server (a
-  branch-switch, no second stack) — `/spec-live main` hands it back.
+  `localhost` URL, the **user** types **`/spec-connect <name>`** (exclusive — it
+  exposes this spec on the canonical ports; `/spec-connect main` hands them back).
+  `/spec-go` never seizes the canonical ports on its own. For a **code-only** spec,
+  the lighter **`/spec-live <name>`** reuses the already-running dev server (a
+  branch-switch, no second stack) — `/spec-live main` hands it back. Both are
+  user-only slash commands: tell the user to run one, never try to invoke it.
 
 ## 3. Pre-flight — commit prior work
 

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

@@ -155,8 +155,22 @@ that header — must exist **before** `spec-env up`:
   bootstrap steps.
 - Run the printed `git worktree add`. **The worktree is checked out at the tag,
   so your uncommitted stub doesn't travel with it** — move it across so `main`
-  stays pristine:
-  `mv specs/in-progress/hotfix-<name> <worktreePath>/specs/in-progress/`.
+  stays pristine. **Create the destination bucket first:**
+
+  ```
+  mkdir -p <worktreePath>/specs/in-progress
+  mv specs/in-progress/hotfix-<name> <worktreePath>/specs/in-progress/
+  ```
+
+  The `mkdir -p` is not belt-and-braces. Git does not store empty directories, so
+  `specs/in-progress/` is **absent** from the worktree whenever nothing was in
+  progress at that point in history — and here that point is an **old release
+  tag**, where it is absent more often than not. `mv` into a missing destination
+  renames your spec folder **to** `specs/in-progress`, silently: the spec's files
+  end up one level too high, `00-overview.md` sits where the bucket should be, and
+  every later step still appears to work until something cannot find the spec.
+  Confirm the result before carrying on — you want
+  `<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
@@ -349,7 +363,7 @@ full test result. The spec stays in `in-progress`.
 
 - **`/spec-live` is refused for a hotfix** — its branch is built on an old tag, so
   hot-reloading it onto the running dev server could break the shared instance.
-  To test it, use `/spec-connect` (its own isolated stack).
+  To test it, the user runs `/spec-connect` (its own isolated stack).
 - Suggest **`/spec-complete`** to land it: it patch-bumps the base tag, tags the
   hotfix branch **locally** (you push it to deploy), and cherry-picks the fix onto
   `main`. Add `--also <tag>` at completion to also patch other release lines

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

@@ -142,7 +142,38 @@ never apply one they didn't agree to), and re-run with the `--state` flags. If i
 made no suggestion for a bucket, **ask** which state means "finished" here rather
 than guessing.
 
-## 7. Write it
+## 7. Does this repo deploy through stages? (optional)
+
+A spec's lifecycle ends at `complete`. Where a ticket goes **after** that —
+deployed to test, approved for demo, live in production — is a fact about an
+environment, and nothing in the repo can derive it. If the team runs a deploy
+pipeline, it can declare that ladder here and CI moves tickets along it with
+`spec-sync stage`.
+
+**Ask, do not assume.** Most projects have no ladder, and an invented one is
+worse than none: `spec-sync stage` refuses cleanly when none is declared, whereas
+a wrong ladder is a pipeline quietly moving tickets to the wrong column. If the
+user does not raise deployment, offer it once in a line and take "no" for an
+answer.
+
+If they do want one, ask for the stages **in deployment order**, and map each to
+a state from the `list_issue_statuses` names you already have:
+
+```
+--stage test="On Test" --stage demo="Ready for Demo" --stage prod="Done"
+```
+
+- The **key** (`test`) is what a pipeline names; the **state** is the Linear
+  column. Pipelines reference the key, so renaming the column later is one edit
+  here.
+- Order is recorded, not enforced — a rollback and a hotfix straight to prod are
+  both legitimate and are never refused.
+- **Ask what closes an issue.** If the last rung is not a completed-type state,
+  tickets that finish the ladder never reach Done. That is fine when Linear
+  automation closes them and a problem otherwise — `spec-sync doctor` warns about
+  it either way, so say which it is.
+
+## 8. Write it
 
 ```
 skitterspec spec-sync init-config \
@@ -157,12 +188,17 @@ shows this repo's choices and keeps inheriting everything else. `--force` is
 required to replace an existing config — never pass it without the user having
 asked for a rewrite in step 1.
 
+Every `--stage` state is checked against the workspace exactly like a bucket
+state, and a bad one is refused the same way — as `release.stages[test]` rather
+than `states.complete`. There is no suggestion for a rung: the vocabulary is the
+project's own, so ask rather than guess.
+
 **Relay the engine's report as printed.** It names the team, the project (or
 "team only"), the intake labels, and how many state names were checked against
 the workspace — that report is the evidence the setup is right, so don't
 paraphrase it into "done".
 
-## 8. Report and hand off
+## 9. Report and hand off
 
 **Finish by checking, not by describing.** First write down what the MCP server
 says, from the reads you already made in step 2 — no extra round trip unless a

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

@@ -1,6 +1,7 @@
 ---
 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".
+disable-model-invocation: true
 ---
 
 # /spec-status — one-way sync drift report