@skitterbyte/skitterspec-linear 10.6.0 → 10.8.0

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
@@ -309,6 +323,38 @@ and **never auto-push git** — Linear's own automation reacts to real branch/PR
 events later. Report the Linear issue URL as part of the skill's finish-up
 message.
 
+### Picking the Linear Project
+
+Run this **only when minting a spec issue** — creating it for the first time. On
+an update the issue already has a project (or deliberately has none), and that
+placement is **Linear's to own**: never send `project` on an update, and never
+record the choice in the spec file or the snapshot. A PM re-homing a spec issue
+must not show up as drift or be overwritten on the next push.
+
+1. **List the candidates.** Ask the engine:
+   `skitterspec spec-sync projects --json`. On the API path it returns the team's
+   projects; on the MCP path it says so, and you call the discovered project-list
+   tool instead. Drop archived / completed projects — they can't take new work.
+2. **Offer them.** Show the names (most recently updated first is fine), plus an
+   explicit **None (team only)** option. Pre-select `linear.projectId` from
+   `linear.config.json` when it's set and still in the list; otherwise pre-select
+   **None**.
+3. **Narrow on request.** If the user types a fragment rather than choosing, filter
+   the list case-insensitively by name and re-offer. Don't re-fetch.
+4. **Never offer to create a project.** Projects are the PM's surface — if none
+   fits, that's **None (team only)**, and someone makes the project in Linear.
+5. **Pass it once**, to whichever thing mints the issue: `--project <chosen id>`
+   on `spec-sync apply`, or `project: <chosen id>` on the MCP issue-create call.
+   Chose None → omit it entirely (do not pass an empty string).
+
+**Degrade, never block.** If the list can't be fetched — Linear not connected, no
+project-list tool, no API key, or `spec-sync projects` reporting it couldn't ask —
+say so in one line — *"project picker unavailable"* — and carry on with
+`linear.projectId` if it's set, else no project at all. A missing picker must never fail the skill that called it.
+
+If `linear.projectId` is set but that Project is archived or missing, relay
+Linear's error and stop rather than silently minting an unparented issue.
+
 ## 6. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix on the branch. Match surrounding code;
@@ -349,7 +395,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

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

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

package/assets/skills/spec-to-main/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: spec-to-main
 description: Land an in-progress spec's branch onto main WITHOUT finishing it — rebase + fast-forward so the work reaches main (to run it in CI / a shared test env), while the worktree stays and the spec stays In Progress. Repeatable — land again as you commit more. Targets a spec by name (arg) or the spec in context. Use when the user says "/spec-to-main", "land this on main but keep going", "I need this on main to run tests before finishing", or "merge to main without completing the spec".
+disable-model-invocation: true
 ---
 
 # /spec-to-main — land the branch on main, keep the spec open
