@skitterbyte/skitterspec 12.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.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-
@@ -155,6 +155,20 @@ no live `env.config.json` was found.
   // 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": []
   }
 }
 ```
@@ -165,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,14 @@ 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
@@ -77,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,13 +52,45 @@ 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
@@ -93,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-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-live/SKILL.md

@@ -18,7 +18,10 @@ 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. The engine enforces this and prints why.
+`/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
 

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

@@ -0,0 +1,99 @@
+---
+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".
+---
+
+# /spec-to-main — land the branch on main, keep the spec open
+
+The **intermediate** landing. `/spec-complete` also lands the branch, but then
+verifies every phase, flips the status to Complete, `git mv`s the spec to
+`complete/`, and tears the environment down. **`/spec-to-main` stops after the
+land**: the worktree stays, the spec stays `In Progress`, and you can land again
+as you add commits.
+
+Use it when a later phase can only be done *after* the current work is on `main` —
+e.g. it needs to run in CI, a deploy pipeline, or a shared test environment that
+builds from `main`. Land what you have, run that step, then come back and finish
+the remaining phases with `/spec-go` and eventually `/spec-complete`.
+
+It reuses the **same engine** as `/spec-complete`'s landing (`spec-env integrate`
+— rebase + fast-forward), so it produces identical linear history. Because a
+fast-forward leaves `base == branch`, the operation is **idempotent and
+repeatable**: new commits put the branch ahead of base again, and you can run
+`/spec-to-main` as many times as you like.
+
+## 0. Preconditions — when this applies
+
+- **Isolation must be on** (`specs/.core/env.config.json` exists **and** the spec
+  is on a worktree provisioned by `/spec-go`). If isolation is absent, there is
+  nothing to land — the spec is authored directly on `main` already. Say so and
+  stop.
+- **Feature / Bug specs only.** A **Hotfix** (`Type: Hotfix`) is built on a
+  release *tag* and cannot fast-forward onto `main` — refuse it and point the user
+  at `/spec-complete` (it lands a hotfix via tag + cherry-pick). Check the header
+  `> **Type:**` before proceeding.
+
+## 1. Identify the target spec
+
+- Use the name/path argument if given, else the spec **in context**. If unclear,
+  ask which spec.
+- Locate its folder under `specs/in-progress/`. Entry point is `00-overview.md`;
+  confirm `> **Status:**` is `In Progress` and `> **Type:**` is `Feature` or
+  `Bug`.
+
+## 2. Require a clean worktree
+
+The land rebases the branch — it refuses a dirty tree. If the worktree has
+uncommitted changes, 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 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`).
+
+## 3. Tests must be green before landing
+
+Don't push red to `main`. Run the project's typecheck and test commands **in the
+worktree**; the suite must be **green**. For a **Bug** spec, confirm the
+originally-failing test now passes. If anything is red, stop and report — landing
+broken code onto `main` defeats the purpose.
+
+(Note this is the *worktree* suite. The whole point of this skill is often to run
+a *further* check that only exists on `main` / in CI — that one runs **after** the
+land, in step 5.)
+
+## 4. Land — rebase + fast-forward
+
+Run `skitterspec spec-env integrate <name>` and run the printed commands **in
+order**:
+
+- `git -C <worktree> rebase <base>` — replay the branch onto base.
+- `git -C <mainRepoPath> merge --ff-only <branch>` — fast-forward base.
+
+On a **rebase conflict** (non-zero exit), run `git -C <worktree> rebase --abort`,
+relay the conflict, and **stop** — leave the resolution to the user; change
+nothing else.
+
+On a **no-op** ("already landed on `<base>` — nothing to integrate"), just say so
+and continue — the branch has no commits base doesn't already have.
+
+## 5. Re-test on base, then report
+
+- Run the project's test command **from the primary checkout** — base must be
+  **green** after the fast-forward.
+- Add a **Changelog** entry to `00-overview.md` recording the intermediate land
+  and *why*, e.g.
+  `- <YYYY-MM-DD> — Landed intermediate work onto <base> to <run CI / deploy to
+  test env / …>; spec stays In Progress.`
+- Do **NOT**: add a State-log row (status doesn't change), flip any phase/status
+  to Complete, `git mv` the spec, or tear down the worktree/stack. **The spec
+  stays `In Progress` and the worktree stays put.**
+- Report: the base branch, the fast-forward result, and the green base test. It
+  **never pushes** — mention the user can `git push` the base branch themselves to
+  trigger CI / the shared env.
+- Point the way forward: `/spec-go` to continue the remaining phases (you'll keep
+  committing on the same branch and can `/spec-to-main` again), and `/spec-complete`
+  when every phase is genuinely done — it will land the final commits, finalise,
+  and tear down.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "12.0.0",
+  "version": "13.0.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",