@skitterbyte/skitterspec 18.0.0 → 20.0.0

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

@@ -5,6 +5,11 @@ description: Fix a production bug on the exact released version — fork a workt
 
 # /spec-hotfix — fix a released version, tag it, cherry-pick back to main
 
+> 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.
+
 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
@@ -61,8 +66,7 @@ that header — must exist **before** `spec-env up`:
   `## 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.
+  `main`), the worktree path, and any `in the worktree, run:` bootstrap steps.
 - Run the printed `git worktree add`, then **move the stub across yourself.**
   This is where a hotfix differs from `/spec-bug`, which no longer needs the move:
   that skill's worktree forks from `main`, so committing the stub puts it there,
@@ -193,6 +197,8 @@ narrative and decisions).
 
 
 
+
+
 ### Release gating (only when configured)
 
 **Only when `specs/.core/gating.config.json` exists.** A hotfix is the one spec
@@ -224,18 +230,115 @@ is a no-op.
 
 
 
+## 6b. Render the page — then offer the review, never write it
+
+**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
+present). Without it there is no worktree to read and this step does not exist —
+skip it in silence rather than explaining an absence.
+
+The fix is green and nothing is committed yet. That is the moment the page is
+about, so render it now — **after** the tests pass and **before** the commit:
+
+```
+skitterspec spec-env review <spec>
+```
+
+**This is free.** The engine reads git and splices the patches into a template;
+the diff never passes through you, so a 266KB patch costs nothing.
+
+**Then offer `/spec-diff`. Do not run it.** The written review is the part that
+costs — roughly **700 output tokens**, because writing it means reading the diff
+— and that spend is the operator's call, not a default.
+
+**The offer is the `Review` row of step 6's block** — the counts, the page link
+and a question, in one row:
+
+| **Review** | <N> files, +<a> −<d> · [open the page](<the `open:` URL>) — want a written review before you commit? |
+
+**It ends in a question, addressed to someone.** It was once a fenced block of
+engine output, and it fired on every phase and was never once taken: two quoted
+lines under the test counts, addressed to nobody, with the report then closing
+on *"commit this first"* — the last instruction the reader got was to move on,
+so they did. A row in a labelled table is findable; a question in it is
+answerable. Both halves are load-bearing.
+
+**Never bury it and never split it.** It sits above `Follow-ups` and `Next`, and
+the page and the question stay in the same row: two adjacent rows about one page
+make the reader resolve a distinction before acting on either. A later edit that
+moves it out of the block, or separates the link from the question, undoes this
+and should be read as a regression rather than tidying.
+
+
+Relay the **`open:`** line rather than the bare path: a path is not clickable in
+any terminal, and a page nobody can open is a page nobody reads.
+
+- **Never write the review unasked**, and **never publish**. Publishing leaves
+  something behind that this tooling cannot remove, so it is always an ask. A
+  `file://` link is no use on a phone, and saying so **is** the ask —
+  `/spec-diff` §6 owns how.
+**Follow the `reader:` line the engine printed — do not sniff for it.** It
+answers where the person reading this is sitting, and the offer changes with it:
+
+- **absent** (`unknown`) — the `file://` URL, exactly as always. **Do not warn:**
+  unknown is the ordinary state of a local machine, and a warning there is an
+  accusation against a healthy session.
+- **`local`** — the `file://` URL.
+- **`remote`** — the engine has already stood its local server up and put a URL
+  the reader can open on `open:`. So there is **nothing special to say**: relay
+  that line like any other. Any `also:` lines under it are the other addresses
+  this machine has, offered because the best-guess one can be wrong — pass them
+  on rather than editing them out.
+
+**Never read an environment variable to decide this** — not `SSH_CONNECTION`,
+not `CLAUDE_CODE_*`, not a tty check. The engine did it, reports it on that line
+and in `--json`, and a second implementation here could not be tested and would
+drift.
+
+**Serving is the engine's to do; publishing is never.** A `remote` reader
+authorises a local server — one process, ended by one flag, leaving nothing
+behind — and authorises nothing else. Publishing leaves a page this tooling
+cannot remove, so it stays an ask in every case, always. If the engine could not
+serve (a busy port, a machine with no network address) it falls back to the
+`file://` URL with its marker, and that is when publishing is worth naming.
+
+- **Never fatal.** A failed render — no worktree, a git error — is one line, and
+  the fix is still done. The page is a convenience; the repo is the record.
+
+**The range is measured from the base tag, not from `main`.** A hotfix forks its
+worktree from its `> **Base version:**` tag, and the engine reads that header, so
+the header line says `since <tag>` — do not relay it as `since main`, and do not
+reach for a branch view expecting the base branch.
+
 ## 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`.
