@skitterbyte/skitterspec-linear 10.1.0 → 10.3.0

package/README.md

@@ -82,14 +82,37 @@ On top of the base skills (`/spec`, `/spec-go`, isolation, …):
   phase sub-issues), stamping the returned ids back into the spec.
 - **`spec-sync` CLI** (`skitterspec-linear spec-sync …`) — the deterministic
   engine behind the skills, for CI / local runs:
-  `normalize` · `push` · `stamp` · `record` · `status` · `linked`.
-
-The shared `/spec`, `/spec-bug` and `/spec-go` skills come composed with the
-Linear steps filled in: `/spec` asks which Linear **Project** the spec belongs to,
-then links it to a Linear issue (a sub-issue per phase). `/spec` and `/spec-bug`
-can also start **from** an existing issue — `/spec SKI-123`, or `/spec
---from-issue` to browse the ones your web app filed. There is no pull — the repo
-is already canonical, so `/spec-go` just builds.
+  `normalize` · `push` · `apply` · `states` · `stamp` · `record` · `verify` ·
+  `status` · `linked`.
+- **A direct-API push path.** Set a Linear personal API key and `/spec-push`
+  applies its plan through the engine instead of one assistant call per issue —
+  descriptions never pass through the model, in either direction:
+
+  ```bash
+  export LINEAR_API_KEY=lin_api_…    # Linear → Settings → Security & access
+  ```
+
+  `auth.keyEnv` names the variable (never the key itself); `apply.transport`
+  pins `api`/`mcp`, or leave it empty to use the API whenever a key is present.
+  `--via mcp` forces the original path for one run.
+  **With no key nothing changes** — the MCP path is fully supported and stays
+  the default for anyone who never sets one.
+- **One-command adoption on an existing repo.**
+  `skitterspec-linear spec-sync apply --all complete` pushes every spec in a
+  lifecycle bucket, reporting what it created, updated, skipped and failed. A
+  spec that fails doesn't stop the rest, and re-running retries only those —
+  every id is written into the spec as soon as its object exists, so nothing is
+  ever duplicated. Needs an API key. See `specs/.core/linear.config.md`.
+
+**Every skill that moves a spec through its lifecycle** comes composed with the
+Linear steps filled in, so the mirror keeps up without anyone remembering to
+push: `/spec`, `/spec-bug` and `/spec-hotfix` link the spec they create (asking
+which **Project** it belongs to, and minting a sub-issue per phase);
+`/spec-go` refreshes it as work starts; `/spec-complete`, `/spec-cancel` and
+`/spec-review` refresh it after they change it. All three creating skills can
+also start **from** an existing issue — `/spec SKI-123`,
+`/spec-hotfix v33.16.4 SKI-123`, or `--from-issue` to browse the ones your web
+app filed. There is no pull — the repo is already canonical.
 
 ## Opt-in
 
@@ -121,14 +144,32 @@ are left alone. Your spec files are never modified. After a push, each stored
 description is read back and compared against what was sent, ignoring Linear's
 own reformatting and reporting anything genuinely lost. Both are automatic.
 
-**Adopting on a long backlog.** By default a spec costs one `save_issue` call
-plus one per phase, so mirroring a backlog that already runs to dozens of specs
-front-loads hundreds of calls for work nobody has started. Set
-`mapping.phases: "deferred"` and a spec sitting in `specs/backlog/` mirrors as
-**the issue alone**, keeping its phase list in the description; its sub-issues are
-created by the push that follows `/spec-go`, when the work actually starts. Phases
-that are already linked keep syncing either way, so switching an existing project
-over never strands a live sub-issue. See `linear.config.md` for the details.
+**How phases are mirrored** is `mapping.phases`, and it takes one mode for the
+whole repo *or* one per lifecycle bucket:
+
+```json
+"mapping": { "phases": { "backlog": "deferred", "complete": "inline" } }
+```
+
+- `"subissue"` (default) — every phase is a sub-issue from the spec's first push,
+  so agents can be assigned one each.
+- `"deferred"` — unlinked phases wait until the work starts. A spec sitting in
+  `specs/backlog/` mirrors as **the issue alone**, keeping its phase list in the
+  description; the sub-issues arrive with the push that follows `/spec-go`. Worth
+  it when adopting sync on a backlog of dozens of specs, where the default
+  front-loads hundreds of calls for work nobody has started.
+- `"inline"` — phases become **sections of the spec issue's own description**,
+  full task lists included, and no sub-issues are minted. For work nobody will
+  pick up phase by phase: 250 completed specs are 250 readable issues instead of
+  250 issues plus 669 sub-issues.
+
+The per-bucket form exists because those answers differ by *when*, not by repo —
+finished work wants one issue, work in flight wants the assignable sub-issues.
+A bucket the map omits defaults to `"subissue"`; a bad key or mode fails loudly at
+load. Phases already carrying an id keep their sub-issue in every mode and are
+never also inlined, so switching an existing project over never strands a live
+sub-issue. `/spec-push` and `/spec-status` print the mode that resolved. See
+`linear.config.md` for the details and the adoption path.
 
 **Which Project a spec lands in** is asked once, when the issue is first created
 — a filterable list of your team's projects, defaulting to `linear.projectId` and
