@skitterbyte/skitterspec-linear 18.3.1 → 19.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/MIGRATION.md +170 -1
- package/README.md +9 -7
- package/assets/core/SETUP.md +4 -4
- package/assets/core/env.config.md +1 -1
- package/assets/core/linear.config.json.example +2 -1
- package/assets/core/linear.config.md +59 -48
- package/assets/rules/spec-planning.md +35 -12
- package/assets/rules/spec-reports.md +47 -6
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +32 -9
- package/assets/skills/spec-bug/SKILL.md +6 -4
- package/assets/skills/spec-hotfix/SKILL.md +4 -2
- package/assets/skills/spec-linear-setup/SKILL.md +9 -35
- package/assets/skills/spec-list/SKILL.md +13 -1
- package/assets/skills/spec-next/SKILL.md +5 -3
- package/assets/skills/spec-push/SKILL.md +1 -1
- package/assets/skills/spec-status/SKILL.md +30 -26
- package/assets/skills/spec-sync/SKILL.md +6 -5
- package/package.json +1 -1
- package/src/cli.js +114 -28
- package/src/env/resolve.js +11 -4
- package/src/env/review.js +126 -2
- package/src/vendor/linear/api.js +30 -1
- package/src/vendor/linear/cli-sync.js +64 -269
- package/src/vendor/linear/config.js +30 -49
- package/src/vendor/linear/doctor.js +4 -66
- package/src/vendor/provider-kit/src/config.js +101 -48
- package/src/vendor/provider-kit/src/list-assignee.js +71 -0
- package/src/vendor/provider-kit/src/list-rows.js +35 -0
- package/src/vendor/provider-kit/src/released.js +27 -77
- package/src/vendor/provider-kit/src/specs.js +89 -7
- package/src/vendor/sync-core/index.js +3 -4
- package/src/vendor/sync-core/src/compare.js +6 -6
- package/src/vendor/sync-core/src/normalize.js +60 -59
- package/assets/core/ci-stages.md +0 -110
- package/src/vendor/provider-kit/src/releases.js +0 -380
|
@@ -188,9 +188,31 @@ not write the spec until this is resolved.
|
|
|
188
188
|
Stop grilling when there are no unresolved branches that would change the spec.
|
|
189
189
|
Briefly play back the agreed understanding before writing.
|
|
190
190
|
|
|
191
|
+
### Propose the kind — feature or chore
|
|
192
|
+
|
|
193
|
+
This skill writes two kinds of spec, and
|
|
194
|
+
**you propose which from what the grilling defined, with a one-line reason; the user confirms or overrides.**
|
|
195
|
+
The
|
|
196
|
+
line that decides it: a **chore** is anything that is not work end users see or
|
|
197
|
+
functions they use within the app — tooling, CI, dependency bumps, internal
|
|
198
|
+
refactors. Everything user-facing is a **feature**. So the proposal reads like
|
|
199
|
+
*"no user-visible surface → chore"* or *"adds an endpoint users call → feature"*.
|
|
200
|
+
|
|
201
|
+
The kind is recorded twice, and both follow from the answer: the folder prefix
|
|
202
|
+
(`feat-` / `chore-`) and the `> **Type:**` header (`Feature` / `Chore`). A chore
|
|
203
|
+
also defaults its `Gating:` to `none: not user-facing` (only when gating is
|
|
204
|
+
configured — offer the default, let the user override it like any other
|
|
205
|
+
answer), and its commits default to `chore`/`refactor`/`ci` types with no
|
|
206
|
+
`Release-Note:` (see `.claude/rules/spec-planning.md`).
|
|
207
|
+
|
|
208
|
+
There is no `/spec-chore` and none should be added: one entry point, one grill,
|
|
209
|
+
and the kind is an output of understanding the work rather than a door the user
|
|
210
|
+
must pick before describing it.
|
|
211
|
+
|
|
191
212
|
## Phase B — write the spec
|
|
192
213
|
|
|
193
|
-
This skill is for **features**. For bugs, use `/spec-bug`
|
|
214
|
+
This skill is for **features and chores**. For bugs, use `/spec-bug`
|
|
215
|
+
(test-first, red→green).
|
|
194
216
|
|
|
195
217
|
### Write it in its own worktree
|
|
196
218
|
|
|
@@ -257,8 +279,8 @@ move to, **warn, don't refuse**, and say the trailer for that commit wants
|
|
|
257
279
|
that phase's goal, its task checkboxes (tests included), and any phase-specific
|
|
258
280
|
notes. **Even a single-phase spec gets `01-….md`** — never lump phase tasks
|
|
259
281
|
into `00-overview.md`. This keeps each phase easy to dive into on its own.
|
|
260
|
-
- Choose a short kebab-case name and **prefix it
|
|
261
|
-
uses `bug-`).
|
|
282
|
+
- Choose a short kebab-case name and **prefix it with the kind** — `feat-` for
|
|
283
|
+
a feature, `chore-` for a chore (the bug counterpart uses `bug-`).
|
|
262
284
|
|
|
263
285
|
Use this template (keep it **as concise as possible** — no filler, no restating
|
|
264
286
|
the codebase, link rather than duplicate):
|
|
@@ -266,8 +288,8 @@ the codebase, link rather than duplicate):
|
|
|
266
288
|
```markdown
|
|
267
289
|
# <Feature title>
|
|
268
290
|
|
|
269
|
-
> **Type:** Feature
|
|
270
|
-
> **Name:** feat
|
|
291
|
+
> **Type:** <Feature or Chore — the kind proposed after Phase A>
|
|
292
|
+
> **Name:** <feat- or chore-><kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
|
|
271
293
|
> **Status:** Ready — not started
|
|
272
294
|
> **Author:** <git user.name — `git config user.name`>
|
|
273
295
|
> **Developer:** —
|
|
@@ -276,7 +298,8 @@ the codebase, link rather than duplicate):
|
|
|
276
298
|
> **Stack:** <worktree — or "worktree + docker" if it touches the DB/stateful
|
|
277
299
|
> services; only acted on when isolation is enabled — see Phase A item 9>
|
|
278
300
|
> **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
|
|
279
|
-
> is configured; omit the line entirely otherwise.
|
|
301
|
+
> is configured; omit the line entirely otherwise. A chore defaults to
|
|
302
|
+
> "none: not user-facing". An empty value or a bare
|
|
280
303
|
> "none" is not a valid outcome — see Phase A item 10>
|
|
281
304
|
|
|
282
305
|
## Problem
|
|
@@ -538,8 +561,8 @@ the verdict — and the reader's conclusion is about what the page showed them.
|
|
|
538
561
|
|
|
539
562
|
**A watch that dies is re-armed on the same window**, silently and bounded by
|
|
540
563
|
the age of that window — `.claude/rules/spec-reports.md` carries the contract,
|
|
541
|
-
including when to stop
|
|
542
|
-
here.
|
|
564
|
+
including when to stop, what the banner says instead, and when the
|
|
565
|
+
engine's `re-show:` brings the banner back. Do not restate it here.
|
|
543
566
|
|
|
544
567
|
```
|
|
545
568
|
skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json
|
|
@@ -647,7 +670,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
|
|
|
647
670
|
an update the issue already has a project (or deliberately has none), and that
|
|
648
671
|
placement is **Linear's to own**: never send `project` on an update, and never
|
|
649
672
|
record the choice in the spec file or the snapshot. A PM re-homing a spec issue
|
|
650
|
-
must not
|
|
673
|
+
must not be reported or overwritten on the next push.
|
|
651
674
|
|
|
652
675
|
1. **List the candidates.** Ask the engine:
|
|
653
676
|
`skitterspec spec-sync projects --json`. On the API path it returns the team's
|
|
@@ -448,7 +448,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
|
|
|
448
448
|
an update the issue already has a project (or deliberately has none), and that
|
|
449
449
|
placement is **Linear's to own**: never send `project` on an update, and never
|
|
450
450
|
record the choice in the spec file or the snapshot. A PM re-homing a spec issue
|
|
451
|
-
must not
|
|
451
|
+
must not be reported or overwritten on the next push.
|
|
452
452
|
|
|
453
453
|
1. **List the candidates.** Ask the engine:
|
|
454
454
|
`skitterspec spec-sync projects --json`. On the API path it returns the team's
|
|
@@ -571,8 +571,8 @@ and the routing on the verdict is `/spec-diff` §2 and §4, as it is everywhere.
|
|
|
571
571
|
|
|
572
572
|
**A watch that dies is re-armed on the same window**, silently and bounded by
|
|
573
573
|
the age of that window — `.claude/rules/spec-reports.md` carries the contract,
|
|
574
|
-
including when to stop
|
|
575
|
-
here.
|
|
574
|
+
including when to stop, what the banner says instead, and when the
|
|
575
|
+
engine's `re-show:` brings the banner back. Do not restate it here.
|
|
576
576
|
|
|
577
577
|
**Why this skill arms as well as waits.** Waiting is what any offer does;
|
|
578
578
|
**arming** asserts an obligation that outlives the turn, and belongs only to
|
|
@@ -614,7 +614,9 @@ underneath a reader when detection flipped mid-session.
|
|
|
614
614
|
|
|
615
615
|
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
616
616
|
`network` — the other addresses this machine has, offered because the
|
|
617
|
-
best-guess one can be wrong — so pass them on rather than editing them out
|
|
617
|
+
best-guess one can be wrong — so pass them on rather than editing them out: in
|
|
618
|
+
the banner they are indented sub-bullets under **network**, labels
|
|
619
|
+
(`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
|
|
618
620
|
|
|
619
621
|
**Never read an environment variable to decide anything about the offer** — not
|
|
620
622
|
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
@@ -480,7 +480,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
|
|
|
480
480
|
an update the issue already has a project (or deliberately has none), and that
|
|
481
481
|
placement is **Linear's to own**: never send `project` on an update, and never
|
|
482
482
|
record the choice in the spec file or the snapshot. A PM re-homing a spec issue
|
|
483
|
-
must not
|
|
483
|
+
must not be reported or overwritten on the next push.
|
|
484
484
|
|
|
485
485
|
1. **List the candidates.** Ask the engine:
|
|
486
486
|
`skitterspec spec-sync projects --json`. On the API path it returns the team's
|
|
@@ -625,7 +625,9 @@ underneath a reader when detection flipped mid-session.
|
|
|
625
625
|
|
|
626
626
|
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
627
627
|
`network` — the other addresses this machine has, offered because the
|
|
628
|
-
best-guess one can be wrong — so pass them on rather than editing them out
|
|
628
|
+
best-guess one can be wrong — so pass them on rather than editing them out: in
|
|
629
|
+
the banner they are indented sub-bullets under **network**, labels
|
|
630
|
+
(`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
|
|
629
631
|
|
|
630
632
|
**Never read an environment variable to decide anything about the offer** — not
|
|
631
633
|
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
@@ -147,36 +147,14 @@ never apply one they didn't agree to), and re-run with the `--state` flags. If i
|
|
|
147
147
|
made no suggestion for a bucket, **ask** which state means "finished" here rather
|
|
148
148
|
than guessing.
|
|
149
149
|
|
|
150
|
-
## 7.
|
|
150
|
+
## 7. Deploys are the project's own to record
|
|
151
151
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
**Ask, do not assume.** Most projects have no ladder, and an invented one is
|
|
159
|
-
worse than none: `spec-sync stage` refuses cleanly when none is declared, whereas
|
|
160
|
-
a wrong ladder is a pipeline quietly moving tickets to the wrong column. If the
|
|
161
|
-
user does not raise deployment, offer it once in a line and take "no" for an
|
|
162
|
-
answer.
|
|
163
|
-
|
|
164
|
-
If they do want one, ask for the stages **in deployment order**, and map each to
|
|
165
|
-
a state from the `list_issue_statuses` names you already have:
|
|
166
|
-
|
|
167
|
-
```
|
|
168
|
-
--stage test="On Test" --stage demo="Ready for Demo" --stage prod="Done"
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
- The **key** (`test`) is what a pipeline names; the **state** is the Linear
|
|
172
|
-
column. Pipelines reference the key, so renaming the column later is one edit
|
|
173
|
-
here.
|
|
174
|
-
- Order is recorded, not enforced — a rollback and a hotfix straight to prod are
|
|
175
|
-
both legitimate and are never refused.
|
|
176
|
-
- **Ask what closes an issue.** If the last rung is not a completed-type state,
|
|
177
|
-
tickets that finish the ladder never reach Done. That is fine when Linear
|
|
178
|
-
automation closes them and a problem otherwise — `spec-sync doctor` warns about
|
|
179
|
-
it either way, so say which it is.
|
|
152
|
+
Nothing to ask here. Skitterspec moves a Linear issue only at its own
|
|
153
|
+
transitions, and a spec's lifecycle ends at `complete`. Where a ticket goes
|
|
154
|
+
after that is the host project's: its CI can list a release's tickets with
|
|
155
|
+
`skitterspec spec-sync released "<previous-tag>..<tag>" --json` and set whatever
|
|
156
|
+
Linear state or label it likes. If the user asks about deploy tracking, say that
|
|
157
|
+
in one line and point at "Releases and deploys" in `linear.config.md`.
|
|
180
158
|
|
|
181
159
|
## 7b. Assignment is on — does this team want it off?
|
|
182
160
|
|
|
@@ -227,11 +205,6 @@ shows this repo's choices and keeps inheriting everything else. `--force` is
|
|
|
227
205
|
required to replace an existing config — never pass it without the user having
|
|
228
206
|
asked for a rewrite in step 1.
|
|
229
207
|
|
|
230
|
-
Every `--stage` state is checked against the workspace exactly like a bucket
|
|
231
|
-
state, and a bad one is refused the same way — as `release.stages[test]` rather
|
|
232
|
-
than `states.complete`. There is no suggestion for a rung: the vocabulary is the
|
|
233
|
-
project's own, so ask rather than guess.
|
|
234
|
-
|
|
235
208
|
**Relay the engine's report as printed.** It names the team, the project (or
|
|
236
209
|
"team only"), the intake labels, and how many state names were checked against
|
|
237
210
|
the workspace — that report is the evidence the setup is right, so don't
|
|
@@ -312,7 +285,8 @@ Then name the next step:
|
|
|
312
285
|
|
|
313
286
|
- `/spec` — write a spec; with Linear configured it offers the project picker,
|
|
314
287
|
creates the linked issue and stamps the id.
|
|
315
|
-
- `/spec-status` — read-only
|
|
288
|
+
- `/spec-status` — read-only report of what would push, the safe way to prove
|
|
289
|
+
the link works.
|
|
316
290
|
- `/spec-push` — send a spec up.
|
|
317
291
|
|
|
318
292
|
**Never ask for the API key.** `doctor`'s `key` row already reports whether one
|
|
@@ -49,6 +49,18 @@ flags themselves (`--state`, `--all`, `--next`, `--in-progress`) are
|
|
|
49
49
|
**alternatives**, and the engine refuses any two of them rather than letting one
|
|
50
50
|
win silently.
|
|
51
51
|
|
|
52
|
+
**Every row shows the board's state and the spec's own status side by side.**
|
|
53
|
+
The spec status is read from the spec's **own worktree** when one exists, so an
|
|
54
|
+
in-flight spec reads `in-progress` even on the base branch, where its folder
|
|
55
|
+
still says `backlog`. `≠ <bucket>` marks a row whose board state maps to a
|
|
56
|
+
different bucket than its spec; a state that maps to no bucket never gets one.
|
|
57
|
+
`—` means the spec is not on this machine. Relay it as printed; never "correct"
|
|
58
|
+
either column from the other. The board says where the ticket is, and the spec
|
|
59
|
+
says where the work is.
|
|
60
|
+
|
|
61
|
+
`--state` also takes a lifecycle bucket: `--state in-progress` matches every
|
|
62
|
+
board state configured for it (`states` aliases included).
|
|
63
|
+
|
|
52
64
|
`--next N` is **backlog-only and ordered**, so it does not combine with
|
|
53
65
|
`--state` or `--all`; the engine refuses that pair rather than picking a winner.
|
|
54
66
|
It reproduces Linear's own Backlog order — priority first, then the manual
|
|
@@ -58,7 +70,7 @@ then a person's arrangement rather than a ranking.
|
|
|
58
70
|
## 2. Run the engine
|
|
59
71
|
|
|
60
72
|
```
|
|
61
|
-
skitterspec spec-sync list [--state <name> …|--all] [--limit N] [--archived] [--json]
|
|
73
|
+
skitterspec spec-sync list [--state <name|bucket> …|--all] [--limit N] [--archived] [--json]
|
|
62
74
|
```
|
|
63
75
|
|
|
64
76
|
- **`transport = api`** (a key is set) → it queried Linear and printed the
|
|
@@ -506,8 +506,8 @@ reading — and that is the gap the whole gate exists to close.
|
|
|
506
506
|
|
|
507
507
|
**A watch that dies is re-armed on the same window**, silently and bounded by
|
|
508
508
|
the age of that window — `.claude/rules/spec-reports.md` carries the contract,
|
|
509
|
-
including when to stop
|
|
510
|
-
here.
|
|
509
|
+
including when to stop, what the banner says instead, and when the
|
|
510
|
+
engine's `re-show:` brings the banner back. Do not restate it here.
|
|
511
511
|
|
|
512
512
|
Then **end your turn**. Do not poll it and do not hold the turn open: the
|
|
513
513
|
point is that the reader has the terminal back while they read.
|
|
@@ -583,7 +583,9 @@ underneath a reader when detection flipped mid-session.
|
|
|
583
583
|
|
|
584
584
|
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
585
585
|
`network` — the other addresses this machine has, offered because the
|
|
586
|
-
best-guess one can be wrong — so pass them on rather than editing them out
|
|
586
|
+
best-guess one can be wrong — so pass them on rather than editing them out: in
|
|
587
|
+
the banner they are indented sub-bullets under **network**, labels
|
|
588
|
+
(`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
|
|
587
589
|
|
|
588
590
|
**Never read an environment variable to decide anything about the offer** — not
|
|
589
591
|
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
@@ -314,7 +314,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
|
|
|
314
314
|
an update the issue already has a project (or deliberately has none), and that
|
|
315
315
|
placement is **Linear's to own**: never send `project` on an update, and never
|
|
316
316
|
record the choice in the spec file or the snapshot. A PM re-homing a spec issue
|
|
317
|
-
must not
|
|
317
|
+
must not be reported or overwritten on the next push.
|
|
318
318
|
|
|
319
319
|
1. **List the candidates.** Ask the engine:
|
|
320
320
|
`skitterspec spec-sync projects --json`. On the API path it returns the team's
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spec-status
|
|
3
|
-
description: Show a spec's one-way sync status against Linear — a read-only
|
|
3
|
+
description: Show a spec's one-way sync status against Linear — a read-only report naming what would push, and whether someone edited the issue's description since the last push. 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".
|
|
4
4
|
disable-model-invocation: true
|
|
5
5
|
---
|
|
6
6
|
|
|
7
|
-
# /spec-status — one-way sync
|
|
7
|
+
# /spec-status — one-way sync report
|
|
8
8
|
|
|
9
9
|
> Stay silent while this runs — speak only to ask something you cannot answer
|
|
10
10
|
> yourself, or to report a failure at the moment it happens. Read
|
|
@@ -15,13 +15,17 @@ Read-only. Reports two things and writes nothing:
|
|
|
15
15
|
|
|
16
16
|
1. **Pending push** — has the spec changed since the last push (is there an issue
|
|
17
17
|
description/state or any phase sub-issue to create or update)?
|
|
18
|
-
2. **
|
|
19
|
-
|
|
20
|
-
|
|
18
|
+
2. **Description edited** — did someone edit the issue's description on Linear
|
|
19
|
+
since the last push? The next push replaces it, so this is worth reading
|
|
20
|
+
first.
|
|
21
|
+
|
|
22
|
+
**Status is not compared, deliberately.** Skitterspec tells Linear about its
|
|
23
|
+
own transitions and never reads a status back: a card someone moved by hand is
|
|
24
|
+
theirs to have moved, and push resends State only when the spec itself moves.
|
|
21
25
|
|
|
22
26
|
The repo is the source of truth; Linear is a generated mirror, so there is no
|
|
23
|
-
per-field "conflict" — only "what would the next push send" and "did
|
|
24
|
-
|
|
27
|
+
per-field "conflict" — only "what would the next push send" and "did someone
|
|
28
|
+
write over the mirror's text".
|
|
25
29
|
|
|
26
30
|
**Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
|
|
27
31
|
tell the user how to enable Linear sync and stop.
|
|
@@ -30,18 +34,16 @@ tell the user how to enable Linear sync and stop.
|
|
|
30
34
|
|
|
31
35
|
Use the argument, else the spec in context; ask if unclear.
|
|
32
36
|
|
|
33
|
-
## 2. Fetch the Linear issue (optional, for
|
|
37
|
+
## 2. Fetch the Linear issue (optional, for the description check)
|
|
34
38
|
|
|
35
39
|
If the spec has a `linear_identifier`, discover the Linear MCP read tool
|
|
36
|
-
(`get_issue`) and write the issue JSON to a temp file. If Linear isn't
|
|
37
|
-
skip the
|
|
40
|
+
(`get_issue`) and write the issue JSON to a temp file. If Linear isn't
|
|
41
|
+
connected, skip the description check (still report pending-push).
|
|
38
42
|
|
|
39
|
-
**Write the whole issue, including its `description`.**
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
43
|
-
so the loss is silent. Keep `url` too: it is what the description line points
|
|
44
|
-
the reader at.
|
|
43
|
+
**Write the whole issue, including its `description`.** That is the field the
|
|
44
|
+
check reads; without it the check has nothing to look at — and it says nothing
|
|
45
|
+
rather than guessing, so the loss is silent. Keep `url` too: it is what the
|
|
46
|
+
description line points the reader at.
|
|
45
47
|
|
|
46
48
|
**The description itself never enters the conversation.** The engine hashes it
|
|
47
49
|
and compares hashes; what it prints is *that* the text changed, plus where to
|
|
@@ -58,8 +60,9 @@ skitterspec spec-sync status <spec> [--remote <issuefile>] [--workspace-states <
|
|
|
58
60
|
```
|
|
59
61
|
|
|
60
62
|
- Reports `push: pending — N to create, M to update` or `up to date`.
|
|
61
|
-
- With `--remote`, adds a `drift:` line
|
|
62
|
-
|
|
63
|
+
- With `--remote`, adds a `drift:` line when the issue's description was
|
|
64
|
+
edited on Linear since the last push, and nothing otherwise. It never
|
|
65
|
+
reports the issue's state.
|
|
63
66
|
- With `--workspace-states`, fails loudly if a configured state name isn't in the
|
|
64
67
|
workspace (Linear would silently no-op it).
|
|
65
68
|
|
|
@@ -92,18 +95,19 @@ the shape; this section carries only what is specific here.
|
|
|
92
95
|
**Verdicts**
|
|
93
96
|
|
|
94
97
|
- `✅` — in sync; nothing would push.
|
|
95
|
-
- `⚠️` —
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
|
|
100
|
-
|
|
98
|
+
- `⚠️` — N objects would push, or the issue's **description** was edited on
|
|
99
|
+
Linear since the last push. Neither is an error, but both are the reason
|
|
100
|
+
someone ran this. **Say which**, since they call for different things: a
|
|
101
|
+
pending push is routine, and an edited description means a person wrote
|
|
102
|
+
something that the next push replaces.
|
|
103
|
+
An `assignee` drift line is the third case: the assignee is a field the repo
|
|
104
|
+
owns, so the next push restores the spec's record.
|
|
101
105
|
- `⏸` — no config, or the spec is not linked. Nothing to compare.
|
|
102
106
|
|
|
103
107
|
**Fields:** `Tracker` · `Follow-ups` · `Next`
|
|
104
108
|
|
|
105
|
-
`Tracker` is the
|
|
106
|
-
|
|
109
|
+
`Tracker` is the answer in one line — what would push, and whether the
|
|
110
|
+
description was edited. `Next` is `/spec-push` when a push is pending, and nothing to do
|
|
107
111
|
when it is not.
|
|
108
112
|
|
|
109
113
|
A **`phases: <mode>`** line names the phase mode that resolved for this spec's
|
|
@@ -46,8 +46,7 @@ In a project that installs the Linear superset the binary is
|
|
|
46
46
|
| "mirror the whole backlog / every complete spec" | `apply --all <bucket>` — **confirm first** |
|
|
47
47
|
| "is the team key stale?", "did Linear get renamed?" | `retarget` |
|
|
48
48
|
| "what ticket am I on?", writing a commit | `ref` |
|
|
49
|
-
| "what shipped in this release?" | `released` |
|
|
50
|
-
| "move the shipped tickets on", "what's on test?" | `stage` — dry run unless `--apply` |
|
|
49
|
+
| "what shipped in this release?", "which tickets does CI mark deployed?" | `released` — `--json` for a script; recording deploys is the project's own |
|
|
51
50
|
| "is any of this wired up?", "why isn't sync working?" | `doctor` — scaffold, isolation, tracker and key in one |
|
|
52
51
|
| "set my Linear key", "am I authenticated?" | `credentials <status\|set\|unset>` |
|
|
53
52
|
| "who am I in Linear?", "why is it assigning the wrong person?" | `whoami` — `--set` for a shared or bot key |
|
|
@@ -67,7 +66,7 @@ Two front doors to one write path is worse than none:
|
|
|
67
66
|
|
|
68
67
|
- **Push one spec** → `/spec-push`. It owns the transport choice, the
|
|
69
68
|
workspace-state gate, the plan, the apply, the stamping and the snapshot.
|
|
70
|
-
- **Per-spec
|
|
69
|
+
- **Per-spec status** ("is this spec in sync?", "what would push?") →
|
|
71
70
|
`/spec-status`.
|
|
72
71
|
|
|
73
72
|
Say which skill you're handing to and stop; don't reimplement either.
|
|
@@ -169,8 +168,10 @@ and never write `Refs: none`.
|
|
|
169
168
|
|
|
170
169
|
`released` reports the tickets in a commit range — by default since the most
|
|
171
170
|
recent tag, and it always prints the range it chose so a wrong default is
|
|
172
|
-
visible. It is **read-only**: it does not move anything in Linear.
|
|
173
|
-
|
|
171
|
+
visible. It is **read-only**: it does not move anything in Linear. Each ticket
|
|
172
|
+
row names the `spec` and `url` behind it (`null` when no spec linked the ref),
|
|
173
|
+
so `--json` is what a project's CI pipes into its own tooling to record a
|
|
174
|
+
release or a deploy. Recording those is the project's job, not skitterspec's.
|
|
174
175
|
|
|
175
176
|
Relay the **unreferenced count** even when it is zero. A chore commit
|
|
176
177
|
legitimately carries no ticket and a *missed* trailer looks identical, so
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skitterbyte/skitterspec-linear",
|
|
3
|
-
"version": "
|
|
3
|
+
"version": "19.1.0",
|
|
4
4
|
"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.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|
package/src/cli.js
CHANGED
|
@@ -88,6 +88,8 @@ const {
|
|
|
88
88
|
collectReview,
|
|
89
89
|
reviewTierStack,
|
|
90
90
|
reviewTierLine,
|
|
91
|
+
isTailnetAddress,
|
|
92
|
+
tailnetLabel,
|
|
91
93
|
renderReviewPage,
|
|
92
94
|
renderReviewBlock,
|
|
93
95
|
reviewOutPath,
|
|
@@ -117,6 +119,9 @@ const {
|
|
|
117
119
|
passesSince,
|
|
118
120
|
waitForPass,
|
|
119
121
|
WAIT_HEARTBEAT_MS,
|
|
122
|
+
WAIT_RESHOW_EVERY,
|
|
123
|
+
recordWaitStart,
|
|
124
|
+
reshowDue,
|
|
120
125
|
waitingPasses,
|
|
121
126
|
describePending,
|
|
122
127
|
pendingAge,
|
|
@@ -901,7 +906,7 @@ function specEnvUp(dir, config, specArg, flags = {}) {
|
|
|
901
906
|
try {
|
|
902
907
|
spec = resolveSpecWithWorktree(dir, config, specArg)
|
|
903
908
|
} catch (err) {
|
|
904
|
-
const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix)-./.test(specArg)
|
|
909
|
+
const specShaped = typeof specArg === 'string' && /^(feat|bug|hotfix|chore)-./.test(specArg)
|
|
905
910
|
if (err.code !== 'SPEC_NOT_FOUND' || !docs || !specShaped || config.mode === 'checkout') {
|
|
906
911
|
throw err
|
|
907
912
|
}
|
|
@@ -2759,6 +2764,74 @@ function resolveHeartbeatMs(flags) {
|
|
|
2759
2764
|
return seconds * 1000
|
|
2760
2765
|
}
|
|
2761
2766
|
|
|
2767
|
+
/**
|
|
2768
|
+
* Every this-many re-arms the stack is printed again. Default 5, `0` disables.
|
|
2769
|
+
* A value that is not a whole number takes the DEFAULT rather than disabling
|
|
2770
|
+
* (`.claude/rules/negative-checks.md` rule 4), the same as `--heartbeat`.
|
|
2771
|
+
*/
|
|
2772
|
+
function resolveReshowEvery(flags) {
|
|
2773
|
+
if (flags.reshowEvery === undefined || flags.reshowEvery === null) return WAIT_RESHOW_EVERY
|
|
2774
|
+
const n = Number(flags.reshowEvery)
|
|
2775
|
+
if (!Number.isInteger(n) || n < 0) return WAIT_RESHOW_EVERY
|
|
2776
|
+
return n
|
|
2777
|
+
}
|
|
2778
|
+
|
|
2779
|
+
/**
|
|
2780
|
+
* The review server that is running, read and never touched — or null.
|
|
2781
|
+
*
|
|
2782
|
+
* NOT `ensureReviewServer`. That one adopts, and where a server is stale it
|
|
2783
|
+
* replaces it, and a re-show that restarted the server would kill the link
|
|
2784
|
+
* open on the reader's phone in order to remind them of it. This reads the
|
|
2785
|
+
* pidfile and the settings and stops there.
|
|
2786
|
+
*
|
|
2787
|
+
* WHAT WOULD FOOL THIS: a pidfile left by a crash names a pid the OS may have
|
|
2788
|
+
* reused for something else. `isAlive` cannot tell those apart, so the URL it
|
|
2789
|
+
* offers could point at nothing — the same blind spot every adopt has, and the
|
|
2790
|
+
* cost is a dead link in a reminder, never a lost pass.
|
|
2791
|
+
*/
|
|
2792
|
+
function readRunningReviewServer(dir, config) {
|
|
2793
|
+
const abs = (rel) => path.resolve(dir, rel)
|
|
2794
|
+
const settingsFile = `${stateDirLabel(config)}/review-serve.json`
|
|
2795
|
+
const proc = serveProcFor(config, abs(settingsFile), { root: dir })
|
|
2796
|
+
const pid = readPid(abs(proc.pidFile))
|
|
2797
|
+
if (!pid || !isAlive(pid)) return null
|
|
2798
|
+
let settings = null
|
|
2799
|
+
try {
|
|
2800
|
+
settings = JSON.parse(fs.readFileSync(abs(settingsFile), 'utf-8'))
|
|
2801
|
+
} catch {
|
|
2802
|
+
return null
|
|
2803
|
+
}
|
|
2804
|
+
if (!settings || !settings.port) return null
|
|
2805
|
+
return {
|
|
2806
|
+
port: settings.port,
|
|
2807
|
+
token: settings.token || null,
|
|
2808
|
+
loopback: settings.host === '127.0.0.1' || settings.host === 'localhost',
|
|
2809
|
+
}
|
|
2810
|
+
}
|
|
2811
|
+
|
|
2812
|
+
/**
|
|
2813
|
+
* The stack a re-show prints: the same tiers and `live` a render reports, from
|
|
2814
|
+
* the same functions, with nothing rendered and nothing started.
|
|
2815
|
+
*/
|
|
2816
|
+
function reshowStack(dir, config, spec, out) {
|
|
2817
|
+
const cfg = withSpecRemote(config, out)
|
|
2818
|
+
const up = readRunningReviewServer(dir, cfg)
|
|
2819
|
+
const served = up ? reviewServedUrls(up, offerableLanAddresses(), spec.folder) : null
|
|
2820
|
+
const tiers = reviewTierStack({ served, fileUrl: reviewFileUrl(out), publishedUrl: readReviewUrl(out), config: cfg })
|
|
2821
|
+
let live = null
|
|
2822
|
+
try {
|
|
2823
|
+
const primaryState = assertPrimaryOnMain(cfg, gitReader(dir))
|
|
2824
|
+
live = liveStateFor(
|
|
2825
|
+
spec,
|
|
2826
|
+
liveContext(dir, cfg, spec, { onBase: primaryState.onBase, primaryBranch: primaryState.branch }),
|
|
2827
|
+
)
|
|
2828
|
+
} catch {
|
|
2829
|
+
// Cannot tell whether it is live — print no line rather than a wrong one.
|
|
2830
|
+
live = null
|
|
2831
|
+
}
|
|
2832
|
+
return { tiers, live }
|
|
2833
|
+
}
|
|
2834
|
+
|
|
2762
2835
|
async function specEnvReviewWait(dir, config, specArg, flags) {
|
|
2763
2836
|
let spec
|
|
2764
2837
|
try {
|
|
@@ -2792,10 +2865,28 @@ async function specEnvReviewWait(dir, config, specArg, flags) {
|
|
|
2792
2865
|
// SAID BEFORE THE FIRST POLL, not after it. The whole point is that a caller
|
|
2793
2866
|
// knows the wait is running; a line printed on the way out would arrive only
|
|
2794
2867
|
// for the waits that already worked.
|
|
2868
|
+
//
|
|
2869
|
+
// WHICH START THIS IS, counted per window. A wait that dies is re-armed on the
|
|
2870
|
+
// same `--since`, and every re-arm leaves a trace in the conversation, so
|
|
2871
|
+
// after enough of them the banner and its links have scrolled out of sight.
|
|
2872
|
+
// Every `reshowEvery`th re-arm prints the stack again, read-only, for the
|
|
2873
|
+
// skill to relay as the banner.
|
|
2874
|
+
const reshowEvery = resolveReshowEvery(flags)
|
|
2875
|
+
const started = recordWaitStart(out, spec.folder, flags.since)
|
|
2876
|
+
const rearm = started ? started.rearm : null
|
|
2877
|
+
const reshow = reshowDue(rearm, reshowEvery)
|
|
2878
|
+
const stack = reshow ? reshowStack(dir, config, spec, out) : null
|
|
2879
|
+
|
|
2795
2880
|
if (!flags.json) {
|
|
2796
2881
|
process.stdout.write(
|
|
2797
2882
|
`spec-env review wait: ${spec.folder} — waiting for a verdict sent since ${flags.since}` +
|
|
2798
|
-
`${timeoutMs === null ? '' : ` (up to ${flags.timeout}s)`}
|
|
2883
|
+
`${timeoutMs === null ? '' : ` (up to ${flags.timeout}s)`}` +
|
|
2884
|
+
`${rearm ? ` (re-arm ${rearm})` : ''}\n` +
|
|
2885
|
+
(stack
|
|
2886
|
+
? ` re-show: banner (re-arm ${rearm})\n` +
|
|
2887
|
+
stack.tiers.map((t) => reviewTierLine(t) + '\n').join('') +
|
|
2888
|
+
(liveStateLine(stack.live) ? `${liveStateLine(stack.live)}\n` : '')
|
|
2889
|
+
: ''),
|
|
2799
2890
|
)
|
|
2800
2891
|
}
|
|
2801
2892
|
|
|
@@ -2825,7 +2916,20 @@ async function specEnvReviewWait(dir, config, specArg, flags) {
|
|
|
2825
2916
|
})
|
|
2826
2917
|
|
|
2827
2918
|
if (flags.json) {
|
|
2828
|
-
process.stdout.write(
|
|
2919
|
+
process.stdout.write(
|
|
2920
|
+
`${JSON.stringify(
|
|
2921
|
+
{
|
|
2922
|
+
spec: spec.folder,
|
|
2923
|
+
since: flags.since,
|
|
2924
|
+
rearm,
|
|
2925
|
+
reshow,
|
|
2926
|
+
...(stack ? { tiers: stack.tiers, live: stack.live } : {}),
|
|
2927
|
+
...result,
|
|
2928
|
+
},
|
|
2929
|
+
null,
|
|
2930
|
+
2,
|
|
2931
|
+
)}\n`,
|
|
2932
|
+
)
|
|
2829
2933
|
}
|
|
2830
2934
|
|
|
2831
2935
|
if (result.state === 'arrived') {
|
|
@@ -4258,6 +4362,10 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
|
|
|
4258
4362
|
// use, and the engine cannot know — that guess failed three separate ways
|
|
4259
4363
|
// in one day. Now every tier is listed, labelled, and either a URL or the
|
|
4260
4364
|
// one command that turns it on.
|
|
4365
|
+
// The runners-up print as `also:` lines inside the network tier's own
|
|
4366
|
+
// rendering — `reviewTierLine` carries them, which is what puts them
|
|
4367
|
+
// under `network:` rather than dangling after the stack (they used to
|
|
4368
|
+
// print below `remote:`, against the comment that placed them).
|
|
4261
4369
|
reviewTierStack({
|
|
4262
4370
|
served,
|
|
4263
4371
|
fileUrl: reviewFileUrl(out),
|
|
@@ -4266,11 +4374,6 @@ async function specEnvReview(dir, config, specArg, flags, invokedFrom = dir) {
|
|
|
4266
4374
|
})
|
|
4267
4375
|
.map((t) => reviewTierLine(t) + '\n')
|
|
4268
4376
|
.join('') +
|
|
4269
|
-
// The runners-up sit UNDER the network tier, because that is what they are
|
|
4270
|
-
// alternatives to — and virtual adapters are gone from them entirely.
|
|
4271
|
-
(served && !served.loopback && (served.alternates || []).length
|
|
4272
|
-
? served.alternates.map((u) => ` also: ${u}${tailnetLabel(u)}\n`).join('')
|
|
4273
|
-
: '') +
|
|
4274
4377
|
// WHICH TIERS THE WAIT COVERS, once, next to the stack. `local` and
|
|
4275
4378
|
// `network` are two doors into one room — the page POSTs to
|
|
4276
4379
|
// `location.pathname`, so both reach this server and this pending store.
|
|
@@ -4583,26 +4686,6 @@ function offerableLanAddresses(nets = require('node:os').networkInterfaces()) {
|
|
|
4583
4686
|
.map((e) => e.address)
|
|
4584
4687
|
}
|
|
4585
4688
|
|
|
4586
|
-
// 100.64.0.0/10 — the CGNAT range Tailscale assigns from.
|
|
4587
|
-
//
|
|
4588
|
-
// WHAT WOULD FOOL THIS: a carrier-grade NAT or another overlay network using
|
|
4589
|
-
// the same range on a utun adapter is offered too. That costs one dud `also:`
|
|
4590
|
-
// line, where filtering it hides the only link a reader off the wifi can open.
|
|
4591
|
-
function isTailnetAddress(address) {
|
|
4592
|
-
const m = /^100\.(\d+)\./.exec(address)
|
|
4593
|
-
return !!m && Number(m[1]) >= 64 && Number(m[1]) <= 127
|
|
4594
|
-
}
|
|
4595
|
-
|
|
4596
|
-
// The suffix on an `also:` line whose host is a tailnet address, so it reads
|
|
4597
|
-
// apart from the LAN one — a reader off the wifi needs to know which to tap.
|
|
4598
|
-
function tailnetLabel(url) {
|
|
4599
|
-
let host = ''
|
|
4600
|
-
try {
|
|
4601
|
-
host = new URL(url).hostname
|
|
4602
|
-
} catch {}
|
|
4603
|
-
return isTailnetAddress(host) ? ' (tailnet)' : ''
|
|
4604
|
-
}
|
|
4605
|
-
|
|
4606
4689
|
/**
|
|
4607
4690
|
* Bring the review server up, or adopt the one already running.
|
|
4608
4691
|
*
|
|
@@ -5636,6 +5719,7 @@ async function specEnv(rest) {
|
|
|
5636
5719
|
claim: null,
|
|
5637
5720
|
offered: false,
|
|
5638
5721
|
heartbeat: null,
|
|
5722
|
+
reshowEvery: null,
|
|
5639
5723
|
drop: null,
|
|
5640
5724
|
buttons: null,
|
|
5641
5725
|
json: false,
|
|
@@ -5671,6 +5755,7 @@ async function specEnv(rest) {
|
|
|
5671
5755
|
else if (args[i] === '--claim') flags.claim = args[++i]
|
|
5672
5756
|
else if (args[i] === '--claim-since') flags.claimSince = args[++i]
|
|
5673
5757
|
else if (args[i] === '--heartbeat') flags.heartbeat = args[++i]
|
|
5758
|
+
else if (args[i] === '--reshow-every') flags.reshowEvery = args[++i]
|
|
5674
5759
|
else if (args[i] === '--since') flags.since = args[++i]
|
|
5675
5760
|
else if (args[i] === '--timeout') flags.timeout = args[++i]
|
|
5676
5761
|
else if (args[i] === '--drop') flags.drop = args[++i]
|
|
@@ -5850,6 +5935,7 @@ async function specEnv(rest) {
|
|
|
5850
5935
|
' review skip [spec] "<reason>" move on without one, on the record\n' +
|
|
5851
5936
|
' review gate [spec] --offered record that the bypass was offered (spends it)\n' +
|
|
5852
5937
|
' review wait [spec] --heartbeat <secs> proof-of-life cadence on stderr; 0 disables\n' +
|
|
5938
|
+
' review wait [spec] --reshow-every <n> print the stack again every nth re-arm (5); 0 disables\n' +
|
|
5853
5939
|
' review wait [spec] --since <iso> block until a verdict arrives ([--timeout <s>])\n' +
|
|
5854
5940
|
' review waiting [--json] every pass waiting, across every spec\n' +
|
|
5855
5941
|
' review [spec] --claim-since <iso> claim the one pass that arrived since <iso>\n' +
|