@skitterbyte/skitterspec-linear 17.0.0 → 17.2.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.
Files changed (38) hide show
  1. package/README.md +3 -0
  2. package/assets/claude-md-section.md +13 -0
  3. package/assets/commands/allow-main.md +33 -0
  4. package/assets/commands/spec-skip.md +24 -0
  5. package/assets/core/env.config.json.example +2 -1
  6. package/assets/core/env.config.md +83 -2
  7. package/assets/hooks/main-guard.cjs +145 -0
  8. package/assets/hooks/review-gate.cjs +8 -3
  9. package/assets/review/page.html +132 -2
  10. package/assets/rules/commit-trailers.md +17 -7
  11. package/assets/rules/offered-unblocks.md +100 -0
  12. package/assets/rules/spec-planning.md +160 -11
  13. package/assets/rules/spec-reports.md +66 -9
  14. package/assets/skills/no-spec/SKILL.md +221 -0
  15. package/assets/skills/spec/SKILL.md +138 -37
  16. package/assets/skills/spec-bug/SKILL.md +8 -2
  17. package/assets/skills/spec-cancel/SKILL.md +29 -0
  18. package/assets/skills/spec-complete/SKILL.md +25 -0
  19. package/assets/skills/spec-diff/SKILL.md +36 -2
  20. package/assets/skills/spec-init/SKILL.md +4 -2
  21. package/assets/skills/spec-next/SKILL.md +50 -3
  22. package/assets/skills/spec-reviewed/SKILL.md +3 -3
  23. package/assets/skills/spec-start/SKILL.md +14 -0
  24. package/package.json +1 -1
  25. package/src/cli.js +749 -62
  26. package/src/env/config.js +121 -4
  27. package/src/env/hooks.js +102 -33
  28. package/src/env/live.js +30 -1
  29. package/src/env/mainguard.js +240 -0
  30. package/src/env/provision.js +106 -10
  31. package/src/env/registry.js +70 -6
  32. package/src/env/resolve.js +113 -4
  33. package/src/env/review.js +324 -20
  34. package/src/env/reviewers/coderabbit.js +228 -0
  35. package/src/env/reviewers.js +517 -0
  36. package/src/env/serve.js +189 -44
  37. package/src/env/teardown.js +12 -1
  38. package/src/init.js +125 -15
@@ -192,25 +192,56 @@ Briefly play back the agreed understanding before writing.
192
192
 
193
193
  This skill is for **features**. For bugs, use `/spec-bug` (test-first, red→green).
194
194
 
