@skitterbyte/skitterspec-linear 10.5.2 → 10.7.0

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

@@ -7,7 +7,8 @@ description: Promote a spec into active development and build the next phase —
 
 The "up" button: it promotes the spec, provisions its worktree, brings its host
 dev servers up on the spec's reserved ports (with your OK), then builds the phase.
-Diverting your browser to the spec is a separate explicit step — `/spec-connect`.
+Diverting your browser to the spec is a separate explicit step the **user**
+types — `/spec-connect` (a slash command, not a skill you can invoke).
 
 ## 1. Identify the target spec
 
@@ -33,8 +34,8 @@ branch. Instead skip the provisioning bullets and step 2b, leave the spec where
 it is, and go straight to **step 4**, implementing the phase **in the primary
 checkout on the branch** — edits and commits there advance the branch, and
 `/spec-complete` lands them. (`spec-env up` refuses while live and says the same.
-To return to an isolated worktree instead, run `/spec-live main` first, then
-re-run `/spec-go`.)
+To return to an isolated worktree instead, ask the user to type `/spec-live main`
+first, then re-run `/spec-go`.)
 
 **If per-spec isolation is enabled** (`specs/.core/env.config.json` exists), the
 spec **isn't already live** (the check above), and it doesn't already have a
@@ -121,11 +122,12 @@ runnable — its UI/API on the spec's reserved port block, isolated from `main`.
   dev process detached on its port, logs to `.spec-env/logs/`, and waits on each
   `health` check. With no `dev` configured it's a clean no-op; skip this step.
 - **Diverting your browser is a separate step.** To test the spec at your normal
-  `localhost` URL, run **`/spec-connect <name>`** (exclusive — it exposes this
-  spec on the canonical ports; `/spec-connect main` hands them back). `/spec-go`
-  never seizes the canonical ports on its own. For a **code-only** spec, the
-  lighter **`/spec-live <name>`** reuses your already-running dev server (a
-  branch-switch, no second stack) — `/spec-live main` hands it back.
+  `localhost` URL, the **user** types **`/spec-connect <name>`** (exclusive — it
+  exposes this spec on the canonical ports; `/spec-connect main` hands them back).
+  `/spec-go` never seizes the canonical ports on its own. For a **code-only** spec,
+  the lighter **`/spec-live <name>`** reuses the already-running dev server (a
+  branch-switch, no second stack) — `/spec-live main` hands it back. Both are
+  user-only slash commands: tell the user to run one, never try to invoke it.
 
 ## 3. Pre-flight — commit prior work
 
