@skitterbyte/skitterspec 17.0.0 → 19.0.0

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

@@ -1,41 +1,77 @@
 ---
 name: spec-start
-description: Put a spec in flight on this checkout — provision its branch, move it to in-progress, refresh the tracker, then build phase 1. Refuses unless the checkout is on the base branch with nothing already in flight, so it never parks or swaps someone's unfinished work. Use when the user says "/spec-start", "start this spec", or "begin implementing <spec>".
+description: Put a spec in flight — provision its branch, move it to in-progress, refresh the tracker, then build phase 1. Commits the spec itself when that is all that is uncommitted, and refuses to touch anyone else's unfinished work. Use when the user says "/spec-start", "start this spec", or "begin implementing <spec>".
 ---
 
 # /spec-start — put a spec in flight
 
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
 One checkout, one spec in flight. This skill is how a spec gets there:
 provision, move it to `in-progress`, refresh the tracker, then hand straight on
 to `/spec-next` for phase 1. Continuing a spec afterwards is `/spec-next`;
 finishing it is `/spec-complete`.
 
-## 1. The gate — refuse unless the workbench is free
+## 1. The gate — what each mode demands of the tree
 
-**Check this first, before resolving anything or touching a file.** In
-`worktree` mode run `skitterspec spec-env live status`; in `checkout` mode read
-the current branch. The workbench must be:
+**Check this first, before resolving anything or touching a file.** What the
+gate demands depends on the mode, because the two modes hold work in different
+places — read `mode` from `specs/.core/env.config.json` (default `worktree`).
 
-- **on the base branch** (`main`, or the configured `baseBranch`), and
-- **clean** — no uncommitted changes.
+**`worktree` mode — there is no tree gate.** The spec is built in its own
+worktree, so neither another spec being in flight nor its uncommitted files are a
+conflict; both are the parallelism the mode exists for. `git worktree add`
+carries nothing and forks from a commit, and the one thing this run writes into
+the checkout — the spec's own commit, which `spec-env up` plans for you — names
+its paths on both the `add` and the `commit`, so it cannot reach a file that is
+not this spec's. Work belonging to someone else is **reported and left alone**,
+never a refusal. Nothing is switched here and nothing is parked.
 
-**If it isn't, relay what is in flight and stop.** Name the spec holding the
-checkout and the three ways out, then end your turn:
+**`checkout` mode — the workbench must be free**: on the base branch (`main`, or
+the configured `baseBranch`) and clean, since the branch is built right here and
+this mode holds one spec at a time. If it isn't, relay what is in flight and
+stop — name the spec holding the checkout and the two ways out, then end your
+turn:
 
 - **`/spec-complete`** — it's finished; land it and free the workbench.
 - **`/spec-cancel`** — it isn't wanted; record why and free the workbench.
-- **`/spec-live main`** *(worktree mode)* — park it: the branch goes back to its
-  worktree and stays exactly as it is, ready to resume later.
 
-**Never get past the gate yourself.** Do not stash, do not commit on the
-operator's behalf, do not `/spec-live main` for them, do not switch branches. An
-uncommitted tree, a half-built phase and a rebase are each a decision someone
-must make deliberately — and the cost of guessing is another spec's work moved
-without its author asking. A refusal costs one command; the alternative can cost
-an afternoon.
+**Never get past the gate yourself.** Do not stash, do not commit
+**another spec's** work, do not switch branches for them. An uncommitted tree
+and a half-built phase are each a decision someone must make deliberately — and
+the cost of guessing is another spec's work moved without its author asking. A
+refusal costs one command; the alternative can cost an afternoon.
+
+**What `spec-env up` does with the tree**, in both modes — relay what it says
+rather than deciding for yourself:
+
+| What it found | `worktree` | `checkout` |
+|---------------|-------------|-------------|
+| clean | provisions | provisions |
+| every path is this spec's | commits those paths **first**, then forks | same, then switches |
+| some path is not | commits this spec's, provisions, **reports the rest** | refuses, naming them |
+
+That is membership in an exactly-known set — the spec's own folder plus the
+project's `spec.companionPaths` — and **not** a judgement about whether the
+changes look important. It never decides that.
 