195
- ### Write it from the base branch
196
-
197
- **Check where you are before creating the folder.** A backlog spec belongs on
198
- the base branch (`main`). If you are on another spec's branch — most likely
199
- inside its worktree, because a design question came up part-way through
200
- implementing it — say so before writing, and offer to author the spec from the
201
- primary checkout instead.
202
-
203
- It matters for more than tidiness: a spec written inside another spec's worktree
204
- **physically lives on that branch**. It is not on `main` until that spec lands,
205
- it is invisible to anyone listing `specs/backlog/` meanwhile, and if that spec is
206
- cancelled the new spec is cancelled with it. Committing it there also mis-stamps
207
- the commit's ticket trailer, since that is resolved from the branch (see
208
- `.claude/rules/commit-trailers.md`, installed with a ticketing provider).
209
-
210
- **Warn, don't refuse** — doing this deliberately is legitimate, and the user may
211
- have a reason. If they continue, carry on exactly as normal, and mention that
212
- the trailer for that commit wants `spec-sync ref <new-spec-name>` rather than the
213
- bare form.
195
+ ### Write it in its own worktree
196
+
197
+ **Only when the project has per-spec isolation** (`specs/.core/env.config.json`
198
+ present). Without it there is no worktree to make and this section does not
199
+ apply — write the folder where you are standing, exactly as before.
200
+
201
+ **Provision before you write, not after.** Grilling put nothing on disk and the
202
+ spec's name is settled by the time Phase A ends, so this is the one moment where
203
+ a worktree costs nothing to obtain and everything is still ahead of it:
204
+
205
+ ```
206
+ skitterspec spec-env up <name> --docs
207
+ ```
208
+
209
+ Run the commands it prints, then move this session into the worktree with a
210
+ plain `cd` — the Bash working directory persists between calls, so from here on
211
+ the spec is written on its own branch. Confirm the move landed rather than
212
+ reading silence as success (`.claude/rules/negative-checks.md` rule 1):
213
+ `skitterspec spec-env resolve` with no argument must name this spec. If it does
214
+ not, say so and write the spec where you are standing instead; a spec in the
215
+ wrong tree is worse than a spec with no worktree.
216
+
217
+ **`--docs` is what makes this cheap.** It skips the `setup` commands and the
218
+ Docker stack — everything whose only purpose is making a tree *runnable* — so
219
+ provisioning a worktree to write markdown in is a `git worktree add` and nothing
220
+ else. `/spec-start` re-runs `up` over the same worktree without the flag, and the
221
+ setup runs then, at the first moment the tree is used for code.
222
+
223
+ **Why the base branch is no longer where this happens.** `main` is where work
224
+ **lands**, not where it happens. Authoring on it meant the spec sat uncommitted
225
+ there for as long as Phase C2's page went unanswered — which is unbounded by
226
+ design, because a reader walking away from a diff is the normal case — and a
227
+ release could not be cut through it. The verdict lands the spec instead, so
228
+ `main` gains it as one commit and is never dirty on the way.
229
+
230
+ **A spec written in ANOTHER spec's worktree is still the mistake it always was**,
231
+ and this section does not soften that. It physically lives on that branch: not on
232
+ `main` until that spec lands, invisible to anyone listing `specs/backlog/`
233
+ meanwhile, and cancelled along with its host. Committing it there also mis-stamps
234
+ the ticket trailer, which is resolved from the branch (see
235
+ `.claude/rules/commit-trailers.md`, installed with a ticketing provider). The
236
+ difference is whose worktree: **its own** is now the normal path, and someone
237
+ else's is the accident.
238
+
239
+ So if Phase A ran inside another spec's worktree — most likely because a design
240
+ question came up part-way through implementing it — the provision above is the
241
+ fix rather than something to warn about: it moves the session out of that tree
242
+ and into this spec's own. Where isolation is off and there is no worktree to
243
+ move to, **warn, don't refuse**, and say the trailer for that commit wants
244
+ `spec-sync ref <new-spec-name>` rather than the bare form.
214
245
 
215
246
  - **Every spec is a folder** — never a bare file, even for a one-line change:
216
247
  `specs/backlog/feat-<kebab-name>/`. Create it with `mkdir -p`.
@@ -385,26 +416,40 @@ phase of the lifecycle ends — on a page, in a verdict.
385
416
  skitterspec spec-env review <spec> --docs --buttons authoring