@@ -139,11 +141,17 @@ Before writing any code for this phase, get the workspace clean:
   next phase on top of an uncommitted one. (Skip if this is the first phase —
   there's nothing prior to commit.)
 
-## 3b. Sync with the tracker (only if a provider is installed)
+## 4. Implement the phase
+
+Identify the **first unfinished phase** from the `00-overview.md` phase index,
+then open its phase file (`0N-<slug>.md`) — that file holds the tasks. Mark it
+started: set the phase-file heading to `🔄` and its `> **Status:**` to
+`In progress`, and flip the matching row in the overview phase index to `🔄`.
 
-**Only when a ticketing provider is installed** and the spec is linked to the
-tracker. Otherwise skip this step — no provider means zero change to the flow
-below. Follow the provider's steps below (nothing to do here without one).
+**Then sync with the tracker (only if a provider is installed).** The phase has
+just changed state, so refresh the mirror before the build starts — that is what
+makes the phase show as in progress *while* it is being built rather than only
+once it is over. Without a provider this is a no-op and nothing below changes.
 
 **Only when `specs/.core/linear.config.json` exists** and the spec carries a
 `linear_identifier`. Otherwise skip this step — no config means zero change.
@@ -152,26 +160,27 @@ below. Follow the provider's steps below (nothing to do here without one).
   to bring down before building — the repo is already the source of truth. (A
   workflow-state a teammate moved in Linear is advisory only; `/spec-status`
   surfaces it. It is overwritten on the next push.)
-- **Refresh the mirror.** Run `/spec-push` to send the now in-progress spec up.
-  Whether that is optional depends on `mapping.phases`:
-  - `"subissue"` (the default) — **optional**. The phase sub-issues already
-    exist; this push only moves their states. Refresh now or later.
-  - `"deferred"` — **do it now, without asking.** Under deferral a spec sitting
-    in the backlog is mirrored as the issue alone, and this push is what mints
-    its phase sub-issues. Skip it and a started spec stays mirrored as a
-    phase-less issue until someone happens to run `/spec-push` by hand. Run it
-    straight after the step-2 commit, so the sub-issues land with the same
-    branch push that fires the tracker's automation.
+- **Refresh the mirror now, without asking.** Run `/spec-push`. The spec has just
+  moved to `in-progress` and its phase to `🔄` — both real state changes, and the
+  tracker is a generated mirror of them. This holds under **both**
+  `mapping.phases` modes, for different reasons:
+  - `"subissue"` (the default) — the phase sub-issues already exist, and this
+    push is what moves the current one into its in-progress state. Skip it and
+    every sub-issue sits in Backlog until the spec completes.
+  - `"deferred"` — the sub-issues do not exist yet, and this push is what mints
+    them. Skip it and a started spec stays mirrored as a phase-less issue.
+- **Never mint the spec issue.** An unlinked spec is skipped, not created —
+  `/spec-push` is how someone opts in.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **carry on with the build**. The repo is correct regardless; the mirror is
+  disposable and the next push repairs it.
+- **Expect a dirty `specs/.core/` afterwards.** The push writes a base snapshot
+  and stamps any new ids, and `/spec-go` does not commit. The next `/commit`
+  sweeps it up with the phase's own work.
 - Linear's GitHub branch/PR automation may drive status transitions off the
   branch/PR you pushed in step 2; that's expected and the repo still wins on the
   next `/spec-push`.
 
-## 4. Implement the phase
-
-Identify the **first unfinished phase** from the `00-overview.md` phase index,
-then open its phase file (`0N-<slug>.md`) — that file holds the tasks. Mark it
-started: set the phase-file heading to `🔄` and its `> **Status:**` to
-`In progress`, and flip the matching row in the overview phase index to `🔄`.
 Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.md`:
 
 - Work task by task through the phase file. Make focused edits that match
@@ -194,6 +203,29 @@ Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.m
 - If new work surfaced, add it as tasks to the appropriate phase file (or add a
   new phase file + index row) rather than doing it silently.
 
+**Then refresh the mirror (only if a provider is installed).** The phase is done
+in the repo now; leaving the tracker to catch up at `/spec-complete` is what makes
+a mirror lag a whole spec behind. Without a provider this is a no-op.
+
+**Only when `specs/.core/linear.config.json` exists** and the spec carries a
+`linear_identifier`. Either missing → **skip**, in one line
+(`not linked to Linear — /spec-push to mirror it`), and carry on.
+
+**Refresh the mirror now, without asking.** Run `/spec-push`. The repo has just
+become the truth about this phase's progress, and progress is what the mirror
+exists to show. Deferring it to `/spec-complete` is what makes every phase
+sub-issue jump from Backlog straight to Done, with nothing visible in between.
+
+- **Never mint.** An unlinked spec is skipped, not created.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **finish the operation anyway**. The phase is done in the repo regardless;
+  the mirror is disposable and the next push repairs it.
+- **Expect a dirty `specs/.core/` afterwards.** The push writes a base snapshot
+  and stamps any new ids, and these skills do not commit. The next `/commit`
+  sweeps it up with the phase's own work.
+- **Say what happened** in the skill's report: mirror updated, skipped as
+  unlinked, or failed with the reason.
+
 ## 6. Report
 
 Summarise what was implemented, the test result (quote failures if any), and

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

@@ -155,8 +155,22 @@ that header — must exist **before** `spec-env up`:
   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:
-  `mv specs/in-progress/hotfix-<name> <worktreePath>/specs/in-progress/`.
+  stays pristine. **Create the destination bucket first:**
+
+  ```
+  mkdir -p <worktreePath>/specs/in-progress
+  mv specs/in-progress/hotfix-<name> <worktreePath>/specs/in-progress/
+  ```
+
+  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
   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
@@ -318,6 +332,30 @@ message.
 - Commit the fix to the `hotfix/<slug>` branch (this commit is what gets tagged
   and cherry-picked). Tick the Fix tasks; add a Changelog line.
 
+**Then refresh the mirror (only if a provider is installed).** The Fix tasks are
+ticked, so the repo is now the truth about this fix — and this skill can take a
+bug all the way to green without `/spec-go` ever running. Without a provider this
+is a no-op.
+
+**Only when `specs/.core/linear.config.json` exists** and the spec carries a
+`linear_identifier`. Either missing → **skip**, in one line
+(`not linked to Linear — /spec-push to mirror it`), and carry on.
+
+**Refresh the mirror now, without asking.** Run `/spec-push`. The repo has just
+become the truth about this phase's progress, and progress is what the mirror
+exists to show. Deferring it to `/spec-complete` is what makes every phase
+sub-issue jump from Backlog straight to Done, with nothing visible in between.
+
+- **Never mint.** An unlinked spec is skipped, not created.
+- **Never fatal.** If the push fails — offline, no key, a Linear error — say so
+  and **finish the operation anyway**. The phase is done in the repo regardless;
+  the mirror is disposable and the next push repairs it.
+- **Expect a dirty `specs/.core/` afterwards.** The push writes a base snapshot
+  and stamps any new ids, and these skills do not commit. The next `/commit`
+  sweeps it up with the phase's own work.
+- **Say what happened** in the skill's report: mirror updated, skipped as
+  unlinked, or failed with the reason.
+
 ## 7. Report
 
 Summarise: the base tag, root cause, the failing→passing test, the fix, and the
@@ -325,7 +363,7 @@ full test result. 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, use `/spec-connect` (its own isolated stack).
+  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

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

@@ -142,7 +142,38 @@ never apply one they didn't agree to), and re-run with the `--state` flags. If i
 made no suggestion for a bucket, **ask** which state means "finished" here rather
 than guessing.
 
-## 7. Write it
+## 7. Does this repo deploy through stages? (optional)
+
+A spec's lifecycle ends at `complete`. Where a ticket goes **after** that —
+deployed to test, approved for demo, live in production — is a fact about an
+environment, and nothing in the repo can derive it. If the team runs a deploy
+pipeline, it can declare that ladder here and CI moves tickets along it with
+`spec-sync stage`.
+
+**Ask, do not assume.** Most projects have no ladder, and an invented one is
+worse than none: `spec-sync stage` refuses cleanly when none is declared, whereas
+a wrong ladder is a pipeline quietly moving tickets to the wrong column. If the
+user does not raise deployment, offer it once in a line and take "no" for an
+answer.
+
+If they do want one, ask for the stages **in deployment order**, and map each to
+a state from the `list_issue_statuses` names you already have:
+
+```
+--stage test="On Test" --stage demo="Ready for Demo" --stage prod="Done"
+```
+
+- The **key** (`test`) is what a pipeline names; the **state** is the Linear
+  column. Pipelines reference the key, so renaming the column later is one edit
+  here.
+- Order is recorded, not enforced — a rollback and a hotfix straight to prod are
+  both legitimate and are never refused.
+- **Ask what closes an issue.** If the last rung is not a completed-type state,
+  tickets that finish the ladder never reach Done. That is fine when Linear
+  automation closes them and a problem otherwise — `spec-sync doctor` warns about
+  it either way, so say which it is.
+
+## 8. Write it
 
 ```
 skitterspec spec-sync init-config \
@@ -157,12 +188,17 @@ shows this repo's choices and keeps inheriting everything else. `--force` is
 required to replace an existing config — never pass it without the user having
 asked for a rewrite in step 1.
 
+Every `--stage` state is checked against the workspace exactly like a bucket
+state, and a bad one is refused the same way — as `release.stages[test]` rather
+than `states.complete`. There is no suggestion for a rung: the vocabulary is the
+project's own, so ask rather than guess.
+
 **Relay the engine's report as printed.** It names the team, the project (or
 "team only"), the intake labels, and how many state names were checked against
 the workspace — that report is the evidence the setup is right, so don't
 paraphrase it into "done".
 
