@skitterbyte/skitterspec 11.0.0 → 13.0.0

package/README.md

@@ -9,10 +9,10 @@ Spec-driven development for [Claude Code](https://claude.com/claude-code) — a
 ```
 
 Ships the spec-lifecycle skills (`/spec`, `/spec-go`, `/spec-complete`,
-`/spec-cancel`, `/spec-bug`, `/spec-review`, `/spec-init`) plus per-spec
-**isolation** — a git worktree per in-progress spec, Docker on demand, host dev
-servers on reserved ports, and `/spec-connect` to test a worktree at your normal
-`localhost` URL.
+`/spec-cancel`, `/spec-bug`, `/spec-hotfix`, `/spec-review`, `/spec-init`) plus
+per-spec **isolation** — a git worktree per in-progress spec, Docker on demand,
+host dev servers on reserved ports, and `/spec-connect` to test a worktree at your
+normal `localhost` URL.
 
 ```sh
 npx @skitterbyte/skitterspec init
@@ -44,6 +44,17 @@ no external install), so you test at the exact URL you always use.
 `/spec-connect main` hands the ports back. Exclusive: one spec at a time. See
 `specs/.core/env.config.md` for the `dev`/`proxy` config.
 
+## Production hotfixes — `/spec-hotfix`
+
+When prod is on a tagged release, a fix must be built on **that** version, not
+`main`. `/spec-hotfix <tag> <name>` forks a worktree from the tag, then works
+test-first like `/spec-bug`. `/spec-complete` lands it by patch-bumping the tag
+and tagging the branch (your CI/CD deploys the tag — you push it) and
+cherry-picking the fix onto `main`; `--also <tag>` patches extra release lines
+(test/demo). Hotfixes refuse `/spec-live` (their old-tag branch could break the
+running instance) — test them with `/spec-connect`. Tune the `hotfix` block in
+`specs/.core/env.config.md`.
+
 ## v3 — slimmer surface + `/spec-connect`
 
 **3.0** folds provisioning into `/spec-go`, teardown into

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

@@ -34,5 +34,8 @@
   "guards": {
     "refuseTeardownIfDirty": true,
     "refuseTeardownIfUnpushed": true
+  },
+  "live": {
+    "migrations": []
   }
 }

package/assets/core/env.config.md

@@ -4,8 +4,8 @@ Opt-in config for per-spec isolation (git worktree + optional namespaced Docker
 stack + host dev servers + a front-door proxy + an optional opener per
 in-progress spec). Provisioning is folded into `/spec-go`, teardown into
 `/spec-complete` · `/spec-cancel`, and traffic diversion is `/spec-connect`; the
-`skitterspec spec-env <up|down|dev|connect|integrate>` CLI is the engine beneath
-them.
+`skitterspec spec-env <up|down|prune|dev|connect|integrate>` CLI is the engine
+beneath them.
 
 **Once this file is present, isolation is the default policy:** `/spec-go` gives
 **every** in-progress spec its own git worktree automatically. Docker is a **per-