-A dirty tree is refused *with the same words whatever the cause*: the gate does
-not try to judge whether the changes look important.
+**The last row is the only real difference, and it is mechanical.**
+`git switch -c` carries the working tree onto the new branch, so in
+`checkout` mode a colleague's files really would be moved without them asking.
+`git worktree add` carries nothing, so in `worktree` mode the same files are
+simply not this run's business — and refusing over them fired on the commonest
+tree this workflow produces: a second spec authored while the first is still
+uncommitted. When it reports them, say how many and whose in the `Untouched` row
+and **keep the verdict `✅`** — nothing went wrong.
+
+When it plans the commit, the paths are printed above the commands, so run them
+as printed; when it refuses, relay the reason and stop.
+
+It also refuses a **clean** tree whose spec is not in the commit the worktree
+would fork from — otherwise you get a branch missing the very spec it is for.
 
 ## 2. Identify the spec
 
@@ -48,65 +84,201 @@ not try to judge whether the changes look important.
   spec is a `<name>/` folder whose entry point is `00-overview.md`, with one
   file per phase beside it (`01-<slug>.md`, `02-…`). Legacy specs may be a bare
   `<name>.md`, or a `00-overview.md` with inline phases — handle those too.
-- A spec already in `specs/in-progress/` was started before. If its branch is
-  parked in a worktree, this skill brings it back into flight; say so rather
-  than reporting a fresh start.
+- A spec already in `specs/in-progress/` was started before. Its worktree
+  probably still exists, so this is a re-attach: say so rather than reporting a
+  fresh start, and skip the housekeeping that is already done.
+
+## 2b. Bring the review server up — from here, before anything else
+
+**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
+present). Without it there is no review server and this step does not exist —
+skip it in silence rather than explaining an absence.
 
-## 3. Put its branch in this checkout
+```
+skitterspec spec-env review serve --host 0.0.0.0
+```
 
-**Read `mode` from `specs/.core/env.config.json`** (default `worktree`).
+**Here is the point.** Right now this session is standing in the
+**primary checkout**, and in a moment step 3 `cd`s into a worktree and stays
+there. A
+daemon started after that `cd` is started *by the worktree's copy of the code* —
+and when `/spec-complete` removes that worktree, the daemon keeps answering on
+its port and fails on every page it is asked for, for every spec. The engine
+defends against that now, but the cheapest fix is to never create the situation:
+start it while you are still somewhere that outlives the spec.
+
+It is also what lets **several specs be reviewed at once**. Reviews all render
+into the primary checkout's `.spec-env/reviews/`, so one server serves every
+provisioned spec — including specs another agent is building in another
+worktree. Starting it here means that one server belongs to the checkout none of
+them can delete.
+
+**Say nothing when it is already up.** The usual outcome is adoption — a server
+is running and this changes nothing — and a line per `/spec-start` about a
+daemon nobody asked about is the narration `.claude/rules/spec-reports.md`
+forbids. Speak only if it could not start.
+
+**Never fatal, never a gate.** A busy port, no network address, a refused
+spawn — say it in one line and **carry on**; provisioning is not conditional on
+it, and the page falls back to its `file://` URL exactly as it does today.
+
+**`--host 0.0.0.0` is the deliberate half.** It binds the server to this
+machine's network addresses so the page opens on a phone, and the engine mints a
+token with that bind as its only guard. On a machine you would rather not expose,
+drop the flag — the server is then reachable from this machine alone and the
+render says so. On **`--plan`** this step does not run at all.
+
+## 3. Build its branch
 
 ### `worktree` mode
 
+**One path. There is no branching here and none should be added back.**
+
 1. **Provision.** Run `skitterspec spec-env up <name>` — a planner, so run the