@@ -136,13 +177,17 @@ always offering *None*. It's passed on the create call only and never stored, so
 re-homing a spec issue in Linear sticks: it won't read as drift and won't be moved
 back on the next push.
 
-**Starting from an issue** (`intake.label` / `intake.bugLabels` in the config):
-`/spec SKI-123` adopts that issue, `/spec --from-issue [query]` browses the inbox.
-The issue *becomes* the spec's issue — the reporter's thread, comments and links
-stay put, their words are carried into the spec's **Problem**, and the first push
-replaces the description with the spec. A bug-labelled issue routes to
-`/spec-bug`, which adopts it the same way. `skitterspec-linear spec-sync linked`
-lists what's already adopted, so an issue never becomes two specs.
+**Starting from an issue** (the `intake` block in the config): `/spec SKI-123`
+adopts that issue, `--from-issue [query]` browses the inbox, and `/spec-bug` and
+`/spec-hotfix` adopt the same way — `/spec-hotfix v33.16.4 SKI-123` starts a
+patch to a released version from the issue that reported it. The issue *becomes*
+the spec's issue — the reporter's thread, comments and links stay put, their
+words are carried into the spec's **Problem** (or **Symptom**), and the linking
+push replaces the description with the spec as it is created. Labels route an
+issue onward: `intake.hotfixLabels` to `/spec-hotfix`, `intake.bugLabels` to
+`/spec-bug`, with hotfix winning when an issue carries both.
+`skitterspec-linear spec-sync linked` lists what's already adopted, so an issue
+never becomes two specs.
 
 **Phase status.** A phase's state in Linear comes from the `⬜`/`🔄`/`✅` on its
 phase-file **heading** — not from its `> **Status:**` line and not from the

package/assets/core/SETUP.md

@@ -73,28 +73,83 @@ claude mcp list
 > `/spec-status` (drift report) without granting write access. `/spec-push`
 > needs the full (writable) endpoint.
 
-## 3. Find your team id
+## 3. Configure — run `/spec-linear-setup`
 
-`linear.config.json` needs your Linear **team UUID**. The easiest way is to just
-ask Claude once the MCP server is connected:
+With the MCP server connected, let the skill do it:
 
-> "List my Linear teams with their ids."
+```
+/spec-linear-setup
+```
+
+It discovers your workspace (teams, projects, labels, issue workflow states),
+asks how the work is **organised**, and writes `specs/.core/linear.config.json`
+for you. You pick from real lists — no UUID is ever typed by hand.
+
+The questions it asks, and why each one matters:
+
+| It asks | Because |
+|---------|---------|
+| Which team does this repo file into? | The config pins **one team per repo**. With several teams the real question is which product's work this repo holds. |
+| Are products split by team, or by project? | Team-per-product ⇒ `teamId` *is* the product and `projectId` stays empty. Project-per-product ⇒ one team, and `projectId` is the picker's default. |
+| Which labels drive intake? | `intake.label` is the inbox `/spec --from-issue` browses; `bugLabels`/`hotfixLabels` route an issue to `/spec-bug` or `/spec-hotfix`. Optional — "none" leaves intake off. |
+
+### What setup validates
+
+The skill hands your answers to `skitterspec spec-sync init-config`, which
+**checks them before writing** — the config is never composed by the model.
+
+The check that earns its keep is on the **workflow-state names**.
+`states` maps each lifecycle bucket to a Linear issue-state name, and
+**Linear silently ignores an issue state it doesn't recognise**: no error, no
+warning. So a workspace that renamed `Done` to `Shipped` would push perfectly
+clean and produce a mirror that *never moves* — and you'd find out weeks later
+wondering why nothing in Linear reflects your specs. Setup compares the
+configured names against the workspace's real ones and refuses, naming the flag
+that fixes each:
+
+```
+states.complete: "Done" is not an issue state in this workspace
+  pass --state complete="Shipped"
+```
+
+It also writes **only the keys that differ from the defaults**, so the file shows
+the handful of choices that are actually yours and keeps inheriting the rest as
+they improve.
+
+**Re-running is safe.** With a config already present the skill *reviews* it
+against the live workspace rather than replacing it — the quickest way to find
+out that a team was archived or a state renamed. It only rewrites if you ask.
+
+## 4. Configure by hand (if you're not using Claude Code)
+
+The skill is the recommended path, not the only one — the CLI works on its own.
 