@@ -146,6 +146,29 @@ no live `env.config.json` was found.
   "guards": {
     "refuseTeardownIfDirty": true,
     "refuseTeardownIfUnpushed": true
+  },
+
+  // 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
+  // branch that changes any of them is treated as STATEFUL and `live take`
+  // refuses it (code-only v1 — use `/spec-connect` for those). Default: none.
+  "live": {
+    "migrations": []
+  },
+
+  // Hotfix landing (`spec-env hotfix land` / `/spec-complete` on a Type: Hotfix
+  // spec). A hotfix forks from a release tag and lands by tag + cherry-pick, not
+  // fast-forward. `bump` is the version-bump strategy for the new deploy tag (only
+  // "patch" today: v33.16.4 -> v33.16.5). `cherryPickMain` also cherry-picks the
+  // fix onto the base branch for the next release (default true). `targets` is an
+  // optional default list of extra base tags to also patch (test/demo lines);
+  // `--also <tag>` adds more at run time. Nothing is ever pushed — you push the
+  // deploy tag to trigger CI/CD. Default: patch, main, none.
+  "hotfix": {
+    "bump": "patch",
+    "cherryPickMain": true,
+    "targets": []
   }
 }
 ```
@@ -156,3 +179,26 @@ no live `env.config.json` was found.
 - `{repoSlug}` — `{repo}` lower-cased, non-alphanumerics collapsed to `-`
   (safe for a `COMPOSE_PROJECT_NAME`).
 - `{slug}` — the spec slug (folder name minus its `feat-`/`bug-` prefix).
+
+## Pruning orphaned test-DB volumes
+
+`spec-env down` drops the finished spec's own Docker volume, but volumes leak
+when that path is skipped — a declined/guard-aborted teardown, a manual
+`git worktree remove`, or `--keep-volumes`. Over many worktrees these orphaned
+DB volumes pile up and eat disk.
+
+`skitterspec spec-env prune` reconciles the live volumes in the
+`{repoSlug}_*` namespace against the specs that still have a **worktree** and
+lists the orphans (volumes owned by no live spec) plus the `docker volume rm`
+commands to remove them. It plans only — you run the printed commands — and it
+frees any stale registry slot for a reaped spec.
+
+- **Liveness = an existing worktree, not the registry** (the registry is what
+  goes stale). A spec with a live worktree — in any bucket, including one checked
+  out only on its branch — is always protected.
+- **No backup.** Unlike `spec-env down`, prune does **not** run
+  `backupCommand`: an orphan has no running DB to dump. Add `--older-than <days>`
+  to only reap volumes older than a cutoff (volumes of unknown age are kept).
+- `/spec-complete` and `/spec-cancel` run prune (confirm-first) as their last
+  teardown step, so orphans get swept as specs finish. You can also run it by
+  hand at any time to clear an existing backlog.

package/assets/rules/spec-planning.md

@@ -1,6 +1,6 @@
 # Spec Planning
 
-Spec-driven development is driven by seven lifecycle skills (plus `/spec-connect`
+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
 and lifecycle stay consistent. Each sets a status on the spec header
 (`> **Status:** …`):
@@ -9,8 +9,10 @@ and lifecycle stay consistent. Each sets a status on the spec header
 |-------|---------|--------|--------|
 | `/spec` | (Feature) Grill to a clear shared understanding, then write a groomed spec | `Ready` (or `Draft`) | `specs/backlog/` |
 | `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
+| `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag + cherry-pick | `In Progress` | `specs/in-progress/` |
 | `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
 | `/spec-go` | Provision the env, bring dev servers up, implement the next phase | `In Progress` | `specs/in-progress/` |
+| `/spec-to-main` | Land the branch on the base (rebase + ff) **without** finishing — for running the work in CI / a shared env mid-spec; repeatable | `In Progress` (unchanged) | (unchanged) |
 | `/spec-complete` | Verify all phases done + tests green; land + tear down | `Complete` | `specs/complete/` |
 | `/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) | — | — |
@@ -18,8 +20,12 @@ and lifecycle stay consistent. Each sets a status on the spec header
 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.
-`/spec-bug` is test-first and starts straight in `In Progress` (work begins
-immediately), so it skips Draft/Ready.
+`/spec-bug` and `/spec-hotfix` are test-first and start straight in `In Progress`
+(work begins immediately), so they skip Draft/Ready. `/spec-to-main` does **not**
+move the spec through the flow at all — it lands the branch on the base branch
+mid-spec (so the work can run in CI / a shared test env) while the spec stays
+`In Progress` in `specs/in-progress/`; it's the intermediate, repeatable half of
+`/spec-complete`'s landing, without the finalise-and-tear-down.
 
 **Per-spec isolation (opt-in to adopt, then the default policy).** When a project
 adopts isolation (`skitterspec init --isolation`, or `specs/.core/env.config.json`
@@ -35,9 +41,28 @@ 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|dev|connect|integrate>` is the CLI engine. Isolation is **orthogonal to
-lifecycle status** and inactive when `env.config.json` is absent — every skill
-then behaves as it does today.
+<up|down|prune|dev|connect|integrate|hotfix>` is the CLI engine. 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
+exception to "fork from `main`": `/spec-hotfix` forks the worktree from a release
+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`
+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
+checks it out **in the primary checkout**, so your running server hot-reloads the
+feature at the normal URL — no second stack, no proxy. The branch 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 (fixes you make while live commit
+straight onto the branch; `/spec-complete` is live-aware and lands them). Rule of
+thumb: **live overlay is the light default for code-only specs**; it *refuses*
+stateful ones (`Stack: worktree + docker`, or a branch touching migrations) — keep
+`/spec-connect` + a Docker stack for those, and for genuinely parallel testing.
+Beneath it, `skitterspec spec-env live <take|release|abort|status>` is the engine.
 
 **Ticketing-provider sync (opt-in, a separate package).** The base is
 tracker-free: it knows nothing about any specific ticketing system. A