-   `to provision, run:` commands it prints and confirm they succeeded. Then run
-   its **`then, in the worktree, run:`** steps in order (file seeding, then
-   `setup`): a fresh worktree has no dependencies and none of the repo's
-   gitignored files, so hooks, typechecks and tests fail until they are there.
-2. **Bring the branch here.** Tell the user to type **`/spec-live <name>`** — it
-   rebases the branch, frees it from the worktree and checks it out in this
-   checkout, which is what makes this session the workbench. It is a user-only
-   command, so you cannot run it: print it, end your turn, and pick up at step 4
-   when they re-run `/spec-start`.
-   **Already here?** If the live check in step 1 showed this spec live, or the
-   branch is already checked out, the move is done — carry straight on.
-3. **A spec the live overlay refuses** — a hotfix, a stateful spec
-   (`Stack: worktree + docker`), or a branch touching migrations — **parks
-   instead.** Do the housekeeping in step 4 with `git -C <worktreePath>`, run
-   `open.command` if configured, print the worktree path, and say to run
-   `/spec-next` from a session there. Relay the engine's refusal reason as it
-   printed it; those guards protect a shared dev instance and are not yours to
-   weaken.
-   **Trust the worktree first.** `spec-env up` wrote the printed `trusted:` root
-   into `.claude/settings.local.json`, but that file will not hot-reload in this
-   session — run `/add-dir <trusted root>` before editing into the worktree, or
-   the first write prompts.
+   `to provision, run:` commands it prints and confirm they succeeded.
+
+2. **Trust the worktree.** `spec-env up` wrote the printed `trusted:` root into
+   `.claude/settings.local.json`, but that file does not hot-reload in this
+   session — run **`/add-dir <trusted root>`** before editing into the worktree,
+   or the first write prompts. This is not tab machinery: worktrees live outside
+   the checkout, and the trust entry is what stops the prompt.
+
+3. **Bootstrap it, and move into it.** The `cd` is in the command itself, and it
+   **moves this session** — that is what it is for, not a side effect of it. The
+   Bash working directory persists between calls, so from here on this session is
+   standing in the worktree, which is what lets a bare `/spec-next` resolve the
+   spec on its own:
+
+   ```
+   cd "<worktreePath>" && <the planner's "then, in the worktree, run:" steps>
+   ```
+
+   Run the seeding steps before `setup`: a fresh worktree has no dependencies and
+   none of the repo's gitignored files, so hooks, typechecks and tests fail until
+   both have happened.
+
+   **Then confirm the move landed — never assume it.** Ask for a positive signal
+   rather than reading silence as success (`.claude/rules/negative-checks.md`
+   rule 1): run `skitterspec spec-env resolve` with **no argument** and read the
+   `spec:` line it prints.
+
+   ```
+   skitterspec spec-env resolve        # must name this spec
+   ```
+
+   Three states, not two. It names this spec → carry on. It names something else,
+   or resolves nothing → **the `cd` did not take**. Say so plainly and fall back
+   to the stop-here ending in step 6, printing the path so the operator can open
+   a session there themselves; do not build a phase from a session whose location
+   you could not confirm. A failed `cd` leaves you in the primary checkout on the
+   base branch, where a phase's worth of code looks entirely normal at the time.
+
+4. **Housekeep with `git -C <worktreePath>`** — step 4 below, against the
+   worktree.
+
+   **Keep the `-C` prefix**, even though the session is inside the worktree now
+   and a bare `git` would usually do the same thing. It is immune to the one
+   failure this sequence can have — a `cd` that silently did not take — where a
+   bare `git` would instead write the spec's move into the primary checkout on
+   the base branch. It costs nothing and removes a whole failure mode, so do not
+   tidy it away.
+
+5. **Print the worktree path.** What happens next is step 6 — it is offered
+   there, not decided here.
+
+**The session moves into the worktree, and nothing opens a window.** Those are
+two different claims and both are load-bearing. The move is real, and the `cd` in
+step 3 is its whole mechanism — no tool call, because an approval prompt is
+unusable on a phone and leaves the session stuck. Nothing is *spawned*: no new
+terminal, no tab, no editor sent anywhere, because that machinery had nothing
+left to do and was removed deliberately.
+
+**Do not move the branch into this checkout**, and do not ask the operator to.
+`/spec-live` is for testing a finished-enough spec on the already-running dev
+server; it is not how work gets started.
+
+**`/spec-next`'s refusal is unchanged by this.** Its rule 2 — "the worktree you
+are standing in" — is what answers afterwards, and step 3 is what puts the session
+there; nothing about rules 1 to 3 is loosened, and it must stay that way, because
+the refusal exists so the wrong branch is never built. What changed is where the
+session stands, not how weakly the rules read: a bare `/spec-next` typed from
+somewhere that is neither a worktree nor a live checkout still refuses exactly as
+it did. `--worktree <path>` survives untouched beside it — it answers before those
+rules and cannot be reached by guessing.
+
+**And the `cd` is a convenience, not the only thing holding this together.**
+`/spec-next`'s **rule 4** asks the engine for the sole provisioned spec, so a
+bare `/spec-next` resolves this spec from anywhere in the repo — after a
+`/clear`, from a new tab, tomorrow morning. That is what makes step 6's
+stop-here ending an honest offer rather than a promise only this session can
+keep. Do not delete rule 4 as redundant with the `cd`: the `cd` is session state,
+and rule 4 is what is left once it is gone.
 
 ### `checkout` mode
 
 Run `skitterspec spec-env up <name>` and the single `git switch` it prints.
