@skitterbyte/skitterspec-linear 11.0.0 → 13.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
@@ -151,11 +156,13 @@ 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.
-- 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. **Create the destination bucket first:**
+  `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,
+  while **this worktree is checked out at the tag** — a commit on `main` is not in
+  it and never will be. The move is not redundant here; keep it.
+  **Create the destination bucket first:**
 
   ```
   mkdir -p <worktreePath>/specs/in-progress
@@ -164,14 +171,13 @@ that header — must exist **before** `spec-env up`:
 
   The `mkdir -p` is not belt-and-braces. Git does not store empty directories, so
   `specs/in-progress/` is **absent** from the worktree whenever nothing was in
-  progress at that point in history — and here that point is an **old release
-  tag**, where it is absent more often than not. `mv` into a missing destination
-  renames your spec folder **to** `specs/in-progress`, silently: the spec's files
-  end up one level too high, `00-overview.md` sits where the bucket should be, and
-  every later step still appears to work until something cannot find the spec.
-  Confirm the result before carrying on — you want
-  `<worktreePath>/specs/in-progress/hotfix-<name>/00-overview.md`.
-- **Bootstrap the worktree.** A fresh worktree has no installed dependencies and
+  progress at that point in history — and here that point is an
+  **old release tag**, where it is absent more often than not. `mv` into a
+  missing destination renames your spec folder **to** `specs/in-progress`,
+  silently: the spec's files end up one level too high, `00-overview.md` sits
+  where the bucket should be, and every later step still appears to work until
+  something cannot find the spec. Confirm the result before carrying on — you
+  want `<worktreePath>/specs/in-progress/hotfix-<name>/00-overview.md`. - **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.
@@ -213,6 +219,8 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
 > **Base version:** <tag prod is running, e.g. v33.16.4>
 > **Raised:** <YYYY-MM-DD (today)>
 > **Area:** <files/modules>
+> **Gating:** <pre-filled "none: hotfix — restoring released behaviour"; only
+> when release gating is configured, and overridable — see below>
 
 ## Symptom
 
@@ -292,7 +300,7 @@ does — you never create the issue by hand:
 2. **Pick the Project** — run the picker in **Picking the Linear Project** below.
    Keep the chosen id for step 4.
 3. **Get the plan.**
-   `skitterspec spec-sync push <spec> --workspace-states <file> --json > plan.json`
+   `skitterspec spec-sync plan <spec> --workspace-states <file> --json > plan.json`
    — the spec is unlinked, so this plan is all-creates: the issue and one
    sub-issue per phase.
 4. **Apply it.**
@@ -325,6 +333,66 @@ and **never auto-push git** — Linear's own automation reacts to real branch/PR
 events later. Report the Linear issue URL as part of the skill's finish-up
 message.
 
+**Only when all three hold**: `specs/.core/linear.config.json` exists, its
+`sync.fieldOwnership` includes `assignee`, and the spec carries a
+`linear_identifier`. Any one missing → skip this step silently and carry on; a
+project that has not opted in must see no trace of assignment.
+
+**Never blocks, never fails the skill.** Everything below is best-effort: the
+branch is provisioned and the spec is moving either way, and an unassigned issue
+is a cosmetic gap that `/spec-claim` closes later.
+
+1. **Work out who you are.** Run `skitterspec spec-sync whoami --json`.
+   - `ok: true` → use `id` and `name`. Nothing to ask.
+   - `source: "mcp"` or the command reports no API key → call the discovered
+     user-read tool with `me`, then cache it:
+     `skitterspec spec-sync whoami --set <id> --name "<name>"`.
+   - `ok: false` → identity is **unknown**, which is an ordinary state (a shared
+     or bot key, an offline machine). Go to step 2.
+2. **Unknown identity — three states, not two.** Decide by what is actually
+   reachable, and route the third to inaction:
+   - **Linear reachable *and* this is an interactive session** → offer a short
+     user search (`skitterspec spec-sync users <name-or-email>`, or the
+     user-list tool on MCP), let the operator pick, and offer to cache it with
+     `whoami --set` so this is asked once per machine rather than once per spec.
+   - **Not reachable, or not interactive** → say so in one line
+     (`assignment skipped — no Linear identity`) and **carry on**. Do not prompt
+     for something you could not act on, and never stall a `/spec-start` on it.
+3. **Record it on the spec** — through the engine, never by hand-editing
+   frontmatter:
+
+   ```
+   skitterspec spec-sync assign <spec> --to <user-id> --name "<display name>"
+   ```
+
+4. **Leave `> **Developer:**` as `git config user.name`** — the step above this
+   seam already set it, and this seam must not overwrite it with the tracker's
+   display name.
+
+   Those two names are the same person and often not the same string, and the
+   git one is the one everything else in the spec already uses: `Author:`, every
+   **State log** `By` row, and every commit. Writing the tracker's name into this
+   one field would leave a spec whose own audit trail contradicts its header —
+   a worse problem than the one it would solve. Anyone wanting a different name
+   on their specs sets `git config user.name`, and it stays consistent
+   everywhere.
+
+   The header names **who is building this**; the stamp in step 3 names
+   **which tracker account it is assigned to**. They answer different questions,
+   so they need not be the same string. The one place that reasoning does not hold
+   is handing a spec to *someone else* — there is no local git name for them —
+   and that case belongs to `/spec-claim --to`, which sets the header from the
+   tracker deliberately.
+
+**Nothing is pushed here.** `assign` writes the repo only, and the refresh these
+skills already run sends it. Assignment is an ordinary field of the projection,
+not a side errand with its own network call.
+
+**There is no unassign step anywhere.** The projection derives the assignee from
+the spec's lifecycle bucket, so `/spec-complete` and `/spec-cancel` release the
+issue through the push they already make. The stamp deliberately stays in the
+file: who actioned the work outlives who is currently holding it.
+
 ### Picking the Linear Project
 
 Run this **only when minting a spec issue** — creating it for the first time. On
