@skitterbyte/skitterspec 16.7.0 → 16.10.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/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/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

@@ -53,6 +53,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

@@ -53,8 +53,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
@@ -160,6 +174,8 @@ fix narrative and decisions — keep them separate.
 
 
 
+
+
 ## 5. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix. Match surrounding code; honour all

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

@@ -81,6 +81,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

@@ -120,7 +120,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:
@@ -176,6 +176,17 @@ worktree and branch are being kept, and go straight to sub-step 4. Mention
    still respects the guards (won't destroy a dirty, or unpushed-and-unlanded,
    worktree without `--force`), so if it *does* refuse, relay that and stop
    rather than reaching for `--force`.
+
+   **If the plan prints a `remote branch — confirm with the user first:`
+   section, ask before running it.** `/spec-go` pushed this branch when it
+   provisioned, so the remote copy outlives teardown unless someone deletes it.
+   The planner only ever offers this for a branch that has **landed**, so say so
+   plainly when you ask — the commits are on the base branch (or captured by the
+   deploy tag), so deleting the remote branch loses nothing. On a yes, run the
+   printed `git push <remote> --delete <branch>`; on a no, leave it and say the
+   remote branch is still there. Never fold it into the `run these:` batch — a
+   project that wants it unattended sets `teardown.deleteRemoteBranch: "always"`
+   in `env.config.json`, and then it appears in `run these:` instead of here.
 4. **Reap orphaned test-DB volumes:** run `skitterspec spec-env prune`. It lists
    Docker volumes in the repo namespace that belong to **no live spec** (no
    worktree) — leftovers from declined/aborted teardowns, manual

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

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

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

@@ -65,8 +65,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
@@ -171,6 +185,8 @@ narrative and decisions).
 
 
 
+
+
 ## 6. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix on the branch. Match surrounding code;
@@ -194,7 +210,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-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.js