-There is no worktree, no bootstrap, no live step — the checkout is already the
+There is no worktree, no bootstrap and no hand-off — the checkout is already the
 workbench. Its planner enforces the same gate from the engine side, so relay any
 refusal and stop.
 
 ## 4. Move the spec into development
 
-On the branch, in this checkout (or via `git -C <worktreePath>` for a parked
-spec):
+**Do this before you report anything**, so no path can end with a provisioned
+worktree and a spec still reading `Ready` in `specs/backlog/`. In `worktree` mode
+run it against the worktree with `git -C <worktreePath>`; in `checkout` mode the
+branch is already here.
 
 - `git mv "specs/backlog/<name>" "specs/in-progress/<name>"` if it isn't there
   already (`mkdir -p specs/in-progress` first). Use `git mv` to keep history.
 - Set the **Status** header: `> **Status:** In Progress — Phase 1 (started <YYYY-MM-DD>)`.
 - Set **Developer** if it is still `—` (`git config user.name`).
+
+
+
 - Append a **State log** row: `| <YYYY-MM-DD> | In Progress | in-progress | <git user.name> |`.
-- **Commit it, and push the branch.** One commit, the spec's own — it records the
-  in-progress state for everyone and fires the tracker's automation. Do this
-  *before* the tracker refresh below, so the snapshot that refresh writes is
-  swept up by the phase's own commit rather than left dirty.
+
+
+
+- **Commit it.** One commit, the spec's own — it records the in-progress state on
+  the branch, and sweeps up everything above so the worktree is clean when you
+  hand it over.
+
+**Publishing that branch is yours to do, and nothing here does it for you.**
+Whenever you want the work somewhere other than this machine:
+
+```
+git -C <worktreePath> push -u origin <branch>
+```
+
+Print it if it is useful; never run it. This skill once pushed here, justified as
+recording the state "for everyone" and firing the tracker's automation — and
+neither half survives reading. The automation needs `{identifier}` in
+`branch.pattern` (see `env.config.md`) to put an issue id in the branch name, and
+the shipped default carries none, so the tracker has nothing to match. Nor was it
+an invariant: `/spec-bug` provisions a worktree the same way and has never
+pushed, and `/spec-hotfix` forbids it outright. This was the odd one out.
+
+**It also kept a guard from ever firing.** `refuseTeardownIfUnpushed` blocks
+teardown on commits that are unpushed and unlanded — which described no branch at
+all while this skill published every one of them at provisioning. It can fire now,
+and the place it does is `/spec-cancel`, where the work really is about to be
+destroyed: that skill relays the refusal and offers both ways out. Nothing to do
+here beyond knowing it is no longer dead code.
 
 A spec ideally arrives `Ready` from `/spec`; a `Draft` works too — sanity-check
 it is well-formed first.
 
