@skitterbyte/skitterspec-linear 11.0.0 → 13.0.0

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

@@ -6,6 +6,11 @@ disable-model-invocation: true
 
 # /spec-sync — the repo-wide Linear sync operations
 
+> 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.
+
 `/spec-push` and `/spec-status` cover **one spec**. This skill covers everything
 **repo-wide**, and is the answer to a bare "run spec-sync" — which is not itself
 a command.
@@ -34,12 +39,18 @@ In a project that installs the Linear superset the binary is
 |---------------|-----|
 | bare `/spec-sync`, "what's linked?", "how much is mirrored?" | `linked` |
 | "what states / projects does the workspace have?" | `states`, `projects` |
+| "what specs are there?", "what's in the backlog?", "what is Jane on?" | `list` — or hand to `/spec-list` |
 | "did the mirror survive the push?" | `verify <spec> --stored <file>` |
 | "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` |
+| "move the shipped tickets on", "what's on test?" | `stage` — dry run unless `--apply` |
+| "is any of this wired up?", "why isn't sync working?" | `doctor` — scaffold, isolation, tracker and key in one |
+| "set my Linear key", "am I authenticated?" | `credentials <status\|set\|unset>` |
+| "who am I in Linear?", "why is it assigning the wrong person?" | `whoami` — `--set` for a shared or bot key |
+| "who's on this team?", "find Jane's user id" | `users <name-or-email>` |
 | push one spec, or "what would push?" | **defer** — see below |
 
 **With no argument, run `linked`.** It is the repo-wide overview, it is
@@ -74,6 +85,14 @@ pnpm exec skitterspec-linear spec-sync projects [--via api|mcp] [--json]
 - **`states` / `projects`** reach the workspace. `states` also reports the
   **transport** (`api` when a key is set, else `mcp`), which is the honest way to
   answer "how is this talking to Linear?".
+- **`list`** is the read side of the mirror: every spec issue Linear holds,
+  joined to the local spec folder that owns it. Unlike `linked`, it asks LINEAR
+  what exists rather than the repo — which is the only way to see a spec started
+  on a branch this checkout has not got. Scope is the live states by default
+  (`--all`, `--state <name>`, `--in-progress`, or `--next N` for the top of the
+  backlog in Linear's own order), and `--mine` / `--by <user>` filter by
+  assignee. **`/spec-list` is the front door** — hand over to it for anything
+  beyond a bare listing; it carries the MCP path and the offline degradation.
 
 ## 4. `verify` — check what the tracker actually stored
 
@@ -120,7 +139,7 @@ not the same risk:
 
 A repo adopting Linear reports "N to create" for every unlinked spec, so an
 unconsidered `--all` can mint dozens of sub-issues. Get the counts first — run
-`linked` to see what is unlinked, or `spec-sync push <spec>` per spec for exact
+`linked` to see what is unlinked, or `spec-sync plan <spec>` per spec for exact
 numbers — then show the user something like:
 
 ```
@@ -142,10 +161,10 @@ 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`.
+`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
@@ -170,9 +189,9 @@ the report saying which commits it set aside.
 pnpm exec skitterspec-linear spec-sync retarget [--yes]
 ```
 
-Renaming a Linear team rewrites the key in every issue identifier, and **nothing
-in the repo moves**: the frontmatter stamps, the config `teamKey`, and the
-snapshot filenames and their sub-issue keys all keep the old prefix, so
+Renaming a Linear team rewrites the key in every issue identifier, and
+**nothing in the repo moves**: the frontmatter stamps, the config `teamKey`,
+and the snapshot filenames and their sub-issue keys all keep the old prefix, so
 `/spec-push` starts failing with `no Linear issue found for SKI-7`.
 
 `retarget` detects the rename (the team id survives it; the key does not) and
@@ -195,6 +214,23 @@ so and asks you to confirm the key rather than guessing.
 
 ## 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
-that the repo is unchanged — it is the source of truth either way.
+Relay the engine's output **above the block**, and name the subcommand you ran
+**in full**, so the user can re-run it themselves.
+
+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 subcommand did what it says.
+- `⚠️` — it ran, with something worth knowing — a partial result, a warning it
+  printed, a degradation it fell back to.
+- `❌` — it wrote some objects and failed on another. Say what exists now.
+- `⏸` — it refused: no config, an unvalidated state list, a bad argument.
+  Nothing was written.
+
+**Fields:** `Tracker` · `Follow-ups` · `Next`
+
+`Tracker` says what changed in Linear **and that the repo is unchanged** — it is
+the source of truth either way, and a report that omits the second half reads as
+though a sync had edited the repo.

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

@@ -6,11 +6,16 @@ disable-model-invocation: true
 
 # /spec-to-main — land the branch on main, keep the spec open
 
+> 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.
+
 The **intermediate** landing. `/spec-complete` also lands the branch, but then
 verifies every phase, flips the status to Complete, `git mv`s the spec to
-`complete/`, and tears the environment down. **`/spec-to-main` stops after the
-land**: the worktree stays, the spec stays `In Progress`, and you can land again
-as you add commits.
+`complete/`, and tears the environment down.
+**`/spec-to-main` stops after the land**: the worktree stays, the spec stays
+`In Progress`, and you can land again as you add commits.
 
 Use it when a later phase can only be done *after* the current work is on `main` —
 e.g. it needs to run in CI, a deploy pipeline, or a shared test environment that
@@ -19,9 +24,9 @@ the remaining phases with `/spec-next` and eventually `/spec-complete`.
 
 It reuses the **same engine** as `/spec-complete`'s landing (`spec-env integrate`
 — rebase + fast-forward), so it produces identical linear history. Because a