+Do **not** `git push` or `git tag`-and-push unless the user asks — deploying to
+prod is theirs to trigger. 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, the user runs `/spec-connect` (its own isolated stack).
-- Suggest **`/spec-complete`** to land it: it patch-bumps the base tag, tags the
-  hotfix branch **locally** (you push it to deploy), and cherry-picks the fix onto
-  `main`. Add `--also <tag>` at completion to also patch other release lines
-  (test/demo on their own versions).
+- `Next` points at **`/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.
+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**
+
+- `✅` — red→green on the base tag, fix in, suite passing.
+- `⚠️` — green, with something worth knowing.
+- `❌` — still red, or a later test broke. Quote the failure.
+- `⏸` — no reproduction on that tag, or the tag could not be established.
+
+**Fields:** `Tracker` · `Branch` · `Spec` · `Cause` · `Built` · `Tests` ·
+`Review` · `Follow-ups` · `Next`
+
+**The base tag goes in the verdict clause** — `✅ /spec-hotfix · hotfix-foo ·
+green on v2.3.1`. Which released version this was fixed against is the first
+thing anyone needs, and it is not a field: the clause is where the run says
+where it got to.
+
+Step 6b's offer is the `Review` row, not a paragraph after the block — the
+counts, the link and the question in one row. Nothing follows the block.

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

@@ -5,6 +5,11 @@ description: Bootstrap the spec-driven-development workflow in the current proje
 
 # /spec-init — set up the spec-driven-development workflow
 
+> 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.
+
 Bootstrap (or repair) everything this project needs to run the spec lifecycle.
 **Idempotent:** detect what already exists, create only what's missing, and never
 clobber customised content. Finish with a summary of created vs already-present.
@@ -22,10 +27,11 @@ clobber customised content. Finish with a summary of created vs already-present.
 > **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
 > `--reset` (reset needs `--yes`) drive the stronger actions.
 
-The system is **ten skills**: `spec` (feature), `spec-bug` (bug),
+The system is **twelve skills**: `spec` (feature), `spec-bug` (bug),
 `spec-hotfix` (a bug fixed on a released tag), `spec-review`, `spec-start`,
-`spec-next`, `spec-to-main`, `spec-complete`, `spec-cancel`, and this
-`spec-init`. The lifecycle is `backlog → in-progress → complete / cancelled`,
+`spec-next`, `spec-diff` (read a spec's diff as a page),
+`spec-reviewed` (pick up a review you approved on that page), `spec-to-main`,
+`spec-complete`, `spec-cancel`, and this `spec-init`. The lifecycle is `backlog → in-progress → complete / cancelled`,
 with `.core` holding always-apply project rules.
 
 ## 0. Workspace mode (only when adopting isolation)
@@ -99,6 +105,28 @@ Ensure it exists. If missing, create it documenting:
 Read a sibling spec skill (e.g. `spec`, `spec-next`) for the canonical shapes
 rather than inventing them. If the rule already exists, leave it unless stale.
 
+## 4a. The review-gate hook (`.claude/hooks/review-gate.js`)
+
+`skitterspec init` installs the hook script and registers it in the project's
+**committed** `.claude/settings.json` as a `PreToolUse` hook on `Bash`. It runs
+one engine call per Bash tool call and refuses a `git commit` in a worktree
+whose phase is still awaiting a verdict.
+
+**Committed, not machine-local**, and the difference is the point: the trusted
+worktree root is one machine's absolute path, while *a phase that ended owes an
+answer* is the project's policy and should reach everyone who clones it. The
+command is written with `${CLAUDE_PROJECT_DIR}`, so it holds in worktrees too.
+
+**Say it is there, once.** A hook that blocks a commit with the operator not
+knowing a hook exists reads as a broken git, so name it in the report when it is
+newly registered — and say what turns it off (`review.required: false` in
+`env.config.json`, which the hook defers to entirely).
+
+**Never fatal, and never rewritten.** A settings file that is not parseable JSON
+is reported and left exactly as it is — it is the operator's config, and
+everything else in it would be lost. A settings file that already names this
+script, however it was wrapped, is left alone rather than gaining a second copy.
+
 ## 5. CLAUDE.md
 
 Ensure a `## Spec workflow` section exists. If absent, add one with the
@@ -109,7 +137,28 @@ the section exists, refresh only stale folder/skill names — don't rewrite it.
 
 ## 6. Report
 
-Summarise per area — folders, `.gitignore` lines, tooling-ignore negations,
-skills (present/missing), rule file, CLAUDE.md section — as created / updated /
-already-present, plus the `git check-ignore` result for `.core`. Do **not**
-`git commit` unless the user asks.
+Do **not** `git commit` unless the user asks.
+
+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**
+
+- `✅` — every area is in place.
+- `⚠️` — bootstrapped, with something worth knowing: a skill that could not be
+  installed, a CLAUDE.md that was left alone, a `.core` that is still ignored.
+- `❌` — it wrote some areas and failed on another. Name which, so the re-run is
+  informed; this skill is idempotent and re-running it is the fix.
+- `⏸` — not a git repo, or nothing it could safely write into.
+
+**Fields:** `Built` · `Follow-ups` · `Next`
+
+**`Built` is per area, one line each** — folders, `.gitignore` lines,
+tooling-ignore negations, skills (present/missing), rule files, CLAUDE.md
+section — as created / updated / already-present, plus the `git check-ignore`
+result for `.core`. This is the one skill whose `Built` is a list rather than a
+clause, because "what is now true of this project" is the entire answer it
+exists to give.
+
+**There is no spec to name**, so the verdict line drops that segment:
+`✅ /spec-init · every area in place`.