@@ -63,16 +88,24 @@ consistent with the codebase:
 - **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
   (architecture, code style, testing, database, etc.) rather than restating them.
 
-## Spec types — Feature vs Bug
+## Spec types — Feature, Bug, Hotfix
 
-Every spec is one of two types, recorded **both** in the header and the filename:
+Every spec is one of three types, recorded **both** in the header and the filename:
 
-- **Header field:** `> **Type:** Feature` or `> **Type:** Bug` (authoritative,
-  greppable: `grep -rl 'Type:.*Bug' specs/`).
-- **Filename prefix:** `feat-<name>` for features, `bug-<name>` for bugs
-  (visible in listings; glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
+- **Header field:** `> **Type:** Feature`, `> **Type:** Bug`, or
+  `> **Type:** Hotfix` (authoritative, greppable:
+  `grep -rl 'Type:.*Hotfix' specs/`).
+- **Filename prefix:** `feat-<name>` for features, `bug-<name>` for bugs,
+  `hotfix-<name>` for hotfixes (visible in listings; glob-safe — never use
+  `[BUG]`/`[FEATURE]` brackets).
 
-Both types share the same lifecycle folders below — type is orthogonal to status.
+A **Hotfix** is a Bug fixed against a **released tag** rather than `main`: it
+carries an extra `> **Base version:** <tag>` header, forks its worktree from that
+tag, and lands by tagging a new patch + cherry-picking onto `main` (never a
+fast-forward merge). `/spec-live` refuses a hotfix — test it with `/spec-connect`.
+
+All three types share the same lifecycle folders below — type is orthogonal to
+status.
 
 ## Header fields & State log (audit trail)
 

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

@@ -64,5 +64,10 @@ 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`).
+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
+   the printed `docker volume rm` commands. Non-fatal: if it can't run or the user
+   declines, report and finish cancelling anyway.
 
 If `env.config.json` is absent, skip this entirely — behave exactly as before.

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

@@ -21,8 +21,9 @@ Before marking complete, confirm the work is actually finished:
   done in the code — tick it (`- [x]`) if so, or surface it if not.
 - Run the project's typecheck and test commands. The suite must be **green** to
   call a spec complete.
-- For a **Bug** spec (`Type: Bug`), confirm the originally-failing test named in
-  the spec now passes — that test is the proof the bug is fixed.
+- For a **Bug** or **Hotfix** spec (`Type: Bug` / `Type: Hotfix`), confirm the
+  originally-failing test named in the spec now passes — that test is the proof
+  the fix works.
 - If genuinely incomplete work remains, **stop and tell the user** rather than
   forcing completion. Offer to finish it (`/spec-go`) or to complete with the
   remaining items explicitly listed as deferred.
@@ -51,17 +52,55 @@ specs — `git log`/the per-spec State log give the completion order.
 Confirm the move, the final test result, and list anything deferred. Do **not**
 `git commit` unless the user asks.
 
-## 6. Integrate onto the base branch (opt-in, only if isolated)
+## 6. Land the branch (opt-in, only if isolated)
 
 **Only when `specs/.core/env.config.json` exists and the spec is on a worktree**
-(it was provisioned by `/spec-go`). Otherwise skip this entirely — a non-isolated
-spec has nothing to land, and `/spec-complete` behaves exactly as before. When it
-applies, offer to land the finished branch on the base branch so the work reaches
-`main` (or your configured `baseBranch`) in one flow:
+(it was provisioned by `/spec-go` or `/spec-hotfix`). Otherwise skip this entirely
+— a non-isolated spec has nothing to land, and `/spec-complete` behaves exactly as
+before. When it applies, offer to land the finished branch so the work reaches its
+destination in one flow. **How it lands depends on the spec type:**
+
+### 6-hotfix. `Type: Hotfix` — tag + cherry-pick (not fast-forward)
+
+A hotfix is built on an old release **tag**, so it can't fast-forward onto `main`.
+Use the hotfix landing instead of the integrate steps below:
+
+1. **Require a clean worktree** — the completion edits (status flip, `git mv` to
+   `complete/`) must be committed first. If dirty, offer `/commit` and **stop**.
+2. **Plan + execute.** Run `skitterspec spec-env hotfix land <name>` — add
+   `--also <tag>` for each extra release line to patch (test/demo on their own
+   versions). Run the printed commands **in order**. It:
+   - tags the hotfix branch with the **patch-bumped base tag** (the deploy tag) —
+     **created locally; you push it** (`git push origin <tag>`) to trigger CI/CD;
+   - for each `--also` target, cherry-picks the fix onto a throwaway worktree at
+     that tag and re-tags it;
+   - cherry-picks the fix onto `main` for the next release.
+   On a **cherry-pick conflict** (non-zero exit), run `git -C <checkout>
+   cherry-pick --abort` there, relay the conflict, and **stop** — don't offer
+   teardown.
+   On a **no-op** ("nothing to land"), say so and continue.
+3. **Re-test on `main`** after the cherry-pick — it must be **green**.
+4. **Report** the deploy tag(s) and the `main` cherry-pick. It **never pushes** —
+   remind the user to `git push origin <deploy-tag>` to deploy. Then teardown
+   (step 7) applies: a tagged hotfix branch tears down with **no `--force`**.
+
+### 6-feature/bug. `Type: Feature` / `Type: Bug` — rebase + fast-forward
+
+Land the finished branch on the base branch so the work reaches `main` (or your
+configured `baseBranch`) in one flow. (Need the work on `main` *before* the spec
+is finished — e.g. to run a later phase in CI or a shared test env? Use
+**`/spec-to-main`**: same rebase + fast-forward, but it leaves the spec
+`In Progress` and the worktree standing, and it's repeatable.)
 
 1. **Require a clean worktree.** The completion edits (status flip, the
    `git mv` to `complete/`) must be committed first — integrate refuses a dirty
    tree. If it's dirty, offer `/commit` and **stop**; don't auto-commit.
+   **If the spec is live** (you took the running instance with `/spec-live`):
+   `integrate` is live-aware — it ends the live session first (releases the branch
+   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.
 2. **Plan + execute.** Run `skitterspec spec-env integrate <name>` and run the
    printed commands **in order**:
    - `git -C <worktree> rebase <base>` — replay the branch onto base.
@@ -87,9 +126,20 @@ directly (the old `/spec-env-down` skill is gone — teardown is folded in here)
 2. **Stop its host dev servers:** `skitterspec spec-env dev down <name>` (a
    no-op when none are running / configured).
 3. **Remove worktree + stack + slot:** run `skitterspec spec-env down <name>`
-   and execute the commands it prints, in order. Post-integrate the branch is
-   merged into base, so teardown needs **no `--force`** and deletes the branch
-   (`git branch -d`) as part of the plan. It still respects the guards (won't
-   destroy a dirty or unpushed-and-unmerged worktree without `--force`).
+   and execute the commands it prints, in order. After a **feature/bug** landing
+   the branch is merged into base, so teardown needs **no `--force`** and deletes
+   the branch (`git branch -d`). After a **hotfix** landing the branch isn't
+   merged (it was tagged + cherry-picked), but its head is captured by the deploy
+   tag, so teardown still needs no `--force` and drops the branch with
+   `git branch -D` (the tag holds the commits). It still respects the guards (won't
+   destroy a dirty, or unpushed-and-unlanded, worktree without `--force`).
+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
+   `git worktree remove`, or `--keep-volumes`. Show the user the orphan list and,
+   **only on their confirmation**, execute the printed `docker volume rm`
+   commands. Non-fatal: if prune can't run (Docker down) or the user declines,
+   report it and finish completing anyway — never block the spec on it. Skip when
+   Docker isn't in use (the command self-reports "no orphaned volumes").
 
 If `env.config.json` is absent, skip this entirely — behave exactly as before.

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

@@ -15,6 +15,12 @@ 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**

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

@@ -98,7 +98,9 @@ runnable — its UI/API on the spec's reserved port block, isolated from `main`.
 - **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.
+  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.
 
 ## 3. Pre-flight — commit prior work
 

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

@@ -0,0 +1,161 @@
+---
+name: spec-hotfix
+description: Fix a production bug on the exact released version — fork a worktree from a release tag, drive it red→green like /spec-bug, then land it by tagging a new patch (for CI/CD to deploy) and cherry-picking the fix back onto main. ALWAYS starts from a base tag and works on the hotfix's own branch, never on main. Creates specs/in-progress/hotfix-<name>/00-overview.md. Use when the user says "/spec-hotfix", "hotfix <tag>", "prod is broken on <version>", "patch the released version", or needs a fix shipped against a tagged release rather than main.
+---
+
+# /spec-hotfix — fix a released version, tag it, cherry-pick back to main
+
+This is the **hotfix** counterpart to `/spec-bug`. Same test-first discipline
+(reproduce as a **failing test (RED)**, then drive to **GREEN**), but the base is
+a **release tag**, not `main`: prod is running a tagged version, so the fix must
+be built on **that** commit line, shipped as a **new patch tag** (your CI/CD
+deploys tags), and only then cherry-picked onto `main` for the next release.
+
+Spec type convention (see `.claude/rules/spec-planning.md`):
+- Hotfix specs are named `hotfix-<kebab-name>`; every header carries
+  `> **Type:** Hotfix` and `> **Base version:** <tag>`.
+- Branch is `hotfix/<slug>`, forked from the base tag.
+
+**Isolation is required.** A hotfix forks a worktree from a tag and lands by
+tag + cherry-pick — it needs the isolation engine (`specs/.core/env.config.json`).
+If isolation is absent, say so and stop; there is no in-place path.
+
+## 1. Establish the base version (the tag)
+
+- Take the release tag from the argument — `/spec-hotfix <tag> <name>` (e.g.
+  `/spec-hotfix v33.16.4 login-crash`). If it's missing, **ask which version prod
+  is running** — don't guess.
+- **Verify the tag exists** before anything else:
+  `git rev-parse --verify <tag>^{commit}`. If it doesn't resolve, stop and ask.
+
+## 2. Reproduce & isolate (light investigation)
+
+Hotfixes are concrete — confirm, don't over-grill. Establish:
+
+- **Repro:** exact steps / input that triggers it on the released version.
+- **Expected vs actual:** what *should* happen vs what does.
+- **Root cause:** read the code **at the base tag** and trace it to `file:line`.
+  The fix belongs on the tag's line, so reason about that code, not `main`'s.
+
+## 3. Seed the stub, then provision the worktree from the tag
+
+The engine forks the worktree from the spec's `Base version`, so the stub — with
+that header — must exist **before** `spec-env up`:
+
+- From the base branch (`main`), create
+  `specs/in-progress/hotfix-<name>/00-overview.md` with the header block
+  (including `> **Type:** Hotfix` and `> **Base version:** <tag>`) and the
+  `## Symptom` you established. It starts in `in-progress` — work begins now.
+- Run `skitterspec spec-env up hotfix-<name>`. It prints a `git worktree add …
+  -b hotfix/<slug> <tag>` command (the branch forks from **the tag**, not
+  `main`), the worktree path, the opener, and any `in the worktree, run:`
+  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/`.
+- **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
+  anything else.
+- **Trust the worktree for this session.** The engine wrote the printed
+  `trusted:` root into `.claude/settings.local.json`, but it won't hot-reload now
+  — run `/add-dir <trusted root>` before editing into the worktree, or the first
+  edits will prompt.
+- **Do everything below in the worktree**, on the `hotfix/<slug>` branch — the red
+  test, the fix, and the rest of the spec. Act with absolute paths /
+  `git -C <worktreePath>`, or open a fresh session rooted there. `main` changes
+  only at `/spec-complete` (via cherry-pick, not merge).
+
+## 4. Write the failing test FIRST (RED) — mandatory
+
+Encode the **correct** (expected) behaviour as a test, then run it and confirm it
+**fails for the right reason**, on the hotfix branch:
+
+- Put it where the suite already covers that area. Reuse existing test helpers /
+  factories; follow the project's test rules (see `.claude/rules/`). Never
+  hardcode dates — compute them relative to now.
+- Run it with the project's test command. Quote the red output. A test that
+  passes before the fix proves nothing — keep refining until it genuinely
+  captures the bug on this version.
+
+## 5. Write the Hotfix spec
+
+Flesh out `00-overview.md` in the worktree (you seeded the stub in §3). A hotfix
+is usually a single-pass fix, so the `## Fix` block can live directly in
+`00-overview.md`. Keep it lean:
+
+```markdown
+# Hotfix: <short title>
+
+> **Type:** Hotfix
+> **Status:** In Progress — fixing (red test added)
+> **Author:** <git user.name — who reported/captured it>
+> **Developer:** <git user.name — you, since you're fixing it now>
+> **Base version:** <tag prod is running, e.g. v33.16.4>
+> **Raised:** <YYYY-MM-DD (today)>
+> **Area:** <files/modules>
+
+## Symptom
+
+<observed wrong behaviour on the released version + repro steps; paste any error>
+
+## Root cause
+
+<the actual cause, at `file:line` on the base tag. One paragraph — be specific.>
+
+## Failing test (red)
+
+<test name + path; what it asserts. How to run it. Paste the red failure line.>
+
+## Fix
+
+- [ ] <the minimal change that addresses the root cause, not the symptom>
+- [ ] Failing test now passes (GREEN); run the project's typecheck and test
+      commands — confirm no regressions.
+- [ ] <any follow-up hardening, or "None">
+
+## Landing
+
+- [ ] Deploy tag (patch bump of the base version) created at `/spec-complete`
+      and pushed **by you** to trigger CI/CD.
+- [ ] Fix cherry-picked onto `main` (and any `--also` release lines).
+
+## State log
+
+| Date | Status | Folder | By |
+|------|--------|--------|----|
+| <YYYY-MM-DD> | In Progress | in-progress | <developer> |
+
+## Changelog
+
+- <YYYY-MM-DD> — Hotfix reproduced on <tag>; failing test added (red).
+```
+
+Keep the **State log** (state transitions) separate from the **Changelog** (fix
+narrative and decisions).
+
+## 6. Drive to GREEN
+
+- Implement the **minimal, root-cause** fix on the branch. Match surrounding code;
+  honour all project rules (see `.claude/rules/`).
+- Re-run the failing test → it must pass. Then run the project's typecheck and
+  test commands to confirm no regressions. Quote results.
+- Commit the fix to the `hotfix/<slug>` branch (this commit is what gets tagged
+  and cherry-picked). Tick the Fix tasks; add a Changelog line.
+
+## 7. Report
+
+Summarise: the base tag, root cause, the failing→passing test, the fix, and the
+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).
+- 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
+  (test/demo on their own versions).
+
+Do **not** `git push` or `git tag`-and-push unless the user asks — deploying to
+prod is theirs to trigger.

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

@@ -13,6 +13,14 @@ clobber customised content. Finish with a summary of created vs already-present.
 > all of the below mechanically. This skill is the manual/repair path and is
 > useful when the package isn't available or you only need to fix part of the
 > setup.
+>
+> **Re-running on an already-set-up repo is safe.** `init` detects the existing
+> setup (via the committed `specs/.core/.skitterspec-manifest.json` of installed
+> file hashes) and, interactively, offers three paths — **Resync** (update managed
+> skills/rules to the latest but keep files you've edited), **Start again** (reset
+> the managed scaffolding fresh — never your specs or config, with a confirm), or
+> **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
+> `--reset` (reset needs `--yes`) drive the stronger actions.
 
 The system is **eight skills**: `spec` (feature), `spec-bug` (bug), `spec-ready`,
 `spec-review`, `spec-go`, `spec-complete`, `spec-cancel`, and this `spec-init`. The lifecycle is

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

@@ -0,0 +1,73 @@
+---
+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.