-It calls the Linear `list_teams` tool and returns rows like:
+**Find your team id.** Ask Claude ("List my Linear teams with their ids"), or
+call Linear's `list_teams` yourself. You'll get rows like:
 
 ```
 Skitterspec — e07c2b54-dcf6-4b6e-81bd-175a9bc79868  (key: SKI)
 ```
 
-Copy the `id` (the UUID). The `key` (e.g. `SKI`) is the short human handle. If most
-of your specs belong to one **Project**, ask "list my Linear projects" and copy
-that id into `linear.projectId` — it becomes the *default* the project picker
-pre-selects, not a fixed destination.
+Copy the `id` (the UUID); the `key` (e.g. `SKI`) is the short human handle.
 
-## 4. Scaffold the config
+**Then either run the engine directly:**
 
-`init` dropped a `specs/.core/linear.config.json.example`. Copy it and fill in the
-ids from step 3 — the team id is the only required field:
+```sh
+skitterspec spec-sync init-config \
+  --team-id e07c2b54-dcf6-4b6e-81bd-175a9bc79868 --team-key SKI \
+  --intake-label web-app --bug-labels bug \
+  --states states.json          # a JSON array of your issue-state names
+```
+
+`--states` is optional here (unlike `/spec-push`'s check, which is mandatory) —
+without a config there is nothing to read a team from, so the names can't be
+fetched first. Pass it if you have them; without it the command writes and tells
+you the names are unverified.
+
+**Or copy the example and edit it.** `init` dropped a
+`specs/.core/linear.config.json.example`; the team id is the only required
+field:
 
 ```jsonc
 // specs/.core/linear.config.json
@@ -115,6 +170,10 @@ Everything else (state names, field ownership) has sensible defaults — see
 `linear.config.md` to customise. The moment this file exists, the Linear steps in
 `/spec` and `/spec-go` and the three sync skills switch on.
 
+> Editing by hand skips the state-name check described above. If you go this
+> route and your workspace renamed any state, `/spec-push` catches it at your
+> first push instead.
+
 ## 5. Link a spec to a Linear issue
 
 A spec syncs once its `00-overview.md` frontmatter carries a `linear_identifier`.
@@ -199,7 +258,8 @@ With a linked spec, confirm push end-to-end:
   pass the file yourself.
 - **"refusing — configured state name(s) not in the workspace"** — Linear ignores
   an unknown issue state, so this is caught before the push rather than after.
-  Fix `linear.config.json` to the real issue-state names
+  The refusal names the replacement for each; re-run `/spec-linear-setup` to fix
+  it, or edit `linear.config.json` → `states` to the real issue-state names
   (`Backlog / Todo / In Progress / Done / Canceled`). Upgrading from 8.x, the
   value inverts: project status `Completed` → issue state `Done`.
 - **Reconnecting doesn't switch workspace** — Linear ties the OAuth session to one

package/assets/core/linear.config.json.example

@@ -6,7 +6,8 @@
   },
   "intake": {
     "label": "",
-    "bugLabels": []
+    "bugLabels": [],
+    "hotfixLabels": []
   },
   "mapping": {
     "specFolder": "issue",
@@ -25,6 +26,12 @@
   "branch": {
     "pattern": "{type}/{slug}"
   },
+  "auth": {
+    "keyEnv": "LINEAR_API_KEY"
+  },
+  "apply": {
+    "transport": ""
+  },
   "sync": {
     "baseDir": "specs/.core/linear-base",
     "fieldOwnership": {

package/assets/core/linear.config.md

@@ -35,10 +35,11 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push` is a hard error
   },
 
   // Issue intake: `/spec <ISSUE-REF>` adopts any issue; `/spec --from-issue`