386
417
  ```
387
418
 
388
- `--docs` reads the spec's own documents from the tree you are standing in, so it
389
- never wants a worktree — a backlog spec has none. It renders
390
- **this spec's documents and nobody else's**: several specs are routinely
391
- authored in one
392
- checkout, and the file set comes from `spec-env stage`'s `owned` half precisely
393
- so a colleague's spec cannot land on your page and then be committed under your
394
- verdict.
419
+ `--docs` reads the spec's own documents from the tree you are standing in, which
420
+ after Phase B is **this spec's own worktree**. It renders
421
+ **this spec's documents and nobody else's**: the `owned` half of
422
+ `spec-env stage` is what supplies the file set, and it stays load-bearing even
423
+ now that the tree holds one spec — a project's `spec.companionPaths` and a
424
+ hand-edited `specs/.core/` both land in the same tree, and only the spec's own
425
+ documents belong under this verdict.
395
426
 
396
427
  **This is free.** The engine reads git and splices text into a template; the
397
428
  diff never passes through you.
398
429
 
430
+ **Never pass `--run-reviewers` here.** A spec is prose, and the reviewers
431
+ `review.reviewers` names read code — spending a rate-limited review on a
432
+ paragraph buys nothing. The engine refuses it on a `--docs` render whatever this
433
+ skill asks for, so this is a note about intent rather than a guard you are
434
+ holding: do not add the flag on the assumption that it was an oversight.
435
+
399
436
  **Render nothing when nothing was written.** A `⏸` run — grilling that never
400
437
  reached a shared understanding — has no spec to show, and must not ask for a
401
438
  verdict on one.
402
439
 
403
440
  **Arm nothing.** There is no `spec-env review arm` in this path, and that is a
404
441
  decision rather than an omission: the gate asserts that *a phase which ended*
405
- owes an answer, and a backlog spec owes no phase. Walking away from this page
406
- costs nothing — the spec is simply still uncommitted, which `/spec-start` already
407
- handles. A `/spec` run must leave `spec-env review gate --check` exiting 0.
442
+ owes an answer, and a backlog spec owes no phase. A `/spec` run must leave
443
+ `spec-env review gate --check` exiting 0.
444
+
445
+ **And walking away from this page now costs nobody anything**, which is a
446
+ stronger reason than the one that used to sit here. It read *"the spec is simply
447
+ still uncommitted, which `/spec-start` already handles"* — true, and a
448
+ concession: an uncommitted spec meant a dirty base branch, which is everyone's
449
+ problem, so "arm nothing" was tolerating a mess rather than describing a clean
450
+ state. Since Phase B the unanswered spec sits on its own branch in its own
451
+ worktree, where it is in nothing's way: no release is blocked, no other spec has
452
+ to replay over it, and it is still exactly where it was tomorrow morning.
408
453
 
409
454
  ### The two endings this page offers
410
455
 
@@ -413,12 +458,46 @@ committing pair, because "commit and build the next phase" is meaningless for a
413
458
  spec with no phase in flight.
414
459
 
415
460
  - **`commit-start`** — hand off to `review.commitWith` (`/commit` by default),
416
- passing the pathspec the render reported on `docs.paths`, then run
417
- **`/spec-start <name>`** and **stop there**. It never completes, lands or tears
418
- anything down, exactly as `commit-continue` stops after `/spec-next`. This is
419
- the `commit && /spec-start` that was typed by hand.
420
- - **`commit`** — the same commit, then finish. The spec stays `Ready` in
421
- `backlog`, ready for a `/spec-start` whenever it is wanted.
461
+ passing the pathspec the render reported on `docs.paths`; **land it** (below);
462
+ then **keep the worktree** and run **`/spec-start <name>`**, and **stop there**.
463
+ It never completes or tears anything down, exactly as `commit-continue` stops
464
+ after `/spec-next`. This is the `commit && /spec-start` that was typed by hand.
465
+ - **`commit`** — the same commit and the same land, then
466
+ **tear the worktree down** and finish. The spec stays `Ready` in `backlog` —
467
+ on the base branch, where anyone can see it — ready for a `/spec-start`
468
+ whenever it is wanted.
469
+
470
+ **Both committing verdicts land, and that is what keeps the backlog findable.**
471
+ `ls specs/backlog/` is how specs are found, and a folder bucket is only the truth
472
+ on the branch you are standing on — so a spec left on its own branch would be
473
+ invisible to everyone, including the next `/spec` run. The commit goes on the
474
+ branch and then the branch goes onto the base:
475
+
476
+ ```
477
+ skitterspec spec-env integrate <name>
478
+ ```
479
+
480
+ It plans a rebase onto the base branch in the worktree, then a
481
+ `merge --ff-only` in the primary checkout — run the commands it prints. It
482
+ refuses on a dirty tree, which is correct here: the commit ran first, so anything
483
+ still uncommitted at this point is not this spec's and the land must not proceed.
484
+
485
+ **If the rebase conflicts, stop and say so.** It is unlikely on a
486
+ documents-only branch and not impossible — two specs authored at once can both
487
+ touch `specs/.core/`. Run `git rebase --abort`, leave the commit sitting on the
488
+ branch, and report `❌` with the conflict: there is a standing worktree to clear,
489
+ which is what separates `❌` from `⏸`. Never resolve someone else's conflict to
490
+ get the land through.
491
+
492
+ **The worktree lifetime follows the verdict, and the asymmetry is deliberate.**
493
+ `commit-start` keeps it because you are carrying straight on, and `/spec-start`
494
+ re-runs `up` over it without `--docs` — which is where the setup commands
495
+ Phase B skipped finally run. Plain `commit` tears it down with
496
+ `skitterspec spec-env down <name>`, because a spec parked in the backlog should
497
+ hold no worktree and no `node_modules`; `/spec-start` provisions from scratch
498
+ whenever it is wanted. Always-keep would leave five backlog specs holding five
499
+ checkouts, and always-teardown would have `commit-start` re-provision seconds
500
+ after destroying the tree it needed.
422
501
  - **`changes`** — work the notes into the spec, record a resolution for each one
423
502
  so the next render shows it struck through with what changed, then
424
503
  **re-render, and wait again**. The reader is still holding a decision, so
@@ -436,7 +515,9 @@ the verdict — and the reader's conclusion is about what the page showed them.
436
515
 
437
516
  1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
438
517
  the whole scope of what you may claim.
439
- 2. **Run the engine's wait in the background, and end your turn:**
518
+ 2. **Run the engine's wait, and end your turn** — under the harness's
519
+ persistent watch primitive where one exists, else in the background
520
+ (`.claude/rules/spec-reports.md` carries the preference):
440
521
 
441
522
  ```
