@skitterbyte/skitterspec-linear 12.0.0 → 13.0.0

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

@@ -5,6 +5,11 @@ description: Investigate a bug, capture it as a Bug-type spec, and drive it red
 
 # /spec-bug — investigate a bug, prove it with a failing test, fix it
 
+> 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 **bug** counterpart to `/spec` (which is for **features**, plan-only).
 Unlike `/spec`, this skill is hands-on and test-first: it reproduces the bug as a
 **failing test (RED)**, captures a lean Bug spec, then works the test to **GREEN**.
@@ -140,7 +145,7 @@ provision from — you'll flesh it out in §4:
   `## Symptom` you established above.
 - Run `skitterspec spec-env up bug-<name>` (the `spec-env` CLI engine). It prints
   the `git worktree add … -b bug/<name>` command (a branch forked from `main`),
-  the worktree path, the opener, and any `in the worktree, run:` bootstrap steps.
+  the worktree path, and any `in the worktree, run:` bootstrap steps.
 - Run the printed commands in order. The plan **commits the stub first** — the
   worktree forks from `main`'s last commit, so the stub has to be in it — and
   then adds the worktree. Nothing to move afterwards: the spec is already there.
@@ -157,8 +162,8 @@ provision from — you'll flesh it out in §4:
   edits will prompt.
 - **Do everything below in the worktree**, on the branch — the red test, the fix,
   and the rest of the spec. Act on the worktree with absolute paths /
-  `git -C <worktreePath>`, or open a fresh session rooted there (the printed
-  opener). `main` changes only when the branch merges (at `/spec-complete`).
+  `git -C <worktreePath>`, or open a session rooted at the printed path. `main`
+  changes only when the branch merges (at `/spec-complete`).
 
 ## 3. Write the failing test FIRST (RED) — mandatory
 
@@ -271,7 +276,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.**
@@ -304,6 +309,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
@@ -386,10 +451,108 @@ 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.
 
+## 5b. 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.
+
 ## 6. Report
 
-Summarise: root cause, the failing→passing test, the fix, and the full test
-result. The spec stays in `in-progress`; suggest `/spec-complete` to verify and
-archive it (**when isolated**, the fix lives on the bug's branch, and
-`/spec-complete` merges it back to `main`). Do **not** `git commit` unless the
-user asks.
+Do **not** `git commit` unless the user asks. The spec stays in `in-progress`;
+`Next` names the commit and then `/spec-complete`, as
+`/commit, then /spec-complete` — this skill leaves the fix uncommitted, and
+`/spec-complete` §2 refuses on pre-existing uncommitted changes, so naming only
+the second half sends the reader into a refusal. `/spec-complete` then verifies
+and archives it (**when isolated**, the fix lives on the bug's branch, and it
+merges that back to `main`).
+
+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, the fix is in and the suite passes.
+- `⚠️` — green, with something worth knowing (a narrowed repro, a mirror that
+  did not refresh).
+- `❌` — the test is still red, or a later test broke. Quote the failure.
+- `⏸` — the bug could not be reproduced, so nothing was written. Say what was
+  tried; an unreproduced bug is a finding, not a failed run.
+
+**Fields:** `Tracker` · `Branch` · `Spec` · `Cause` · `Built` · `Tests` ·
+`Review` · `Follow-ups` · `Next`
+
+`Cause` is the root cause in one clause and `Built` is the fix — the
+failing→passing test belongs in `Tests`, named, so the evidence is a test name
+rather than an adjective.
+
+Step 5b'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-cancel/SKILL.md

@@ -5,6 +5,11 @@ description: Cancel a spec — capture the reason, record final progress, stamp
 
 # /spec-cancel — record, stamp a reason, archive a spec
 
+> 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.
+
 ## 1. Identify the target spec
 
 - Use the name/path argument if given, else the spec **in context**. If unclear,
@@ -71,6 +76,12 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
   Do not roll anything back, and do not stop to ask.
 - **Say what happened** in the skill's report: mirror updated, skipped as
   unlinked, or failed with the reason.