-## 8. Report and hand off
+## 9. Report and hand off
 
 **Finish by checking, not by describing.** First write down what the MCP server
 says, from the reads you already made in step 2 — no extra round trip unless a

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

@@ -1,6 +1,7 @@
 ---
 name: spec-status
 description: Show a spec's one-way sync status against Linear — a read-only drift report. Reports whether the spec changed since the last push (there's something to push) and, optionally, whether Linear's issue workflow-state differs from the spec's. Fetches the Linear issue over MCP and runs `skitterspec spec-sync status`. Changes nothing. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-status", "is this spec in sync with Linear", "what would push", or "show spec sync status".
+disable-model-invocation: true
 ---
 
 # /spec-status — one-way sync drift report

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

@@ -1,6 +1,7 @@
 ---
 name: spec-sync
 description: Run the repo-wide spec-sync operations against Linear — what's linked, the workspace's states and projects, read-back verification, manual stamping, and bulk `apply --all <bucket>`. Run it bare for the repo-wide overview. Wraps the `spec-sync` CLI, which is a local devDependency and never on PATH, so this skill always states the full invocation. Defers to /spec-push and /spec-status for per-spec work. Opt-in — needs specs/.core/linear.config.json. Use when the user says "/spec-sync", "run spec-sync", "what's linked to Linear", "which states does the workspace have", or "mirror the whole backlog".