442
523
  skitterspec spec-env review wait <spec> --since <the timestamp>
@@ -447,6 +528,11 @@ the verdict — and the reader's conclusion is about what the page showed them.
447
528
  verdict to a lunch break.
448
529
  3. **On waking, let the engine pick:**
449
530
 
531
+ **A watch that dies is re-armed on the same window**, silently and bounded by
532
+ the age of that window — `.claude/rules/spec-reports.md` carries the contract,
533
+ including when to stop and what the banner says instead. Do not restate it
534
+ here.
535
+
450
536
  ```
451
537
  skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json
452
538
  ```
@@ -588,15 +674,25 @@ the shape; this section carries only what is specific here.
588
674
 
589
675
  - `✅` — a `Ready` spec is written to `specs/backlog/<name>/`.
590
676
  - `⚠️` — written as `Draft`; open questions were deliberately left. Name them.
677
+ - `❌` — the spec was committed and the land failed part-way: the rebase
678
+ conflicted, or the fast-forward was refused. There is a standing worktree and a
679
+ branch to deal with, so say where both are.
591
680
  - `⏸` — grilling did not reach a shared understanding, so nothing was written.
592
681
  That is the skill working: a spec written over an unresolved requirement is
593
682
  the outcome Phase A exists to prevent.
594
683
 
595
- **Fields:** `Tracker` · `Spec` · `Built` · `Follow-ups` · `Next`
684
+ **Fields:** `Tracker` · `Spec` · `Built` · `Landed` · `Worktree` · `Follow-ups` ·
685
+ `Next`
596
686
 
597
687
  `Built` is the spec's path and phase count; `Spec` is its status and bucket;
598
688
  `Tracker` appears only when a provider is installed and linked it.
599
689
 
690
+ `Landed` and `Worktree` belong to the **verdict** half of the run and appear
691
+ only once one has been acted on — a run that is still waiting on the page has
692
+ neither. `Landed` says the base branch fast-forwarded and to what; `Worktree`
693
+ says kept (on `commit-start`) or removed (on `commit`), with the path. Neither
694
+ appears where isolation is off: nothing was provisioned and nothing was landed.
695
+
600
696
  **`Next` depends on whether Phase C2 rendered a page.** Where it did, the run is