+- **There is no unassign step, and that is not an omission.** With `assignee` in
+  `sync.fieldOwnership`, the projection derives it from the spec's lifecycle
+  bucket — so moving the folder to `complete`/`cancelled` is *itself* what
+  releases the issue, and the push above carries it like any other field. The
+  `linear_assignee_id` stamp and the `> **Developer:**` header both stay put:
+  they record who actioned the work, which outlives who is holding it.
 
 ### Why it sits here
 
@@ -81,17 +92,33 @@ In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
   its folder bucket. Push while the folder is still in `in-progress/` and the
   issue is set to the state the spec is *leaving*.
 - **Before the commit**, because the push stamps ids into the spec and writes a
-  snapshot under `specs/.core/`. The `git add specs/` that follows sweeps both up
-  with the status change; push after it instead and those files are left
+  snapshot under `specs/.core/`. Push after the commit instead and both are left
   uncommitted, which makes `spec-env integrate` refuse to land the branch.
 
+The snapshot is reached **by name**, not by breadth. It is a declared
+`spec.companionPaths` entry (`specs/.core/linear-base/{identifier}.base.json`),
+so `spec-env stage` returns it among this spec's owned paths and the commit below
+names it. This is why the commit no longer stages `specs/` wholesale: the one
+file outside the spec's folder that had to be swept up is addressable, so the
+breadth bought nothing and cost another session's work.
+
 Then **commit the cancellation edits** — this skill wrote them, so it commits
-them:
+them. Ask the engine which paths are this spec's, then stage and commit
+**exactly those**:
 
 ```
-git add specs/ && git commit -m "chore(spec): cancel <name>"
+skitterspec spec-env stage <name>     # lists them; --json to consume
+git add -- <the owned paths>
+git commit -m "chore(spec): cancel <name>" -- <the owned paths>
 ```
 
+**Never `git add specs/`.** That stages a *directory*, so a spec another
+session is part-way through writing lands in this commit under this spec's
+ticket. The `--` on the **commit** is the other half: a checkout has one
+`.git/index`, shared by every session standing in it, so a bare `git commit`
+takes whatever else is staged there however carefully you staged your own.
+`.claude/rules/spec-planning.md` carries the full account.
+
 **This matters more here than anywhere else.** Teardown (step 7) refuses a dirty
 worktree and offers `--force` as the way through — and forcing would destroy the
 cancellation record this skill just wrote. Committing first means teardown never
@@ -99,7 +126,31 @@ needs `--force`. Do not `git push`.
 
 ## 6. Report
 
-Confirm the cancellation, the reason recorded, the new location, and the commit.
+**The block is emitted when the run ends, not where this section sits.** The
+sections below run after it, so their outcome belongs in the block — write it
+once, at the end, with what actually happened.
+
+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**
+
+- `✅` — stamped, moved to `cancelled`, committed, torn down.
+- `⚠️` — cancelled, with something worth knowing: teardown declined, a tracker
+  refresh that failed, unpushed commits the operator chose to let go.
+- `❌` — it acted and stopped part-way. Say what is where.
+- `⏸` — no reason given, or no such spec. Nothing changed.
+
+**Fields:** `Tracker` · `Spec` · `Worktree` · `Follow-ups` · `Next`
+
+**The reason goes in the verdict clause** — `✅ /spec-cancel · feat-foo ·
+superseded by feat-bar`. It is the one thing anyone reading this later wants,
+and a cancellation is an ordinary successful run, so it must not be mistaken for
+a `Why`: that field is for a run that did not do what it set out to.
+
+`Worktree` says what was reclaimed, or that teardown was declined and the
+worktree still stands — on a cancelled spec that worktree may hold the only copy
+of the work, so an unreclaimed one is worth a line rather than a silence.
 
 ## 7. Tear down the environment (opt-in, only if configured)
 
@@ -110,22 +161,22 @@ directly (the old `/spec-env-down` skill is gone — teardown is folded in here)
 1. If `.spec-env/connected` names this spec, run `skitterspec spec-env connect
    main` first to free the canonical ports.
 2. `skitterspec spec-env dev down <name>` — stop its host dev servers.
