@skitterbyte/skitterspec-jira 2.15.0 → 2.17.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 +27 -0
- package/assets/claude-md-section.md +18 -9
- package/assets/commands/allow-main.md +1 -2
- package/assets/core/SETUP.md +12 -12
- package/assets/core/env.config.json.example +0 -1
- package/assets/core/env.config.md +28 -26
- package/assets/hooks/main-guard.cjs +73 -6
- package/assets/hooks/project-guard.cjs +80 -6
- package/assets/hooks/review-gate.cjs +73 -6
- package/assets/review/page.html +10 -83
- package/assets/rules/commit-trailers.md +2 -2
- package/assets/rules/spec-planning.md +26 -22
- package/assets/rules/spec-reports.md +52 -52
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +22 -5
- package/assets/skills/spec-bug/SKILL.md +18 -15
- package/assets/skills/spec-complete/SKILL.md +23 -1
- package/assets/skills/spec-diff/SKILL.md +47 -115
- package/assets/skills/spec-hotfix/SKILL.md +18 -15
- package/assets/skills/spec-init/SKILL.md +4 -2
- package/assets/skills/spec-next/SKILL.md +66 -41
- package/assets/skills/spec-park/SKILL.md +92 -0
- package/assets/skills/spec-resume/SKILL.md +153 -0
- package/assets/skills/spec-review/SKILL.md +2 -2
- package/assets/skills/spec-reviewed/SKILL.md +1 -8
- package/assets/skills/spec-sync/SKILL.md +10 -10
- package/assets/skills/spec-todo/SKILL.md +5 -2
- package/package.json +1 -1
- package/src/cli.js +361 -208
- package/src/env/bootstrap.js +3 -1
- package/src/env/checks.js +49 -0
- package/src/env/config.js +27 -7
- package/src/env/hooks.js +53 -4
- package/src/env/live.js +48 -0
- package/src/env/provision.js +10 -2
- package/src/env/resume.js +234 -0
- package/src/env/review.js +71 -173
- package/src/env/serve.js +3 -7
- package/src/init.js +383 -50
- package/src/tada/todo.js +19 -4
- package/src/vendor/provider-kit/src/specs.js +46 -1
- package/src/vendor/sync-core/src/summary.js +10 -1
- package/assets/commands/spec-remote-review.md +0 -37
|
@@ -35,11 +35,32 @@ Before marking complete, confirm the work is actually finished:
|
|
|
35
35
|
- If genuinely incomplete work remains, **stop and tell the user** rather than
|
|
36
36
|
forcing completion. Offer to finish it (`/spec-next`) or to complete with the
|
|
37
37
|
remaining items explicitly listed as deferred.
|
|
38
|
+
- **Report any blocker still standing; never refuse over one.** Run
|
|
39
|
+
`skitterspec spec-env resume <spec> --json` and read `blockers`. Each
|
|
40
|
+
`> **Blocked on:**` line still in the spec goes in the report's `Notes`,
|
|
41
|
+
quoted with its `until` date where it has one. A spec can finish with a wait
|
|
42
|
+
still written down: the soak may have been dropped, or the deploy may have
|
|
43
|
+
happened without anyone saying so. The line staying in the completed spec is
|
|
44
|
+
the record of that, and nothing is gated on it. With none, say nothing.
|
|
38
45
|
- **Check for pre-existing uncommitted changes — before you touch anything.**
|
|
39
46
|
Run `git status`. Anything already uncommitted is the *user's* work (a
|
|
40
47
|
half-finished phase, a stray fix) and must not be swept into the completion
|
|
41
48
|
commit: offer `/commit` and **stop**. Everything this skill writes in steps 3–4
|
|
42
49
|
is its own, and step 4 commits that.
|
|
50
|
+
- **Run the project's completion checks**, once the suite is green:
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
skitterspec spec-env checks <spec>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
It runs each `complete.checks` command from `env.config.json` in the spec's
|
|
57
|
+
worktree — the project's own end-of-spec questions, such as a docs report —
|
|
58
|
+
and always exits 0. Relay what each printed into `Notes`. A check marked
|
|
59
|
+
`failed` makes the run `⚠️`; it **never stops the completion or the land**,
|
|
60
|
+
because a check's output is a reason to look again, not proof of a fault.
|
|
61
|
+
Where a check names a fix you can make now (re-read a page, then record it),
|
|
62
|
+
offer it — the operator answers. `no completion checks configured` is the
|
|
63
|
+
usual answer and says nothing in the report.
|
|
43
64
|
|
|
44
65
|
|
|
45
66
|
### An epic — complete after its members
|
|
@@ -274,7 +295,8 @@ the shape; this section carries only what is specific here.
|
|
|
274
295
|
|
|
275
296
|
`Notes` carries the after-land commands step 6 ran, and where, and any it
|
|
276
297
|
skipped because the land matched no `when` — or, on a failure, the command that failed and the ones that did not run. A project with
|
|
277
|
-
no `afterLand` says nothing about it.
|
|
298
|
+
no `afterLand` says nothing about it. It also carries what each completion
|
|
299
|
+
check reported (§2) — a project with none says nothing about them either.
|
|
278
300
|
|
|
279
301
|
**Report this spec and no other.** A completion is the moment it is most
|
|
280
302
|
tempting to survey what is left — what else is in flight, what is in the
|
|
@@ -14,11 +14,11 @@ A phase is built in its own worktree, and the terminal is somewhere else — so
|
|
|
14
14
|
`git diff` answers about the wrong branch and a 350-line diff read as terminal
|
|
15
15
|
text is scrolling, not review. This renders the diff as a page instead: the
|
|
16
16
|
engine collects it with `git -C`, writes a self-contained HTML file, and you open
|
|
17
|
-
it locally or
|
|
17
|
+
it locally, or on a phone over your LAN or tailnet.
|
|
18
18
|
|
|
19
19
|
**The diff never passes through the model.** git writes the patches and the
|
|
20
20
|
engine splices them into the page. A 266KB patch costs **zero** context tokens,
|
|
21
|
-
and a 289KB page costs the same to
|
|
21
|
+
and a 289KB page costs the same to serve as a 5KB one. Do not "simplify" this
|
|
22
22
|
by reading the diff and emitting HTML — that is the one change that would undo
|
|
23
23
|
the whole design.
|
|
24
24
|
|
|
@@ -354,8 +354,8 @@ spend it.
|
|
|
354
354
|
|
|
355
355
|
## 2b. An action changes something, then hands the page back
|
|
356
356
|
|
|
357
|
-
Only on a pass carrying an **action**.
|
|
358
|
-
**
|
|
357
|
+
Only on a pass carrying an **action**. Two of them, and
|
|
358
|
+
**both end the same way**:
|
|
359
359
|
do the thing, re-render (§4), and wait again (§4b) — because the reader
|
|
360
360
|
still has a decision in front of them and has not made it.
|
|
361
361
|
|
|
@@ -363,7 +363,11 @@ still has a decision in front of them and has not made it.
|
|
|
363
363
|
|--------|----|------|
|
|
364
364
|
| `live-on` | commit first (below), then `skitterspec spec-env live take <spec>` | re-render `--branch`, wait again |
|
|
365
365
|
| `allow-network` | `skitterspec spec-env review allow network` | re-render, wait again |
|
|
366
|
-
|
|
366
|
+
|
|
367
|
+
**There is no `allow-remote` either.** It permitted publishing the page as a
|
|
368
|
+
claude.ai artifact, and that tier was retired (feat-tailnet-remote-tier):
|
|
369
|
+
`remote` is the tailnet address now, on `network`'s switch, so `allow-network`
|
|
370
|
+
turns both on.
|
|
367
371
|
|
|
368
372
|
**THERE IS NO `live-off`, and its absence is deliberate.** Putting *this* change
|
|
369
373
|
live is about the diff on screen; handing the whole instance back to `main` is a
|
|
@@ -371,7 +375,7 @@ workspace decision with nothing to do with this review. The `live:` line names
|
|
|
371
375
|
`/spec-live main` for it — a command the operator types, which is also why no
|
|
372
376
|
skill runs it.
|
|
373
377
|
|
|
374
|
-
**AN ACTION IS NOT A VERDICT, and the gate is untouched by
|
|
378
|
+
**AN ACTION IS NOT A VERDICT, and the gate is untouched by both.** A phase
|
|
375
379
|
that ended armed the gate, and it is discharged by a committing verdict or a
|
|
376
380
|
recorded skip and by nothing else — so after any of these the phase still owes
|
|
377
381
|
an answer, and that is exactly why the run waits again rather than finishing.
|
|
@@ -425,17 +429,9 @@ edits `specs/.core/env.config.json` in the **primary checkout**, so it changes
|
|
|
425
429
|
behaviour for everyone who pulls and leaves that tree dirty — one server binds
|
|
426
430
|
for every spec, so the bind cannot be narrower. The engine prints the absolute
|
|
427
431
|
path; relay that rather than letting a shared setting change land silently.
|
|
428
|
-
|
|
429
|
-
|
|
430
|
-
|
|
431
|
-
over the network kills the page doing the turning.
|
|
432
|
-
|
|
433
|
-
**`allow remote` permits publishing. It does not publish by itself.**
|
|
434
|
-
Publishing stays an explicit ask (§6), because the page it leaves behind is one
|
|
435
|
-
this tooling cannot remove. A reader who presses `Allow remote` on the page, or
|
|
436
|
-
types `/spec-remote-review` beside a waiting review, **has** asked: the engine
|
|
437
|
-
names the page on its `review:`/`publish:` lines, and that page is published
|
|
438
|
-
and the stack re-shown. Nothing it does not name is published.
|
|
432
|
+
And it is **enable-only**: there is no action that turns a tier off, because
|
|
433
|
+
turning `network` off from a page reached over the network kills the page doing
|
|
434
|
+
the turning.
|
|
439
435
|
|
|
440
436
|
## 3. Gate it on nothing
|
|
441
437
|
|
|
@@ -493,7 +489,7 @@ could not run is that strip's business rather than yours.
|
|
|
493
489
|
|
|
494
490
|
**There is no switch left to handle.** The engine serves and prints a **stack** —
|
|
495
491
|
one line per tier, `local`, `network`, `remote`, each either a URL or the one
|
|
496
|
-
command that turns it on. All of it is free and
|
|
492
|
+
command that turns it on. All of it is free, and all of it is one server.
|
|
497
493
|
You are not choosing between them; you are relaying every line it printed.
|
|
498
494
|
`.claude/rules/spec-reports.md` carries the shape and why.
|
|
499
495
|
|
|
@@ -564,7 +560,7 @@ says:
|
|
|
564
560
|
|------|---------|
|
|
565
561
|
| `local` | the loopback URL — or the `file://` page when nothing served, which says it cannot send a verdict |
|
|
566
562
|
| `network` | the LAN URL and any `also:` alternates under it — or `off` with the command that turns it on |
|
|
567
|
-
| `remote` | the
|
|
563
|
+
| `remote` | the tailnet URL, labelled `(tailnet)` — or `off` with `network`'s command, or `no tailnet address on this machine` |
|
|
568
564
|
|
|
569
565
|
**The `reader:` line decides nothing here any more.** It is still printed and
|
|
570
566
|
still the only place that question is answered, but the offer no longer branches
|
|
@@ -581,23 +577,20 @@ tested and would drift. The ranking and the traps
|
|
|
581
577
|
a tty under Claude Code) live in `review.js` beside the code, which is where they
|
|
582
578
|
belong.
|
|
583
579
|
|
|
584
|
-
**It authorises serving,
|
|
585
|
-
local server — one process, ended by one flag, leaving nothing
|
|
586
|
-
|
|
587
|
-
|
|
588
|
-
|
|
589
|
-
`specs/complete/bug-remote-reader-gets-a-dead-link/`.
|
|
580
|
+
**It authorises serving, and serving is all there is.** A `remote` reader
|
|
581
|
+
authorises a local server — one process, ended by one flag, leaving nothing
|
|
582
|
+
behind. Publishing the page was once a second answer and was retired with the
|
|
583
|
+
published tier (feat-tailnet-remote-tier): the tailnet reaches a reader off the
|
|
584
|
+
wifi without a page this tooling could never remove.
|
|
590
585
|
|
|
591
586
|
When serving fails — a busy port, or a machine with no network address — the
|
|
592
|
-
engine falls back to the `file://` URL with its marker and nothing breaks.
|
|
593
|
-
is the one case where naming publishing is worth doing, because it is the only
|
|
594
|
-
answer left.
|
|
587
|
+
engine falls back to the `file://` URL with its marker and nothing breaks.
|
|
595
588
|
|
|
596
589
|
`review.reader` in `env.config.json` (`local` · `remote` · `detect`) lets the
|
|
597
590
|
operator settle where they are reading, and an explicit value is believed without
|
|
598
591
|
sniffing. What the engine may *do* is settled by the tier settings instead —
|
|
599
|
-
`review.serve` (`always` · `never`)
|
|
600
|
-
|
|
592
|
+
`review.serve` (`always` · `never`) and `review.allowNetwork` — not by the
|
|
593
|
+
reader.
|
|
601
594
|
|
|
602
595
|
## 4b. Wait for the verdict — because asking for one means waiting for it
|
|
603
596
|
|
|
@@ -623,9 +616,6 @@ transport only decides what carries the answer back:
|
|
|
623
616
|
- **A `file://` page** has nothing to post to, so the reader pastes the pass and
|
|
624
617
|
their next message carries it. Say you are holding and **end the turn** — that
|
|
625
618
|
is the same wait, carried by the conversation. It is not a lesser one.
|
|
626
|
-
- **A published page** writes to the artifact's own store, which nothing reaches
|
|
627
|
-
from here. That is the one case where the honest sentence is *press a verdict,
|
|
628
|
-
then type `/spec-reviewed`* — see the published-page paragraph below.
|
|
629
619
|
|
|
630
620
|
**Do not ask, and therefore do not wait, on a render nobody is waiting behind** —
|
|
631
621
|
a bare `--page-only`, a page produced alongside other work, a pass that has
|
|
@@ -673,18 +663,15 @@ the stranger's pass the old rule was written about, and two arrivals refuse
|
|
|
673
663
|
rather than pick. What is left of the old rule is unchanged and still absolute —
|
|
674
664
|
outside this window, a pass is claimed because a person named it.
|
|
675
665
|
|
|
676
|
-
**The wait covers
|
|
677
|
-
|
|
678
|
-
|
|
679
|
-
|
|
680
|
-
|
|
681
|
-
notice, and it was made three times in a row while three verdicts sat unread.
|
|
682
|
-
Where the page is published, say plainly that `/spec-reviewed` is what picks it
|
|
683
|
-
up.
|
|
666
|
+
**The wait covers every served door.** It watches the engine's local store,
|
|
667
|
+
which is where a served page POSTs — from `local`, `network` or `remote` alike,
|
|
668
|
+
since all three are the same server. A published page once wrote to a store no
|
|
669
|
+
watch reached, and three verdicts sat unread under a line claiming the run was
|
|
670
|
+
waiting; that is why the published tier was retired rather than caveated.
|
|
684
671
|
|
|
685
672
|
**`/spec-reviewed` is not replaced by this.** It stays the way in for a pass
|
|
686
|
-
that arrived when nobody was waiting, for the two-passes case
|
|
687
|
-
|
|
673
|
+
that arrived when nobody was waiting, and for the two-passes case. It is
|
|
674
|
+
user-only, and that is still the
|
|
688
675
|
enforcement that makes a named claim a person's decision.
|
|
689
676
|
|
|
690
677
|
**A harness with no file-watch is no longer on that list**, and that is the
|
|
@@ -743,78 +730,23 @@ Then re-render with it spliced in — the engine renders it, you never emit HTML
|
|
|
743
730
|
skitterspec spec-env review <spec> --review <file>
|
|
744
731
|
```
|
|
745
732
|
|
|
746
|
-
## 6.
|
|
747
|
-
|
|
748
|
-
**
|
|
749
|
-
|
|
750
|
-
|
|
751
|
-
|
|
752
|
-
|
|
753
|
-
|
|
754
|
-
|
|
755
|
-
|
|
756
|
-
|
|
757
|
-
|
|
758
|
-
|
|
759
|
-
|
|
760
|
-
|
|
761
|
-
|
|
762
|
-
|
|
763
|
-
decision is being made, so it is the moment worth saying it — `spec-env down`
|
|
764
|
-
repeats it at teardown, by which point the page has outlived the spec.
|
|
765
|
-
- **Degrade in one line.** If the harness cannot publish — no capability, an
|
|
766
|
-
error — say so, report the local file path, and carry on. That is a working
|
|
767
|
-
outcome, not a failure.
|
|
768
|
-
- **Reach for `--publish-copy`, never a hand transform.** The engine writes the
|
|
769
|
-
page as a complete HTML document and an artifact host wraps page *content*, so
|
|
770
|
-
publishing the page as-written nests two documents. `spec-env review <spec>
|
|
771
|
-
--publish-copy` emits the body-only copy and names its path on a `publish:`
|
|
772
|
-
line. Do not split the document yourself: a rendered page contains the diff,
|
|
773
|
-
and a diff of this project contains `<!doctype html>` as ordinary patch text.
|
|
774
|
-
|
|
775
|
-
The engine knows nothing about publishing and cannot do it. It writes a file and
|
|
776
|
-
reads a URL back as an opaque string; everything about what that string means
|
|
777
|
-
lives here.
|
|
778
|
-
|
|
779
|
-
### Publish it so the buttons still work
|
|
780
|
-
|
|
781
|
-
A published page is the answer for a reader **no local server can reach** — a
|
|
782
|
-
phone on mobile data, anyone away from the LAN the engine serves on. It is also
|
|
783
|
-
the one surface where the verdict buttons have nowhere to POST: the page's own
|
|
784
|
-
URL is on claude.ai, so a POST fails and the reader gets "could not reach the
|
|
785
|
-
server" after pressing a verdict they meant.
|
|
786
|
-
|
|
787
|
-
So **publish it with a store**, and the page uses it:
|
|
788
|
-
|
|
789
|
-
- Declare `capabilities: {db: {}}`. The page checks for `window.claude.use` and
|
|
790
|
-
writes the pass into the artifact's own `passes` collection instead of
|
|
791
|
-
POSTing. Nothing else about it changes — same marks, same verdicts, same
|
|
792
|
-
refusal to commit over an open comment.
|
|
793
|
-
- **Do not declare `user`.** The pass is not per-viewer private state, a shared
|
|
794
|
-
collection is what it wants, and a declaration nothing uses is a grant asked
|
|
795
|
-
for nothing.
|
|
796
|
-
- **Same file path every time**, so a redeploy reuses the URL. That is what
|
|
797
|
-
answers the clear-down worry: one page per spec, replaced at each render,
|
|
798
|
-
rather than an artifact per phase accumulating in the gallery.
|
|
799
|
-
- **Send a push notification with the URL** when you publish. The reader is by
|
|
800
|
-
definition somewhere else — that is why it was published.
|
|
801
|
-
|
|
802
|
-
### Taking a stored pass back
|
|
803
|
-
|
|
804
|
-
A pass in the store is claimed the same way in spirit and a different way in
|
|
805
|
-
mechanism, because the engine cannot see it:
|
|
806
|
-
|
|
807
|
-
1. Read the `passes` collection with the Artifact tool's `read_db`.
|
|
808
|
-
2. **Apply step 0 unchanged.** One waiting pass, offered by what it says and
|
|
809
|
-
when it was sent; two is a refusal to guess. Nothing here is automatic —
|
|
810
|
-
there is no wait window on this transport, because nothing pushes from the
|
|
811
|
-
store to this conversation.
|
|
812
|
-
3. Write the pass's `blob` to a scratch file **verbatim** and merge it with
|
|
813
|
-
`spec-env review <spec> --notes <file>`. It rejoins the ordinary path at §2
|
|
814
|
-
step 1, so the verdict is judged and routed exactly as any other.
|
|
815
|
-
4. **Delete the document** with `write_db` once it is merged. A claim consumes:
|
|
816
|
-
a pass left in the store is claimable twice, which is the one property the
|
|
817
|
-
six-digit code has always had and this transport must not lose.
|
|
733
|
+
## 6. There is no publishing
|
|
734
|
+
|
|
735
|
+
**This skill does not publish the page, and nothing in this workflow does.**
|
|
736
|
+
Publishing it as a claude.ai artifact was retired with the published tier
|
|
737
|
+
(feat-tailnet-remote-tier). It wrote to a store no wait could watch, and left a
|
|
738
|
+
page this tooling could never remove. A reader off the wifi opens the `remote`
|
|
739
|
+
line — the review server's tailnet address — and sends the verdict into the
|
|
740
|
+
same store as every other door.
|
|
741
|
+
|
|
742
|
+
**Where no door reaches the reader** — no network, no tailnet, a server that
|
|
743
|
+
could not start — say so plainly with the stack the engine printed, and stop.
|
|
744
|
+
Do not reach for the Artifact tool as a fallback: that is the second store this
|
|
745
|
+
design removed.
|
|
746
|
+
|
|
747
|
+
A page published before this change still exists, and teardown still names it
|
|
748
|
+
(`spec-env down` reads the `.url` sidecar it left). Nothing writes that sidecar
|
|
749
|
+
any more.
|
|
818
750
|
|
|
819
751
|
## 7. Report
|
|
820
752
|
|
|
@@ -42,8 +42,14 @@ Then:
|
|
|
42
42
|
|
|
43
43
|
1. **Exclude what's already adopted.** Run `skitterspec spec-sync linked --json`
|
|
44
44
|
and drop any issue whose identifier is already stamped on a spec. If the user
|
|
45
|
-
named such an issue directly,
|
|
46
|
-
|
|
45
|
+
named such an issue directly, it already has a spec, and one issue never
|
|
46
|
+
becomes two specs. **Offer `/spec-resume <ref>`** instead, carrying the rest
|
|
47
|
+
of what they wrote as its message: feedback on shipped work, or "the deploy
|
|
48
|
+
is out", belongs to the spec that is already in flight. Confirm it, as kind
|
|
49
|
+
routing does (`.claude/rules/spec-planning.md`), and invoke it in-session on
|
|
50
|
+
a yes. On a no, stop and name the spec. That spec may exist only on its
|
|
51
|
+
branch, which `linked` reads too, so a missing `specs/` folder here is not
|
|
52
|
+
evidence that the issue is free.
|
|
47
53
|
2. **Read the issue** with the discovered issue-read tool (`getJiraIssue`):
|
|
48
54
|
title, description, labels, reporter, URL. If Jira isn't connected, say so
|
|
49
55
|
and offer to carry on without it — a spec written from the user's own
|
|
@@ -587,10 +593,9 @@ line with it where the engine printed one, and nothing where it did not.
|
|
|
587
593
|
`.claude/rules/spec-reports.md` carries the shape, including why a rigid
|
|
588
594
|
contract took that line.
|
|
589
595
|
|
|
590
|
-
- **Never write the review unasked**, and **never publish
|
|
591
|
-
|
|
592
|
-
|
|
593
|
-
`/spec-diff` §6 owns how.
|
|
596
|
+
- **Never write the review unasked**, and **never publish** — there is no
|
|
597
|
+
publishing (`/spec-diff` §6). A `file://` link is no use on a phone, and the
|
|
598
|
+
stack says why nothing was served.
|
|
594
599
|
**The `reader:` line no longer decides anything here, and that is the point.**
|
|
595
600
|
It is still printed, and it is still the only place that question is answered —
|
|
596
601
|
but the offer does not change with it, because the stack lists every tier
|
|
@@ -600,22 +605,20 @@ that branching is exactly what produced a `file://` page on a session detected
|
|
|
600
605
|
underneath a reader when detection flipped mid-session.
|
|
601
606
|
|
|
602
607
|
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
603
|
-
|
|
604
|
-
|
|
605
|
-
|
|
606
|
-
|
|
608
|
+
their tier — the other addresses this machine has of that kind — so pass them
|
|
609
|
+
on rather than editing them out: in the banner they are indented sub-bullets
|
|
610
|
+
under that tier, labels included, exactly as `.claude/rules/spec-reports.md`
|
|
611
|
+
shows.
|
|
607
612
|
|
|
608
613
|
**Never read an environment variable to decide anything about the offer** — not
|
|
609
614
|
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
610
615
|
here for a detection to decide, and a second implementation of one could not be
|
|
611
616
|
tested and would drift.
|
|
612
617
|
|
|
613
|
-
**Serving is the engine's to do
|
|
618
|
+
**Serving is the engine's to do, and there is nothing else.** A `remote` reader
|
|
614
619
|
authorises a local server — one process, ended by one flag, leaving nothing
|
|
615
|
-
behind
|
|
616
|
-
|
|
617
|
-
serve (a busy port, a machine with no network address) it falls back to the
|
|
618
|
-
`file://` URL with its marker, and that is when publishing is worth naming.
|
|
620
|
+
behind. If the engine could not serve (a busy port, a machine with no network
|
|
621
|
+
address) it falls back to the `file://` URL with its marker.
|
|
619
622
|
|
|
620
623
|
- **Never fatal.** A failed render — no worktree, a git error — is one line, and
|
|
621
624
|
the fix is still done. The page is a convenience; the repo is the record.
|
|
@@ -27,14 +27,16 @@ 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 **
|
|
30
|
+
The system is **twenty skills**: `spec` (feature, chore or issue), `spec-bug` (bug),
|
|
31
31
|
`spec-hotfix` (a bug fixed on a released tag),
|
|
32
32
|
`spec-incident` (a live outage, recorded as it happens),
|
|
33
33
|
`no-spec` (work that genuinely has none — off the base branch all the same),
|
|
34
34
|
`spec-review`, `spec-start`,
|
|
35
35
|
`spec-next`, `spec-diff` (read a spec's diff as a page),
|
|
36
36
|
`spec-reviewed` (pick up a review you approved on that page),
|
|
37
|
-
`spec-epic-next` (name the epic member that can start now),
|
|
37
|
+
`spec-epic-next` (name the epic member that can start now),
|
|
38
|
+
`spec-resume` (back into a spec in flight, by name or ticket),
|
|
39
|
+
`spec-park` (record what a spec in flight is waiting on), `spec-to-main`,
|
|
38
40
|
`spec-complete`, `spec-cancel`, `spec-tada` (a ta-da list of what got done),
|
|
39
41
|
`spec-todo` (where you left off, and what is ahead), `spec-idea` (an idea
|
|
40
42
|
parked without a spec),
|
|
@@ -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
|
|
@@ -215,6 +233,24 @@ once at the start, so each phase is asked as it is built.
|
|
|
215
233
|
not matter for this phase, and the bypass is that knowledge on the record. What
|
|
216
234
|
it rules out is the silent build.
|
|
217
235
|
|
|
236
|
+
**Then ask whether the spec is parked.** Run
|
|
237
|
+
`skitterspec spec-env resume <spec> --json` and read `blocking`. It is the
|
|
238
|
+
`> **Blocked on:**` line that holds this build: the spec's own line, or this
|
|
239
|
+
phase's. A line on a later phase is not this build's business, and the engine
|
|
240
|
+
leaves it out.
|
|
241
|
+
|
|
242
|
+
- **`blocking: null`**: carry on in silence. This is the usual case.
|
|
243
|
+
- **Anything else**: stop with the `⏸` block before marking anything started.
|
|
244
|
+
`Why` quotes the blocker, with its `until` date where it has one. `Next` is
|
|
245
|
+
`/spec-resume <spec> <what happened>`, which is the exit. It hears that the
|
|
246
|
+
condition is met, clears the line on the record, and builds.
|
|
247
|
+
|
|
248
|
+
**No bypass is offered here, and none is needed.** Unlike an epic wait, a
|
|
249
|
+
blocker is a condition only a person can judge (a deploy, another project's
|
|
250
|
+
release, a week in prod), so the person who knows it is met says so to
|
|
251
|
+
`/spec-resume`, and that clears it with a Changelog line. A build past one
|
|
252
|
+
without a word would be exactly the silent step this check exists to stop.
|
|
253
|
+
|
|
218
254
|
Mark it started: set the phase-file heading to `🔄` and its `> **Status:**` to
|
|
219
255
|
`In progress`, and flip the matching row in the overview phase index to `🔄`.
|
|
220
256
|
|
|
@@ -464,11 +500,11 @@ so one subject lives in one place:
|
|
|
464
500
|
|
|
465
501
|
- **local** — <the `local:` URL>
|
|
466
502
|
- **network** — <the `network:` URL, or off with the command that turns it on>
|
|
467
|
-
- **remote** — <the `remote:` URL, or
|
|
503
|
+
- **remote** — <the `remote:` tailnet URL, or what that line says when there is none>
|
|
468
504
|
|
|
469
505
|
<the `live:` line, exactly as the engine printed it — omitted when it printed none>
|
|
470
506
|
|
|
471
|
-
I'm holding here until you send a verdict — the wait covers
|
|
507
|
+
I'm holding here until you send a verdict — the wait covers <the tiers the engine's `covers` names>.
|
|
472
508
|
|
|
473
509
|
`/spec-reviewed` picks it up · `spec-env review skip "<reason>"` moves on
|
|
474
510
|
|
|
@@ -489,22 +525,14 @@ reviewer sees the heading they have always seen.
|
|
|
489
525
|
printed one line per tier, in that order, and `--json` carries the same thing as
|
|
490
526
|
`tiers`. Relay all three whatever they say, including the ones that are off with
|
|
491
527
|
the command that turns them on: a reader who has left the house cannot ask for a
|
|
492
|
-
remote
|
|
528
|
+
remote door they were never shown.
|
|
493
529
|
|
|
494
530
|
**Do not pick one for them.** The engine used to, and the guess failed three
|
|
495
531
|
separate ways in one day. `.claude/rules/spec-reports.md` carries the shape and
|
|
496
532
|
why the *one link, never two* rule now reads
|
|
497
|
-
**one link per
|
|
498
|
-
local and
|
|
499
|
-
covers
|
|
500
|
-
*a verdict here needs `/spec-reviewed`*, because nothing pushes from
|
|
501
|
-
the artifact store into this conversation. Never let the holding line promise a
|
|
502
|
-
wait over that tier.
|
|
503
|
-
|
|
504
|
-
**Publishing is still never yours to do.** `remote` reading `off` is the normal
|
|
505
|
-
state, and the fix for it is the command on that line — typed by the operator,
|
|
506
|
-
or pressed on the page, because a published page is one this tooling cannot
|
|
507
|
-
remove and permitting it is not publishing it.
|
|
533
|
+
**one link per door, each labelled, all into one store** —
|
|
534
|
+
local, network and remote are three doors into one room, so the wait
|
|
535
|
+
covers every one the stack shows.
|
|
508
536
|
|
|
509
537
|
**The `live:` line goes with the stack**, and it is the engine's line too —
|
|
510
538
|
copied as printed, and **absent when the engine printed none**. The page can act
|
|
@@ -519,7 +547,7 @@ verdict.
|
|
|
519
547
|
**Where you are not waiting, it stays the `Review` row** — the counts and the
|
|
520
548
|
page link, and **no question**:
|
|
521
549
|
|
|
522
|
-
| **Review** | <N> files, +<a> −<d> · **local** <URL> · **network** <URL> · **remote**
|
|
550
|
+
| **Review** | <N> files, +<a> −<d> · **local** <URL> · **network** <URL> · **remote** <URL> (tailnet) |
|
|
523
551
|
|
|
524
552
|
At the end of a phase you are always waiting, so this shape belongs to the
|
|
525
553
|
renders that are not this step: a mid-phase `/spec-diff`, a page produced
|
|
@@ -633,10 +661,9 @@ Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines
|
|
|
633
661
|
never the bare `page:` path: a path is not clickable in any terminal, and a page
|
|
634
662
|
nobody can open is a page nobody reads.
|
|
635
663
|
|
|
636
|
-
- **Never write the review unasked**, and **never publish
|
|
637
|
-
|
|
638
|
-
|
|
639
|
-
the ask — publishing is the answer to it, and `/spec-diff` §6 owns how.
|
|
664
|
+
- **Never write the review unasked**, and **never publish** — there is no
|
|
665
|
+
publishing (`/spec-diff` §6). A `file://` link is no use on a phone, and the
|
|
666
|
+
stack says why nothing was served.
|
|
640
667
|
**The `reader:` line no longer decides anything here, and that is the point.**
|
|
641
668
|
It is still printed, and it is still the only place that question is answered —
|
|
642
669
|
but the offer does not change with it, because the stack lists every tier
|
|
@@ -646,23 +673,20 @@ that branching is exactly what produced a `file://` page on a session detected
|
|
|
646
673
|
underneath a reader when detection flipped mid-session.
|
|
647
674
|
|
|
648
675
|
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
649
|
-
|
|
650
|
-
|
|
651
|
-
|
|
652
|
-
|
|
676
|
+
their tier — the other addresses this machine has of that kind — so pass them
|
|
677
|
+
on rather than editing them out: in the banner they are indented sub-bullets
|
|
678
|
+
under that tier, labels included, exactly as `.claude/rules/spec-reports.md`
|
|
679
|
+
shows.
|
|
653
680
|
|
|
654
681
|
**Never read an environment variable to decide anything about the offer** — not
|
|
655
682
|
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
656
683
|
here for a detection to decide, and a second implementation of one could not be
|
|
657
684
|
tested and would drift.
|
|
658
685
|
|
|
659
|
-
**Serving is the engine's to do
|
|
686
|
+
**Serving is the engine's to do, and there is nothing else.** The server is one
|
|
660
687
|
process, ended by one flag, leaving nothing behind, and `review.allowNetwork`
|
|
661
|
-
decides whether it binds wide —
|
|
662
|
-
|
|
663
|
-
the stack. Publishing leaves a page this tooling cannot remove, so it stays an
|
|
664
|
-
ask in every case, always — which is why `remote` shows the command rather than
|
|
665
|
-
a URL until someone types it.
|
|
688
|
+
decides whether it binds wide — on the LAN and the tailnet alike — with no
|
|
689
|
+
detection involved.
|
|
666
690
|
|
|
667
691
|
- **Never fatal.** A failed render — no worktree, a git error — is one line and
|
|
668
692
|
the phase is still done. The page is a convenience; the repo is the record.
|
|
@@ -684,7 +708,8 @@ the shape; this section carries only what is specific here.
|
|
|
684
708
|
**Some failed** or **Not yet**: the phase stays `🔄`, `Notes` says which steps
|
|
685
709
|
are open, and `Next` is `/commit, then /spec-next` to pick them up.
|
|
686
710
|
- `❌` — the phase's tests are red, or it stopped part-way. Quote the failure.
|
|
687
|
-
- `⏸` — no spec in flight,
|
|
711
|
+
- `⏸` — no spec in flight, several in flight with this session in none of
|
|
712
|
+
them, or the name given does not match the one that is.
|
|
688
713
|
|
|
689
714
|
**Fields:** `Tracker` · `Branch` · `Built` · `Tests` · `Notes` · `Review` ·
|
|
690
715
|
`Follow-ups` · `Next`
|