601
697
  waiting on a verdict, so the block **omits the `Review` row** and ends on the
602
698
  banner defined in `.claude/rules/spec-reports.md` — counts, the tier stack, and
@@ -619,6 +715,11 @@ I'm holding here until you send a verdict — the wait covers local and network.
619
715
  There `Next` names the page rather than a command, because the button is what
620
716
  carries the work on.
621
717
 
718
+ **Neither exit leaves the spec anywhere awkward**, and the banner does not
719
+ explain that — the whole point of Phase B is that there is nothing to warn
720
+ about. Both buttons commit and land, so either way the spec reaches the base
721
+ branch as one commit; the only difference is whether the worktree stays.
722
+
622
723
  Where no page was rendered — isolation is not configured, or nothing was
623
724
  written — `Next` is `/spec-start <name>`, with the name spelled the way it must
624
725
  be typed.
@@ -508,13 +508,19 @@ skitterspec spec-env review arm <spec>
508
508
 
509
509
  **Then wait**, and `/spec-next` §5 owns the sequence — follow it there rather
510
510
  than reading a second copy here: note the moment, run
511
- `skitterspec spec-env review wait <spec> --since <that moment>` in the
512
- background, end your turn, and let `--claim-since` pick the one pass that
511
+ `skitterspec spec-env review wait <spec> --since <that moment>` under the
512
+ harness's persistent watch primitive where one exists (else in the
513
+ background), end your turn, and let `--claim-since` pick the one pass that
513
514
  arrived inside the window. **Do not compose a watcher**, and do not give the
514
515
  wait a timeout — the reasoning is in `/spec-next` §5 and is not repeated here.
515
516
  The banner it describes is what this skill emits in place of a `Review` row,
516
517
  and the routing on the verdict is `/spec-diff` §2 and §4, as it is everywhere.
517
518
 
519
+ **A watch that dies is re-armed on the same window**, silently and bounded by
520
+ the age of that window — `.claude/rules/spec-reports.md` carries the contract,
521
+ including when to stop and what the banner says instead. Do not restate it
522
+ here.
523
+
518
524
  **Why this skill arms as well as waits.** Waiting is what any offer does;
519
525
  **arming** asserts an obligation that outlives the turn, and belongs only to
520
526
  work that is finished. A bug fix is a completed unit — red→green, suite
@@ -158,6 +158,35 @@ of the work, so an unreclaimed one is worth a line rather than a silence.
158
158
  reclaim the cancelled spec's environment. On confirmation, run the `spec-env` CLI
159
159
  directly (the old `/spec-env-down` skill is gone — teardown is folded in here):
160
160
 
161
+ 0. **Name a pass still waiting for THIS spec — before anything is removed.**
162
+
163
+ ```
164
+ skitterspec spec-env review waiting --json
165
+ ```
166
+
167
+ Filter to the spec being cancelled and say nothing about any other: a run
168
+ reports itself and nothing else (`.claude/rules/spec-reports.md`). For each
169
+ one, give the code, the verdict and the age, then the two exits — claim it
170
+ now with `/spec-reviewed <code>` **while the worktree still stands**, or
171
+ disown it with `skitterspec spec-env review <spec> --drop <code>`.
172
+
173
+ **Why here and not anywhere else.** Nothing is about to become unreachable —
174
+ a pass can be disowned long after its spec is gone. What is about to pass is
175
+ the last moment the verdict can still be **honoured**: before teardown a
176
+ `commit` pass can be claimed and acted on, after it there is no branch left
177
+ to commit to and disowning is all that remains. On a cancelled spec that is
178
+ sharper still — the worktree may hold the only copy of the work, so a pass
179
+ approving it is the one thing that might argue for keeping it.
180
+
181
+ **It reports, and it never blocks.** No refusal, no confirmation of its own,
182
+ no non-zero exit — this step already asks before it reclaims anything, and a
183
+ waiting pass is information rather than a second gate.
184
+ And **it never claims** — reporting a pass is not taking one, and
185
+ `/spec-diff` §0 is untouched by this step.
186
+
187
+ Put what you found in the report's `Notes` row.
188
+ Silent when nothing is waiting, which is the usual case.
189
+
161
190
  1. If `.spec-env/connected` names this spec, run `skitterspec spec-env connect
162
191
  main` first to free the canonical ports.
