@skitterbyte/skitterspec-linear 10.6.0 → 10.8.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 — `<spec>` takes it, a bare `take` takes the spec you are on, `main` hands the instance back
+argument-hint: "[<spec> | main | take | release | abort | status]"
+allowed-tools: Bash({{exec}} skitterspec spec-env live:*)
+disable-model-invocation: true
+---
+!`{{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,10 @@
   "snapshot": {
     "overviewFile": "00-overview.md"
   },
+  "release": {
+    "stages": [],
+    "ignorePaths": ["specs/"]
+  },
   "branch": {
     "pattern": "{type}/{slug}"
   },

package/assets/core/linear.config.md

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

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.
@@ -41,7 +55,8 @@ your canonical `localhost` ports so you can test it at the normal URL
 move, header edits, the code) happens on the spec's branch in the worktree; `main`
 changes only when it merges. Teardown is folded into `/spec-complete` ·
 `/spec-cancel`. Beneath the skills, `skitterspec spec-env
-<up|down|prune|dev|connect|integrate|hotfix>` is the CLI engine. Teardown drops
+<up|down|prune|dev|connect|integrate|hotfix|live|status|resolve>` is the CLI
+engine (omit the spec name and it uses the worktree you are standing in). Teardown drops
 the finished spec's own test-DB volume; `spec-env prune` additionally reaps
 **orphaned** volumes left by declined/aborted teardowns, so `/spec-complete` and
 `/spec-cancel` also sweep orphans (confirm-first). A **hotfix** is the one
@@ -50,7 +65,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
@@ -298,6 +312,38 @@ and **never auto-push git** — Linear's own automation reacts to real branch/PR
 events later. Report the Linear issue URL as part of the skill's finish-up
 message.
 
+### Picking the Linear Project
+
+Run this **only when minting a spec issue** — creating it for the first time. On
+an update the issue already has a project (or deliberately has none), and that
+placement is **Linear's to own**: never send `project` on an update, and never
+record the choice in the spec file or the snapshot. A PM re-homing a spec issue
+must not show up as drift or be overwritten on the next push.
+
+1. **List the candidates.** Ask the engine:
+   `skitterspec spec-sync projects --json`. On the API path it returns the team's
+   projects; on the MCP path it says so, and you call the discovered project-list
+   tool instead. Drop archived / completed projects — they can't take new work.
+2. **Offer them.** Show the names (most recently updated first is fine), plus an
+   explicit **None (team only)** option. Pre-select `linear.projectId` from
+   `linear.config.json` when it's set and still in the list; otherwise pre-select
+   **None**.
+3. **Narrow on request.** If the user types a fragment rather than choosing, filter
+   the list case-insensitively by name and re-offer. Don't re-fetch.
+4. **Never offer to create a project.** Projects are the PM's surface — if none
+   fits, that's **None (team only)**, and someone makes the project in Linear.
+5. **Pass it once**, to whichever thing mints the issue: `--project <chosen id>`
+   on `spec-sync apply`, or `project: <chosen id>` on the MCP issue-create call.
+   Chose None → omit it entirely (do not pass an empty string).
+
+**Degrade, never block.** If the list can't be fetched — Linear not connected, no
+project-list tool, no API key, or `spec-sync projects` reporting it couldn't ask —
+say so in one line — *"project picker unavailable"* — and carry on with
+`linear.projectId` if it's set, else no project at all. A missing picker must never fail the skill that called it.
+
+If `linear.projectId` is set but that Project is archived or missing, relay
+Linear's error and stop rather than silently minting an unparented issue.
+
 ## 5. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix. Match surrounding code; honour all

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