@@ -51,7 +52,7 @@ uncommitted changes, offer `/commit` and **stop**; don't auto-commit.
 back to base, re-isolates it into its worktree, clears the receipt), then prints
 the 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`).
+`/spec-live main`, which the user types).
 
 ## 3. Tests must be green before landing
 

package/bin/skitterspec-linear.js

@@ -41,6 +41,16 @@ const {
 async function main(argv) {
   const [cmd, ...rest] = argv
 
+// The check above asks whether src/ exists, which is inert in a workspace source
+// package — src/ is committed there. That is exactly where the other half of the
+// problem lives: a source package HAS a runnable bin and src, but its assets/ is
+// PRE-composition (seam markers still literal). Installing from it writes those
+// markers into the user's skills. So ask a second, positive question before any
+// install command runs.
+  if (cmd === 'init' || cmd === 'update') {
+    require('../src/init.js').assertComposedAssets()
+  }
+
   // Base help + what this distribution adds. Matched on the COMMAND SLOT only,
   // never the whole argv: `spec-sanitise --help` must reach that command's own
   // help, not be swallowed by the top-level one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "10.6.0",
+  "version": "10.8.0",
   "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
   "keywords": [
     "claude",

package/src/cli.js

@@ -185,23 +185,48 @@ async function cleanupReleaseTooling(dir, opts) {
 
 // --- spec-env: per-spec isolation engine (Phase 1: status + resolve) --------
 
-// Print provisioned specs, their slots, and port blocks from the registry.
+/**
+ * Print what is provisioned: every spec that owns a git worktree, with its slot
+ * and port block when it has one.
+ *
+ * The worktree — not the slot registry — is what "provisioned" means. `specEnvUp`
+ * allocates a slot only when `wantsDocker`, so a `Stack: worktree` spec never
+ * enters the registry and a project with `docker.enabled: false` has an
+ * permanently empty one. Reading the registry alone reported `no provisioned
+ * specs` while worktrees were standing.
+ *
+ * The registry is still read, but only to ANNOTATE a spec that has a slot — it
+ * is the authority on port blocks and nothing else.
+ *
+ * BLIND SPOT: a worktree removed behind git's back (`rm -rf` without
+ * `git worktree prune`) stays listed until pruned. That over-reports, which is
+ * the harmless direction for a read-only report.
+ */
 function specEnvStatus(dir, config) {
-  const registry = readRegistry(dir, config)
-  const names = Object.keys(registry.slots)
-  if (!names.length) {
+  const worktreePaths = liveWorktreePaths(dir)
+  const provisioned = allSpecs(dir, config, worktreePaths)
+    .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath) }))
+    // The primary checkout is itself in `git worktree list`; a spec is
+    // provisioned only when it has its OWN worktree, separate from it.
+    .filter((s) => s.wt !== dir && worktreePaths.has(s.wt))
+    .sort((a, b) => a.folder.localeCompare(b.folder))
+
+  if (!provisioned.length) {
     process.stdout.write('spec-env: no provisioned specs.\n')
     return
   }
+
+  const registry = readRegistry(dir, config)
   process.stdout.write('Provisioned specs:\n')
-  names
-    .sort((a, b) => registry.slots[a] - registry.slots[b])
-    .forEach((name) => {
-      const slot = registry.slots[name]
+  for (const { folder, wt } of provisioned) {
+    const slot = registry.slots[folder]
+    let ports = ''
+    if (slot !== undefined) {
       const off = portOffset(slot, config)
-      const hi = off + config.docker.portsPerSpec - 1
-      process.stdout.write(`  ${name}  slot ${slot}  ports ${off}-${hi}\n`)
-    })
+      ports = `  slot ${slot}  ports ${off}-${off + config.docker.portsPerSpec - 1}`
+    }
+    process.stdout.write(`  ${folder}${ports}\n    ${path.relative(dir, wt) || wt}\n`)
+  }
 }
 
 // Plan a provision: allocate the slot, persist the registry, and print the plan
@@ -209,10 +234,6 @@ function specEnvStatus(dir, config) {
 // opener). This creates no worktree and starts no stack — the caller runs the
 // printed commands. Keep the output's verb honest about that.
 function specEnvUp(dir, config, specArg) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env up <spec>\n')
-    return
-  }
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // Live-safe: if this spec is already live on the primary checkout (its branch was
@@ -328,7 +349,7 @@ function gitReader(cwd) {
 // ancestor of it (fully landed), which lets teardown skip the unpushed guard.
 function worktreeGitState(worktreePath, base) {
   if (!fs.existsSync(worktreePath)) {
-    return { dirty: false, unpushed: false, merged: true, reachableFromTag: false }
+    return { dirty: false, unpushed: false, merged: true, reachableFromTag: false, remoteBranch: null }
   }
   const git = gitReader(worktreePath)
 
@@ -357,7 +378,41 @@ function worktreeGitState(worktreePath, base) {
   const pointing = git(['tag', '--points-at', 'HEAD'])
   const reachableFromTag = pointing !== null && pointing.length > 0
 
-  return { dirty, unpushed, merged, reachableFromTag }
+  // remoteBranch = the remote-tracking ref for this worktree's branch when one
+  // actually exists here (e.g. "origin/feat/thing"), else null. Teardown plans a
+  // remote delete off it, so it has to be a ref we can SEE — never an inference
+  // from the branch name, and never a bare assumption that `origin` has it.
+  //
+  // WHAT WOULD FOOL THIS, both left open deliberately:
+  //   * A STALE ref — the branch was deleted from another clone and this one
+  //     hasn't pruned. We plan a delete that no-ops: `git push --delete` errors
+  //     on a branch that isn't there, which is loud, not destructive.
+  //   * A branch pushed FROM ANOTHER MACHINE has no remote-tracking ref here, so
+  //     teardown misses it and the remote branch survives. That is the safe
+  //     direction — under-cleaning. Closing it means `git ls-remote`, which makes
+  //     every teardown network-dependent for what is cosmetic cleanup. Not done.
+  //
+  // Upstream first, so a non-`origin` remote is honoured; `--abbrev-ref` gives the
+  // short ref, and the verify catches an upstream configured for a ref that is
+  // gone. With no upstream (the branch was pushed without `-u`), ask each remote
+  // in turn rather than guessing a name.
+  let remoteBranch = null
+  const upstream = git(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'])
+  if (upstream && git(['rev-parse', '--verify', '--quiet', `refs/remotes/${upstream}`]) !== null) {
+    remoteBranch = upstream
+  } else {
+    const branch = git(['rev-parse', '--abbrev-ref', 'HEAD'])
+    if (branch && branch !== 'HEAD') {
+      for (const remote of (git(['remote']) || '').split('\n').map((r) => r.trim()).filter(Boolean)) {
+        if (git(['rev-parse', '--verify', '--quiet', `refs/remotes/${remote}/${branch}`]) !== null) {
+          remoteBranch = `${remote}/${branch}`
+          break
+        }
+      }
+    }
+  }
+
+  return { dirty, unpushed, merged, reachableFromTag, remoteBranch }
 }
 
 // A deterministic-enough compact timestamp for backup filenames (CLI-only; the
@@ -376,10 +431,6 @@ function compactTimestamp() {
 // the shared parent of every spec's worktree and harmless when empty; removing it
 // would just re-prompt on the next /spec-go (see spec: isolation-trusts-worktree-dir).
 function specEnvDown(dir, config, specArg, flags) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env down <spec> [--keep-volumes] [--force]\n')
-    return
-  }
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // A worktree-only spec never held a slot but its worktree still needs removing,
@@ -419,6 +470,15 @@ function specEnvDown(dir, config, specArg, flags) {
   out.push('')
   out.push('  run these:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
+  // Kept out of `run these:` on purpose — everything above is local and
+  // reversible-ish, while this reaches a shared remote. The skills ask before
+  // running it; a project that never wants to be asked sets
+  // `teardown.deleteRemoteBranch: "always"`, which folds it in above instead.
+  if (plan.remoteCommands && plan.remoteCommands.length) {
+    out.push('')
+    out.push('  remote branch — confirm with the user first:')
+    for (const cmd of plan.remoteCommands) out.push(`    ${cmd}`)
+  }
   process.stdout.write(out.join('\n') + '\n')
 }
 
@@ -482,6 +542,77 @@ function liveWorktreePaths(dir) {
   return paths
 }
 
+/**
+ * The spec to act on when the caller named none.
+ *
+ * Two signals, strongest first:
+ *
+ *   1. **The worktree you are standing in.** A spec-env verb run from inside a
+ *      spec's worktree means that spec — there is nothing to infer. This is the
+ *      case that carries the feature in practice: several worktrees at once is
+ *      the normal shape of this workflow, so "the only one" rarely resolves.
+ *   2. **The only spec that has a worktree**, when cwd says nothing (you are in
+ *      the primary checkout, or somewhere else entirely).
+ *
+ * `git worktree list` is the authority for both, and deliberately so. Two
+ * nearer-looking signals are wrong here:
+ *
+ *   - The **slot registry** covers only Docker specs — `specEnvUp` allocates a
+ *     slot exclusively when `wantsDocker`, so a `Stack: worktree` spec never
+ *     appears in it and a project with `docker.enabled: false` has a permanently
+ *     empty registry. Absence there says nothing about provisioning.
+ *   - The **`specs/in-progress/` bucket** says a spec is being worked on, not
+ *     that it has a worktree — and git does not track an empty directory, so the
+ *     bucket disappears the moment it empties.
+ *
+ * Three outcomes, never two: resolved → that spec; several candidates and no cwd
+ * hint → throw, listing them; none → throw, pointing at /spec-go. *Cannot tell*
+ * never becomes a guess.
+ *
+ * BLIND SPOT: a spec taken live with `/spec-live` has had its branch moved into
+ * the primary checkout and its worktree left on a detached HEAD — it still has a
+ * worktree, so it is still a candidate, which is correct. What would fool this is
+ * a worktree removed behind git's back (`rm -rf` without `git worktree prune`);
+ * git keeps listing it as prunable. That over-reports rather than under-reports,
+ * so the failure is an ambiguity error, never a wrong spec.
+ */
+function soleProvisionedSpec(dir, config, cwd = process.cwd()) {
+  const worktreePaths = liveWorktreePaths(dir)
+  const provisioned = allSpecs(dir, config, worktreePaths)
+    .map((s) => ({ folder: s.folder, wt: path.resolve(s.worktreePath) }))
+    // The primary checkout is itself in `git worktree list`; a spec is
+    // provisioned only when it has its OWN worktree, separate from it.
+    .filter((s) => s.wt !== dir && worktreePaths.has(s.wt))
+    .sort((a, b) => a.folder.localeCompare(b.folder))
+
+  // 1. Standing inside a spec's worktree names it outright. Deepest match wins,
+  //    so a nested worktree is not shadowed by an ancestor one.
+  let here
+  try {
+    here = fs.realpathSync(path.resolve(cwd))
+  } catch {
+    here = path.resolve(cwd)
+  }
+  const inside = provisioned
+    .filter((s) => here === s.wt || here.startsWith(s.wt + path.sep))
+    .sort((a, b) => b.wt.length - a.wt.length)[0]
+  if (inside) return inside.folder
+
+  // 2. Otherwise only an unambiguous set answers.
+  if (provisioned.length === 1) return provisioned[0].folder
+  if (provisioned.length === 0) {
+    throw new Error(
+      'no spec given, and no spec has a worktree — name one explicitly, or run ' +
+        '/spec-go to provision it.',
+    )
+  }
+  throw new Error(
+    `no spec given, and ${provisioned.length} specs have worktrees — name the one ` +
+      `you mean, or run this from inside one:\n` +
+      provisioned.map((s, i) => `  ${i + 1}. ${s.folder}`).join('\n'),
+  )
+}
+
 // Resolve a spec argument the ONE way every spec-env subcommand resolves it:
 // against the primary checkout first, then the spec's own worktree, then every
 // other checkout git knows about. An in-progress spec is git-mv'd into
@@ -493,6 +624,10 @@ function liveWorktreePaths(dir) {
 // coordinate tokens always expand against `dir` (the primary checkout), so the
 // answer is identical whether the command was run from main or a worktree.
 function resolveSpecWithWorktree(dir, config, specArg) {
+  // Fill in a missing argument first: everything below (starting with
+  // path.basename) assumes a string, and every subcommand that reaches here is
+  // one where a missing spec was previously a usage error.
+  specArg = specArg || soleProvisionedSpec(dir, config)
   const { slug } = splitPrefix(path.basename(specArg))
   const { repo, repoSlug } = repoInfo(dir)
   const wtTokens = { repo, repoSlug, slug }
@@ -604,6 +739,15 @@ function specEnvPrune(dir, config, flags) {
   out.push('')
   out.push('  run these:')
   for (const cmd of plan.commands) out.push(`    ${cmd}`)
+  // Kept out of `run these:` on purpose — everything above is local and
+  // reversible-ish, while this reaches a shared remote. The skills ask before
+  // running it; a project that never wants to be asked sets
+  // `teardown.deleteRemoteBranch: "always"`, which folds it in above instead.
+  if (plan.remoteCommands && plan.remoteCommands.length) {
+    out.push('')
+    out.push('  remote branch — confirm with the user first:')
+    for (const cmd of plan.remoteCommands) out.push(`    ${cmd}`)
+  }
   process.stdout.write(out.join('\n') + '\n')
 }
 
@@ -611,10 +755,6 @@ function specEnvPrune(dir, config, flags) {
 // Queries git for the facts, prints the plan / block / no-op. The /spec-complete
 // skill executes the printed commands (and aborts a conflicting rebase).
 function specEnvIntegrate(dir, config, specArg) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env integrate <spec>\n')
-    return
-  }
 
   // `dir` is already anchored on the primary checkout by the dispatch, so it is
   // both where the spec resolves and the target of the fast-forward — /spec-complete
@@ -734,8 +874,9 @@ function specEnvIntegrate(dir, config, specArg) {
 function specEnvHotfix(dir, config, positional, flags) {
   const action = positional[0]
   const specArg = positional[1]
-  if (action !== 'land' || !specArg) {
-    process.stdout.write('Usage: skitterspec spec-env hotfix land <spec> [--also <tag>]...\n')
+  // The action must be named; the spec may be omitted (resolved from the registry).
+  if (action !== 'land') {
+    process.stdout.write('Usage: skitterspec spec-env hotfix land [spec] [--also <tag>]...\n')
     return
   }
 
@@ -815,10 +956,6 @@ function specEnvHotfix(dir, config, positional, flags) {
 
 // Print the resolved identity/coordinates for a single spec.
 function specEnvResolve(dir, config, specArg) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env resolve <spec>\n')
-    return
-  }
   const r = resolveSpecWithWorktree(dir, config, specArg)
   process.stdout.write(
     `spec:       ${r.folder} (${r.bucket})\n` +
@@ -836,8 +973,9 @@ function specEnvResolve(dir, config, specArg) {
 async function specEnvDev(dir, config, positional) {
   const action = positional[0]
   const specArg = positional[1]
-  if ((action !== 'up' && action !== 'down') || !specArg) {
-    process.stdout.write('Usage: skitterspec spec-env dev <up|down> <spec>\n')
+  // The action must be named; the spec may be omitted (resolved from the registry).
+  if (action !== 'up' && action !== 'down') {
+    process.stdout.write('Usage: skitterspec spec-env dev <up|down> [spec]\n')
     return
   }
   const spec = resolveSpecWithWorktree(dir, config, specArg)
@@ -1013,33 +1151,56 @@ const DEPS_RE = /(^|\/)(package\.json|pnpm-lock\.yaml|package-lock\.json|yarn\.l
 // receipt is advisory metadata. `status` is read-only; `take` performs the switch
 // (release/abort land in a later phase).
 async function specEnvLive(dir, config, positional) {
-  const action = positional[0] || 'status'
+  const { action, specArg } = liveGrammar(dir, config, positional)
   switch (action) {
     case 'status':
-      specEnvLiveStatus(dir, config, positional[1])
+      specEnvLiveStatus(dir, config, specArg)
       break
     case 'take':
-      await specEnvLiveTake(dir, config, positional[1])
+      await specEnvLiveTake(dir, config, specArg)
       break
     case 'release':
-      await specEnvLiveRelease(dir, config, positional[1])
+      await specEnvLiveRelease(dir, config, specArg)
       break
     case 'abort':
       await specEnvLiveAbort(dir, config)
       break
     default:
-      process.stdout.write('Usage: skitterspec spec-env live <take|release|abort|status> [spec]\n')
+      process.stdout.write(
+        'Usage: skitterspec spec-env live <spec>|<base branch>|<take|release|abort|status> [spec]\n',
+      )
   }
 }
 
+const LIVE_VERBS = new Set(['status', 'take', 'release', 'abort'])
+
+// The two front doors every doc names — `/spec-live <spec>` and `/spec-live main`
+// — translated to verbs. They live here rather than in the command because
+// `.claude/commands/spec-live.md` relays `$ARGUMENTS` untranslated (it is a
+// pre-executed script, with no model turn to rewrite them); the skill this
+// replaced did the translation itself, which is how these forms came to be
+// documented but unimplemented. `connect` needs no equivalent — its argument was
+// always spec-shaped (`specArg || 'main'`).
+//
+// VERB PRECEDENCE IS DELIBERATE, and so is the order below: the four verbs and
+// the base branch are matched BEFORE the spec-name fallback, so a spec folder
+// that happens to be called `status` cannot silently branch-switch the primary
+// checkout. Such a spec is still reachable — as `live take status`. The literal
+// `main` is honoured even where the base branch is named something else,
+// matching `connect main`, so the muscle memory works in either repo.
+function liveGrammar(dir, config, positional) {
+  const [first, second] = positional
+  if (!first) return { action: 'status', specArg: undefined }
+  if (LIVE_VERBS.has(first)) return { action: first, specArg: second }
+  if (first === 'main' || first === resolveBaseBranch(config, gitReader(dir))) {
+    return { action: 'release', specArg: undefined }
+  }
+  return { action: 'take', specArg: first }
+}
+
 // Take the running instance: rebase the spec's branch onto base, free it from its
 // worktree, and check it out in the primary checkout so the dev server reloads it.
 async function specEnvLiveTake(dir, config, specArg) {
-  if (!specArg) {
-    process.stdout.write('Usage: skitterspec spec-env live take <spec>\n')
-    return
-  }
-
   const spec = resolveSpecWithWorktree(dir, config, specArg)
 
   // Probe the primary checkout's git state (IO stays here; the planner is pure).
@@ -1329,7 +1490,13 @@ async function specEnv(rest) {
       break
     default:
       process.stdout.write(
-        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>]\n',
+        'Usage: skitterspec spec-env <up|down|prune|dev|connect|integrate|hotfix|live|status|resolve> [spec] [--keep-volumes] [--force] [--also <tag>] [--older-than <days>]\n' +
+          '  [spec] is optional for up/down/dev/integrate/hotfix/resolve and live take:\n' +
+          '  omit it and the sole provisioned spec is used (several -> it lists them).\n' +
+          '  NOTE connect and live status keep their own meaning for a missing spec:\n' +
+          '  connect disconnects (= main), live status reports on the whole repo.\n' +
+          '  connect and live also take a bare spec name: `live <spec>` takes the\n' +
+          '  instance, `live main` (or your base branch) hands it back.\n',
       )
   }
 }

package/src/env/config.js

@@ -29,6 +29,7 @@
  *     branch:   { pattern, identifierField },  // git branch naming (provider-neutral)
  *     baseBranch: "",          // "" = auto-detect (origin/HEAD → main → master)
  *     guards:   { refuseTeardownIfDirty, refuseTeardownIfUnpushed },
+ *     teardown: { deleteRemoteBranch },
  *     live:     { migrations: [ "glob", ... ] }  // migration globs → `live take`
  *               // refuses a branch that changes them (code-only v1)
  *     hotfix:   { bump, cherryPickMain, targets }  // `hotfix land`: patch-bump the
@@ -79,6 +80,12 @@ const DEFAULT_CONFIG = Object.freeze({
   // Integration base branch. Empty = auto-detect (origin/HEAD → main → master).
   baseBranch: '',
   guards: Object.freeze({ refuseTeardownIfDirty: true, refuseTeardownIfUnpushed: true }),
+  // Teardown cleanup beyond this machine. `deleteRemoteBranch` decides what
+  // `spec-env down` does about the branch `/spec-go` pushed: "prompt" (default)
+  // plans the delete in its own confirm-first section for the skill to ask about,
+  // "never" omits it, "always" folds it into the run-blind command list. Only ever
+  // planned for a LANDED branch — see teardown.js.
+  teardown: Object.freeze({ deleteRemoteBranch: 'prompt' }),
   // Live overlay (`spec-env live`). `migrations` is a list of globs marking
   // migration files; a branch that changes any of them is treated as stateful and
   // `live take` refuses it (code-only v1). Default: none (nothing is stateful).
@@ -109,6 +116,7 @@ function defaults() {
     branch: { ...DEFAULT_CONFIG.branch },
     baseBranch: DEFAULT_CONFIG.baseBranch,
     guards: { ...DEFAULT_CONFIG.guards },
+    teardown: { ...DEFAULT_CONFIG.teardown },
     live: { migrations: [] },
     hotfix: { ...DEFAULT_CONFIG.hotfix, targets: [] },
   }
@@ -254,6 +262,17 @@ function mergeConfig(base, parsed) {
     assign(base.guards, parsed.guards, 'refuseTeardownIfUnpushed', 'boolean')
   }
 
+  // An unrecognised policy falls through to the default rather than erroring or
+  // being taken literally — a typo ("Always", "yes") must not silently become a
+  // stronger setting than the author typed, and "prompt" is the one value that
+  // cannot act without a human first.
+  if (isObject(parsed.teardown)) {
+    const policy = parsed.teardown.deleteRemoteBranch
+    if (policy === 'prompt' || policy === 'never' || policy === 'always') {
+      base.teardown.deleteRemoteBranch = policy
+    }
+  }
+
   if (isObject(parsed.live) && Array.isArray(parsed.live.migrations)) {
     base.live.migrations = normalizeFileList(parsed.live.migrations)
   }