-**Standing in the worktree? Leave it before you tear it down.** If this
-session's cwd is inside the spec's own worktree, get out **first**, then run the
-teardown commands. How you leave depends on how you got in:
-
-- **`/spec-start` moved this session in** — the normal path in `worktree` mode.
-  Call **`ExitWorktree`** with `action: "keep"`. It restores the session to the
-  directory it started from *and* clears the caches still pointing at the
-  worktree, which a bare `cd` does not: after a `cd` the session stays registered
-  against the tree and asks you about it again when it ends.
-- **You opened the terminal yourself** — `cd` to the primary checkout, as always.
-  `ExitWorktree` is a no-op outside a session it moved, so trying it costs
-  nothing, but the `cd` is what relocates you.
-
-**Always `keep`, never `remove`.** `ExitWorktree` refuses to remove a worktree
-entered by path in any case, and the `spec-env down` plan below has to stay the
-single thing that deletes — a second deleter is how the teardown guards get
+**Standing in the worktree? Leave it before you tear it down.** If this session's
+cwd is inside the spec's own worktree — the normal case in `worktree` mode, since
+`/spec-start` moves you there — get out **first**, then run the teardown commands.
+One instruction covers it:
+
+```
+cd <primary checkout>
+```
+
+That is the whole mechanism, and it does not matter how you got in: the session
+was moved by a `cd` and it leaves by one. There is no tool to call here, and none
+should be reached for — the move in is a plain `cd` precisely because a tool that
+asks for approval is unusable on a phone.
+
+**`spec-env down` stays the single thing that deletes a worktree.** The plan
+below is the only deleter, because a second one is how the teardown guards get
 bypassed.
 
 Not because git refuses — it does not. `git worktree remove` **succeeds** on the
