@skitterbyte/skitterspec-linear 12.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:
 
 ```
@@ -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,6 +6,11 @@ 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.
@@ -93,10 +98,27 @@ and continue — the branch has no commits base doesn't already have.
 - 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
+- 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": "12.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"
+  }
+}