@@ -357,6 +425,21 @@ say so in one line — *"project picker unavailable"* — and carry on with
 If `linear.projectId` is set but that Project is archived or missing, relay
 Linear's error and stop rather than silently minting an unparented issue.
 
+### Release gating (only when configured)
+
+**Only when `specs/.core/gating.config.json` exists.** A hotfix is the one spec
+type that does **not** ask the question cold: it writes
+`none: hotfix — restoring released behaviour` and asks only for confirmation.
+
+The default differs on purpose. A hotfix restores behaviour a release already
+had, under time pressure, and the fix is captured by a deploy tag rather than
+riding the next release — so a flag has nothing to gate and nothing to roll back
+to. Making someone answer a design question mid-incident buys nothing.
+
+It is a **default, not a rule**: say what you are writing and let the user
+override it. If they name a flag, record that instead. Skip entirely when the
+config is absent.
+
 ## 6. Drive to GREEN
 
 - Implement the **minimal, root-cause** fix on the branch. Match surrounding code;
@@ -390,18 +473,115 @@ sub-issue jump from Backlog straight to Done, with nothing visible in between.
 - **Say what happened** in the skill's report: mirror updated, skipped as
   unlinked, or failed with the reason.
 
+## 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)
@@ -37,6 +43,19 @@ checkout you are already in; one spec at a time, no hand-off). It is a question
 about how the operator works, not about what the repo contains, so ask rather
 than infer it from whether dev servers or Docker are configured.
 
+## 0b. Release gating (optional, and separate)
+
+Ask whether specs should record a **release-gating** decision — does this change
+ship behind a feature flag, or land live? Adopting it copies
+`specs/.core/gating.config.json.example` → `gating.config.json` and sets
+`guidance` to wherever this project documents its flags.
+
+It is **orthogonal to isolation**: a project can adopt either, both, or neither.
+Skitterspec never learns how the flags work — it asks the question, cites that
+path, and records the answer on each spec. Leave it off and nothing appears:
+no question, no header, no check. Off is a perfectly good answer for a project
+that does not use flags.
+
 ## 1. Folders
 
 Create any that are missing; drop a `.gitkeep` into ones that would otherwise be
@@ -80,8 +99,8 @@ Ensure it exists. If missing, create it documenting:
 - the **Author** / **Developer** header fields;
 - the **State log** audit table (folder/status transitions), kept separate from
   the **Changelog** (decisions);
-- the project's concrete typecheck/test commands, and the rule that **every
-  phase ends with creating + running tests**.
+- the project's concrete typecheck/test commands, and the rule that
+  **every phase ends with creating + running tests**.
 
 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.
