@skitterbyte/skitterspec-linear 19.16.0 → 19.18.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 +78 -0
- package/README.md +0 -1
- package/assets/claude-md-section.md +6 -9
- package/assets/commands/allow-main.md +1 -2
- package/assets/core/env.config.json.example +0 -1
- package/assets/core/env.config.md +24 -27
- package/assets/review/page.html +10 -83
- package/assets/rules/spec-planning.md +14 -21
- package/assets/rules/spec-reports.md +112 -54
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +2 -2
- package/assets/skills/spec-bug/SKILL.md +10 -13
- package/assets/skills/spec-diff/SKILL.md +47 -115
- package/assets/skills/spec-hotfix/SKILL.md +10 -13
- package/assets/skills/spec-next/SKILL.md +59 -42
- package/assets/skills/spec-review/SKILL.md +2 -2
- package/assets/skills/spec-reviewed/SKILL.md +1 -8
- package/package.json +1 -1
- package/src/cli.js +251 -204
- package/src/env/config.js +16 -7
- package/src/env/hooks.js +6 -3
- package/src/env/live.js +48 -0
- package/src/env/review.js +71 -173
- package/src/env/serve.js +3 -7
- package/src/init.js +509 -13
- package/assets/commands/spec-remote-review.md +0 -37
|
@@ -689,10 +689,9 @@ line with it where the engine printed one, and nothing where it did not.
|
|
|
689
689
|
`.claude/rules/spec-reports.md` carries the shape, including why a rigid
|
|
690
690
|
contract took that line.
|
|
691
691
|
|
|
692
|
-
- **Never write the review unasked**, and **never publish
|
|
693
|
-
|
|
694
|
-
|
|
695
|
-
`/spec-diff` §6 owns how.
|
|
692
|
+
- **Never write the review unasked**, and **never publish** — there is no
|
|
693
|
+
publishing (`/spec-diff` §6). A `file://` link is no use on a phone, and the
|
|
694
|
+
stack says why nothing was served.
|
|
696
695
|
**The `reader:` line no longer decides anything here, and that is the point.**
|
|
697
696
|
It is still printed, and it is still the only place that question is answered —
|
|
698
697
|
but the offer does not change with it, because the stack lists every tier
|
|
@@ -702,22 +701,20 @@ that branching is exactly what produced a `file://` page on a session detected
|
|
|
702
701
|
underneath a reader when detection flipped mid-session.
|
|
703
702
|
|
|
704
703
|
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
705
|
-
|
|
706
|
-
|
|
707
|
-
|
|
708
|
-
|
|
704
|
+
their tier — the other addresses this machine has of that kind — so pass them
|
|
705
|
+
on rather than editing them out: in the banner they are indented sub-bullets
|
|
706
|
+
under that tier, labels included, exactly as `.claude/rules/spec-reports.md`
|
|
707
|
+
shows.
|
|
709
708
|
|
|
710
709
|
**Never read an environment variable to decide anything about the offer** — not
|
|
711
710
|
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
712
711
|
here for a detection to decide, and a second implementation of one could not be
|
|
713
712
|
tested and would drift.
|
|
714
713
|
|
|
715
|
-
**Serving is the engine's to do
|
|
714
|
+
**Serving is the engine's to do, and there is nothing else.** A `remote` reader
|
|
716
715
|
authorises a local server — one process, ended by one flag, leaving nothing
|
|
717
|
-
behind
|
|
718
|
-
|
|
719
|
-
serve (a busy port, a machine with no network address) it falls back to the
|
|
720
|
-
`file://` URL with its marker, and that is when publishing is worth naming.
|
|
716
|
+
behind. If the engine could not serve (a busy port, a machine with no network
|
|
717
|
+
address) it falls back to the `file://` URL with its marker.
|
|
721
718
|
|
|
722
719
|
- **Never fatal.** A failed render — no worktree, a git error — is one line, and
|
|
723
720
|
the fix is still done. The page is a convenience; the repo is the record.
|
|
@@ -50,8 +50,10 @@ evidence.
|
|
|
50
50
|
Otherwise resolve **in this order**, and stop at the first that answers:
|
|
51
51
|
|
|
52
52
|
1. **The live spec of this checkout** — run
|
|
53
|
-
`skitterspec spec-env live status` and read its `
|
|
54
|
-
|
|
53
|
+
`skitterspec spec-env live status` and read its `in-flight:` line. A spec
|
|
54
|
+
name there is the spec whose branch is checked out here; that is the one to
|
|
55
|
+
build. `none` and `unknown` answer nothing — carry on down the list. (The
|
|
56
|
+
bare report's first line is a bare `spec-env live:` header, not an answer.)
|
|
55
57
|
2. **The worktree you are standing in** — if this session's cwd is inside a
|
|
56
58
|
spec's worktree, that spec is in flight *for this session*. This is the
|
|
57
59
|
manual-parallel path: several specs may be provisioned, and a terminal tab
|
|
@@ -62,10 +64,17 @@ Otherwise resolve **in this order**, and stop at the first that answers:
|
|
|
62
64
|
named, from wherever you happen to be standing:
|
|
63
65
|
|
|
64
66
|
```
|
|
65
|
-
skitterspec spec-env resolve
|
|
67
|
+
skitterspec spec-env resolve --json
|
|
66
68
|
```
|
|
67
69
|
|
|
68
|
-
Take its `spec
|
|
70
|
+
Take its `spec` **only when it names exactly one spec** (`ok: true`); `via`
|
|
71
|
+
says which rung answered.
|
|
72
|
+
|
|
73
|
+
From the primary checkout that includes the spec `/spec-live main` last
|
|
74
|
+
released here (`via: "last-live"`): releasing leaves the session standing
|
|
75
|
+
in the primary checkout, which says nothing on its own, so the engine
|
|
76
|
+
remembers the spec it handed back — for as long as that spec's worktree
|
|
77
|
+
exists — ahead of counting worktrees.
|
|
69
78
|
|
|
70
79
|
This is the **durable** rung, and that is the whole reason it exists. Rungs 1
|
|
71
80
|
to 3 all read *session* state, and session state does not survive a `/clear`,
|
|
@@ -81,13 +90,14 @@ Otherwise resolve **in this order**, and stop at the first that answers:
|
|
|
81
90
|
`.claude/rules/spec-planning.md` states has none left.
|
|
82
91
|
|
|
83
92
|
**Say which spec you resolved and how**, before writing a line of it:
|
|
84
|
-
*"not standing in a worktree — `<spec>` is the only spec provisioned"
|
|
93
|
+
*"not standing in a worktree — `<spec>` is the only spec provisioned"*, or
|
|
94
|
+
*"`<spec>` was last live on this checkout"*. Rungs
|
|
85
95
|
1 to 3 are self-evident to whoever typed the command; this one is not, and
|
|
86
96
|
the operator cannot see from where they sit what you picked.
|
|
87
97
|
|
|
88
|
-
**Several worktrees stay a refusal.** The engine
|
|
89
|
-
|
|
90
|
-
unchanged and stop; never pick from it.
|
|
98
|
+
**Several worktrees stay a refusal.** The engine answers `ok: false` with
|
|
99
|
+
`reason: "ambiguous"` and lists the `candidates`, each with its `worktree`,
|
|
100
|
+
and resolves nothing. Relay that list unchanged and stop; never pick from it.
|
|
91
101
|
|
|
92
102
|
WHAT WOULD FOOL THIS: a worktree left behind by a declined teardown is still
|
|
93
103
|
a worktree, so a finished spec can go on counting as provisioned. That widens
|
|
@@ -96,10 +106,18 @@ Otherwise resolve **in this order**, and stop at the first that answers:
|
|
|
96
106
|
manufacture an *absence*, which is why the absence below is still worth
|
|
97
107
|
refusing on.
|
|
98
108
|
|
|
99
|
-
**If none answers, refuse and stop
|
|
100
|
-
`
|
|
109
|
+
**If none answers, refuse and stop — and say which absence it is.** Rung 4's
|
|
110
|
+
`reason` tells them apart, and they send the reader to different places:
|
|
111
|
+
|
|
112
|
+
- **`reason: "none"`** — no spec has a worktree anywhere:
|
|
113
|
+
`no spec in flight — run /spec-start <name> to start one`.
|
|
114
|
+
- **`reason: "ambiguous"`** — several specs are in flight and this session is
|
|
115
|
+
standing in none of them: `several specs are in flight and this session is
|
|
116
|
+
not in one of them`, then the candidates as the engine listed them (spec and
|
|
117
|
+
worktree), and `/spec-next --worktree <path>` as the way to name one.
|
|
118
|
+
`/spec-start` is wrong here: every one of them is already started.
|
|
101
119
|
|
|
102
|
-
|
|
120
|
+
The first answers a real absence — no worktree anywhere, the engine included —
|
|
103
121
|
rather than a session that merely lost track of where it was standing.
|
|
104
122
|
|
|
105
123
|
**Never fall back to the spec "in context".** A spec discussed in conversation
|
|
@@ -340,6 +358,13 @@ plain markdown list in the conversation — never fenced, and
|
|
|
340
358
|
out of the terminal to find out what to do, which is the failure this exists to
|
|
341
359
|
fix; the steps themselves are what they act on.
|
|
342
360
|
|
|
361
|
+
**Steps you had to write are saved first.** When the phase file holds only a
|
|
362
|
+
vague manual task — "check it on the running host" — and you wrote the steps
|
|
363
|
+
yourself, add them under that task as numbered sub-checkboxes **before** you
|
|
364
|
+
ask. The conversation does not survive a `/clear`, and a later run that makes
|
|
365
|
+
up its own set lists different steps from the ones the reader was shown. A
|
|
366
|
+
phase whose manual steps are already tasks is left as it is.
|
|
367
|
+
|
|
343
368
|
Then ask one question, with three answers:
|
|
344
369
|
|
|
345
370
|
- **All done** — tick those steps and carry on to the end of the phase.
|
|
@@ -358,6 +383,8 @@ needs no new shape in the report.
|
|
|
358
383
|
tasks after an unconfirmed step are not built past it, and the phase did not
|
|
359
384
|
end: **skip §4's done-marking and §5 entirely** — no page, no arm, no wait.
|
|
360
385
|
End `⚠️` and name `/spec-next` in `Next`; it re-lists the same unticked steps.
|
|
386
|
+
Its `Next` lists the open steps a row each, copied from the phase file —
|
|
387
|
+
`.claude/rules/spec-reports.md`, *Open manual steps are rows*.
|
|
361
388
|
|
|
362
389
|
## 4. Record progress
|
|
363
390
|
|
|
@@ -493,11 +520,11 @@ so one subject lives in one place:
|
|
|
493
520
|
|
|
494
521
|
- **local** — <the `local:` URL>
|
|
495
522
|
- **network** — <the `network:` URL, or off with the command that turns it on>
|
|
496
|
-
- **remote** — <the `remote:` URL, or
|
|
523
|
+
- **remote** — <the `remote:` tailnet URL, or what that line says when there is none>
|
|
497
524
|
|
|
498
525
|
<the `live:` line, exactly as the engine printed it — omitted when it printed none>
|
|
499
526
|
|
|
500
|
-
I'm holding here until you send a verdict — the wait covers
|
|
527
|
+
I'm holding here until you send a verdict — the wait covers <the tiers the engine's `covers` names>.
|
|
501
528
|
|
|
502
529
|
`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
|
|
503
530
|
|
|
@@ -518,22 +545,14 @@ reviewer sees the heading they have always seen.
|
|
|
518
545
|
printed one line per tier, in that order, and `--json` carries the same thing as
|
|
519
546
|
`tiers`. Relay all three whatever they say, including the ones that are off with
|
|
520
547
|
the command that turns them on: a reader who has left the house cannot ask for a
|
|
521
|
-
remote
|
|
548
|
+
remote door they were never shown.
|
|
522
549
|
|
|
523
550
|
**Do not pick one for them.** The engine used to, and the guess failed three
|
|
524
551
|
separate ways in one day. `.claude/rules/spec-reports.md` carries the shape and
|
|
525
552
|
why the *one link, never two* rule now reads
|
|
526
|
-
**one link per
|
|
527
|
-
local and
|
|
528
|
-
covers
|
|
529
|
-
*a verdict here needs `/spec-reviewed`*, because nothing pushes from
|
|
530
|
-
the artifact store into this conversation. Never let the holding line promise a
|
|
531
|
-
wait over that tier.
|
|
532
|
-
|
|
533
|
-
**Publishing is still never yours to do.** `remote` reading `off` is the normal
|
|
534
|
-
state, and the fix for it is the command on that line — typed by the operator,
|
|
535
|
-
or pressed on the page, because a published page is one this tooling cannot
|
|
536
|
-
remove and permitting it is not publishing it.
|
|
553
|
+
**one link per door, each labelled, all into one store** —
|
|
554
|
+
local, network and remote are three doors into one room, so the wait
|
|
555
|
+
covers every one the stack shows.
|
|
537
556
|
|
|
538
557
|
**The `live:` line goes with the stack**, and it is the engine's line too —
|
|
539
558
|
copied as printed, and **absent when the engine printed none**. The page can act
|
|
@@ -548,7 +567,7 @@ verdict.
|
|
|
548
567
|
**Where you are not waiting, it stays the `Review` row** — the counts and the
|
|
549
568
|
page link, and **no question**:
|
|
550
569
|
|
|
551
|
-
| **Review** | <N> files, +<a> −<d> · **local** <URL> · **network** <URL> · **remote**
|
|
570
|
+
| **Review** | <N> files, +<a> −<d> · **local** <URL> · **network** <URL> · **remote** <URL> (tailnet) |
|
|
552
571
|
|
|
553
572
|
At the end of a phase you are always waiting, so this shape belongs to the
|
|
554
573
|
renders that are not this step: a mid-phase `/spec-diff`, a page produced
|
|
@@ -662,10 +681,9 @@ Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines
|
|
|
662
681
|
never the bare `page:` path: a path is not clickable in any terminal, and a page
|
|
663
682
|
nobody can open is a page nobody reads.
|
|
664
683
|
|
|
665
|
-
- **Never write the review unasked**, and **never publish
|
|
666
|
-
|
|
667
|
-
|
|
668
|
-
the ask — publishing is the answer to it, and `/spec-diff` §6 owns how.
|
|
684
|
+
- **Never write the review unasked**, and **never publish** — there is no
|
|
685
|
+
publishing (`/spec-diff` §6). A `file://` link is no use on a phone, and the
|
|
686
|
+
stack says why nothing was served.
|
|
669
687
|
**The `reader:` line no longer decides anything here, and that is the point.**
|
|
670
688
|
It is still printed, and it is still the only place that question is answered —
|
|
671
689
|
but the offer does not change with it, because the stack lists every tier
|
|
@@ -675,23 +693,20 @@ that branching is exactly what produced a `file://` page on a session detected
|
|
|
675
693
|
underneath a reader when detection flipped mid-session.
|
|
676
694
|
|
|
677
695
|
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
|
|
696
|
+
their tier — the other addresses this machine has of that kind — so pass them
|
|
697
|
+
on rather than editing them out: in the banner they are indented sub-bullets
|
|
698
|
+
under that tier, labels included, exactly as `.claude/rules/spec-reports.md`
|
|
699
|
+
shows.
|
|
682
700
|
|
|
683
701
|
**Never read an environment variable to decide anything about the offer** — not
|
|
684
702
|
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
685
703
|
here for a detection to decide, and a second implementation of one could not be
|
|
686
704
|
tested and would drift.
|
|
687
705
|
|
|
688
|
-
**Serving is the engine's to do
|
|
706
|
+
**Serving is the engine's to do, and there is nothing else.** The server is one
|
|
689
707
|
process, ended by one flag, leaving nothing behind, and `review.allowNetwork`
|
|
690
|
-
decides whether it binds wide —
|
|
691
|
-
|
|
692
|
-
the stack. Publishing leaves a page this tooling cannot remove, so it stays an
|
|
693
|
-
ask in every case, always — which is why `remote` shows the command rather than
|
|
694
|
-
a URL until someone types it.
|
|
708
|
+
decides whether it binds wide — on the LAN and the tailnet alike — with no
|
|
709
|
+
detection involved.
|
|
695
710
|
|
|
696
711
|
- **Never fatal.** A failed render — no worktree, a git error — is one line and
|
|
697
712
|
the phase is still done. The page is a convenience; the repo is the record.
|
|
@@ -711,9 +726,11 @@ the shape; this section carries only what is specific here.
|
|
|
711
726
|
- `⚠️` — built and green, with something worth knowing (a mirror that did not
|
|
712
727
|
refresh, a deviation from the plan) — or stopped at manual steps answered
|
|
713
728
|
**Some failed** or **Not yet**: the phase stays `🔄`, `Notes` says which steps
|
|
714
|
-
are open, and `Next` is `/commit
|
|
729
|
+
are open, and `Next` is `/commit`, then a row per open step, then
|
|
730
|
+
`/spec-next` to pick them up.
|
|
715
731
|
- `❌` — the phase's tests are red, or it stopped part-way. Quote the failure.
|
|
716
|
-
- `⏸` — no spec in flight,
|
|
732
|
+
- `⏸` — no spec in flight, several in flight with this session in none of
|
|
733
|
+
them, or the name given does not match the one that is.
|
|
717
734
|
|
|
718
735
|
**Fields:** `Tracker` · `Branch` · `Built` · `Tests` · `Notes` · `Review` ·
|
|
719
736
|
`Follow-ups` · `Next`
|
|
@@ -290,9 +290,9 @@ reader:
|
|
|
290
290
|
|
|
291
291
|
- **local** — <the `local:` URL>
|
|
292
292
|
- **network** — <the `network:` URL, or off with the command that turns it on>
|
|
293
|
-
- **remote** — <the `remote:` URL, or
|
|
293
|
+
- **remote** — <the `remote:` tailnet URL, or what that line says when there is none>
|
|
294
294
|
|
|
295
|
-
I'm holding here until you send a verdict — the wait covers
|
|
295
|
+
I'm holding here until you send a verdict — the wait covers <the tiers the engine's `covers` names>.
|
|
296
296
|
|
|
297
297
|
`Commit` commits the refresh · `Request changes` works them now
|
|
298
298
|
|
|
@@ -176,14 +176,7 @@ everything a decision needs, so there is nothing to go looking for, and going
|
|
|
176
176
|
looking is the bypass step 0 forbids. The file is right there and readable; that
|
|
177
177
|
is precisely why the rule is written down rather than assumed.
|
|
178
178
|
|
|
179
|
-
**
|
|
180
|
-
has a published page (`--json` reports a `url`): a reader off the LAN sent their
|
|
181
|
-
pass to the artifact's own `passes` collection rather than to the engine, so an
|
|
182
|
-
empty holding area is not an empty answer yet. Read it with the Artifact tool's
|
|
183
|
-
`read_db`, merge the `blob` through `--notes`, and **delete the document** —
|
|
184
|
-
`/spec-diff` §6 owns the whole sequence, including that a claim consumes.
|
|
185
|
-
|
|
186
|
-
**Nothing waiting in either is an ordinary answer.** Say so and stop. Do not hunt
|
|
179
|
+
**Nothing waiting is an ordinary answer.** Say so and stop. Do not hunt
|
|
187
180
|
through other specs, and do not treat an empty holding area as a problem — a
|
|
188
181
|
`file://` page copies to the clipboard instead of sending, so mention that the
|
|
189
182
|
pass may be on their clipboard waiting to be pasted, and finish.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skitterbyte/skitterspec-linear",
|
|
3
|
-
"version": "19.
|
|
3
|
+
"version": "19.18.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",
|