@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
|
@@ -105,11 +105,40 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
|
|
|
105
105
|
description (an **update** to the existing issue, plus a sub-issue per phase).
|
|
106
106
|
Recording a snapshot here would declare the mirror already in sync and strand
|
|
107
107
|
the issue showing the raw report forever.
|
|
108
|
+
- **Preserve the original, before anything replaces it.** Run this the moment
|
|
109
|
+
the spec file exists and **before the linking push**:
|
|
110
|
+
|
|
111
|
+
```
|
|
112
|
+
skitterspec spec-sync preserve <spec>
|
|
113
|
+
```
|
|
114
|
+
|
|
115
|
+
It posts the issue's current description onto the issue as a comment — the one
|
|
116
|
+
surface one-way sync never touches, so no push can clobber it. On the API path
|
|
117
|
+
it reads the description itself; without a key it prints the body and the
|
|
118
|
+
marker, and you post it with the Linear comment tool after checking the
|
|
119
|
+
comments for that marker.
|
|
120
|
+
|
|
121
|
+
**The ordering is the whole correctness condition.** Run before the push, this
|
|
122
|
+
keeps what the reporter filed. Run after it, it would keep the generated spec
|
|
123
|
+
and report success — which is why it is a step of its own here rather than a
|
|
124
|
+
line in the push sequence. The engine warns when it can tell it is late, but it
|
|
125
|
+
cannot always tell.
|
|
126
|
+
|
|
127
|
+
**It never fails the adoption.** A project that set
|
|
128
|
+
`intake.preserveOriginal: false`, an unreachable Linear, an issue with no
|
|
129
|
+
description, a comment Linear refused — every one of them exits 0 and says so.
|
|
130
|
+
Relay what it printed and carry on.
|
|
108
131
|
- **Say what will happen** in the finish-up message. The linking step runs right
|
|
109
132
|
after the spec is written, so the issue's description is replaced by the spec
|
|
110
|
-
**then** — not on some later manual push.
|
|
111
|
-
|
|
112
|
-
|
|
133
|
+
**then** — not on some later manual push. Say both halves: the description
|
|
134
|
+
becomes the spec, **and** the original is preserved as a comment on the same
|
|
135
|
+
issue, so the reporter can still read what they wrote.
|
|
136
|
+
|
|
137
|
+
**Do not send anyone to the issue's history for it.** This used to say Linear
|
|
138
|
+
keeps the original there, and that is true and useless: history is a diff
|
|
139
|
+
viewer nobody opens, it is not quotable, and it degrades to "it is in there
|
|
140
|
+
somewhere". The comment is the answer, and the other half is the spec's own
|
|
141
|
+
**Problem** (or **Symptom**) section quoting the reporter.
|
|
113
142
|
|
|
114
143
|
## Phase A — reach a clear shared understanding (grill first)
|
|
115
144
|
|
|
@@ -163,25 +192,56 @@ Briefly play back the agreed understanding before writing.
|
|
|
163
192
|
|
|
164
193
|
This skill is for **features**. For bugs, use `/spec-bug` (test-first, red→green).
|
|
165
194
|
|
|
166
|
-
### Write it
|
|
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.
|
|
167
200
|
|
|
168
|
-
**
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
implementing it — say so before writing, and offer to author the spec from the
|
|
172
|
-
primary checkout instead.
|
|
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:
|
|
173
204
|
|
|
174
|
-
|
|
175
|
-
|
|
176
|
-
|
|
177
|
-
cancelled the new spec is cancelled with it. Committing it there also mis-stamps
|
|
178
|
-
the commit's ticket trailer, since that is resolved from the branch (see
|
|
179
|
-
`.claude/rules/commit-trailers.md`, installed with a ticketing provider).
|
|
205
|
+
```
|
|
206
|
+
skitterspec spec-env up <name> --docs
|
|
207
|
+
```
|
|
180
208
|
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
the
|
|
184
|
-
|
|
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.
|
|
185
245
|
|
|
186
246
|
- **Every spec is a folder** — never a bare file, even for a one-line change:
|
|
187
247
|
`specs/backlog/feat-<kebab-name>/`. Create it with `mkdir -p`.
|
|
@@ -339,6 +399,157 @@ open questions, `Draft` when you deliberately left some unresolved. Either way
|
|
|
339
399
|
the next step is `/spec-start`. The Report section below is where all of that
|
|
340
400
|
reaches the user — do not narrate it here as well.
|
|
341
401
|
|
|
402
|
+
## Phase C2 — render the spec, then wait for the verdict
|
|
403
|
+
|
|
404
|
+
**Only when the project has per-spec isolation** (`specs/.core/env.config.json`
|
|
405
|
+
present). Without it there is no page and this phase does not exist — skip it in
|
|
406
|
+
silence rather than explaining an absence.
|
|
407
|
+
|
|
408
|
+
A spec is the one artefact whose whole purpose is to be
|
|
409
|
+
**read before work begins**, and until now it was the only one with no reading
|
|
410
|
+
surface: `/spec`
|
|
411
|
+
finished, the spec sat uncommitted, and `/spec-start` had to point that out and
|
|
412
|
+
commit it as a side effect of provisioning. So this phase ends where every other
|
|
413
|
+
phase of the lifecycle ends — on a page, in a verdict.
|
|
414
|
+
|
|
415
|
+
```
|
|
416
|
+
skitterspec spec-env review <spec> --docs --buttons authoring
|
|
417
|
+
```
|
|
418
|
+
|
|
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.
|
|
426
|
+
|
|
427
|
+
**This is free.** The engine reads git and splices text into a template; the
|
|
428
|
+
diff never passes through you.
|
|
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
|
+
|
|
436
|
+
**Render nothing when nothing was written.** A `⏸` run — grilling that never
|
|
437
|
+
reached a shared understanding — has no spec to show, and must not ask for a
|
|
438
|
+
verdict on one.
|
|
439
|
+
|
|
440
|
+
**Arm nothing.** There is no `spec-env review arm` in this path, and that is a
|
|
441
|
+
decision rather than an omission: the gate asserts that *a phase which ended*
|
|
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.
|
|
453
|
+
|
|
454
|
+
### The two endings this page offers
|
|
455
|
+
|
|
456
|
+
`--buttons authoring` offers `Commit & Start` and `Commit` in place of the
|
|
457
|
+
committing pair, because "commit and build the next phase" is meaningless for a
|
|
458
|
+
spec with no phase in flight.
|
|
459
|
+
|
|
460
|
+
- **`commit-start`** — hand off to `review.commitWith` (`/commit` by default),
|
|
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.
|
|
501
|
+
- **`changes`** — work the notes into the spec, record a resolution for each one
|
|
502
|
+
so the next render shows it struck through with what changed, then
|
|
503
|
+
**re-render, and wait again**. The reader is still holding a decision, so
|
|
504
|
+
ending the turn and
|
|
505
|
+
making them type `/spec-diff` would reopen the loop this exists to close.
|
|
506
|
+
- **`discuss`** — report and talk. Claim nothing, change nothing.
|
|
507
|
+
|
|
508
|
+
**Take the pathspec from the render, not from the tree.** A checkout is shared,
|
|
509
|
+
so the set of this spec's uncommitted documents can differ between the render and
|
|
510
|
+
the verdict — and the reader's conclusion is about what the page showed them.
|
|
511
|
+
|
|
512
|
+
### Then wait for it
|
|
513
|
+
|
|
514
|
+
**The wait is a command. Do not write one.**
|
|
515
|
+
|
|
516
|
+
1. **Note the moment you start waiting**, as an ISO timestamp. That instant is
|
|
517
|
+
the whole scope of what you may claim.
|
|
518
|
+
2. **Run the engine's wait in the background, and end your turn:**
|
|
519
|
+
|
|
520
|
+
```
|
|
521
|
+
skitterspec spec-env review wait <spec> --since <the timestamp>
|
|
522
|
+
```
|
|
523
|
+
|
|
524
|
+
It takes no timeout unless you pass one, and you must not pass one: a reader
|
|
525
|
+
who walks away from a spec is the normal case, and a bounded watch once lost a
|
|
526
|
+
verdict to a lunch break.
|
|
527
|
+
3. **On waking, let the engine pick:**
|
|
528
|
+
|
|
529
|
+
**A watch that dies is re-armed on the same window**, silently and bounded by
|
|
530
|
+
the age of that window — `.claude/rules/spec-reports.md` carries the contract,
|
|
531
|
+
including when to stop and what the banner says instead. Do not restate it
|
|
532
|
+
here.
|
|
533
|
+
|
|
534
|
+
```
|
|
535
|
+
skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
It claims the one pass that arrived inside the window, acts on nothing when
|
|
539
|
+
none did, and refuses to choose when two did.
|
|
540
|
+
4. **Route on the verdict** as above.
|
|
541
|
+
|
|
542
|
+
**Where the page is `file://`** — the engine could not serve — there is no server
|
|
543
|
+
to POST to, so the pass is copied and pasted and the reader's next message is
|
|
544
|
+
what carries it. **Do not start a watch that cannot fire**: a wait on the pending
|
|
545
|
+
store would spin forever while the report underneath it claimed to be holding,
|
|
546
|
+
which is the exact failure `.claude/rules/spec-reports.md` records. The wait is
|
|
547
|
+
the turn ending, and the banner says so.
|
|
548
|
+
|
|
549
|
+
Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines, all
|
|
550
|
+
three, in that order — never the bare `page:` path. `.claude/rules/spec-reports.md`
|
|
551
|
+
carries the shape and why every tier is named rather than one being chosen.
|
|
552
|
+
|
|
342
553
|
## Phase D — record the isolation stack (only if configured)
|
|
343
554
|
|
|
344
555
|
**Only when `specs/.core/env.config.json` exists** (per-spec isolation is
|
|
@@ -461,16 +672,61 @@ the shape; this section carries only what is specific here.
|
|
|
461
672
|
|
|
462
673
|
- `✅` — a `Ready` spec is written to `specs/backlog/<name>/`.
|
|
463
674
|
- `⚠️` — written as `Draft`; open questions were deliberately left. Name them.
|
|
675
|
+
- `❌` — the spec was committed and the land failed part-way: the rebase
|
|
676
|
+
conflicted, or the fast-forward was refused. There is a standing worktree and a
|
|
677
|
+
branch to deal with, so say where both are.
|
|
464
678
|
- `⏸` — grilling did not reach a shared understanding, so nothing was written.
|
|
465
679
|
That is the skill working: a spec written over an unresolved requirement is
|
|
466
680
|
the outcome Phase A exists to prevent.
|
|
467
681
|
|
|
468
|
-
**Fields:** `Tracker` · `Spec` · `Built` · `Follow-ups` ·
|
|
682
|
+
**Fields:** `Tracker` · `Spec` · `Built` · `Landed` · `Worktree` · `Follow-ups` ·
|
|
683
|
+
`Next`
|
|
469
684
|
|
|
470
685
|
`Built` is the spec's path and phase count; `Spec` is its status and bucket;
|
|
471
|
-
`Next` is `/spec-start <name>`, with the name spelled the way it must be typed.
|
|
472
686
|
`Tracker` appears only when a provider is installed and linked it.
|
|
473
687
|
|
|
688
|
+
`Landed` and `Worktree` belong to the **verdict** half of the run and appear
|
|
689
|
+
only once one has been acted on — a run that is still waiting on the page has
|
|
690
|
+
neither. `Landed` says the base branch fast-forwarded and to what; `Worktree`
|
|
691
|
+
says kept (on `commit-start`) or removed (on `commit`), with the path. Neither
|
|
692
|
+
appears where isolation is off: nothing was provisioned and nothing was landed.
|
|
693
|
+
|
|
694
|
+
**`Next` depends on whether Phase C2 rendered a page.** Where it did, the run is
|
|
695
|
+
waiting on a verdict, so the block **omits the `Review` row** and ends on the
|
|
696
|
+
banner defined in `.claude/rules/spec-reports.md` — counts, the tier stack, and
|
|
697
|
+
this page's two exits:
|
|
698
|
+
|
|
699
|
+
---
|
|
700
|
+
|
|
701
|
+
## ⏸ Review ready — <N> files, +<a> −<d>
|
|
702
|
+
|
|
703
|
+
- **local** — <the `local:` URL>
|
|
704
|
+
- **network** — <the `network:` URL, or off with the command that turns it on>
|
|
705
|
+
- **remote** — <the `remote:` URL, or off with the command that turns it on>
|
|
706
|
+
|
|
707
|
+
I'm holding here until you send a verdict — the wait covers local and network.
|
|
708
|
+
|
|
709
|
+
`Commit & Start` puts it in flight · `Commit` keeps it for later
|
|
710
|
+
|
|
711
|
+
---
|
|
712
|
+
|
|
713
|
+
There `Next` names the page rather than a command, because the button is what
|
|
714
|
+
carries the work on.
|
|
715
|
+
|
|
716
|
+
**Neither exit leaves the spec anywhere awkward**, and the banner does not
|
|
717
|
+
explain that — the whole point of Phase B is that there is nothing to warn
|
|
718
|
+
about. Both buttons commit and land, so either way the spec reaches the base
|
|
719
|
+
branch as one commit; the only difference is whether the worktree stays.
|
|
720
|
+
|
|
721
|
+
Where no page was rendered — isolation is not configured, or nothing was
|
|
722
|
+
written — `Next` is `/spec-start <name>`, with the name spelled the way it must
|
|
723
|
+
be typed.
|
|
724
|
+
|
|
725
|
+
**A spec written without a page is still uncommitted**, so that `Next` relies on
|
|
726
|
+
`/spec-start` committing the spec when it is all that is uncommitted. Say
|
|
727
|
+
`/commit, then /spec-start <name>` when anything else is uncommitted too, or the
|
|
728
|
+
row sends the reader to a refusal.
|
|
729
|
+
|
|
474
730
|
**`Follow-ups` is almost always `none` here.** This skill's whole job is to
|
|
475
731
|
capture work, so anything it surfaced belongs in the spec it just wrote rather
|
|
476
732
|
than in a follow-up line beneath it.
|
|
@@ -104,11 +104,40 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
|
|
|
104
104
|
description (an **update** to the existing issue, plus a sub-issue per phase).
|
|
105
105
|
Recording a snapshot here would declare the mirror already in sync and strand
|
|
106
106
|
the issue showing the raw report forever.
|
|
107
|
+
- **Preserve the original, before anything replaces it.** Run this the moment
|
|
108
|
+
the spec file exists and **before the linking push**:
|
|
109
|
+
|
|
110
|
+
```
|
|
111
|
+
skitterspec spec-sync preserve <spec>
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
It posts the issue's current description onto the issue as a comment — the one
|
|
115
|
+
surface one-way sync never touches, so no push can clobber it. On the API path
|
|
116
|
+
it reads the description itself; without a key it prints the body and the
|
|
117
|
+
marker, and you post it with the Linear comment tool after checking the
|
|
118
|
+
comments for that marker.
|
|
119
|
+
|
|
120
|
+
**The ordering is the whole correctness condition.** Run before the push, this
|
|
121
|
+
keeps what the reporter filed. Run after it, it would keep the generated spec
|
|
122
|
+
and report success — which is why it is a step of its own here rather than a
|
|
123
|
+
line in the push sequence. The engine warns when it can tell it is late, but it
|
|
124
|
+
cannot always tell.
|
|
125
|
+
|
|
126
|
+
**It never fails the adoption.** A project that set
|
|
127
|
+
`intake.preserveOriginal: false`, an unreachable Linear, an issue with no
|
|
128
|
+
description, a comment Linear refused — every one of them exits 0 and says so.
|
|
129
|
+
Relay what it printed and carry on.
|
|
107
130
|
- **Say what will happen** in the finish-up message. The linking step runs right
|
|
108
131
|
after the spec is written, so the issue's description is replaced by the spec
|
|
109
|
-
**then** — not on some later manual push.
|
|
110
|
-
|
|
111
|
-
|
|
132
|
+
**then** — not on some later manual push. Say both halves: the description
|
|
133
|
+
becomes the spec, **and** the original is preserved as a comment on the same
|
|
134
|
+
issue, so the reporter can still read what they wrote.
|
|
135
|
+
|
|
136
|
+
**Do not send anyone to the issue's history for it.** This used to say Linear
|
|
137
|
+
keeps the original there, and that is true and useless: history is a diff
|
|
138
|
+
viewer nobody opens, it is not quotable, and it degrades to "it is in there
|
|
139
|
+
somewhere". The comment is the answer, and the other half is the spec's own
|
|
140
|
+
**Problem** (or **Symptom**) section quoting the reporter.
|
|
112
141
|
|
|
113
142
|
## 1. Reproduce & isolate (light investigation)
|
|
114
143
|
|
|
@@ -309,10 +338,14 @@ and **never auto-push git** — Linear's own automation reacts to real branch/PR
|
|
|
309
338
|
events later. Report the Linear issue URL as part of the skill's finish-up
|
|
310
339
|
message.
|
|
311
340
|
|
|
312
|
-
**Only when all three hold**: `specs/.core/linear.config.json` exists,
|
|
313
|
-
`
|
|
341
|
+
**Only when all three hold**: `specs/.core/linear.config.json` exists, the repo
|
|
342
|
+
**owns** `assignee` in its `sync.fieldOwnership`, and the spec carries a
|
|
314
343
|
`linear_identifier`. Any one missing → skip this step silently and carry on; a
|
|
315
|
-
project that
|
|
344
|
+
project that declined must see no trace of assignment.
|
|
345
|
+
|
|
346
|
+
Ownership is the **value**, not the key: `assignee` is owned by default, and
|
|
347
|
+
`"none"` is how a project declines it. Testing whether the key is *present* would
|
|
348
|
+
read as opted-in everywhere, since the default puts it in every config.
|
|
316
349
|
|
|
317
350
|
**Never blocks, never fails the skill.** Everything below is best-effort: the
|
|
318
351
|
branch is provisioned and the spec is moving either way, and an unassigned issue
|
|
@@ -474,11 +507,18 @@ skitterspec spec-env review arm <spec>
|
|
|
474
507
|
```
|
|
475
508
|
|
|
476
509
|
**Then wait**, and `/spec-next` §5 owns the sequence — follow it there rather
|
|
477
|
-
than reading a second copy here: note the moment
|
|
478
|
-
|
|
479
|
-
|
|
480
|
-
|
|
481
|
-
|
|
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
|
|
513
|
+
arrived inside the window. **Do not compose a watcher**, and do not give the
|
|
514
|
+
wait a timeout — the reasoning is in `/spec-next` §5 and is not repeated here.
|
|
515
|
+
The banner it describes is what this skill emits in place of a `Review` row,
|
|
516
|
+
and the routing on the verdict is `/spec-diff` §2 and §4, as it is everywhere.
|
|
517
|
+
|
|
518
|
+
**A watch that dies is re-armed on the same window**, silently and bounded by
|
|
519
|
+
the age of that window — `.claude/rules/spec-reports.md` carries the contract,
|
|
520
|
+
including when to stop and what the banner says instead. Do not restate it
|
|
521
|
+
here.
|
|
482
522
|
|
|
483
523
|
**Why this skill arms as well as waits.** Waiting is what any offer does;
|
|
484
524
|
**arming** asserts an obligation that outlives the turn, and belongs only to
|
|
@@ -499,30 +539,33 @@ this worktree is refused until a verdict is sent or
|
|
|
499
539
|
`skitterspec spec-env review skip "<reason>"` records the decision to move on.
|
|
500
540
|
The exit is always one command, and one of them is *"I am moving on"*.
|
|
501
541
|
|
|
502
|
-
Relay the
|
|
503
|
-
|
|
542
|
+
Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines, all
|
|
543
|
+
three — rather than the bare `page:` path: a path is not clickable in any
|
|
544
|
+
terminal, and a page nobody can open is a page nobody reads. Relay the `live:`
|
|
545
|
+
line with it where the engine printed one, and nothing where it did not.
|
|
546
|
+
`.claude/rules/spec-reports.md` carries the shape, including why a rigid
|
|
547
|
+
contract took that line.
|
|
504
548
|
|
|
505
549
|
- **Never write the review unasked**, and **never publish**. Publishing leaves
|
|
506
550
|
something behind that this tooling cannot remove, so it is always an ask. A
|
|
507
551
|
`file://` link is no use on a phone, and saying so **is** the ask —
|
|
508
552
|
`/spec-diff` §6 owns how.
|
|
509
|
-
**
|
|
510
|
-
|
|
511
|
-
|
|
512
|
-
|
|
513
|
-
|
|
514
|
-
|
|
515
|
-
|
|
516
|
-
|
|
517
|
-
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
521
|
-
|
|
522
|
-
|
|
523
|
-
|
|
524
|
-
|
|
525
|
-
drift.
|
|
553
|
+
**The `reader:` line no longer decides anything here, and that is the point.**
|
|
554
|
+
It is still printed, and it is still the only place that question is answered —
|
|
555
|
+
but the offer does not change with it, because the stack lists every tier
|
|
556
|
+
whatever it says. Three reader states used to mean three different offers, and
|
|
557
|
+
that branching is exactly what produced a `file://` page on a session detected
|
|
558
|
+
`unknown`, a LAN URL for a phone off the network, and an address that changed
|
|
559
|
+
underneath a reader when detection flipped mid-session.
|
|
560
|
+
|
|
561
|
+
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
562
|
+
`network` — the other addresses this machine has, offered because the
|
|
563
|
+
best-guess one can be wrong — so pass them on rather than editing them out.
|
|
564
|
+
|
|
565
|
+
**Never read an environment variable to decide anything about the offer** — not
|
|
566
|
+
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
567
|
+
here for a detection to decide, and a second implementation of one could not be
|
|
568
|
+
tested and would drift.
|
|
526
569
|
|
|
527
570
|
**Serving is the engine's to do; publishing is never.** A `remote` reader
|
|
528
571
|
authorises a local server — one process, ended by one flag, leaving nothing
|
|
@@ -76,8 +76,8 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
|
|
|
76
76
|
Do not roll anything back, and do not stop to ask.
|
|
77
77
|
- **Say what happened** in the skill's report: mirror updated, skipped as
|
|
78
78
|
unlinked, or failed with the reason.
|
|
79
|
-
- **There is no unassign step, and that is not an omission.**
|
|
80
|
-
`
|
|
79
|
+
- **There is no unassign step, and that is not an omission.** Where the repo owns
|
|
80
|
+
`assignee`, the projection derives it from the spec's lifecycle
|
|
81
81
|
bucket — so moving the folder to `complete`/`cancelled` is *itself* what
|
|
82
82
|
releases the issue, and the push above carries it like any other field. The
|
|
83
83
|
`linear_assignee_id` stamp and the `> **Developer:**` header both stay put:
|
|
@@ -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.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spec-claim
|
|
3
|
-
description: Take ownership of a spec, hand it back, or give it to a teammate — the spec records who is building it and its Linear issue is assigned to them. Opt-in — needs specs/.core/linear.config.json with assignee in sync.fieldOwnership. Use when the user says "/spec-claim", "claim this spec", "take ownership of this", "I'm picking this up", "hand this back", or "assign this spec to someone".
|
|
3
|
+
description: Take ownership of a spec, hand it back, or give it to a teammate — the spec records who is building it and its Linear issue is assigned to them. Opt-in — needs specs/.core/linear.config.json with the repo owning assignee in sync.fieldOwnership. Use when the user says "/spec-claim", "claim this spec", "take ownership of this", "I'm picking this up", "hand this back", or "assign this spec to someone".
|
|
4
4
|
disable-model-invocation: true
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -16,9 +16,17 @@ and the push that follows tells Linear. This skill is how that record changes
|
|
|
16
16
|
after `/spec-start` has set it — a hand-off mid-flight, a spec picked up from
|
|
17
17
|
someone who moved on, or work a lead is distributing.
|
|
18
18
|
|
|
19
|
-
**Opt-in.** Needs `specs/.core/linear.config.json` *and*
|
|
20
|
-
`sync.fieldOwnership
|
|
21
|
-
|
|
19
|
+
**Opt-in.** Needs `specs/.core/linear.config.json` *and* the repo to **own**
|
|
20
|
+
`assignee` in its `sync.fieldOwnership` — which `"none"` declines as surely as
|
|
21
|
+
omitting it does. If either is missing, say which one and stop: without the field
|
|
22
|
+
the stamp would sit in the file doing nothing.
|
|
23
|
+
|
|
24
|
+
**The engine refuses this too, and that is the point.** `spec-sync assign` checks
|
|
25
|
+
the same thing and writes nothing, so the rule holds for a script, a chained
|
|
26
|
+
command, and anyone who reached for the CLI directly. This paragraph was the only
|
|
27
|
+
thing enforcing it for long enough that the engine's own success line —
|
|
28
|
+
`next: push it, so Linear agrees` — was printed over a push that would drop the
|
|
29
|
+
field. Prose in one skill is not a guard; it is a guard's documentation.
|
|
22
30
|
|
|
23
31
|
## 1. Identify the target spec
|
|
24
32
|
|
|
@@ -95,8 +95,8 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
|
|
|
95
95
|
Do not roll anything back, and do not stop to ask.
|
|
96
96
|
- **Say what happened** in the skill's report: mirror updated, skipped as
|
|
97
97
|
unlinked, or failed with the reason.
|
|
98
|
-
- **There is no unassign step, and that is not an omission.**
|
|
99
|
-
`
|
|
98
|
+
- **There is no unassign step, and that is not an omission.** Where the repo owns
|
|
99
|
+
`assignee`, the projection derives it from the spec's lifecycle
|
|
100
100
|
bucket — so moving the folder to `complete`/`cancelled` is *itself* what
|
|
101
101
|
releases the issue, and the push above carries it like any other field. The
|
|
102
102
|
`linear_assignee_id` stamp and the `> **Developer:**` header both stay put:
|
|
@@ -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.
|