@@ -96,7 +115,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`.

package/assets/skills/spec-linear-setup/SKILL.md

@@ -5,6 +5,11 @@ description: Configure Linear sync for this repo by interview rather than by han
 
 # /spec-linear-setup — configure Linear sync by interview
 
+> 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.
+
 Writes `specs/.core/linear.config.json`, the file that switches one-way Linear
 sync on for this repo. You **discover and interview**; the engine
 (`spec-sync init-config`) **validates and writes**. Keep that split: composing the
@@ -173,13 +178,39 @@ a state from the `list_issue_statuses` names you already have:
   automation closes them and a problem otherwise — `spec-sync doctor` warns about
   it either way, so say which it is.
 
+## 7b. Should a spec's issue be assigned to whoever is building it? (optional)
+
+Ask it plainly, in one line: with this on, `/spec-start` records the developer
+and their Linear issue is assigned to them, released again when the spec
+completes. Off, nothing about assignment happens at all.
+
+**Offer once and take "no" for an answer.** It is off by default deliberately —
+a team whose PM owns assignment in Linear does not want the repo writing that
+field, and the cost of guessing wrong is somebody else's triage being
+overwritten.
+
+If they want it, pass **`--assign`** in step 8. Then settle who *they* are, so
+`/spec-start` never has to stop and ask:
+
+```
+skitterspec spec-sync whoami
+```
+
+It answers straight from the API key. If it reports `transport = mcp`, read `me`
+with the user tool and cache the answer
+(`spec-sync whoami --set <id> --name "<name>"`); if it reports unknown — a shared
+or bot key — look the person up with `spec-sync users <name-or-email>` and cache
+their id the same way. **Never write a user id into `linear.config.json`**: that
+file is committed, so it would assign every teammate's specs to whoever ran
+setup.
+
 ## 8. Write it
 
 ```
 skitterspec spec-sync init-config \
   --team-id <uuid> [--team-key KEY] [--project-id <uuid>] \
   [--intake-label <name>] [--bug-labels a,b] [--hotfix-labels a,b] \
-  [--state <bucket>=<name> …] \
+  [--state <bucket>=<name> …] [--assign] \
   --states <statesfile> [--force] [--json]
 ```
 
@@ -198,6 +229,31 @@ project's own, so ask rather than guess.
 the workspace — that report is the evidence the setup is right, so don't
 paraphrase it into "done".
 
+## 8b. Let `/spec-start` commit the snapshot with its spec
+
+**Only when `specs/.core/env.config.json` exists** (per-spec isolation is on). If
+it is absent, skip this — there is nothing to configure.
+
+`/spec-start` commits an uncommitted spec for you, but only the paths it can
+prove belong to that spec. Its own folder always does; this repo's per-spec
+Linear snapshot (`sync.baseDir`, `specs/.core/linear-base/<ID>.base.json`) does
+not, because the base engine is deliberately tracker-free and cannot know that
+path exists. Declare it once, in `env.config.json`:
+
+```json
+"spec": {
+  "companionPaths": ["specs/.core/linear-base/{identifier}.base.json"]
+}
+```
+
+`{identifier}` resolves through `branch.identifierField`, so **set that too** if
+it is still empty — `"linear_identifier"` is the field `/spec` stamps. Without
+it the pattern expands to nothing and the snapshot is treated as another spec's
+file: `/spec-start` then refuses the tree instead of committing it, which is the
+safe failure but a needless one.
+
+Leave both alone if the user has already set them.
+
 ## 9. Report and hand off
 
 **Finish by checking, not by describing.** First write down what the MCP server
@@ -254,13 +310,36 @@ more detail if you need it. If the key is missing, tell the user to run this
 skitterspec spec-sync credentials set
 ```
 
-**Do not ask the user to paste an API key into this conversation, and do not
-offer to store one for them.** A key pasted into a chat enters the transcript,
-is sent to the model, and may be logged — moving where a key is stored is
-pointless if it travels through the conversation to get there. Your job is to
-confirm the setup is ready and name the command; the value is theirs alone. The
-key is optional: without one, pushes go over MCP.
+**Do not ask the user to paste an API key into this conversation, and do not offer to store one for them.**
+A key pasted into a chat enters the transcript, is sent to the model, and may
+be logged — moving where a key is stored is pointless if it travels through the
+conversation to get there. Your job is to confirm the setup is ready and name
+the command; the value is theirs alone. The key is optional: without one,
+pushes go over MCP.
 
 Mention what setup did **not** configure, so the defaults aren't mistaken for
 decisions: phase mapping (`mapping.phases` — sub-issue per phase by default) and
 field ownership. Point at `linear.config.md` for those.
+
+End with the block defined in `.claude/rules/spec-reports.md`. That file carries
+the shape; this section carries only what is specific here.
+
+**The `doctor` table goes above the block, verbatim.** It is a check rather than
+a summary, and every row that needs attention names its own fix — paraphrasing
+it into fields would lose exactly that.
+
+**Verdicts**
+
+- `✅` — every layer `doctor` checked is configured and working.
+- `⚠️` — configured, with a `missing` row: an opt-in nobody took, which is fine.
+  Report it; do not treat it as a failure.
+- `❌` — a `broken` row: configured but wrong. On a broken `mcp` row **stop** —
+  which side is correct is the user's to say.
+- `⏸` — an existing config was reviewed and left alone, or the workspace could
+  not be discovered. Nothing was written.
+
+**Fields:** `Built` · `Follow-ups` · `Next`
+
+`Built` is the config written or reviewed, plus what was deliberately left
+unset. **The key is never a field** — `doctor`'s `key` row already reports
+whether one is set, masked, and the value is the user's alone.