-  // browses the inbox. Both optional.
+  // browses the inbox. All optional.
   "intake": {
     "label": "",          // inbox filter — the label the web app files under
-    "bugLabels": []       // e.g. ["bug"] — these route to /spec-bug instead
+    "bugLabels": [],      // e.g. ["bug"] — these route to /spec-bug instead
+    "hotfixLabels": []    // e.g. ["production"] — these route to /spec-hotfix
   },
 
   // How a spec's parts map onto Linear objects: a spec is an Issue, each phase a
@@ -175,15 +176,103 @@ altered is reported with both sides of the first difference. It warns rather tha
 fails — the repo is unaffected and re-pushing overwrites the mirror. This is not
 a pull: nothing read back is merged, stamped or written anywhere.
 
-## Deferring sub-issues until a spec starts
+## How the push reaches Linear — `auth` and `apply`
 
-`mapping.phases` decides *when* a phase becomes a sub-issue:
+By default `/spec-push` applies its plan **over MCP**: the assistant makes one
+`save_issue` call per object. That works with no setup at all — MCP carries the
+Linear session you are already signed into — but it means every issue description
+is generated as output tokens, and read back the same way, so a large push is
+bounded by the model rather than by Linear.
+
+Set a **Linear personal API key** and the engine talks to Linear directly
+instead:
+
+```bash
+export LINEAR_API_KEY=lin_api_…      # from Linear → Settings → Security & access
+```
+
+```json
+"auth":  { "keyEnv": "LINEAR_API_KEY" },
+"apply": { "transport": "" }
+```
+
+- **`auth.keyEnv`** names the environment variable the key is read from.
+  It names the **variable, never the key** — nothing secret is ever written to
+  this file or to the repo.
+- **`apply.transport`** pins the transport: `"api"`, `"mcp"`, or `""` (the
+  default) to decide per run — the API when a key is present, MCP when it isn't.
+  `spec-sync apply --via <api|mcp>` overrides it for one run.
+
+With a key present, `/spec-push` runs a single `spec-sync apply`, which writes,
+reads back what Linear stored, stamps the ids into your spec and records the
+snapshot. Descriptions never pass through the assistant in either direction.
+
+**An interrupted run is safe to repeat.** Each id is written into the spec as soon
+as its object exists, so re-running applies only what is still missing.
+It never mints a second copy of an issue it already created. There is no ledger
+to keep in step; the spec files are the record.
+
+Without a key, nothing changes: the MCP path is fully supported and remains the
+default for anyone who never sets one.
+
+## How phases are mirrored — `mapping.phases`
+
+`mapping.phases` decides *whether and when* a phase becomes a sub-issue:
 
 - `"subissue"` (default) — from the spec's first push. A spec costs `1 + N`
   `save_issue` calls to mirror, N being its phase count.
 - `"deferred"` — only once the work starts. A spec sitting in `specs/backlog/`
   mirrors as **the issue alone**; its sub-issues are created by the push that
   follows `/spec-go`.
+- `"inline"` — never. Each phase becomes a **section of the spec issue's own
+  description**, with its full task list, and the `## Phases` index stays as the
+  table of contents. One issue per spec, however many phases it has.
+
+### One mode, or one per bucket
+
+Either form is valid:
+
+```json
+"mapping": { "phases": "subissue" }
+```
+
+```json
+"mapping": {
+  "phases": { "backlog": "subissue", "in-progress": "subissue", "complete": "inline" }
+}
+```
+
+A **scalar** applies one mode to the whole repo — that is what every config was
+before per-bucket mapping, and it still means exactly what it meant. A **map**
+keys the mode by the spec's lifecycle bucket: `backlog`, `in-progress`,
+`complete`, `cancelled`. A bucket the map **omits defaults to `subissue`**, so a
+partial map adds an exception for the buckets it names rather than quietly
+changing the ones it does not.
+
+An unknown key or an unknown mode is a **loud error** at load, not a fallback: a
+misspelt `"completed"` that read as "the map said nothing" would go on minting
+exactly the sub-issues the config was written to stop, and look deliberate doing
+it.
+
+Why per bucket rather than per repo: phases became sub-issues so that parallel
+agents could be assigned one each. That reasoning holds for work in flight and
+does not hold for work that finished long ago — a repo with 250 completed specs
+gets 669 sub-issues nobody will ever read. Set `complete: "inline"` and those
+mirror as 250 readable issues, while the backlog keeps the assignable sub-issues
+that made the choice worth it.
+
+### Switching modes is non-destructive
+
+**A phase already carrying a `linear_issue_id` keeps its sub-issue in every
+mode**, and is never *also* inlined. One-way sync has no delete op, so
+withholding a live sub-issue would not remove it from Linear — it would freeze it
+there, never updated again. So changing `mapping.phases` only ever changes what
+has yet to be minted, and a spec part-way through keeps a coherent mirror.
+
+**Adopting on an established repo:** set `complete: "inline"` (and `"deferred"`
+or `"inline"` for `backlog`) **before** the first backfill push. Finished specs
+then never mint sub-issues at all, rather than minting them and stranding them.
+
 
 Deferral is worth setting when you adopt sync on a project that already has a
 long backlog, where the default means mirroring every phase of every spec nobody