@@ -22,7 +22,23 @@ if (!existsSync(join(__dirname, '..', 'src'))) {
 
 const { run } = require('../src/cli.js')
 
-run(process.argv.slice(2)).catch((err) => {
+// 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.
+const argv = process.argv.slice(2)
+if (argv[0] === 'init' || argv[0] === 'update') {
+  try {
+    require('../src/init.js').assertComposedAssets()
+  } catch (err) {
+    console.error(`skitterspec: ${err.message}`)
+    process.exit(1)
+  }
+}
+
+run(argv).catch((err) => {
   console.error(`skitterspec: ${err.message}`)
   process.exit(1)
 })

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "16.7.0",
+  "version": "16.10.0",
   "description": "Spec-driven development for Claude Code — a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "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)
   }

package/src/env/teardown.js

@@ -13,6 +13,12 @@
  * Volumes are the only destructive action — dropped by default (reclaims disk)
  * unless `--keep-volumes`, and always backed up first when a `backupCommand` is
  * configured.
+ *
+ * `commands` is safe for a caller to run BLIND — that is the property the remote
+ * delete must not break. A remote branch delete reaches outside this machine, so
+ * it is returned in a separate `remoteCommands` array that the skills confirm
+ * with the user before running, and it never enters `commands` unless the
+ * project has opted in with `teardown.deleteRemoteBranch: "always"`.
  */
 
 const { expandTokens } = require('./resolve.js')
@@ -21,9 +27,10 @@ const { expandTokens } = require('./resolve.js')
  * @param {object} spec  resolved spec: { slug, branch, worktreePath, projectName, ... }
  * @param {object} config normalised env config.
  * @param {object} flags { keepVolumes, force }
- * @param {object} ctx   { worktreeState: { dirty, unpushed, merged, reachableFromTag }, timestamp }
- * @returns {object} { blocked, reason, commands, backupCommand, backupPath,
- *                     volumesDropped }
+ * @param {object} ctx   { worktreeState: { dirty, unpushed, merged, reachableFromTag,
+ *                     remoteBranch }, timestamp }
+ * @returns {object} { blocked, reason, commands, remoteCommands, backupCommand,
+ *                     backupPath, volumesDropped }
  */
 function planDown(spec, config, flags, ctx) {
   const { worktreeState = {}, timestamp } = ctx || {}
@@ -113,7 +120,57 @@ function planDown(spec, config, flags, ctx) {
     commands.push(`git branch ${landed ? '-D' : '-d'} ${spec.branch}`)
   }
 
-  return { blocked: false, reason: null, commands, backupCommand, backupPath, volumesDropped }
+  // --- delete the branch on the remote (planned, never run here) ---
+  //
+  // `/spec-go` pushes the branch at provision time, so a completed spec otherwise
+  // leaves a merged branch on the remote forever. Cleaning that up is the goal;
+  // doing it safely is the constraint.
+  //
+  // Gated on `landed` because until the branch is merged (or captured by a tag)
+  // the remote copy is the ONLY backup of the work — that is the whole reason
+  // `refuseTeardownIfUnpushed` exists, and deleting the remote branch of an
+  // unlanded spec would defeat it. `--force` deliberately does NOT enable this:
+  // force is for "I accept losing this worktree", not "also reach out and delete
+  // the backup". The same `landed` that decides `-D` vs `-d` decides this, so the
+  // two can never disagree about whether the commits are recoverable.
+  //
+  // A null `remoteBranch` plans nothing. An absence is not evidence — the branch
+  // may well be on a remote this clone cannot see (pushed from another machine),
+  // and the honest answer to "is there a remote branch?" is then "cannot tell",
+  // which routes to doing nothing.
+  const remoteCommands = []
+  const policy = (config.teardown && config.teardown.deleteRemoteBranch) || 'prompt'
+  if (spec.branch && landed && worktreeState.remoteBranch && policy !== 'never') {
+    // `remoteBranch` is a short ref like "origin/feat/thing" and the branch name
+    // itself contains slashes, so the remote is what remains once the exact
+    // "/<branch>" suffix is stripped — not the text before the first slash.
+    //
+    // If it does not end that way the ref maps to a differently-named branch on
+    // the remote (a push refspec, or push.default set to something exotic). We
+    // cannot tell what to delete, so we plan nothing rather than guess at a
+    // branch name on someone's shared remote.
+    const suffix = `/${spec.branch}`
+    if (worktreeState.remoteBranch.endsWith(suffix)) {
+      const remote = worktreeState.remoteBranch.slice(0, -suffix.length)
+      if (remote) {
+        const cmd = `git push ${remote} --delete ${spec.branch}`
+        // "always" is the project saying it never wants to be asked, so the push
+        // joins the run-blind list. Everything else keeps it quarantined.
+        if (policy === 'always') commands.push(cmd)
+        else remoteCommands.push(cmd)
+      }
+    }
+  }
+
+  return {
+    blocked: false,
+    reason: null,
+    commands,
+    remoteCommands,
+    backupCommand,
+    backupPath,
+    volumesDropped,
+  }
 }
 
 function blocked(reason) {
@@ -121,6 +178,7 @@ function blocked(reason) {
     blocked: true,
     reason,
     commands: [],
+    remoteCommands: [],
     backupCommand: null,
     backupPath: null,
     volumesDropped: false,

package/src/init.js

@@ -23,6 +23,21 @@ function listSkills() {
     .sort()
 }
 
+// Slash commands shipped as `assets/commands/*.md`, installed to
+// `.claude/commands/`. Discovered from the bundled tree exactly like skills, so
+// each distribution installs precisely what it ships.
+function listCommands() {
+  const dir = path.join(ASSETS, 'commands')
+  try {
+    return fs
+      .readdirSync(dir)
+      .filter((f) => f.endsWith('.md'))
+      .sort()
+  } catch {
+    return [] // a distribution may ship no commands
+  }
+}
+
 function listRules() {
   return fs
     .readdirSync(path.join(ASSETS, 'rules'))
@@ -42,6 +57,8 @@ function listCoreTemplates() {
 
 const SKILLS = listSkills()
 
+const COMMANDS = listCommands()
+
 const RULES = listRules()
 
 const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled']
@@ -50,6 +67,89 @@ const SPEC_FOLDERS = ['.core', 'backlog', 'in-progress', 'complete', 'cancelled'
 // env.config isolation templates; a provider superset also ships its own).
 const CORE_FILES = listCoreTemplates()
 
+// The CLI is a local devDependency and never on PATH, so a command file that
+// pre-executes it must carry a literal, working invocation. Detect the runner
+// from the lockfile and bake it in at write time.
+//
+// The lockfile is a POSITIVE signal — a file that must be present for the answer
+// to be yes — rather than an absence. When none is found we do not guess a
+// package manager we have no evidence for; `npx` is the fallback because it is
+// the one runner that works across all three installs.
+const PACKAGE_MANAGERS = [
+  ['pnpm-lock.yaml', 'pnpm exec'],
+  ['yarn.lock', 'yarn'],
+  ['package-lock.json', 'npx'],
+  ['bun.lockb', 'bunx'],
+]
+
+function detectPackageManager(dir) {
+  for (const [lockfile, exec] of PACKAGE_MANAGERS) {
+    if (fs.existsSync(path.join(dir, lockfile))) return exec
+  }
+  return 'npx'
+}
+
+// Fill a command file's `{{exec}}` placeholders. Kept a pure function of
+// (content, dir) so `managedTargets` can compare against exactly what
+// `installCommands` would write — otherwise every install would hash as
+// customized on the next run.
+function renderCommand(content, dir) {
+  return content.split('{{exec}}').join(detectPackageManager(dir))
+}
+
+// --- composed-assets guard -------------------------------------------------
+//
+// A source package's `assets/` is PRE-composition: `<!-- seam:NAME -->` is still
+// literal text that scripts/build-dist.js replaces — with a provider's fragment
+// for the provider distribution, with nothing for the base. Only a built
+// distribution's assets are installable.
+//
+// This is a POSITIVE signal, not an absence: a seam marker must be **present**
+// for the guard to fire, so it cannot misfire on a tree it simply failed to read.
+// And it refuses rather than repairing — installing the wrong thing is the
+// expensive mistake here. In a dev-linked checkout the installed skills are
+// symlinks to the composed distribution, so a `--force` install would write
+// these markers straight through the link and into the built assets.
+const SEAM_RE = /<!--\s*seam:[A-Za-z0-9_-]+\s*-->/
+
+function assetFiles(dir) {
+  const out = []
+  const walk = (d) => {
+    let entries
+    try {
+      entries = fs.readdirSync(d, { withFileTypes: true })
+    } catch {
+      return // a distribution need not ship every asset kind
+    }
+    for (const e of entries) {
+      const p = path.join(d, e.name)
+      if (e.isDirectory()) walk(p)
+      else if (e.name.endsWith('.md')) out.push(p)
+    }
+  }
+  walk(dir)
+  return out
+}
+
+// Throws when this package's assets are uncomposed. Called from the **bins** —
+// the outermost boundary, and the only way a real install happens — never from
+// init()/resync()/run(), which the unit tests legitimately drive against this
+// source tree. Guarding any deeper would make the library untestable while
+// protecting nothing extra.
+function assertComposedAssets() {
+  const offenders = assetFiles(ASSETS)
+    .filter((f) => SEAM_RE.test(fs.readFileSync(f, 'utf8')))
+    .map((f) => path.relative(ASSETS, f))
+  if (!offenders.length) return
+  throw new Error(
+    `refusing to install: this package's assets are uncomposed (${offenders.length} ` +
+      `file(s) still carry a <!-- seam:… --> marker, e.g. ${offenders[0]}).\n` +
+      '  These are a workspace source package\'s assets, not a distribution\'s. ' +
+      'Run "npm run build" in the skitterspec repo, then run the command again ' +
+      'from the built distribution.',
+  )
+}
+
 const SPEC_MARKER_START = '<!-- skitterspec:start -->'
 const SPEC_MARKER_END = '<!-- skitterspec:end -->'
 
@@ -99,13 +199,15 @@ function sha1(content) {
 // the bundled content that ships in this distribution's assets.
 function managedTargets(dir) {
   const out = []
-  const add = (assetRel, targetAbs) =>
+  const add = (assetRel, targetAbs, render = (c) => c) =>
     out.push({
       relPath: rel(dir, targetAbs),
       abs: targetAbs,
-      bundled: fs.readFileSync(path.join(ASSETS, assetRel), 'utf8'),
+      bundled: render(fs.readFileSync(path.join(ASSETS, assetRel), 'utf8'), dir),
     })
   for (const name of SKILLS) add(path.join('skills', name, 'SKILL.md'), path.join(dir, '.claude', 'skills', name, 'SKILL.md'))
+  for (const name of COMMANDS)
+    add(path.join('commands', name), path.join(dir, '.claude', 'commands', name), renderCommand)
   for (const name of RULES) add(path.join('rules', name), path.join(dir, '.claude', 'rules', name))
   for (const asset of CORE_FILES) add(asset, path.join(dir, 'specs', '.core', path.basename(asset)))
   return out
@@ -230,6 +332,16 @@ function installSkills(dir, opts) {
   }
 }
 
+function installCommands(dir, opts) {
+  for (const name of COMMANDS) {
+    const content = renderCommand(
+      fs.readFileSync(path.join(ASSETS, 'commands', name), 'utf8'),
+      dir,
+    )
+    writeFile(dir, path.join(dir, '.claude', 'commands', name), content, opts)
+  }
+}
+
 function installRule(dir, opts) {
   for (const name of RULES) {
     copyAsset(
@@ -519,6 +631,7 @@ function reset(dir, { claudeMd = true } = {}) {
   }
   if (claudeMd) stripClaudeMdSection(dir)
   installSkills(dir, { force: true })
+  installCommands(dir, { force: true })
   installRule(dir, { force: true })
   installFolders(dir)
   removeRetiredFiles(dir)
@@ -597,6 +710,7 @@ async function init({ dir, force, claudeMd, mode, isolation }) {
   resetReport()
 
   installSkills(dir, { force })
+  installCommands(dir, { force })
   installRule(dir, { force })
   installFolders(dir)
   removeRetiredFiles(dir)
@@ -615,6 +729,7 @@ async function init({ dir, force, claudeMd, mode, isolation }) {
 module.exports = {
   init,
   SKILLS,
+  COMMANDS,
   RULES,
   SPEC_FOLDERS,
   MANIFEST_FILE,
@@ -627,4 +742,7 @@ module.exports = {
   resync,
   reset,
   assertSafeToDelete,
+  assertComposedAssets,
+  detectPackageManager,
+  renderCommand,
 }

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

@@ -1,59 +0,0 @@
----
-name: spec-connect
-description: Point your local canonical origin (localhost:3000/:8080) at a spec's running dev servers so you can test a worktree's UI/API changes at the normal URL — or `spec-connect main` to hand the ports back to your main checkout. Runs `skitterspec spec-env connect` (a small bundled reverse proxy). Opt-in — needs specs/.core/env.config.json with a `dev` block. Use when the user says "/spec-connect", "test <spec> locally", "point local at <spec>", or "connect to <spec>".
----
-
-# /spec-connect — expose one spec on the canonical ports
-
-Make `http://localhost:<frontPort>` serve a **spec's** warm dev servers instead of
-your main checkout's, so you can test a worktree's UI/API at the exact URL you
-always use — no bookmark, base-URL, or OAuth-callback changes. **Exclusive:** one
-spec is exposed at a time. `spec-connect main` stops the proxy and hands the ports
-back to your primary checkout.
-
-This skill is **opt-in**: it needs `specs/.core/env.config.json` with a `dev`
-block (host dev servers + their `frontPort`s). If isolation or `dev` is absent,
-say so and stop.
-
-**Lighter alternative for a code-only spec:** `/spec-live` reuses the dev server
-you already have running (it branch-switches the primary checkout) instead of
-starting a second stack — no proxy, one process. Prefer it for code-only specs;
-use `/spec-connect` when a spec has its own Docker stack, or to run several stacks
-in parallel.
-
-## 1. Identify the target
-
-- Use the spec named as an argument. The literal `main` means **disconnect**
-  (hand the ports back to the primary checkout). Else use the spec **currently in
-  context**; if unclear, ask.
-
-## 2. Make sure the spec's dev servers are running
-
-`connect` proxies to a spec's dev servers on its reserved port block — it does
-**not** start them. If they aren't up yet, start them first:
-
-```
-skitterspec spec-env dev up <spec>
-```
-
-(This is automatic under `/spec-go`; run it by hand only when connecting a spec
-whose servers you stopped.)
-
-## 3. Connect (or disconnect)
-
-```
-skitterspec spec-env connect <spec>     # expose <spec> on the canonical ports
-skitterspec spec-env connect main       # stop the proxy — main owns the ports
-```
-
-The engine (re)starts a small bundled Node reverse proxy and **prints** the
-canonical URL → spec-port mapping. **If it reports a canonical port is in use**,
-your **main dev server still holds it** — stop main on that port, then re-run
-(the proxy can't share a port main is bound to). Relay the printed message.
-
-## 4. Report
-
-Echo which spec is now on the canonical ports (and the URLs), or that the proxy
-was stopped and main owns them again. Switching to a different spec is just
-`spec-connect <other>` — the dev servers stay warm, so it's a near-instant
-re-point.

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

@@ -1,73 +0,0 @@
----
-name: spec-live
-description: Test a spec on your already-running dev server by checking its branch out in the primary checkout — no second stack, no proxy. `spec-live <spec>` takes the running instance for that spec; `spec-live main` releases it. Runs `skitterspec spec-env live`. Opt-in — needs specs/.core/env.config.json. Code-only specs; stateful (Docker/migration) specs use /spec-connect. Use when the user says "/spec-live", "go live with <spec>", "take the instance for <spec>", or "test <spec> on the running server".
----
-
-# /spec-live — put one spec live on the running instance
-
-Instead of running a second dev stack for a spec (that's `/spec-connect`), **reuse
-the one instance you already have**: rebase the spec's branch onto base, hand it
-from its worktree to the **primary checkout**, and let your running dev server
-hot-reload it. You test at your normal URL, with one process. The branch that's
-checked out in the primary checkout **is** the lock — exactly one spec is live at
-a time, and `/spec-live main` hands the instance back.
-
-This skill is **opt-in**: it needs `specs/.core/env.config.json`. If isolation is
-absent, say so and stop.
-
-**Code-only.** Live overlay refuses a **stateful** spec — one whose `> **Stack:**`
-is `worktree + docker`, or whose branch changes migrations (per
-`env.config.json` → `live.migrations`). Those keep their isolated stack; use
-`/spec-connect` for them. It also **always refuses a `Type: Hotfix` spec** — its
-branch is built on an old release tag, so hot-reloading it onto the running dev
-server could break the shared instance; test a hotfix with `/spec-connect`. The
-engine enforces all of this and prints why.
-
-## 1. Identify the target
-
-- Use the spec named as an argument. The literal `main` means **release** (hand
-  the instance back to base). Else use the spec **currently in context**; if
-  unclear, ask.
-
-## 2. Make sure a dev server is running
-
-`live take` **verifies** a dev server is up on your canonical ports and switches
-the branch under it — it does **not** start one. If nothing is listening it
-refuses; start your dev server first (however you normally run it, or
-`skitterspec spec-env dev up <spec>`). (Projects with no `dev` servers configured
-have nothing to hot-reload — the switch still happens, with a warning.)
-
-## 3. Take (or release)
-
-```
-skitterspec spec-env live take <spec>   # rebase → detach worktree → checkout in primary
-skitterspec spec-env live release        # hand the instance back to base, re-isolate the branch
-skitterspec spec-env live abort          # crash recovery (see below)
-skitterspec spec-env live status         # who's live (branch in the primary checkout + receipt)
-```
-
-**Take** rebases the branch onto base, frees it from its worktree
-(`switch --detach`), checks it out in the primary checkout, then writes a receipt
-(`.spec-env/live.json`). Relay its output. **If it reports the rebase hit
-conflicts**, it left everything untouched — rebase the branch in its worktree,
-resolve, then retry. **If it says a spec already holds the instance**, release it
-first. If it warns dependencies changed, restart your dev server after the switch.
-
-**Release** (`/spec-live main`) is the graceful exit of an unfinished session:
-`skitterspec spec-env live release` reads the live spec from the receipt, checks
-base back out in the primary checkout, re-attaches the branch to its worktree, and
-clears the receipt. Commit any fixes to the branch first — it refuses on a dirty
-tree rather than discard them. (To *finish* a live spec instead of releasing it,
-use `/spec-complete`, which is live-aware.)
-
-**Abort** is crash recovery, for when a session died mid-take and left the primary
-checkout on a feature branch: `skitterspec spec-env live abort` restores base from
-the receipt and re-isolates. It refuses if the primary checkout has uncommitted
-changes (it won't discard them) — commit or stash first.
-
-## 4. Report
-
-Echo which spec is now live on the primary checkout (and any warning), that it was
-released / recovered, or — for `status` — which branch the primary checkout is on
-and whether the instance is free. Fixes you make while live commit straight onto
-the spec's branch.