@skitterbyte/skitterspec 11.0.0 → 12.0.0

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

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

package/assets/core/env.config.md

@@ -146,6 +146,15 @@ 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": []
   }
 }
 ```

package/assets/rules/spec-planning.md

@@ -39,6 +39,20 @@ changes only when it merges. Teardown is folded into `/spec-complete` ·
 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
 ticketing provider is installed as its own distribution that plugs into two named

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

@@ -62,6 +62,12 @@ applies, offer to land the finished branch on the base branch so the work reache
 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.

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-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,70 @@
+---
+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. The engine enforces 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.

package/package.json

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