163
192
  2. `skitterspec spec-env dev down <name>` — stop its host dev servers.
@@ -275,6 +275,31 @@ nothing left to protect.
275
275
  worktree and branch are being kept, and go straight to sub-step 4. Mention
276
276
  `skitterspec spec-env up <name>` re-attaches it later either way.
277
277
 
278
+ 0. **Name a pass still waiting for THIS spec — before anything is removed.**
279
+
280
+ ```
281
+ skitterspec spec-env review waiting --json
282
+ ```
283
+
284
+ Filter to the spec being completed and say nothing about any other: a run
285
+ reports itself and nothing else (`.claude/rules/spec-reports.md`). For each
286
+ one, give the code, the verdict and the age, then the two exits — claim it
287
+ now with `/spec-reviewed <code>` **while the worktree still stands**, or
288
+ disown it with `skitterspec spec-env review <spec> --drop <code>`.
289
+
290
+ **Why here and not anywhere else.** Nothing is about to become unreachable —
291
+ a pass can be disowned long after its spec is gone. What is about to pass is
292
+ the last moment the verdict can still be **honoured**: before teardown a
293
+ `commit` pass can be claimed and acted on, after it there is no branch left
294
+ to commit to and disowning is all that remains.
295
+
296
+ **It reports, and it never blocks.** No refusal, no confirmation of its own,
297
+ no non-zero exit. And **it never claims** — reporting a pass is not taking
298
+ one, and `/spec-diff` §0 is untouched by this step.
299
+
300
+ Put what you found in the report's `Notes` row.
301
+ Silent when nothing is waiting, which is the usual case.
302
+
278
303
  1. **Disconnect the proxy if this spec is connected.** If `.spec-env/connected`
279
304
  names this spec, run `skitterspec spec-env connect main` first so the
280
305
  canonical ports go back to the primary checkout.
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: spec-diff
3
- description: See what a spec's worktree changed — render its diff as a page you can mark up, take that review pass back, and act on it. Answers at any point, including half-way through a phase. Use when the user says "/spec-diff", "show me the diff", "what did this phase change", "review this spec's work", wants to read a worktree's changes away from the terminal, or hands back what the review page produced — a six-digit claim code, a bare verdict word, or the pasted JSON.
3
+ description: See what a spec's worktree changed — render its diff as a page you can mark up, take that review pass back, and act on it. Answers at any point, including half-way through a phase, and takes --reviewers to run the project's configured code reviewers. Use when the user says "/spec-diff", "show me the diff", "what did this phase change", "review this spec's work", "run the reviewers", or hands back what the review page produced — a six-digit claim code, a bare verdict word, or the pasted JSON.
4
4
  ---
5
5
 
6
6
  # /spec-diff — see the phase before you commit it
@@ -161,6 +161,13 @@ back, and these steps replace §3–§5 below.
161
161
  applies: it concluded nothing. Go to **§2b**. The engine refuses a pass
162
162
  carrying both, so there is never a choice to make between them.
163
163
 
164
+ **It is on the `claimed:` line** — `· action: live-on` at the end of it, and
165
+ `claimed.action` under `--json`. Read it there rather than inferring one
166
+ from a pass that merged nothing: a claim reporting no verdict and no counts
167
+ used to be the only trace a press left, which made every action look like a
168
+ reader who had concluded nothing. If the line carries no action, there was
169
+ none.
170
+
164
171
  3. **Say what you read, then ask what's up.** Report the accepted count, then
165
172
  each open comment as `file:line — note`, then the files you would touch.