-fast-forward leaves `base == branch`, the operation is **idempotent and
-repeatable**: new commits put the branch ahead of base again, and you can run
-`/spec-to-main` as many times as you like.
+fast-forward leaves `base == branch`, the operation is
+**idempotent and repeatable**: new commits put the branch ahead of base again,
+and you can run `/spec-to-main` as many times as you like.
 
 ## 0. Preconditions — when this applies
 
@@ -58,10 +63,10 @@ primary checkout is dirty, or if a *different* spec holds it (release that one w
 
 ## 3. Tests must be green before landing
 
-Don't push red to `main`. Run the project's typecheck and test commands **in the
-worktree**; the suite must be **green**. For a **Bug** spec, confirm the
-originally-failing test now passes. If anything is red, stop and report — landing
-broken code onto `main` defeats the purpose.
+Don't push red to `main`. Run the project's typecheck and test commands
+**in the worktree**; the suite must be **green**. For a **Bug** spec, confirm
+the originally-failing test now passes. If anything is red, stop and report —
+landing broken code onto `main` defeats the purpose.
 
 (Note this is the *worktree* suite. The whole point of this skill is often to run
 a *further* check that only exists on `main` / in CI — that one runs **after** the
@@ -69,8 +74,8 @@ land, in step 5.)
 
 ## 4. Land — rebase + fast-forward
 
-Run `skitterspec spec-env integrate <name>` and run the printed commands **in
-order**:
+Run `skitterspec spec-env integrate <name>` and run the printed commands
+**in order**:
 
 - `git -C <worktree> rebase <base>` — replay the branch onto base.
 - `git -C <mainRepoPath> merge --ff-only <branch>` — fast-forward base.
@@ -91,12 +96,29 @@ and continue — the branch has no commits base doesn't already have.
   `- <YYYY-MM-DD> — Landed intermediate work onto <base> to <run CI / deploy to
   test env / …>; spec stays In Progress.`
 - Do **NOT**: add a State-log row (status doesn't change), flip any phase/status
-  to Complete, `git mv` the spec, or tear down the worktree/stack. **The spec
-  stays `In Progress` and the worktree stays put.**
-- Report: the base branch, the fast-forward result, and the green base test. It
-  **never pushes** — mention the user can `git push` the base branch themselves to
+  to Complete, `git mv` the spec, or tear down the worktree/stack.
+  **The spec stays `In Progress` and the worktree stays put.**
+- It **never pushes** — say the user can `git push` the base branch themselves to
   trigger CI / the shared env.
-- Point the way forward: `/spec-next` to continue the remaining phases (you'll keep
-  committing on the same branch and can `/spec-to-main` again), and `/spec-complete`
-  when every phase is genuinely done — it will land the final commits, finalise,
-  and tear down.
+- `Next` points the way forward: `/spec-next` to continue the remaining phases
+  (you'll keep committing on the same branch and can `/spec-to-main` again), and
+  `/spec-complete` when every phase is genuinely done — it will land the final
+  commits, finalise, and tear down.
+
+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 branch is on the base and the base is green.
+- `⚠️` — landed, with something worth knowing.
+- `❌` — the rebase conflicted, or the base went red after the fast-forward.
+  Quote it; the repo is mid-something and that is what the reader needs.
+- `⏸` — a dirty worktree, red tests, or no spec to land. Nothing moved.
+
+**Fields:** `Branch` · `Tests` · `Landed` · `Follow-ups` · `Next`
+
+**No `Spec` field, deliberately.** This skill changes no status and moves no
+folder, and a `Spec` line here would read as though it had. The spec stays
+`In Progress` and the worktree stays standing — if that needs saying, the
+verdict clause says it.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@skitterbyte/skitterspec-linear",
-  "version": "11.0.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.",
+  "version": "13.0.0",
+  "description": "Spec-driven development for Claude Code, with one-way Linear sync \u2014 a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status \u00b7 /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",
     "claude-code",
@@ -25,14 +25,18 @@
     "MIGRATION.md"
   ],
   "engines": {
-    "node": ">=18"
+    "node": ">=22.13"
   },
   "dependencies": {
     "prompts": "^2.4.2"
   },
+  "scripts": {
+    "prepare": "node ../../scripts/build-dist.js skitterspec-linear",
+    "prepack": "node ../../scripts/build-dist.js skitterspec-linear"
+  },
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/skitterbyte/skitterspec.git"
-  },
-  "scripts": {}
-}
+    "url": "git+https://github.com/SkitterByte/skitterspec.git",
+    "directory": "packages/skitterspec-linear"
+  }
+}