@@ -140,6 +191,32 @@ only ordering that survives.
    remove the worktree/stack and free the slot. It respects the teardown guards
    (won't destroy a dirty/unpushed worktree without `--force`).
 
+   **When it refuses over unpushed commits, relay both ways out.**
+   A cancelled spec is normally unlanded, so this is the one moment in the
+   lifecycle where that guard genuinely fires — and it fires about real loss.
+   The worktree is the only copy of this work: the branch is on no remote and
+   not merged into the base branch, so removing it ends it. Say that plainly,
+   relay the engine's reason, and give both endings:
+
+   ```
+   publish it first — keeps the work reachable, then re-run /spec-cancel:
+     git -C <worktreePath> push -u origin <branch>
+
+   or accept the loss (the worktree and its commits go):
+     skitterspec spec-env down <name> --force
+   ```
+
+   **Print the push; never run it.** Publishing abandoned work to a shared
+   remote is the same unasked-for act this workflow took out of `/spec-start`,
+   and it is no more wanted here — someone may well want this branch to exist
+   nowhere but their own machine. Offer the command and wait for an answer.
+
+   **Never reach for `--force` yourself either.** The engine's own message names
+   only that half, which is the whole reason this step exists: meeting a wall
+   labelled *--force to tear down anyway* at the exact moment a backup is still
+   cheap is how work gets thrown away. Both options, then stop — the choice is
+   a decision about someone's work, and it is theirs.
+
    If the plan prints a `remote branch — confirm with the user first:` section,
    **ask before running that line** — it is a `git push <remote> --delete`, and
    the branch is merged, so it loses nothing. Usually there is nothing to ask:

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

@@ -0,0 +1,114 @@
+---
+name: spec-claim
+description: Take ownership of a spec, hand it back, or give it to a teammate — the spec records who is building it and its Linear issue is assigned to them. Opt-in — needs specs/.core/linear.config.json with assignee in sync.fieldOwnership. Use when the user says "/spec-claim", "claim this spec", "take ownership of this", "I'm picking this up", "hand this back", or "assign this spec to someone".
+disable-model-invocation: true
+---
+
+# /spec-claim — take a spec, hand it back, or hand it over
+
+> 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.
+
+Ownership lives in the repo: the spec's frontmatter records who is building it,
+and the push that follows tells Linear. This skill is how that record changes
+after `/spec-start` has set it — a hand-off mid-flight, a spec picked up from
+someone who moved on, or work a lead is distributing.
+
+**Opt-in.** Needs `specs/.core/linear.config.json` *and* `assignee` in its
+`sync.fieldOwnership`. If either is missing, say which one and stop — without the
+field the stamp would sit in the file doing nothing.
+
+## 1. Identify the target spec
+
+The argument, else the spec in flight for this session, else ask. Unlike
+`/spec-next` this does not refuse a spec you are not standing in: reassigning a
+colleague's spec from your own checkout is a normal thing to want, and it writes
+no code.
+
+## 2. Work out the mode
+
+| Invocation | Mode |
+|------------|------|
+| `/spec-claim [<spec>]` | **take** — you are building it |
+| `/spec-claim [<spec>] --release` | **release** — nobody is |
+| `/spec-claim [<spec>] --to <name-or-email>` | **hand over** — they are |
+
+### take
+
+1. `skitterspec spec-sync whoami --json`. If it answers, use that `id`/`name`.
+   If it reports `transport = mcp`, call the user-read tool with `me` and cache
+   the answer with `whoami --set <id> --name "<name>"`.
+2. **If the spec already records someone else, confirm before taking it** —
+   name them and say what will happen. Taking a colleague's spec by accident is
+   the one mistake here worth a round trip; every other path is reversible with
+   a second `/spec-claim`.
+3. Stamp it: `skitterspec spec-sync assign <spec> --to <id> --name "<name>"`.
+4. Set `> **Developer:**` to **`git config user.name`** — not the Linear display
+   name. You are taking this spec yourself, so the header should name you the
+   way `Author:`, the **State log** and your commits already do. The Linear name
+   belongs to the *assignment*, which step 3 just recorded; the two answer
+   different questions.
+
+### release
+
+`skitterspec spec-sync assign <spec> --release`. This removes the stamp and, on
+the next push, unassigns the Linear issue.
+
+**It does not clear `> **Developer:**`** — that header records who *actioned*
+the work, which outlives who is currently holding it. If nobody will pick the
+spec up, `/spec-cancel` is the honest move; releasing only says "not me, for
+now".
+
+### hand over (`--to`)
+
+1. **Resolve the person through a search, never a typed id.** Run
+   `skitterspec spec-sync users <name-or-email>` (or the user-list tool on MCP)
+   and **confirm the match** before writing. This is the one path where the repo
+   writes into somebody else's Linear inbox, so a mistyped id would assign a
+   stranger and nothing downstream would notice.
+2. On several matches, show them and let the user pick. On none, say so and
+   stop — do not fall back to the raw argument as an id.
+3. Stamp it with the resolved id and display name.
+4. Set `> **Developer:**` to that person's **Linear display name**.
+
+   This is the **one** place the tracker's name reaches the header, and the
+   exception is the whole reason it exists: there is no `git config user.name`
+   for somebody else's machine, so without it the header would go on crediting
+   you for work you just gave away. Everywhere else — `/spec-start`, the
+   `/spec-next` backfill, and taking a spec above — the git name wins, because
+   there the person *is* you and the rest of the spec already names you that way.
+
+## 3. Record it in the spec
+
+Add a dated line to the **Changelog** in `00-overview.md` — who it moved to (or
+from), and why if the user said. Ownership is a course-correction, not a
+lifecycle transition, so it belongs there and **not** in the State log.
+
+## 4. Push
+
+Run `/spec-push`. The stamp is repo state, and the mirror catches up like any
+other edit.
+
+**If the push fails, the claim still stands.** Say so and stop: the repo is
+correct, the mirror is disposable, and the next push repairs it. Do not roll the
+stamp back — that would throw away the one durable half of the change.
+
+## 5. Report
+
+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 spec records the new owner and Linear agrees.
+- `⚠️` — the spec records it; Linear does not yet. The spec file is the record
+  and the ticket is the mirror, so this is a lag rather than a conflict — say
+  which way round it is.
+- `⏸` — nothing to claim, or no provider configured.
+
+**Fields:** `Tracker` · `Follow-ups` · `Next`
+
+`Tracker` is who owns it now and whether Linear agrees yet — the whole answer,
+in one row.