166
173
  **Wait — unless the verdict already said otherwise.** Pasting on its own is
@@ -395,6 +402,14 @@ way out. **Never park another spec's live session** to make room — that is
395
402
  someone else's work, and freeing it is their decision. Re-render and wait, so
396
403
  the reader can choose something else.
397
404
 
405
+ **A refusal may declare the way out of itself.** Ask with
406
+ `skitterspec spec-env live take <spec> --json` and read its `offer` field:
407
+ where one is present, relay the refusal and **then** offer it, exactly as
408
+ `.claude/rules/offered-unblocks.md` describes. Do not re-decide from the reason
409
+ text, and do not infer an offer that is not there — the boundary that keeps
410
+ another spec's workbench out of this lives in that field rather than in prose
411
+ here.
412
+
398
413
  **`allow` writes a committed file, and that is worth a sentence.** It edits
399
414
  `specs/.core/env.config.json` in the **primary checkout**, so it changes
400
415
  behaviour for everyone who pulls and leaves that tree dirty — unlike the live
@@ -437,9 +452,26 @@ help someone give one.
437
452
  ```
438
453
  skitterspec spec-env review <spec> # uncommitted work (the default)
439
454
  skitterspec spec-env review <spec> --branch # everything since the base branch
455
+ skitterspec spec-env review <spec> --run-reviewers # …and run review.reviewers
440
456
  skitterspec spec-env review serve # every spec, on localhost
441
457
  ```
442
458
 
459
+ **`--run-reviewers` is opt-in here, and a BARE `/spec-diff` MUST NOT PASS IT.**
460
+ `/spec-next` runs the project's configured reviewers once per phase, where the
461
+ cost is paid against work that is finished. This skill answers at any point,
462
+ including several times in one phase — and each run spends a review against
463
+ whatever hourly limit the reviewer has, which on the tiers this was built for is
464
+ measured in single figures.
465
+
466
+ So pass it when the operator asked for it: `/spec-diff --reviewers`, or they said
467
+ in words that they want the second opinion. Otherwise render without it. The
468
+ cached findings from the phase-end run still show on the page whenever the diff
469
+ has not moved, so the usual mid-phase read loses nothing by not asking.
470
+
471
+ Where it does run, say what it cost — a reviewer takes 30s–3min — and nothing
472
+ else. The page's own strip reports each reviewer's outcome, and a reviewer that
473
+ could not run is that strip's business rather than yours.
474
+
443
475
  **There is no switch left to handle.** The engine serves and prints a **stack** —
444
476
  one line per tier, `local`, `network`, `remote`, each either a URL or the one
445
477
  command that turns it on. All of it is free and none of it publishes anything.
@@ -582,7 +614,9 @@ already arrived. Those get the `Review` row, no question, and nothing is owed.
582
614
 
583
615
  1. **Note the moment**, as an ISO timestamp, before you start. That instant is
584
616
  the entire scope of what may be claimed without a person naming it.
585
- 2. **Run the engine's wait in the background, and end the turn:**
617
+ 2. **Run the engine's wait, and end your turn** — under the harness's
618
+ persistent watch primitive where one exists, else in the background
619
+ (`.claude/rules/spec-reports.md` carries the preference):
586
620
 
587
621
  ```
588
622
  skitterspec spec-env review wait <spec> --since <timestamp>
@@ -27,8 +27,10 @@ clobber customised content. Finish with a summary of created vs already-present.
27
27
  > **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
28
28
  > `--reset` (reset needs `--yes`) drive the stronger actions.
29
29
 
30
- The system is **twelve skills**: `spec` (feature), `spec-bug` (bug),
31
- `spec-hotfix` (a bug fixed on a released tag), `spec-review`, `spec-start`,
30
+ The system is **thirteen skills**: `spec` (feature), `spec-bug` (bug),
31
+ `spec-hotfix` (a bug fixed on a released tag),
32
+ `no-spec` (work that genuinely has none — off the base branch all the same),
33
+ `spec-review`, `spec-start`,
32
34
  `spec-next`, `spec-diff` (read a spec's diff as a page),
33
35
  `spec-reviewed` (pick up a review you approved on that page), `spec-to-main`,
34
36
  `spec-complete`, `spec-cancel`, and this `spec-init`. The lifecycle is `backlog → in-progress → complete / cancelled`,
@@ -148,6 +148,12 @@ 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
@@ -334,13 +340,34 @@ the moment the page is about, so render it now — **after** the tests pass and
334
340
  **before** the commit:
335
341
 
336
342
  ```