+## 4b. Note a missing gating decision (only if configured)
+
+**Only when `specs/.core/gating.config.json` exists.** Run
+`skitterspec gating check <name>` and, if it names this spec, mention it **once**
+before phase 1 starts — the cheapest moment to decide is before any code exists.
+
+**This check is advisory.** It reports; it never refuses, and nothing below is
+conditional on it. A spec written before the project adopted gating has no header
+and is not broken — turning this into a gate would accuse the very specs the
+feature was designed not to disturb.
+
 ## 5. Bring the spec's dev servers up — confirm before heavy steps
 
 **Only when the project configures host dev servers** (`env.config.json` → a
@@ -121,10 +293,80 @@ invoke it yourself.
 
 ## 6. Build phase 1
 
-**Carry straight on into `/spec-next`** in this session: it marks phase 1
-started, refreshes the mirror again, builds it with tests and reports. Do not
-stop and ask the operator to run it — the workbench is set up and they asked to
-start the spec.
+**`checkout` mode — carry straight on into `/spec-next`** in this session: it
+marks phase 1 started, refreshes the mirror again, builds it with tests and
+reports. Do not stop and ask the operator to run it: the branch is here and they
+asked to start the spec.
+
+**`worktree` mode — offer it, then do what they say.** Step 3 left this session
+standing in the worktree, so both endings happen right here and neither needs a
+second session opened anywhere. In prose: say the worktree is ready and name its
+path, then ask **"build phase 1 now?"** — recommending that they do, and naming
+both endings so the decline is a real answer rather than a formality.
+
+**Never fence that question.** A grey box is read as an artefact to skim rather
+than as something someone is being asked, which is the whole reason
+`.claude/rules/spec-reports.md` bans fencing a message to the reader. This step
+prescribed a fenced block for a long time and an operator read straight past it,
+which is the evidence, not a preference.
+
+- **Build it here** — carry on into a bare **`/spec-next`**. Bare is right: the
+  session is in the worktree, so its rule 2 resolves this spec with nothing
+  passed and nothing guessed.
+- **Stop here** — the operator is left standing in the worktree on a provisioned
+  branch, which is a perfectly good place to leave things. Nothing has to be
+  reopened or handed anywhere, and `/spec-next` typed an hour later — from this
+  session or a fresh one — does exactly what it would have done now.
+
+**Ask rather than deciding for them, and mean it.** Provisioning is cheap and
+reversible; a phase build is neither, and one yes should not cover both. A large
+phase is often better started in a session of its own with a whole context budget
+to spend, and only the operator knows which this is. On **`--plan`** this step
+does not run at all — nothing was provisioned to build in.
+
+**`--worktree <path>` is still there, and is still not a way around the refusal.**
+It builds a spec the session is *not* standing in, which after step 3 is the
+exception rather than the normal path. Reach for it in exactly two cases: the
+confirm in step 3 reported the `cd` did not take, or you deliberately mean to
+build some other spec's phase from here. A path someone typed is not a path
+anything guessed, which is why it was never a loosening of the refusal and still
+is not.
+
+## 7. Report
+
+**When step 6 carried on into `/spec-next`, emit no block here.** That skill ends
+with its own, and its `Branch` and `Spec` fields already carry everything this
+one would say. Two blocks for one run is the noise the contract exists to
+remove — this section is for the run that stops at step 6.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — the branch is provisioned, the spec is `in-progress`, the session is
+  standing in the worktree.
+- `⚠️` — provisioned, with something worth knowing (dev servers that did not
+  come up, a mirror that did not refresh, a missing gating decision).
+- `❌` — provisioning failed part-way and left something behind. Say what, and
+  where.
+- `⏸` — the gate refused: in `checkout` mode a dirty tree or someone else's
+  unfinished work, in either mode a spec whose own files are not in the commit
+  the worktree would fork from. Nothing changed. Another spec's uncommitted work
+  is **not** on this list in `worktree` mode — it is an `Untouched` row on a
+  `✅`.
+
+**Fields:** `Tracker` · `Branch` · `Spec` · `Worktree` · `Untouched` · `Follow-ups` · `Next`
+
+`Worktree` carries the path, because the session is now standing in it and the
+operator's next command depends on knowing that. `Next` is `/spec-next`.
+
+`Untouched` appears only when `spec-env up` reported uncommitted work that was
+not this spec's — say how much and whose, and **keep the verdict `✅`**. Nothing
+went wrong: a worktree carries nothing, so that work was never in play.
+
+On **`--plan`** nothing was provisioned, so the verdict is `⏸` and `Built`
+carries the plan rather than a claim about the repo.
 
 ## Opt-outs
 
@@ -133,14 +375,29 @@ start the spec.
   that the work lands wherever you are (usually the base branch); reserve it for
   a trivial change or an explicit request.
 
-There is no `--here`: `/spec-start` **is** here. It puts the branch in the
-checkout you are in, which is what the old opt-out was reaching for.
+There is no `--here`. It existed to ask for the branch in the checkout you are
+standing in — and in `checkout` mode that is already what happens, while in
+`worktree` mode `--no-worktree` is the way to say it.
+
+## Why this skill links nothing, but does mirror what it changes
+
+This skill creates no spec and mints no issue, so it has **nothing to link** —
+the intake and picker steps belong to `/spec`, `/spec-bug` and `/spec-hotfix`.
 
-## Why there is no tracker seam here
+It does push, though, and that is step 4's seam. The state change it makes — the
+spec moving to `in-progress` with a developer stamped on it — is mirrored by the
+skill that makes it, exactly as `/spec-complete`, `/spec-cancel` and
+`/spec-review` mirror theirs. It was once reasoned that the refresh `/spec-next`
+runs would cover it, so a push here would send the same thing twice one commit
+apart. That only ever held in `checkout` mode, where `/spec-next` follows
+immediately; in `worktree` mode it can be hours away or never come, and the
+issue sits in its old state with nobody assigned meanwhile.
 
-This skill creates no spec and mints no issue, so it has nothing to link — the
-intake and picker steps belong to `/spec`, `/spec-bug` and `/spec-hotfix`. The
-state change it *does* make (the spec moving to `in-progress`) is mirrored by
-the refresh `/spec-next` runs the moment it starts, which pushes the issue state
-and the phase states together. Adding a push here would send the same thing
-twice, one commit apart.
+The **assignment** seam just above it is still not a push, and does not need to
+be. This is the one moment in the lifecycle where "who is building this" is
+actually decided — the branch is being provisioned for someone, and that someone
+is at the keyboard. It stamps the spec file and stops there, so it costs no
+tracker call and rides out on the push below like every other field. Deferring
+the stamp to `/spec-next` would be worse than untidy: in `worktree` mode the two
+can be separated by hours, and a spec in flight with nobody named on it is
+exactly the gap assignment exists to close.

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

@@ -6,11 +6,16 @@ disable-model-invocation: true
 
 # /spec-to-main — land the branch on main, keep the spec open
 
+> Stay silent while this runs — speak only to ask something you cannot answer
+> yourself, or to report a failure at the moment it happens. Read
+> `.claude/rules/spec-reports.md` before reporting; it defines the block this
+> skill ends with.
+
 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.
+`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
@@ -19,9 +24,9 @@ the remaining phases with `/spec-next` 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.
+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
 
@@ -58,10 +63,10 @@ primary checkout is dirty, or if a *different* spec holds it (release that one w
 
 ## 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.
+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
@@ -69,8 +74,8 @@ land, in step 5.)
 
 ## 4. Land — rebase + fast-forward
 
-Run `skitterspec spec-env integrate <name>` and run the printed commands **in
-order**:
+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.
@@ -91,12 +96,29 @@ and continue — the branch has no commits base doesn't already have.
   `- <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
+  to Complete, `git mv` the spec, or tear down the worktree/stack.
+  **The spec stays `In Progress` and the worktree stays put.**
+- It **never pushes** — say the user can `git push` the base branch themselves to
   trigger CI / the shared env.
-- Point the way forward: `/spec-next` 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.
+- `Next` points the way forward: `/spec-next` 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.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**Verdicts**
+
+- `✅` — the branch is on the base and the base is green.
+- `⚠️` — landed, with something worth knowing.
+- `❌` — the rebase conflicted, or the base went red after the fast-forward.
+  Quote it; the repo is mid-something and that is what the reader needs.
+- `⏸` — a dirty worktree, red tests, or no spec to land. Nothing moved.
+
+**Fields:** `Branch` · `Tests` · `Landed` · `Follow-ups` · `Next`
+
+**No `Spec` field, deliberately.** This skill changes no status and moves no
+folder, and a `Spec` line here would read as though it had. The spec stays
+`In Progress` and the worktree stays standing — if that needs saying, the
+verdict clause says it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@skitterbyte/skitterspec",
-  "version": "17.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.",
+  "version": "19.0.0",
+  "description": "Spec-driven development for Claude Code \u2014 a tracker-free filesystem workflow: lifecycle skills and per-spec isolation. For Linear sync, install @skitterbyte/skitterspec-linear instead.",
   "keywords": [
     "claude",
     "claude-code",
@@ -23,14 +23,18 @@
     "MIGRATION.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.13"
   },
   "dependencies": {
     "prompts": "^2.4.2"
   },
+  "scripts": {
+    "prepare": "node ../../scripts/build-dist.js skitterspec",
+    "prepack": "node ../../scripts/build-dist.js skitterspec"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/skitterbyte/skitterspec.git"
-  },
-  "scripts": {}
-}
+    "url": "git+https://github.com/SkitterByte/skitterspec.git",
+    "directory": "packages/skitterspec"
+  }
+}