@skitterbyte/skitterspec-linear 10.5.2 → 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

@@ -0,0 +1,84 @@
+# Commit Trailers
+
+Extends `commit-messages.md` — the format, length limits and `Release-Note:`
+grammar there all still apply. This file adds one trailer, and it is only
+installed when a ticketing provider is.
+
+## `Refs:` — the ticket this commit belongs to
+
+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
+
+- Key the apply read-back by ref, resolving id via the projection
+
+Release-Note: Pushing a spec whose phases already exist in Linear no
+longer reports every one of them as a possible stale reference.
+
+Refs: SKS-29
+```
+
+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. 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.
+  `Refs:` is deliberately inert to Linear's automation.
+- **Blank line before it**, like `Release-Note:` — it is a git trailer, not body
+  text.
+- Put it **after** `Release-Note:` when both are present, so the human-facing
+  note reads first.
+
+## Why it exists
+
+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. 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
@@ -311,6 +325,30 @@ test, split the fix into phase files (`01-<slug>.md` …) with a phase index in
 `00-overview.md`, and leave the spec in `in-progress` for `/spec-go` to continue.
 Say so explicitly — don't fake green.
 
+**Then refresh the mirror (only if a provider is installed).** The Fix tasks are
+ticked, so the repo is now the truth about this fix — and this skill can take a
+bug all the way to green without `/spec-go` ever running. Without a provider this
+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.
+
 ## 6. Report
 
 Summarise: root cause, the failing→passing test, the fix, and the full test

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