@skitterbyte/skitterspec-linear 15.0.0 → 17.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 +218 -0
- package/README.md +37 -1
- package/assets/claude-md-section.md +42 -18
- package/assets/commands/allow-main.md +33 -0
- package/assets/commands/spec-remote-review.md +22 -0
- package/assets/commands/spec-skip.md +24 -0
- package/assets/core/SETUP.md +10 -6
- package/assets/core/env.config.json.example +6 -3
- package/assets/core/env.config.md +183 -25
- package/assets/core/linear.config.json.example +2 -1
- package/assets/core/linear.config.md +49 -22
- package/assets/hooks/main-guard.cjs +145 -0
- package/assets/hooks/review-gate.cjs +8 -3
- package/assets/review/page.html +1174 -101
- package/assets/rules/commit-trailers.md +17 -7
- package/assets/rules/offered-unblocks.md +100 -0
- package/assets/rules/spec-planning.md +195 -14
- package/assets/rules/spec-reports.md +181 -29
- package/assets/skills/no-spec/SKILL.md +219 -0
- package/assets/skills/spec/SKILL.md +277 -21
- package/assets/skills/spec-bug/SKILL.md +73 -30
- package/assets/skills/spec-cancel/SKILL.md +31 -2
- package/assets/skills/spec-claim/SKILL.md +12 -4
- package/assets/skills/spec-complete/SKILL.md +27 -2
- package/assets/skills/spec-diff/SKILL.md +164 -37
- package/assets/skills/spec-hotfix/SKILL.md +61 -25
- package/assets/skills/spec-init/SKILL.md +4 -2
- package/assets/skills/spec-linear-setup/SKILL.md +19 -11
- package/assets/skills/spec-next/SKILL.md +168 -60
- package/assets/skills/spec-push/SKILL.md +45 -0
- package/assets/skills/spec-review/SKILL.md +89 -2
- package/assets/skills/spec-reviewed/SKILL.md +31 -5
- package/assets/skills/spec-start/SKILL.md +40 -3
- package/assets/skills/spec-status/SKILL.md +20 -6
- package/assets/skills/spec-sync/SKILL.md +1 -0
- package/package.json +2 -2
- package/src/cli.js +1612 -172
- package/src/env/classify.js +87 -2
- package/src/env/config.js +333 -19
- package/src/env/hooks.js +102 -33
- package/src/env/live.js +124 -1
- package/src/env/mainguard.js +240 -0
- package/src/env/provision.js +106 -10
- package/src/env/registry.js +70 -6
- package/src/env/resolve.js +128 -5
- package/src/env/review.js +854 -29
- package/src/env/reviewers/coderabbit.js +228 -0
- package/src/env/reviewers.js +517 -0
- package/src/env/serve.js +474 -50
- package/src/env/supervise.js +8 -1
- package/src/env/teardown.js +12 -1
- package/src/init.js +185 -24
- package/src/vendor/linear/api.js +111 -2
- package/src/vendor/linear/cli-sync.js +661 -11
- package/src/vendor/linear/config.js +41 -13
- package/src/vendor/linear/doctor.js +6 -5
- package/src/vendor/sync-core/index.js +11 -3
- package/src/vendor/sync-core/src/compare.js +65 -0
- package/src/vendor/sync-core/src/normalize.js +26 -0
|
@@ -148,12 +148,36 @@ Before writing any code for this phase, get the workspace clean:
|
|
|
148
148
|
anything is owed (`.claude/rules/negative-checks.md`). Do not mention it: a
|
|
149
149
|
line about a gate nobody armed is an accusation against a healthy repo.
|
|
150
150
|
|
|
151
|
+
**It may also declare the way out.** An `armed` answer can carry an `offer`,
|
|
152
|
+
and where it does, relay the refusal and **then** offer it — once — exactly as
|
|
153
|
+
`.claude/rules/offered-unblocks.md` describes, spending it with
|
|
154
|
+
`skitterspec spec-env review gate <spec> --offered` as you raise it. Where
|
|
155
|
+
there is no `offer`, the three exits in the `Next` row are the whole answer.
|
|
156
|
+
|
|
151
157
|
**This refusal counts nothing.** It is not a tally of ticked boxes — those
|
|
152
158
|
still gate nothing and still are not counted. It asserts one thing: a phase
|
|
153
159
|
that ended has an answer. And the exit is always **one command**, one of them
|
|
154
160
|
being *"I am moving on"*, which is what keeps this a push rather than a wall —
|
|
155
161
|
a gate with no exit gets switched off wholesale instead of answered.
|
|
156
162
|
|
|
163
|
+
- **Report anything left waiting, and claim none of it.** Ask the engine once:
|
|
164
|
+
|
|
165
|
+
```
|
|
166
|
+
skitterspec spec-env review waiting
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
A pass listed here arrived when nothing was watching — a wait that never ran,
|
|
170
|
+
a session cleared, a terminal closed overnight — and no watcher can recover
|
|
171
|
+
those, however good. Relay what it prints: the spec, the code, the verdict and
|
|
172
|
+
the age, with `/spec-reviewed <code>` to pick one up and `--drop <code>` to
|
|
173
|
+
disown it.
|
|
174
|
+
|
|
175
|
+
**It is information, not a gate.** It never refuses, nothing here is
|
|
176
|
+
conditional on it, and **you never claim one** — `/spec-diff` §0 stands
|
|
177
|
+
unchanged, and a pass sitting there when you arrived was not sent to you.
|
|
178
|
+
Silent when nothing is waiting, which is the usual case: say nothing rather
|
|
179
|
+
than reporting that there was nothing to report.
|
|
180
|
+
|
|
157
181
|
## 3. Implement the phase
|
|
158
182
|
|
|
159
183
|
Identify the **first unfinished phase** from the `00-overview.md` phase index,
|
|
@@ -184,8 +208,8 @@ once it is over. Without a provider this is a no-op and nothing below changes.
|
|
|
184
208
|
them. Skip it and a started spec stays mirrored as a phase-less issue.
|
|
185
209
|
- **Never mint the spec issue.** An unlinked spec is skipped, not created —
|
|
186
210
|
`/spec-push` is how someone opts in.
|
|
187
|
-
- **Backfill a missing assignee silently; never ask.** Only when
|
|
188
|
-
`
|
|
211
|
+
- **Backfill a missing assignee silently; never ask.** Only when the repo owns
|
|
212
|
+
`assignee` (it does by default; `"none"` declines it). If the spec records nobody and
|
|
189
213
|
`skitterspec spec-sync whoami --json` answers, stamp it with
|
|
190
214
|
`skitterspec spec-sync assign <spec> --to <id> --name "<name>"` and let the
|
|
191
215
|
push above carry it. If identity is unknown, skip it in silence.
|
|
@@ -316,13 +340,34 @@ the moment the page is about, so render it now — **after** the tests pass and
|
|
|
316
340
|
**before** the commit:
|
|
317
341
|
|
|
318
342
|
```
|
|
319
|
-
skitterspec spec-env review <spec>
|
|
343
|
+
skitterspec spec-env review <spec> --run-reviewers
|
|
320
344
|
```
|
|
321
345
|
|
|
322
346
|
**This is free.** It is the engine reading git and splicing text into a template;
|
|
323
347
|
the diff never passes through you, so a 266KB patch costs nothing. Report the
|
|
324
348
|
path it prints and move on.
|
|
325
349
|
|
|
350
|
+
**`--run-reviewers` is free to *you* as well, and costs wall-clock.** Where the
|
|
351
|
+
project configured any (`review.reviewers` — empty in most projects, and then
|
|
352
|
+
this flag does nothing at all), the engine runs each one against the diff before
|
|
353
|
+
rendering, so the page is already populated when it is opened. Their findings
|
|
354
|
+
come back as JSON and land on the page as **checks**; the patch still never
|
|
355
|
+
passes through you. What it spends is 30s–3min once, after the tests are green —
|
|
356
|
+
which is the cheap half of a step that is about to wait on a person for far
|
|
357
|
+
longer. A re-render of unchanged work reuses the cached findings rather than
|
|
358
|
+
spending another review.
|
|
359
|
+
|
|
360
|
+
**Findings never gate.** A check is not a comment, so a page carrying twenty of
|
|
361
|
+
them still offers `Commit`; a reader who replies to one creates a comment, and
|
|
362
|
+
that does gate, because then a person has asked for something. Nothing here
|
|
363
|
+
counts them, and nothing here acts on them — you render and wait exactly as you
|
|
364
|
+
would have.
|
|
365
|
+
|
|
366
|
+
**A reviewer that could not run is reported by the page**, not by you. Do not
|
|
367
|
+
re-state its outcome, do not investigate it, and never treat it as a failure of
|
|
368
|
+
the phase: the strip on the page says `clean` or `did not run — <why>` for each
|
|
369
|
+
one, which is where a reader deciding whether to commit will look.
|
|
370
|
+
|
|
326
371
|
**This render takes the committing button set**, which is the default — so
|
|
327
372
|
`--buttons` is not passed. That is a statement about the work, not about the
|
|
328
373
|
gate: the phase is finished, so `Commit` and `Commit & Continue` are the right
|
|
@@ -351,32 +396,66 @@ so one subject lives in one place:
|
|
|
351
396
|
|
|
352
397
|
---
|
|
353
398
|
|
|
354
|
-
## ⏸ Review ready — <N> files, +<a> −<d>
|
|
399
|
+
## ⏸ Review ready — <N> files, +<a> −<d><, <n> flagged by <reviewer> — only where one found something>
|
|
355
400
|
|
|
356
|
-
**
|
|
401
|
+
- **local** — <the `local:` URL>
|
|
402
|
+
- **network** — <the `network:` URL, or off with the command that turns it on>
|
|
403
|
+
- **remote** — <the `remote:` URL, or off with the command that turns it on>
|
|
357
404
|
|
|
358
|
-
|
|
405
|
+
<the `live:` line, exactly as the engine printed it — omitted when it printed none>
|
|
406
|
+
|
|
407
|
+
I'm holding here until you send a verdict — the wait covers local and network.
|
|
359
408
|
|
|
360
|
-
|
|
361
|
-
banner carries the served URL and the wait is real. Where it could not serve —
|
|
362
|
-
a busy port, a machine with no network address — that is the case publishing
|
|
363
|
-
exists for, and then the banner carries the published URL with what is true of
|
|
364
|
-
it: *press a verdict, then type `/spec-reviewed`*, because nothing pushes from
|
|
365
|
-
the artifact store into this conversation.
|
|
409
|
+
`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
|
|
366
410
|
|
|
367
|
-
**
|
|
368
|
-
|
|
369
|
-
|
|
370
|
-
|
|
371
|
-
|
|
372
|
-
|
|
411
|
+
**The findings count goes in the COUNTS, and nowhere else.** Where `--json`
|
|
412
|
+
reported a reviewer in the `findings` state, its count joins the heading — the
|
|
413
|
+
slot that already says `7 files, +212 −18` — and that is the whole of it. No
|
|
414
|
+
extra line, no extra row, and nothing at all when every reviewer was `clean`,
|
|
415
|
+
`cached` or could not run: the page's own strip is where the per-reviewer
|
|
416
|
+
outcomes belong, and repeating them here would be the second place naming one
|
|
417
|
+
subject that `.claude/rules/spec-reports.md` exists to prevent.
|
|
418
|
+
|
|
419
|
+
**This is not a third amendment to that contract.** The counts slot is already
|
|
420
|
+
there and already carries numbers about the same diff; nothing about the
|
|
421
|
+
banner's shape, its lines or its exits changes. A reader who has configured no
|
|
422
|
+
reviewer sees the heading they have always seen.
|
|
423
|
+
|
|
424
|
+
**The stack is the engine's — copy it, do not compose it.** `spec-env review`
|
|
425
|
+
printed one line per tier, in that order, and `--json` carries the same thing as
|
|
426
|
+
`tiers`. Relay all three whatever they say, including the ones that are off with
|
|
427
|
+
the command that turns them on: a reader who has left the house cannot ask for a
|
|
428
|
+
remote page they were never shown.
|
|
429
|
+
|
|
430
|
+
**Do not pick one for them.** The engine used to, and the guess failed three
|
|
431
|
+
separate ways in one day. `.claude/rules/spec-reports.md` carries the shape and
|
|
432
|
+
why the *one link, never two* rule now reads
|
|
433
|
+
**one link per reachable store, each labelled** —
|
|
434
|
+
local and network are two doors into one room, so the wait
|
|
435
|
+
covers both. `remote` is a second store, so its own line carries its own caveat:
|
|
436
|
+
*a verdict here needs `/spec-reviewed`*, because nothing pushes from
|
|
437
|
+
the artifact store into this conversation. Never let the holding line promise a
|
|
438
|
+
wait over that tier.
|
|
439
|
+
|
|
440
|
+
**Publishing is still never yours to do.** `remote` reading `off` is the normal
|
|
441
|
+
state, and the fix for it is the command on that line — typed by the operator,
|
|
442
|
+
or pressed on the page, because a published page is one this tooling cannot
|
|
443
|
+
remove and permitting it is not publishing it.
|
|
444
|
+
|
|
445
|
+
**The `live:` line goes with the stack**, and it is the engine's line too —
|
|
446
|
+
copied as printed, and **absent when the engine printed none**. The page can act
|
|
447
|
+
on it: a press puts the spec live or takes it down and hands the reader back the
|
|
448
|
+
same page, which is `/spec-diff` §2b's routing and not this skill's. What
|
|
449
|
+
matters here is that an action **never clears the gate this phase armed** — the
|
|
450
|
+
reader has looked at it running and concluded nothing, so the phase still owes a
|
|
451
|
+
verdict.
|
|
373
452
|
|
|
374
453
|
---
|
|
375
454
|
|
|
376
455
|
**Where you are not waiting, it stays the `Review` row** — the counts and the
|
|
377
456
|
page link, and **no question**:
|
|
378
457
|
|
|
379
|
-
| **Review** | <N> files, +<a> −<d> ·
|
|
458
|
+
| **Review** | <N> files, +<a> −<d> · **local** <URL> · **network** <URL> · **remote** off |
|
|
380
459
|
|
|
381
460
|
At the end of a phase you are always waiting, so this shape belongs to the
|
|
382
461
|
renders that are not this step: a mid-phase `/spec-diff`, a page produced
|
|
@@ -406,16 +485,30 @@ whether the two places are adjacent rows or a row and a banner.
|
|
|
406
485
|
|
|
407
486
|
The row is findable, but a row cannot make the continuation follow from the
|
|
408
487
|
reading — and that is the gap the whole gate exists to close.
|
|
409
|
-
|
|
410
|
-
|
|
411
|
-
reader pressed is what carries the work on.
|
|
488
|
+
|
|
489
|
+
**The wait is a command. Do not write one.**
|
|
412
490
|
|
|
413
491
|
1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
|
|
414
492
|
the whole scope of what you may claim.
|
|
415
|
-
2. **
|
|
416
|
-
|
|
417
|
-
|
|
418
|
-
|
|
493
|
+
2. **Run the engine's wait in the background, and end your turn:**
|
|
494
|
+
|
|
495
|
+
```
|
|
496
|
+
skitterspec spec-env review wait <spec> --since <the timestamp>
|
|
497
|
+
```
|
|
498
|
+
|
|
499
|
+
It returns when a pass arrives inside that window, and
|
|
500
|
+
**it takes no timeout unless you pass one** —
|
|
501
|
+
the wait lasts as long as your session, because a reader who walks away from
|
|
502
|
+
a diff is the normal case rather than the edge one. Do not give it a duration
|
|
503
|
+
of your own.
|
|
504
|
+
|
|
505
|
+
**A watch that dies is re-armed on the same window**, silently and bounded by
|
|
506
|
+
the age of that window — `.claude/rules/spec-reports.md` carries the contract,
|
|
507
|
+
including when to stop and what the banner says instead. Do not restate it
|
|
508
|
+
here.
|
|
509
|
+
|
|
510
|
+
Then **end your turn**. Do not poll it and do not hold the turn open: the
|
|
511
|
+
point is that the reader has the terminal back while they read.
|
|
419
512
|
3. **On waking, let the engine pick**:
|
|
420
513
|
|
|
421
514
|
```
|
|
@@ -423,11 +516,26 @@ reader pressed is what carries the work on.
|
|
|
423
516
|
```
|
|
424
517
|
|
|
425
518
|
It claims the one pass that arrived inside the window, and acts on nothing
|
|
426
|
-
at all when none did (the
|
|
427
|
-
when two did (two sittings, or two people — the operator has the
|
|
519
|
+
at all when none did (the wait can be woken by something that was not a
|
|
520
|
+
pass) or when two did (two sittings, or two people — the operator has the
|
|
521
|
+
codes).
|
|
428
522
|
4. **Route on the verdict** exactly as `/spec-diff` §2 and §4 describe. Do not
|
|
429
523
|
restate that routing here.
|
|
430
524
|
|
|
525
|
+
**WHY A COMMAND RATHER THAN A LOOP YOU COMPOSE.** This step used to say "watch
|
|
526
|
+
the pending store" and stop, so every run invented its own watcher in shell —
|
|
527
|
+
and three failed in two days, each reaching the operator as *"I pressed the
|
|
528
|
+
button and nothing happened"*. The worst wrote
|
|
529
|
+
`until [ -f "$P" ] && [ "$x" \> "$y" ]`: valid bash, a syntax error in zsh, a
|
|
530
|
+
predicate that could never be true. It spun for five minutes writing to a
|
|
531
|
+
stderr nobody reads.
|
|
532
|
+
|
|
533
|
+
**The bug is not the lesson — the silence is.** A watcher that can never fire
|
|
534
|
+
and one patiently working are indistinguishable from outside, so nothing about
|
|
535
|
+
that run looked wrong until the operator asked. `review wait` says it has
|
|
536
|
+
started, is written once, and is tested against a store that gains a pass
|
|
537
|
+
mid-flight. A predicate composed fresh each time is proven by nothing.
|
|
538
|
+
|
|
431
539
|
**WHY THIS IS SAFE, AND WHAT IT COSTS.** It was once true that a device
|
|
432
540
|
reaching your page could not reach your conversation, and that fact was the
|
|
433
541
|
whole guard: a pass sat in the holding area until a person typed
|
|
@@ -441,11 +549,11 @@ is that the page can now act, so the token has become a credential rather than
|
|
|
441
549
|
a convenience — and `--claim-since` refusing to choose between two passes is
|
|
442
550
|
what stops a race becoming a wrong commit.
|
|
443
551
|
|
|
444
|
-
**Where the harness cannot
|
|
445
|
-
the wait. Say the page is rendered and that you are holding
|
|
446
|
-
your turn; the reader's next message is what carries it,
|
|
447
|
-
it up from the paste exactly as it always has. The gate
|
|
448
|
-
the engine's, not the
|
|
552
|
+
**Where the harness cannot run something in the background, you still wait** —
|
|
553
|
+
the turn ending is the wait. Say the page is rendered and that you are holding
|
|
554
|
+
for the pass, then end your turn; the reader's next message is what carries it,
|
|
555
|
+
and `/spec-diff` picks it up from the paste exactly as it always has. The gate
|
|
556
|
+
holds either way: it is the engine's, not the wait's.
|
|
449
557
|
|
|
450
558
|
This once read *"change nothing"* — keep the row, keep the question, do not
|
|
451
559
|
wait — and that exemption is the hatch a whole class of unanswerable questions
|
|
@@ -455,38 +563,38 @@ came through. Every harness can end a turn.
|
|
|
455
563
|
one line; by the time this step is reached the chain has finished, so waiting
|
|
456
564
|
here stops nothing that was still going to happen.
|
|
457
565
|
|
|
458
|
-
Relay the
|
|
459
|
-
|
|
566
|
+
Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines —
|
|
567
|
+
never the bare `page:` path: a path is not clickable in any terminal, and a page
|
|
568
|
+
nobody can open is a page nobody reads.
|
|
460
569
|
|
|
461
570
|
- **Never write the review unasked**, and **never publish**. Publishing leaves
|
|
462
571
|
something behind that this tooling cannot remove, so it is always something
|
|
463
572
|
someone asks for. A `file://` link is no use on a phone, and saying so **is**
|
|
464
573
|
the ask — publishing is the answer to it, and `/spec-diff` §6 owns how.
|
|
465
|
-
**
|
|
466
|
-
|
|
467
|
-
|
|
468
|
-
|
|
469
|
-
|
|
470
|
-
|
|
471
|
-
|
|
472
|
-
|
|
473
|
-
|
|
474
|
-
|
|
475
|
-
|
|
476
|
-
|
|
477
|
-
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
482
|
-
|
|
483
|
-
|
|
484
|
-
|
|
485
|
-
|
|
486
|
-
|
|
487
|
-
|
|
488
|
-
|
|
489
|
-
`file://` URL with its marker, and that is when publishing is worth naming.
|
|
574
|
+
**The `reader:` line no longer decides anything here, and that is the point.**
|
|
575
|
+
It is still printed, and it is still the only place that question is answered —
|
|
576
|
+
but the offer does not change with it, because the stack lists every tier
|
|
577
|
+
whatever it says. Three reader states used to mean three different offers, and
|
|
578
|
+
that branching is exactly what produced a `file://` page on a session detected
|
|
579
|
+
`unknown`, a LAN URL for a phone off the network, and an address that changed
|
|
580
|
+
underneath a reader when detection flipped mid-session.
|
|
581
|
+
|
|
582
|
+
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
583
|
+
`network` — the other addresses this machine has, offered because the
|
|
584
|
+
best-guess one can be wrong — so pass them on rather than editing them out.
|
|
585
|
+
|
|
586
|
+
**Never read an environment variable to decide anything about the offer** — not
|
|
587
|
+
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
588
|
+
here for a detection to decide, and a second implementation of one could not be
|
|
589
|
+
tested and would drift.
|
|
590
|
+
|
|
591
|
+
**Serving is the engine's to do; publishing is never.** The server is one
|
|
592
|
+
process, ended by one flag, leaving nothing behind, and `review.allowNetwork`
|
|
593
|
+
decides whether it binds wide — no detection involved. A reader the server CAN
|
|
594
|
+
reach is not a reason to publish as well: the tiers they can already open are on
|
|
595
|
+
the stack. Publishing leaves a page this tooling cannot remove, so it stays an
|
|
596
|
+
ask in every case, always — which is why `remote` shows the command rather than
|
|
597
|
+
a URL until someone types it.
|
|
490
598
|
|
|
491
599
|
- **Never fatal.** A failed render — no worktree, a git error — is one line and
|
|
492
600
|
the phase is still done. The page is a convenience; the repo is the record.
|
|
@@ -155,6 +155,24 @@ the chosen project through as `--project <id>`.
|
|
|
155
155
|
|
|
156
156
|
## 4a. Apply it yourself — the MCP path (order matters)
|
|
157
157
|
|
|
158
|
+
**First, check whether you are about to overwrite someone.** On the API path
|
|
159
|
+
`apply` does this for itself, off the read-back it already makes. On the MCP
|
|
160
|
+
path nothing has read the issue yet, so ask before you write:
|
|
161
|
+
|
|
162
|
+
```
|
|
163
|
+
skitterspec spec-sync status <spec> --remote <issuefile>
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
using the same issue JSON step 2 fetched — it must carry the `description`. A
|
|
167
|
+
`drift: … description was edited on Linear since the last push` line means a
|
|
168
|
+
person wrote something there that step 1 below replaces.
|
|
169
|
+
|
|
170
|
+
**It is a warning and never a gate.** The repo is the source of truth and the
|
|
171
|
+
push still goes ahead; relay the line, name the issue, and carry on. What is
|
|
172
|
+
forbidden is doing it *silently* — someone's paragraph disappearing with nothing
|
|
173
|
+
said about it is the failure this exists to end. Nothing printed means nothing to
|
|
174
|
+
say, which includes every case the engine could not tell.
|
|
175
|
+
|
|
158
176
|
1. **Spec issue** → if the overview has no `linear_identifier`, this push
|
|
159
177
|
**mints** it: run the picker in **Picking the Linear Project** below, then
|
|
160
178
|
create it with `save_issue` (`team` = `linear.teamId`; `project` = the picked
|
|
@@ -233,6 +251,33 @@ This writes the last-pushed snapshot from the now-stamped files, so the next
|
|
|
233
251
|
`/spec-push` produces an empty plan. Commit the stamped spec + snapshot into the
|
|
234
252
|
branch so the mirror-link rides in the PR.
|
|
235
253
|
|
|
254
|
+
## 5b. A refused mint, and the way back
|
|
255
|
+
|
|
256
|
+
Two refusals reach you from `apply`, and neither is a failure to retry.
|
|
257
|
+
|
|
258
|
+
**`N already exists and no spec claims it`** — the push was about to mint, and
|
|
259
|
+
an issue with **exactly** this title is sitting there unheld. That is almost
|
|
260
|
+
always the spec's own issue, whose link was lost: a bad merge, a hand edit, a
|
|
261
|
+
stray `sed` over the frontmatter. Adopt it rather than creating a twin:
|
|
262
|
+
|
|
263
|
+
```
|
|
264
|
+
skitterspec spec-sync reattach <spec> --to <ISSUE-REF>
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
Bare, `reattach` searches by title itself and stamps the one unclaimed match;
|
|
268
|
+
it refuses when several match and names them, because choosing between two is
|
|
269
|
+
a guess. `--force-new` is the escape when the duplicate title is genuine.
|
|
270
|
+
|
|
271
|
+
**`N exists in Linear but could not be recorded`** — the create landed and the
|
|
272
|
+
stamp did not, so Linear holds an issue the repo does not point at.
|
|
273
|
+
**Do not re-run**:
|
|
274
|
+
the plan still reads the spec as unlinked, so a re-run mints a second.
|
|
275
|
+
`reattach --to <the named id>` is the fix.
|
|
276
|
+
|
|
277
|
+
Everything else — a rate limit, a refusal that says waiting will not help — is
|
|
278
|
+
reported with Linear's own explanation and whether retrying can help. Relay it;
|
|
279
|
+
do not paraphrase.
|
|
280
|
+
|
|
236
281
|
## 6. Report
|
|
237
282
|
|
|
238
283
|
End with the block defined in `.claude/rules/spec-reports.md`. That file carries
|
|
@@ -120,8 +120,8 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
|
|
|
120
120
|
Do not roll anything back, and do not stop to ask.
|
|
121
121
|
- **Say what happened** in the skill's report: mirror updated, skipped as
|
|
122
122
|
unlinked, or failed with the reason.
|
|
123
|
-
- **There is no unassign step, and that is not an omission.**
|
|
124
|
-
`
|
|
123
|
+
- **There is no unassign step, and that is not an omission.** Where the repo owns
|
|
124
|
+
`assignee`, the projection derives it from the spec's lifecycle
|
|
125
125
|
bucket — so moving the folder to `complete`/`cancelled` is *itself* what
|
|
126
126
|
releases the issue, and the push above carries it like any other field. The
|
|
127
127
|
`linear_assignee_id` stamp and the `> **Developer:**` header both stay put:
|
|
@@ -146,6 +146,67 @@ names it. This is why the commit no longer stages `specs/` wholesale: the one
|
|
|
146
146
|
file outside the spec's folder that had to be swept up is addressable, so the
|
|
147
147
|
breadth bought nothing and cost another session's work.
|
|
148
148
|
|
|
149
|
+
## 4b. Hand the refresh back on a page, then wait
|
|
150
|
+
|
|
151
|
+
**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
|
|
152
|
+
present) **and this review actually changed something.** Either missing → skip
|
|
153
|
+
the whole step in silence.
|
|
154
|
+
|
|
155
|
+
A refreshed spec is a rewrite of a document someone is about to work from, so it
|
|
156
|
+
gets read before it is committed — the same ending `/spec` now has:
|
|
157
|
+
|
|
158
|
+
```
|
|
159
|
+
skitterspec spec-env review <spec> --docs --buttons refresh
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
`--docs` reads the spec's own documents from the tree you are standing in, so it
|
|
163
|
+
wants no worktree and works for a spec in any bucket. These documents are
|
|
164
|
+
**tracked**, so the diff against `HEAD` is a patch rather than a set of new
|
|
165
|
+
files — which is exactly what the reader wants here: what drifted, and what you
|
|
166
|
+
rewrote.
|
|
167
|
+
|
|
168
|
+
**Render nothing when nothing changed.** `/spec-review` frequently concludes a
|
|
169
|
+
spec is still accurate, and that is a success rather than a gap. A page showing
|
|
170
|
+
an empty diff under a commit button asks for a verdict on nothing, and the
|
|
171
|
+
engine refuses it for the same reason — `nothing to review`. Take that refusal
|
|
172
|
+
as the answer and report the `⏸`/`✅` you already had.
|
|
173
|
+
|
|
174
|
+
**Arm nothing.** No `review arm` here: the gate asserts that a phase which ended
|
|
175
|
+
owes an answer, and a re-validated spec has ended no phase. Walking away leaves
|
|
176
|
+
an uncommitted spec, which is the state this skill has always finished in.
|
|
177
|
+
|
|
178
|
+
### The three endings
|
|
179
|
+
|
|
180
|
+
`--buttons refresh` offers `Commit`, `Request changes` and `Discuss`.
|
|
181
|
+
|
|
182
|
+
**No start verdict, deliberately.** The spec this skill refreshed may already be
|
|
183
|
+
in progress — that is half of what it is used for — so `Commit & Start` would
|
|
184
|
+
offer to provision a worktree for a spec that already has one.
|
|
185
|
+
|
|
186
|
+
- **`commit`** — hand off to `review.commitWith` (`/commit` by default) with the
|
|
187
|
+
pathspec the render reported on `docs.paths`, then finish. The spec keeps
|
|
188
|
+
whatever status step 4 left it in.
|
|
189
|
+
- **`changes`** — work the notes into the spec, record a resolution for each so
|
|
190
|
+
the next render strikes it through with what changed, re-render, and wait
|
|
191
|
+
again.
|
|
192
|
+
- **`discuss`** — report and talk. Claim nothing, change nothing.
|
|
193
|
+
|
|
194
|
+
### Then wait for it
|
|
195
|
+
|
|
196
|
+
**The wait is a command. Do not write one.** Note the moment you start waiting
|
|
197
|
+
as an ISO timestamp, run the engine's wait in the background, and end your turn:
|
|
198
|
+
|
|
199
|
+
```
|
|
200
|
+
skitterspec spec-env review wait <spec> --since <the timestamp>
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
Pass no timeout. On waking, let the engine pick the pass —
|
|
204
|
+
`skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json`
|
|
205
|
+
— and route on the verdict above.
|
|
206
|
+
|
|
207
|
+
**Where the page is `file://`** the pass is copied and pasted, so the wait is the
|
|
208
|
+
turn ending and the banner says so. Do not start a watch that cannot fire.
|
|
209
|
+
|
|
149
210
|
## 5. Report
|
|
150
211
|
|
|
151
212
|
Do **not** `git commit` unless the user asks.
|
|
@@ -166,6 +227,32 @@ the shape; this section carries only what is specific here.
|
|
|
166
227
|
API that moved, a task the code already does. `Spec` carries the status the
|
|
167
228
|
review leaves it in, which is the answer to "can I start this?".
|
|
168
229
|
|
|
230
|
+
**Where step 4b rendered a page the run is waiting**, so the block omits the
|
|
231
|
+
`Review` row and ends on the banner from `.claude/rules/spec-reports.md` — the
|
|
232
|
+
tier stack copied from the engine's own lines, never one link chosen for the
|
|
233
|
+
reader:
|
|
234
|
+
|
|
235
|
+
---
|
|
236
|
+
|
|
237
|
+
## ⏸ Review ready — <N> files, +<a> −<d>
|
|
238
|
+
|
|
239
|
+
- **local** — <the `local:` URL>
|
|
240
|
+
- **network** — <the `network:` URL, or off with the command that turns it on>
|
|
241
|
+
- **remote** — <the `remote:` URL, or off with the command that turns it on>
|
|
242
|
+
|
|
243
|
+
I'm holding here until you send a verdict — the wait covers local and network.
|
|
244
|
+
|
|
245
|
+
`Commit` commits the refresh · `Request changes` works them now
|
|
246
|
+
|
|
247
|
+
---
|
|
248
|
+
|
|
249
|
+
`Next` then names the page rather than a command, because the button is what
|
|
250
|
+
carries the work on.
|
|
251
|
+
|
|
252
|
+
Where nothing was rendered — no isolation, or no drift to show — `Next` is
|
|
253
|
+
`/commit, then /spec-start <name>`, since this skill does not commit and
|
|
254
|
+
`/spec-start` refuses a tree holding anything that is not the spec's.
|
|
255
|
+
|
|
169
256
|
**Drift found and not fixed is a `Follow-up`, not a silence.** A spec this skill
|
|
170
257
|
declared reviewed is one nobody will re-read; something it noticed and left
|
|
171
258
|
undone has to leave the session in writing or it did not happen.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spec-reviewed
|
|
3
|
-
description: Pick up the review you approved on the page — run it bare to pick up the single waiting pass, paste the six-digit code off the page ("/spec-reviewed 608223") to name one exactly,
|
|
3
|
+
description: Pick up the review you approved on the page — run it bare to pick up the single waiting pass, paste the six-digit code off the page ("/spec-reviewed 608223") to name one exactly, or pass the verdict itself ("/spec-reviewed commit") when the page could not send and copied you a command instead. Use when the user says "/spec-reviewed", "I approved it", "I've reviewed it", "pick up my review", "I pressed approve", or otherwise says they have finished reviewing a rendered diff.
|
|
4
4
|
disable-model-invocation: true
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -70,16 +70,42 @@ Several provisioned and none resolved is a refusal — relay its list and stop,
|
|
|
70
70
|
never pick from it. See `.claude/rules/spec-planning.md`; do not restate the
|
|
71
71
|
rule here.
|
|
72
72
|
|
|
73
|
-
**
|
|
74
|
-
matches `^\d{6}$`; a **
|
|
75
|
-
**
|
|
76
|
-
|
|
73
|
+
**Four argument shapes, and they cannot collide.** A **six-digit code**
|
|
74
|
+
matches `^\d{6}$`; a **verdict** is one of a closed list of six words;
|
|
75
|
+
a **tracker id** carries a letter and a hyphen;
|
|
76
|
+
a **spec name** is none of them and always carries a lifecycle prefix
|
|
77
|
+
(`feat-`, `bug-`, `hotfix-`), which no verdict does. So the parse needs no flag,
|
|
78
|
+
and nothing has to be guessed at from context.
|
|
77
79
|
|
|
78
80
|
A **six-digit code** is a pass the operator read off their own page. It says
|
|
79
81
|
**which pass**, not which spec — so resolve the spec exactly as a bare
|
|
80
82
|
invocation does, above, and claim the code *there*. Then go to step 4 — a named
|
|
81
83
|
pass has nothing to disambiguate.
|
|
82
84
|
|
|
85
|
+
A **verdict word** — `commit`, `commit-continue`, `commit-start`,
|
|
86
|
+
`commit-land`, `continue`, `changes`, `discuss` — is the conclusion itself,
|
|
87
|
+
arriving without a pass behind it. It is
|
|
88
|
+
what a **`file://` page** hands over: that page has no server to POST to and no
|
|
89
|
+
store to write to, so it copies a command instead of sending anything, and this
|
|
90
|
+
is the command. Resolve the spec as a bare invocation does, then send the word
|
|
91
|
+
through the engine:
|
|
92
|
+
|
|
93
|
+
```
|
|
94
|
+
skitterspec spec-env review <spec> --verdict <word>
|
|
95
|
+
```
|
|
96
|
+
|
|
97
|
+
It joins the same merge a claimed pass goes through, so the routing in step 4
|
|
98
|
+
is unchanged: a commit over open notes is refused exactly as it would be, the
|
|
99
|
+
outcome log records it, and the gate a phase armed is cleared. Then go to step
|
|
100
|
+
4 — there is nothing to disambiguate.
|
|
101
|
+
|
|
102
|
+
**A word carries a verdict and nothing else**, and that is a property of the
|
|
103
|
+
transport, not a shortcut. Accepts and comments do not fit on a command line,
|
|
104
|
+
so the page only ever offers the words while the reader has marked nothing —
|
|
105
|
+
the moment they tick an accept or write a note it goes back to handing over the
|
|
106
|
+
blob. If someone tells you they marked things up *and* gives you a word, ask
|
|
107
|
+
for the pass: the word would land a verdict with their notes silently dropped.
|
|
108
|
+
|
|
83
109
|
A **name** targets that spec instead. A **tracker id** does too, but only
|
|
84
110
|
through a **provider seam**: the base knows nothing about tracker ids, so
|
|
85
111
|
resolve one by asking whichever provider is installed for its listing —
|
|
@@ -73,6 +73,20 @@ as printed; when it refuses, relay the reason and stop.
|
|
|
73
73
|
It also refuses a **clean** tree whose spec is not in the commit the worktree
|
|
74
74
|
would fork from — otherwise you get a branch missing the very spec it is for.
|
|
75
75
|
|
|
76
|
+
**A spec that `/spec` already landed is the HEALTHY case of that check.**
|
|
77
|
+
It is not the refusal. `/spec` authors in its own `--docs` worktree and its committing
|
|
78
|
+
verdict fast-forwards the base branch, so by the time `/spec-start` runs the
|
|
79
|
+
spec is already in the commit the worktree forks from and the tree is clean —
|
|
80
|
+
which is exactly what that check is looking for. Do not read "clean tree,
|
|
81
|
+
nothing to commit" as a sign something was skipped: it means the landing worked.
|
|
82
|
+
|
|
83
|
+
**And the worktree may already exist**, because `Commit & Start` keeps it. That
|
|
84
|
+
is a re-attach, not a clash: `spec-env up` plans the attach form rather than a
|
|
85
|
+
second `-b` fork, and its `then, in the worktree, run:` step is where the
|
|
86
|
+
`setup` commands `--docs` deliberately skipped finally run. So run the plan as
|
|
87
|
+
printed — the install belongs to this moment, the first at which the tree is
|
|
88
|
+
used for code — and report a re-attach rather than a fresh provision.
|
|
89
|
+
|
|
76
90
|
## 2. Identify the spec
|
|
77
91
|
|
|
78
92
|
- Use the name/path argument when given.
|
|
@@ -233,10 +247,14 @@ branch is already here.
|
|
|
233
247
|
- Set the **Status** header: `> **Status:** In Progress — Phase 1 (started <YYYY-MM-DD>)`.
|
|
234
248
|
- Set **Developer** if it is still `—` (`git config user.name`).
|
|
235
249
|
|
|
236
|
-
**Only when all three hold**: `specs/.core/linear.config.json` exists,
|
|
237
|
-
`
|
|
250
|
+
**Only when all three hold**: `specs/.core/linear.config.json` exists, the repo
|
|
251
|
+
**owns** `assignee` in its `sync.fieldOwnership`, and the spec carries a
|
|
238
252
|
`linear_identifier`. Any one missing → skip this step silently and carry on; a
|
|
239
|
-
project that
|
|
253
|
+
project that declined must see no trace of assignment.
|
|
254
|
+
|
|
255
|
+
Ownership is the **value**, not the key: `assignee` is owned by default, and
|
|
256
|
+
`"none"` is how a project declines it. Testing whether the key is *present* would
|
|
257
|
+
read as opted-in everywhere, since the default puts it in every config.
|
|
240
258
|
|
|
241
259
|
**Never blocks, never fails the skill.** Everything below is best-effort: the
|
|
242
260
|
branch is provisioned and the spec is moving either way, and an unassigned issue
|
|
@@ -371,6 +389,25 @@ here beyond knowing it is no longer dead code.
|
|
|
371
389
|
A spec ideally arrives `Ready` from `/spec`; a `Draft` works too — sanity-check
|
|
372
390
|
it is well-formed first.
|
|
373
391
|
|
|
392
|
+
- **Report anything left waiting, and claim none of it.** Ask the engine once:
|
|
393
|
+
|
|
394
|
+
```
|
|
395
|
+
skitterspec spec-env review waiting
|
|
396
|
+
```
|
|
397
|
+
|
|
398
|
+
A pass listed here arrived when nothing was watching — a wait that never ran,
|
|
399
|
+
a session cleared, a terminal closed overnight — and no watcher can recover
|
|
400
|
+
those, however good. Relay what it prints: the spec, the code, the verdict and
|
|
401
|
+
the age, with `/spec-reviewed <code>` to pick one up and `--drop <code>` to
|
|
402
|
+
disown it.
|
|
403
|
+
|
|
404
|
+
**It is information, not a gate.** It never refuses, nothing here is
|
|
405
|
+
conditional on it, and **you never claim one** — `/spec-diff` §0 stands
|
|
406
|
+
unchanged, and a pass sitting there when you arrived was not sent to you.
|
|
407
|
+
Silent when nothing is waiting, which is the usual case: say nothing rather
|
|
408
|
+
than reporting that there was nothing to report.
|
|
409
|
+
|
|
410
|
+
|
|
374
411
|
## 4b. Note a missing gating decision (only if configured)
|
|
375
412
|
|
|
376
413
|
**Only when `specs/.core/gating.config.json` exists.** Run
|