337
- skitterspec spec-env review <spec>
343
+ skitterspec spec-env review <spec> --run-reviewers
338
344
  ```
339
345
 
340
346
  **This is free.** It is the engine reading git and splicing text into a template;
341
347
  the diff never passes through you, so a 266KB patch costs nothing. Report the
342
348
  path it prints and move on.
343
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
+
344
371
  **This render takes the committing button set**, which is the default — so
345
372
  `--buttons` is not passed. That is a statement about the work, not about the
346
373
  gate: the phase is finished, so `Commit` and `Commit & Continue` are the right
@@ -369,7 +396,7 @@ so one subject lives in one place:
369
396
 
370
397
  ---
371
398
 
372
- ## ⏸ Review ready — <N> files, +<a> −<d>
399
+ ## ⏸ Review ready — <N> files, +<a> −<d><, <n> flagged by <reviewer> — only where one found something>
373
400
 
374
401
  - **local** — <the `local:` URL>
375
402
  - **network** — <the `network:` URL, or off with the command that turns it on>
@@ -381,6 +408,19 @@ I'm holding here until you send a verdict — the wait covers local and network.
381
408
 
382
409
  `/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
383
410
 
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
+
384
424
  **The stack is the engine's — copy it, do not compose it.** `spec-env review`
385
425
  printed one line per tier, in that order, and `--json` carries the same thing as
386
426
  `tiers`. Relay all three whatever they say, including the ones that are off with
@@ -450,7 +490,9 @@ reading — and that is the gap the whole gate exists to close.
450
490
 
451
491
  1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
452
492
  the whole scope of what you may claim.
453
- 2. **Run the engine's wait in the background, and end your turn:**
493
+ 2. **Run the engine's wait, and end your turn** — under the harness's
494
+ persistent watch primitive where one exists, else in the background
495
+ (`.claude/rules/spec-reports.md` carries the preference):
454
496
 
455
497
  ```
456
498
  skitterspec spec-env review wait <spec> --since <the timestamp>
@@ -462,6 +504,11 @@ reading — and that is the gap the whole gate exists to close.
462
504
  a diff is the normal case rather than the edge one. Do not give it a duration
463
505
  of your own.
464
506
 
507
+ **A watch that dies is re-armed on the same window**, silently and bounded by
508
+ the age of that window — `.claude/rules/spec-reports.md` carries the contract,
509
+ including when to stop and what the banner says instead. Do not restate it
510
+ here.
511
+
465
512
  Then **end your turn**. Do not poll it and do not hold the turn open: the
466
513
  point is that the reader has the terminal back while they read.
467
514
  3. **On waking, let the engine pick**:
@@ -82,9 +82,9 @@ A **six-digit code** is a pass the operator read off their own page. It says
82
82
  invocation does, above, and claim the code *there*. Then go to step 4 — a named
83
83
  pass has nothing to disambiguate.
84
84
 
85
- A **verdict word** — `commit`, `commit-continue`, `commit-start`, `continue`,
86
- `changes`, `discuss` — is the conclusion itself, arriving without a pass behind
87
- it. It is
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
88
  what a **`file://` page** hands over: that page has no server to POST to and no
89
89
  store to write to, so it copies a command instead of sending anything, and this
90
90
  is the command. Resolve the spec as a bare invocation does, then send the word
@@ -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.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "17.0.0",
3
+ "version": "17.2.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",