+disable-model-invocation: true
 ---
 
 # /spec-sync — the repo-wide Linear sync operations
@@ -37,6 +38,8 @@ In a project that installs the Linear superset the binary is
 | "link this spec to KEY-1 by hand" | `stamp <spec> --issue KEY-1` |
 | "mirror the whole backlog / every complete spec" | `apply --all <bucket>` — **confirm first** |
 | "is the team key stale?", "did Linear get renamed?" | `retarget` |
+| "what ticket am I on?", writing a commit | `ref` |
+| "what shipped in this release?" | `released` |
 | push one spec, or "what would push?" | **defer** — see below |
 
 **With no argument, run `linked`.** It is the repo-wide overview, it is
@@ -131,7 +134,29 @@ its object exists, so an interrupted run continues rather than duplicating.
 
 `--all` refuses over MCP by design — bulk goes through the API path.
 
-## 7. `retarget` — after a Linear team is renamed
+## 7. `ref` and `released` — tickets in commits
+
+```
+pnpm exec skitterspec-linear spec-sync ref [--json]
+pnpm exec skitterspec-linear spec-sync released [<range>] [--json]
+```
+
+`ref` prints the ticket for the branch you are on, so a commit can carry
+`Refs: <KEY-N>` — see `.claude/rules/commit-trailers.md`. **Off a spec branch, or
+on a spec that is not linked, it prints nothing and exits non-zero.** That is the
+correct answer, not an error to work around: do not invent a ref, and never write
+`Refs: none`.
+
+`released` reports the tickets in a commit range — by default since the most
+recent tag, and it always prints the range it chose so a wrong default is
+visible. It is **read-only**: it does not move anything in Linear. A release can
+be cut and never deployed, so transitioning tickets stays a deliberate act.
+
+Relay the **unreferenced count** even when it is zero. A chore commit
+legitimately carries no ticket and a *missed* trailer looks identical, so
+omitting the number reads as "everything is accounted for" when it may not be.
+
+## 8. `retarget` — after a Linear team is renamed
 
 ```
 pnpm exec skitterspec-linear spec-sync retarget [--yes]
@@ -160,7 +185,7 @@ rewrites those fields. Read-only until `--yes`.
 Over MCP the team key is unreadable (`get_team` does not return it), so it says
 so and asks you to confirm the key rather than guessing.
 
-## 8. Report
+## 9. Report
 
 Relay the engine's output. Name the subcommand you ran, in full, so the user can
 re-run it themselves. For anything that wrote, say what changed in Linear and

package/assets/skills/spec-to-main/SKILL.md

@@ -1,6 +1,7 @@
 ---
 name: spec-to-main
 description: Land an in-progress spec's branch onto main WITHOUT finishing it — rebase + fast-forward so the work reaches main (to run it in CI / a shared test env), while the worktree stays and the spec stays In Progress. Repeatable — land again as you commit more. Targets a spec by name (arg) or the spec in context. Use when the user says "/spec-to-main", "land this on main but keep going", "I need this on main to run tests before finishing", or "merge to main without completing the spec".
+disable-model-invocation: true
 ---
 
 # /spec-to-main — land the branch on main, keep the spec open
@@ -51,7 +52,7 @@ uncommitted changes, offer `/commit` and **stop**; don't auto-commit.
 back to base, re-isolates it into its worktree, clears the receipt), then prints
 the landing plan. Commit any live fixes to the branch first; it refuses if the
 primary checkout is dirty, or if a *different* spec holds it (release that one with
-`/spec-live main`).
+`/spec-live main`, which the user types).
 
 ## 3. Tests must be green before landing
 

package/bin/skitterspec-linear.js

@@ -41,6 +41,16 @@ const {
 async function main(argv) {
   const [cmd, ...rest] = argv
 
+// The check above asks whether src/ exists, which is inert in a workspace source
+// package — src/ is committed there. That is exactly where the other half of the
+// problem lives: a source package HAS a runnable bin and src, but its assets/ is
+// PRE-composition (seam markers still literal). Installing from it writes those
+// markers into the user's skills. So ask a second, positive question before any
+// install command runs.
+  if (cmd === 'init' || cmd === 'update') {
+    require('../src/init.js').assertComposedAssets()
+  }
+
   // Base help + what this distribution adds. Matched on the COMMAND SLOT only,
   // never the whole argv: `spec-sanitise --help` must reach that command's own
   // help, not be swallowed by the top-level one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "10.5.2",
+  "version": "10.7.0",
   "description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
   "keywords": [
     "claude",