@skitterbyte/skitterspec-linear 12.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,8 +156,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,
@@ -296,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.**
@@ -329,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
@@ -409,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)
@@ -109,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]
 ```
 
@@ -289,3 +320,26 @@ 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.

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

@@ -0,0 +1,218 @@
+---
+name: spec-list
+description: List every spec Linear holds — id, title, workflow state, who holds it, and the local spec folder name to paste into /spec-start. Read-only, and it starts nothing. Falls back to the repo's own listing when Linear is unreachable. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-list", "what specs are there", "what is in the backlog", "what is Jane working on", or "list specs from Linear".
+disable-model-invocation: true
+---
+
+# /spec-list — every spec Linear holds
+
+> 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.
+
+Read-only. It answers a question and writes nothing — no branch, no folder move,
+no Linear write.
+
+Why ask Linear rather than `ls specs/`? Because `/spec-start` moves a spec to
+`specs/in-progress/` **on that spec's own branch**. On the base branch an
+in-flight spec still reads `backlog`, and a teammate's unlanded spec is not on
+disk at all. Linear knows what is actually in progress and who holds it; the repo
+knows what each issue is **called on disk**. The listing joins the two.
+
+**Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
+tell the user how to enable Linear sync (`/spec-linear-setup`) and stop.
+
+## 1. Turn the question into flags
+
+The user asks in plain language; the engine takes flags. Map, then run:
+
+| They ask | Flags |
+|----------|-------|
+| "what specs are there", "/spec-list" | *(none — the live default)* |
+| "what's done", "everything" | `--all` |
+| "what's cancelled", a named state | `--state "<name>"` (repeatable) |
+| "what's next", "the next few in the backlog" | `--next N` |
+| "what am I on", "assigned to me" | `--mine` |
+| "what is Jane on", "Jane's specs" | `--by "Jane"` |
+| "what's in flight", "what's being worked on" | `--in-progress` |
+| "just the first few" | `--limit N` |
+| "include the archived ones" | `--archived` |
+
+The default scope is **live** — whatever `config.states` maps `backlog` and
+`in-progress` to. It is deliberately not everything: in a workspace with any
+history, Done dwarfs the rows anyone wanted.
+
+`--mine` and `--by` filter by assignee and stack with any one scope flag —
+`--next 5 --mine` and `--in-progress --by "Jane"` both read naturally. The scope
+flags themselves (`--state`, `--all`, `--next`, `--in-progress`) are
+**alternatives**, and the engine refuses any two of them rather than letting one
+win silently.
+
+`--next N` is **backlog-only and ordered**, so it does not combine with
+`--state` or `--all`; the engine refuses that pair rather than picking a winner.
+It reproduces Linear's own Backlog order — priority first, then the manual
+drag-order — and when nothing is prioritised it says so, because that order is
+then a person's arrangement rather than a ranking.
+
+## 2. Run the engine
+
+```
+skitterspec spec-sync list [--state <name> …|--all] [--limit N] [--archived] [--json]
+```
+
+- **`transport = api`** (a key is set) → it queried Linear and printed the
+  listing. **Relay its output verbatim** and stop. Do not re-format it and do not
+  make Linear calls of your own — the engine already joined the local spec
+  folders on.
+- **`transport = mcp`** → the engine made no call. Go to step 3.
+- Anything else it prints on one `spec-sync list:` line is a **degradation**, not
+  a crash — go to step 4.
+
+**These two failures are not the same, and the engine says so.**
+Relay the difference rather than flattening it. `--mine` when nobody can say
+who you are (a shared or bot key, an offline machine) is an ordinary state: it
+prints one line, lists nothing and exits 0. `--by "someone"` that matches no
+user, or matches several, is a wrong argument: it lists the candidates or says
+there are none, and exits non-zero. Neither ever falls back to the whole team —
+a heading promising one person's work over everyone's is the failure both are
+written to avoid.
+
+## 3. The MCP path
+
+Only when the engine said `transport = mcp`. Discover the issue **list** tool at
+runtime the way `/spec-push` describes (`list_issues`). If Linear isn't connected
+or the tool is missing, go to step 4 — do not stop with nothing.
+
+Then, per state you are listing:
+
+- **One call per state.** The tool's `state` takes a single state name, not a
+  list, so the live default is **two** calls (`backlog` and `in-progress` from
+  `config.states`). Merge the results and de-duplicate by identifier.
+- **Ask for the fields you print** — `fields: ["title", "status", "assignee",
+  "url", "parentId"]`. `parentId` is not optional: it is the discriminator in the
+  next bullet, and it is absent from the default response.
+- **Filter out phase sub-issues yourself.** The tool can filter *to* a parent
+  (`parentId`) but has no "parentless" filter, so **you** must drop every issue
+  that came back carrying a `parentId`. A spec issue has none; a phase sub-issue
+  does.
+- **Page, and never cap silently.** `limit` defaults to 50 and maxes at 250;
+  follow `cursor` until it runs out. If you stop early, say so on its own line
+  and say what you stopped at.
+- Pass `includeArchived` only when the user asked for `--archived`.
+- **Assignee needs no identity lookup here.** The tool takes `assignee` as a
+  user id, name, email **or the literal `"me"`** — so `--mine` is
+  `assignee: "me"` and `--by "Jane"` is `assignee: "Jane"`. Do **not** call
+  `spec-sync whoami` on this path; it exists for the API path, which needs an
+  id. If the name matches nobody, say so and list nothing.
+
+**`--next` cannot be fully reproduced over MCP, and you must say so.** The tool
+returns `priority` as a field, so order by that; but `sortOrder` — Linear's
+manual drag-order — is **not among the fields it can return** at all, and its
+`orderBy` offers only `createdAt` and `updatedAt`. So within one priority you
+are printing Linear's default order, not the Backlog order. Say that on its own
+line rather than letting the rows imply an order they do not have:
+
+```
+sortOrder is unavailable over MCP — within a priority these are in Linear's
+default order, not the Backlog drag-order. Set a Linear API key for the real one.
+```
+
+**The current phase, on in-progress rows only.** For each row whose state is the
+in-progress one, call the list tool again with `parentId` set to that issue and
+`fields: ["title", "status"]`. Order the children by **identifier**, numerically
+— `sortOrder` is unavailable here for the same reason it is under `--next`, and
+sub-issues are minted in phase order, so the identifier carries it. Print the
+live one as `2/5 — <title>`. Three shapes, none of them guessed at:
+
+- **No child in progress** — print nothing extra. A spec sits between phases all
+  the time; that is not a missing phase.
+- **More than one** — print the lowest-numbered, then append
+  `(+N more in progress)`. Two people on one spec is real, not an error.
+- **`mapping.phases` is `inline` for this spec's bucket** — skip the call
+  entirely. Those phases live in the spec issue's own description, so there are
+  no children, and asking would report "no phase in progress" for a spec that is
+  mid-build.
+
+Do **not** make this call for backlog, done or cancelled rows — one lookup per
+in-progress row is the budget, and there are rarely many.
+
+Then join locally — no second Linear call:
+
+```
+skitterspec spec-sync linked --json
+```
+
+That is `[{ spec, bucket, identifier }]`. Key it by `identifier` and attach each
+issue's local `spec` folder name. Format the rows exactly as the API path does
+(step 5), including the archived-exclusion line and the `showing N of M` count.
+
+## 4. Degrade — never leave them with nothing
+
+Linear unreachable, no credential, no MCP tool, a Linear error: **do not stop**.
+Print the local listing instead:
+
+```
+skitterspec spec-sync linked --json
+```
+
+Show `spec`, `bucket` and `identifier`, under a one-line banner naming what is
+missing and why it may be wrong:
+
+```
+Linear unreachable (<reason>) — this is the repo's own listing.
+Buckets are this branch's; a spec someone else has started still reads "backlog" here.
+```
+
+That caveat is the point of the banner. A local bucket is not evidence of a
+spec's real state — it is evidence of what this branch knows, which is exactly
+what the command exists to go beyond. A query command that fails closed is one
+people stop typing.
+
+## 5. Report
+
+Relay the listing. Whatever the path, three things must survive into what the
+user reads:
+
+- **The count, as `showing N of M`.** If they are not the same number, say what
+  was left out and how to see it.
+- **The archived line.** Excluded by default, and said so — a blind spot named
+  rather than left to be discovered.
+- **The phase, on in-progress rows** — `2/5 — <title>`, after the assignee.
+- **A row with no local match stays in**, marked `— (not linked here)`. It is not
+  noise: a teammate's unlanded spec, or one authored inside another spec's
+  worktree, is precisely what the repo could not have told them.
+
+Finish with the hand-off, because every row carries the folder name for it —
+as a sentence, not a fenced block: say that `/spec-start <name>` starts any of
+them, with the name copied from a row.
+
+**Never start it yourself.** `/spec-start` provisions a branch, moves a folder
+and commits, and it has dirty-tree refusals this skill does not reproduce.
+Offering the name is the whole job.
+
+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 listing goes above the block, unflattened.** It is rows of other people's
+work; the block is the verdict on this run of the query. Do not fold the listing
+into fields, and do not repeat it there.
+
+**Verdicts**
+
+- `✅` — the listing is Linear's, joined to the local folder names.
+- `⚠️` — listed, with a caveat that changes how the rows read: a paging cap you
+  stopped at, or `sortOrder` unavailable over MCP so `--next` is not really
+  Backlog order.
+- `⏸` — `--mine` with no identity available. It lists nothing and that is an
+  ordinary state, not a failure.
+- `❌` — the query was wrong: `--by` matching nobody or several, or two scope
+  flags together.
+
+**Fields:** `Follow-ups` · `Next`
+
+**No `Tracker` row.** This skill names many specs and owns none, so an id row
+would have to pick one. The counts — `showing N of M` — and the archived
+exclusion belong to the listing above, where the engine already prints them.
+
+`Next` is the hand-off: `/spec-start <name>`, with a name copied from a row.