@@ -208,11 +297,43 @@ What defers and what does not:
 - **`/spec-push` and `/spec-status` say so**, printing `N phase(s) deferred`, and
   the JSON plan carries a `phasesDeferred` count — a spec with no sub-issues
   reads as deliberate rather than as phase files that failed to parse.
+- **Both also print the resolved mode** as `phases: <mode>` whenever it is not
+  the default, naming the bucket it resolved through, and the JSON plan always
+  carries it as `phaseMode`. With a per-bucket map the config alone no longer
+  tells you which mode a given spec got, so the report is where that is stated.
 
 There is no snapshot state behind this and nothing to migrate: the last-pushed
 snapshot only ever recorded sub-issues that have an id, so a deferred phase is
 simply absent from it and arrives as an ordinary `create` when it projects.
 
+### What `inline` renders
+
+Each unlinked phase is appended to the description as a `###` section carrying
+the **same body its sub-issue would have had** — the identical composer, so
+`inline` inherits every fidelity guarantee the sub-issue form has rather than
+being a second, thinner projection. The body's own headings are demoted to nest
+under that `###` (a phase's `## Tasks` would otherwise read as a sibling of the
+spec's `## Problem` and drag every later phase under it).
+
+```markdown
+## Phases
+
+| # | Phase | Status | File |
+| 1 | Mode resolver | ✅ | [01-mode-resolver.md](01-mode-resolver.md) |
+
+### Phase 1 — Mode resolver ✅
+
+**Goal:** one resolver decides the mode for a spec.
+
+#### Tasks
+
+- [x] Extend the config loader
+```
+
+The phase heading is the phase file's h1 **as written**, emoji included: a
+sub-issue projects its title as `name` and its status emoji as `state`, and
+inlined there are no such fields for either to live in.
+
 ## Which Project a spec issue belongs to
 
 `linear.projectId` is the **default**, not a mandate. When a spec issue is first
@@ -228,6 +349,28 @@ issue exists, where it lives is Linear's business: move it between projects and
 A spec that **adopted** an existing issue (see below) skips the picker entirely —
 it was filed somewhere deliberately.
 
+### Known limits — one team per repo, no initiatives
+
+Two things this config deliberately cannot express today. Both are limits, not
+oversights; `/spec-linear-setup` says so during setup rather than letting you
+find out later.
+
+**One team per repo.** `linear.teamId` is a single value, so every spec in a repo
+files into the same Linear team. If your workspace runs a team per product and a
+repo genuinely spans two of them, sync has no way to say that — pick the team
+that owns most of the work, or split the specs across two checkouts. (Splitting
+products by **project** inside one team has no such limit: that is what
+`projectId` and the picker are for.)
+
+**Initiatives are not used for placement.** A spec issue attaches to a team and
+optionally a project — never to an initiative. If your projects are grouped under
+initiatives the grouping still works in Linear; you just pick the project inside
+the initiative, and the initiative follows from it. What's missing is *filtering
+the picker* by initiative, which would matter to a workspace with enough projects
+that the flat list stops being useful. The hook is already there when it does:
+Linear's `list_projects` accepts an `initiative` filter, and the API adapter's
+`listProjects` (`src/api.js`) queries `team(id) { projects }` sending none.
+
 ## Starting a spec from an existing issue
 
 With `intake` configured, a spec can begin life as a Linear issue someone else
@@ -236,16 +379,40 @@ filed:
 - `/spec SKI-123` — adopt that issue.
 - `/spec --from-issue [query]` — browse issues labelled `intake.label` (what your
   web app or feedback form files under), optionally filtered by title.
+- `/spec-bug SKI-123` — same, for a bug.
+- `/spec-hotfix v33.16.4 SKI-123` — same, for a bug that has to be patched on a
+  released version. Give the tag or be asked for it; any version the report
+  mentions is offered as a suggestion, never used as a default.
 
 The issue **becomes** the spec's issue: its identifier is stamped as
-`linear_identifier`, phases become its sub-issues, and the first `/spec-push`
-replaces its description with the spec. The reporter's comments, links and
-subscribers stay on the one issue everyone is already watching; their original
-words are carried into the spec's **Problem** section.
+`linear_identifier`, phases become its sub-issues, and the **linking push**
+— which runs as the spec is created — replaces its description with the spec. The
+reporter's comments, links and subscribers stay on the one issue everyone is
+already watching; their original words are carried into the spec's **Problem**
+(or **Symptom**) section, and Linear keeps the original in the issue's history.
 
 An issue already stamped on a spec can't be adopted twice — `skitterspec spec-sync
-linked` is the list that's checked. An issue labelled with one of
-`intake.bugLabels` routes to `/spec-bug` instead, which adopts it identically.
+linked` is the list that's checked.
+
+### Routing an issue to the right skill
+
+Two optional label lists send an issue to a more specific skill, checked in this
+order:
+
+| List | Routes to | Means |
+|------|-----------|-------|
+| `intake.hotfixLabels` | `/spec-hotfix` | broken in production — patch the released version |
+| `intake.bugLabels` | `/spec-bug` | a bug, fixed on `main` like any other |
+
+**`hotfixLabels` wins when an issue carries both.** The two mistakes are not
+equally costly: routing a production issue to `/spec-bug` produces a fix that
+lands on `main` and never reaches the running version — noticed only when someone
+asks why it hasn't shipped. The reverse is a hotfix branch for something that
+could have waited.
+
+`/spec-bug` still checks `hotfixLabels` — being in the bug path is not a reason to
+miss that production is broken. `/spec-hotfix` checks neither; it is already the
+most specific destination. Leave a list empty and nothing routes through it.
 
 ## One direction — nothing to reconcile
 

package/assets/rules/spec-planning.md

@@ -66,17 +66,23 @@ Beneath it, `skitterspec spec-env live <take|release|abort|status>` is the engin
 
 **Ticketing-provider sync (opt-in, a separate package).** The base is
 tracker-free: it knows nothing about any specific ticketing system. A
-ticketing provider is installed as its own distribution that plugs into two named
-**seams** in the shared skills (`/spec` Phase E, `/spec-go` step 3b) and fulfils a
-skill-name + CLI contract. Sync is **one-way**: the repo is the source of truth
-and the tracker is a **generated mirror**. It ships `/spec-push` (repo→tracker;
-computes a create/update plan against a committed last-pushed snapshot and applies
-it) and `/spec-status` (read-only drift report — what would push, and whether the
-tracker's workflow-state drifted), backed by a `spec-sync` CLI. There is no
-content pull — the tracker is never read back or merged. When a provider is
-present, `/spec` also links the spec to the tracker. With no provider installed
-the seams are empty and every skill behaves as a plain filesystem workflow. See
-the provider package's own docs for its config and field reference.
+ticketing provider is installed as its own distribution that plugs into named
+**seams** in the shared skills and fulfils a skill-name + CLI contract.
+Sync is **one-way**: the repo is the source of truth and the tracker is a
+**generated mirror**. It ships `/spec-push` (repo→tracker; computes a create/update plan
+against a committed last-pushed snapshot and applies it) and `/spec-status`
+(read-only drift report — what would push, and whether the tracker's
+workflow-state drifted), backed by a `spec-sync` CLI. There is no content pull —
+the tracker is never read back or merged.
+
+**Every skill that moves a spec through the lifecycle carries a seam**, so the
+mirror keeps up without anyone remembering to push: `/spec`, `/spec-bug` and
+`/spec-hotfix` link the spec they create; `/spec-go` refreshes it as work starts;
+`/spec-complete`, `/spec-cancel` and `/spec-review` refresh it after they change
+it. `/spec-to-main` and `/spec-live` carry none — they change no status.
+With no provider installed the seams are empty and every skill behaves as a plain
+filesystem workflow. See the provider package's own docs for its config and field
+reference.
 
 ## Project conventions (fill this in)