@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.
Files changed (59) hide show
  1. package/MIGRATION.md +218 -0
  2. package/README.md +37 -1
  3. package/assets/claude-md-section.md +42 -18
  4. package/assets/commands/allow-main.md +33 -0
  5. package/assets/commands/spec-remote-review.md +22 -0
  6. package/assets/commands/spec-skip.md +24 -0
  7. package/assets/core/SETUP.md +10 -6
  8. package/assets/core/env.config.json.example +6 -3
  9. package/assets/core/env.config.md +183 -25
  10. package/assets/core/linear.config.json.example +2 -1
  11. package/assets/core/linear.config.md +49 -22
  12. package/assets/hooks/main-guard.cjs +145 -0
  13. package/assets/hooks/review-gate.cjs +8 -3
  14. package/assets/review/page.html +1174 -101
  15. package/assets/rules/commit-trailers.md +17 -7
  16. package/assets/rules/offered-unblocks.md +100 -0
  17. package/assets/rules/spec-planning.md +195 -14
  18. package/assets/rules/spec-reports.md +181 -29
  19. package/assets/skills/no-spec/SKILL.md +219 -0
  20. package/assets/skills/spec/SKILL.md +277 -21
  21. package/assets/skills/spec-bug/SKILL.md +73 -30
  22. package/assets/skills/spec-cancel/SKILL.md +31 -2
  23. package/assets/skills/spec-claim/SKILL.md +12 -4
  24. package/assets/skills/spec-complete/SKILL.md +27 -2
  25. package/assets/skills/spec-diff/SKILL.md +164 -37
  26. package/assets/skills/spec-hotfix/SKILL.md +61 -25
  27. package/assets/skills/spec-init/SKILL.md +4 -2
  28. package/assets/skills/spec-linear-setup/SKILL.md +19 -11
  29. package/assets/skills/spec-next/SKILL.md +168 -60
  30. package/assets/skills/spec-push/SKILL.md +45 -0
  31. package/assets/skills/spec-review/SKILL.md +89 -2
  32. package/assets/skills/spec-reviewed/SKILL.md +31 -5
  33. package/assets/skills/spec-start/SKILL.md +40 -3
  34. package/assets/skills/spec-status/SKILL.md +20 -6
  35. package/assets/skills/spec-sync/SKILL.md +1 -0
  36. package/package.json +2 -2
  37. package/src/cli.js +1612 -172
  38. package/src/env/classify.js +87 -2
  39. package/src/env/config.js +333 -19
  40. package/src/env/hooks.js +102 -33
  41. package/src/env/live.js +124 -1
  42. package/src/env/mainguard.js +240 -0
  43. package/src/env/provision.js +106 -10
  44. package/src/env/registry.js +70 -6
  45. package/src/env/resolve.js +128 -5
  46. package/src/env/review.js +854 -29
  47. package/src/env/reviewers/coderabbit.js +228 -0
  48. package/src/env/reviewers.js +517 -0
  49. package/src/env/serve.js +474 -50
  50. package/src/env/supervise.js +8 -1
  51. package/src/env/teardown.js +12 -1
  52. package/src/init.js +185 -24
  53. package/src/vendor/linear/api.js +111 -2
  54. package/src/vendor/linear/cli-sync.js +661 -11
  55. package/src/vendor/linear/config.js +41 -13
  56. package/src/vendor/linear/doctor.js +6 -5
  57. package/src/vendor/sync-core/index.js +11 -3
  58. package/src/vendor/sync-core/src/compare.js +65 -0
  59. package/src/vendor/sync-core/src/normalize.js +26 -0
@@ -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, 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
@@ -41,13 +41,19 @@ sole candidate or prints the candidates.
41
41
  The page has marks on it — `✓ accept` per file, notes against a line or a whole
42
42
  file, answers to the checks a written review asked — and it
43
43
  **ends in a decision**: `✓ Approve`, `↺ Request changes` or `… Discuss first`.
44
- A review comes back to you one of two ways, and **both are ordinary**:
44
+ A review comes back to you one of three ways, and **all three are ordinary**:
45
45
 
46
46
  - **A six-digit code** — `418207`, on its own. A *served* page hands its pass
47
47
  straight to the engine, which holds it until someone reads the code out. This
48
48
  is the usual way on a phone.
49
- - **A pasted JSON blob** — a `file://` page has no server to talk to, so it
50
- copies. Not legacy: it is the whole story for a local reader.
49
+ - **A verdict word** — `commit`, `commit-continue`, `continue`, `changes` or
50
+ `discuss`. A `file://` page cannot send anything, so where the reader marked
51
+ nothing it copies a command carrying the conclusion on its own. Send it with
52
+ `skitterspec spec-env review <spec> --verdict <word>`; it joins the same merge
53
+ a claimed pass does, so everything below is unchanged.
54
+ - **A pasted JSON blob** — the same `file://` page, once the reader has marked
55
+ something up: accepts and notes do not fit on a command line, so the whole
56
+ pass travels. Not legacy: it is the whole story for a local reader.
51
57
 
52
58
  Either way, **this is not a request to render anything**: it is a review coming
53
59
  back, and these steps replace §3–§5 below.
@@ -151,6 +157,17 @@ back, and these steps replace §3–§5 below.
151
157
  absent verdict has always meant "report it and wait" — which is why that is
152
158
  what it still means.
153
159
 
160
+ **A pass may carry an `action:` instead**, and then none of the above
161
+ applies: it concluded nothing. Go to **§2b**. The engine refuses a pass
162
+ carrying both, so there is never a choice to make between them.
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
+
154
171
  3. **Say what you read, then ask what's up.** Report the accepted count, then
155
172
  each open comment as `file:line — note`, then the files you would touch.
156
173
  **Wait — unless the verdict already said otherwise.** Pasting on its own is
@@ -335,6 +352,77 @@ it — and the paste was the one place it broke. The *work* either authorises is
335
352
  ordinary phase-sized cost, and step 3 is where the operator decides whether to
336
353
  spend it.
337
354
 
355
+ ## 2b. An action changes something, then hands the page back
356
+
357
+ Only on a pass carrying an **action**. Three of them, and
358
+ **all three end the same way**:
359
+ do the thing, re-render (§4), and wait again (§4b) — because the reader
360
+ still has a decision in front of them and has not made it.
361
+
362
+ | Action | Do | Then |
363
+ |--------|----|------|
364
+ | `live-on` | commit first (below), then `skitterspec spec-env live take <spec>` | re-render `--branch`, wait again |
365
+ | `allow-network` | `skitterspec spec-env review allow network` | re-render, wait again |
366
+ | `allow-remote` | `skitterspec spec-env review allow remote --set on` | re-render, wait again |
367
+
368
+ **THERE IS NO `live-off`, and its absence is deliberate.** Putting *this* change
369
+ live is about the diff on screen; handing the whole instance back to `main` is a
370
+ workspace decision with nothing to do with this review. The `live:` line names
371
+ `/spec-live main` for it — a command the operator types, which is also why no
372
+ skill runs it.
373
+
374
+ **AN ACTION IS NOT A VERDICT, and the gate is untouched by all three.** A phase
375
+ that ended armed the gate, and it is discharged by a committing verdict or a
376
+ recorded skip and by nothing else — so after any of these the phase still owes
377
+ an answer, and that is exactly why the run waits again rather than finishing.
378
+ The engine enforces this rather than trusting it: `ACTIONS` is disjoint from
379
+ `VERDICTS` and `COMMITTING`, so nothing that routes on a verdict can see one.
380
+
381
+ **`live-on` commits first, and the commit is a precondition rather than an answer.**
382
+ `live take` refuses a dirty worktree, and even without that guard
383
+ uncommitted work stays behind in the worktree — so what went live would be the
384
+ *previous* commit while the page claimed to be showing this one. Hand off to
385
+ `review.commitWith` exactly as §2a does (do not restate its rules here), then
386
+ take the instance. The reader has not approved anything by pressing it.
387
+
388
+ **It re-renders `--branch` afterwards**, because the working view is now empty:
389
+ the commit just happened, and the branch range is what still answers "what am I
390
+ looking at". §4's clean-tree fallback reaches the same place on its own, so
391
+ passing `--branch` is belt and braces rather than a separate rule.
392
+
393
+ **A mid-phase page does not get the commit.** Where the render took
394
+ `--buttons midrun`, the work is half a phase — committing it to look at it
395
+ running splits one phase across two commits and leaves a mess nobody asked for.
396
+ Say the phase needs to land first, re-render, and wait.
397
+
398
+ **Relay every refusal, and work around none of them.** `live take` refuses a
399
+ workbench another spec holds, a hotfix, a stateful spec, a branch touching
400
+ migrations, and a tree with no dev server listening. Each refusal names its own
401
+ way out. **Never park another spec's live session** to make room — that is
402
+ someone else's work, and freeing it is their decision. Re-render and wait, so
403
+ the reader can choose something else.
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
+
413
+ **`allow` writes a committed file, and that is worth a sentence.** It edits
414
+ `specs/.core/env.config.json` in the **primary checkout**, so it changes
415
+ behaviour for everyone who pulls and leaves that tree dirty — unlike the live
416
+ actions, which move a branch and write a gitignored receipt. The engine prints
417
+ the absolute path and whose tree it dirtied; relay that rather than letting a
418
+ shared setting change land silently. And it is **enable-only**: there is no
419
+ action that turns a tier off, because turning `network` off from a page reached
420
+ over the network kills the page doing the turning.
421
+
422
+ **`allow remote` permits publishing. It does not publish.** Publishing stays an
423
+ explicit ask in every case (§6), because the page it leaves behind is one this
424
+ tooling cannot remove.
425
+
338
426
  ## 3. Gate it on nothing
339
427
 
340
428
  **This skill has no preconditions and must never grow one.** Not tests passing,
@@ -364,18 +452,37 @@ help someone give one.
364
452
  ```
365
453
  skitterspec spec-env review <spec> # uncommitted work (the default)
366
454
  skitterspec spec-env review <spec> --branch # everything since the base branch
455
+ skitterspec spec-env review <spec> --run-reviewers # …and run review.reviewers
367
456
  skitterspec spec-env review serve # every spec, on localhost
368
457
  ```
369
458
 
370
- **The engine handles the switch.** A file when the reader is at this machine, a
371
- served URL when they are not: on a `remote` reader it stands its own server up
372
- and puts a URL the reader can open on the `open:` line. Both are free and neither
373
- publishes anything. You are not choosing between them; you are relaying whichever
374
- one the engine printed.
375
-
376
- The operator who does not want a LAN listener started for them sets
377
- `review.serveOnRemote: false` in `env.config.json`, and the `file://` link with
378
- its *will not open where you are reading* marker comes back.
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
+
475
+ **There is no switch left to handle.** The engine serves and prints a **stack** —
476
+ one line per tier, `local`, `network`, `remote`, each either a URL or the one
477
+ command that turns it on. All of it is free and none of it publishes anything.
478
+ You are not choosing between them; you are relaying every line it printed.
479
+ `.claude/rules/spec-reports.md` carries the shape and why.
480
+
481
+ The operator who does not want a LAN listener sets `review.allowNetwork: false`
482
+ in `env.config.json` — `network` then reads `off` with the command that turns it
483
+ back on, and `local` is the loopback page. Turning serving off entirely is
484
+ `review.serve: "never"`, and then `local` is the `file://` page, which says on
485
+ its own line that it cannot send a verdict.
379
486
 
380
487
  `serve` renders **per request**, so nothing it shows can be stale, and it lists
381
488
  every spec with a worktree rather than one. `--host 0.0.0.0` binds beyond
@@ -428,21 +535,29 @@ committing verdict or a recorded skip.
428
535
 
429
536
  **On `--page-only`, stop here** and report the path.
430
537
 
431
- ## 4a. Read the `reader:` line — never sniff for it yourself
432
-
433
- `spec-env review` reports where it believes the reader is, and
434
- **that is the only place this question is answered.** Three states:
435
-
436
- | `reader:` | What to offer |
437
- |-----------|---------------|
438
- | absent (`unknown`) | the `file://` URL, exactly as always. **Do not warn** — unknown is the ordinary state of a local machine |
439
- | `local` | the `file://` URL |
440
- | `remote` | the `open:` line as printed — the engine already served it. Pass on any `also:` lines too |
441
-
442
- **Never read an environment variable to decide this.** Not `SSH_CONNECTION`, not
443
- `CLAUDE_CODE_*`, not a tty check — the engine already did it, reports the answer
444
- on that line and in `--json`, and a second implementation here could not be
445
- tested and would drift from the first. The ranking and the traps
538
+ ## 4a. Relay the stack — every tier, never one you picked
539
+
540
+ `spec-env review` prints one line per tier and `--json` carries the same thing
541
+ as `tiers`. **Relay all of them, in that order**, whatever the `reader:` line
542
+ says:
543
+
544
+ | Tier | Carries |
545
+ |------|---------|
546
+ | `local` | the loopback URL — or the `file://` page when nothing served, which says it cannot send a verdict |
547
+ | `network` | the LAN URL and any `also:` alternates under it — or `off` with the command that turns it on |
548
+ | `remote` | the published URL and *a verdict here needs `/spec-reviewed`* — or `off` with the command that turns it on |
549
+
550
+ **The `reader:` line decides nothing here any more.** It is still printed and
551
+ still the only place that question is answered, but the offer no longer branches
552
+ on it — because branching on it is what produced a `file://` page for a session
553
+ detected `unknown`, a LAN URL for a phone off the network, and an address that
554
+ changed underneath a reader mid-session. A tier that is off keeps its line, so a
555
+ reader who has left the house can see the surface exists and ask for it.
556
+
557
+ **Never read an environment variable to decide anything about the offer.** Not
558
+ `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check — there is nothing left
559
+ for a detection to decide, and a second implementation of one could not be
560
+ tested and would drift. The ranking and the traps
446
561
  (`CLAUDE_CODE_ENTRYPOINT` describes the *process*, not the reader; stdin is never
447
562
  a tty under Claude Code) live in `review.js` beside the code, which is where they
448
563
  belong.
@@ -461,8 +576,9 @@ answer left.
461
576
 
462
577
  `review.reader` in `env.config.json` (`local` · `remote` · `detect`) lets the
463
578
  operator settle where they are reading, and an explicit value is believed without
464
- sniffing. `review.serveOnRemote` (default `true`) settles whether the engine may
465
- act on it.
579
+ sniffing. What the engine may *do* is settled by the tier settings instead —
580
+ `review.serve` (`always` · `never`), `review.allowNetwork` and
581
+ `review.allowRemote` — not by the reader.
466
582
 
467
583
  ## 4b. Wait for the verdict — because asking for one means waiting for it
468
584
 
@@ -483,8 +599,8 @@ said the page was **ready** rather than that it was **waiting**.
483
599
  **So the question is not "can I watch a file".** It is "am I asking?" — and the
484
600
  transport only decides what carries the answer back:
485
601
 
486
- - **A served page** posts to the local store; a file-watch sees it, and the
487
- steps below are that watch.
602
+ - **A served page** posts to the local store; the engine's own wait returns when
603
+ it lands, and the steps below run it.
488
604
  - **A `file://` page** has nothing to post to, so the reader pastes the pass and
489
605
  their next message carries it. Say you are holding and **end the turn** — that
490
606
  is the same wait, carried by the conversation. It is not a lesser one.
@@ -498,9 +614,20 @@ already arrived. Those get the `Review` row, no question, and nothing is owed.
498
614
 
499
615
  1. **Note the moment**, as an ISO timestamp, before you start. That instant is
500
616
  the entire scope of what may be claimed without a person naming it.
501
- 2. **Watch** `.spec-env/reviews/<spec>.pending.json` in the primary checkout,
502
- and **end the turn**. Not a poll and not a held-open turn: the operator has
503
- their terminal back, and the session costs nothing while they read.
617
+ 2. **Run the engine's wait in the background, and end the turn:**
618
+
619
+ ```
620
+ skitterspec spec-env review wait <spec> --since <timestamp>
621
+ ```
622
+
623
+ **Never a watcher of your own, and never a timeout.** It lasts as long as the
624
+ session, because a reader who walks away from a diff is the normal case — and
625
+ a loop composed here would be proven by nothing, which is how one written as
626
+ `[ "$x" \> "$y" ]` spun for five minutes in zsh and looked exactly like
627
+ patience. `/spec-next` §5 carries the full account.
628
+
629
+ Not a poll and not a held-open turn: the operator has their terminal back,
630
+ and the session costs nothing while they read.
504
631
  3. **On waking, let the engine choose:**
505
632
 
506
633
  ```
@@ -711,8 +838,8 @@ consumed rather than stored.
711
838
  purpose; someone who forgot they had voted has not, and only the report tells
712
839
  them apart.
713
840
 
714
- `Review` carries the files and `+`/`−`, the page's `open:` line, and the
715
- published URL when there is one. Where the page holds a review pass, it also
841
+ `Review` carries the files and `+`/`−`, and the tier stack — labelled, run
842
+ together with `·` because a row is one cell. Where the page holds a review pass, it also
716
843
  carries the three totals — files accepted, comments open, comments answered.
717
844
  `--json` reports those under `notes.totals`; read that, never the diff.
718
845
 
@@ -111,11 +111,40 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
111
111
  description (an **update** to the existing issue, plus a sub-issue per phase).
112
112
  Recording a snapshot here would declare the mirror already in sync and strand
113
113
  the issue showing the raw report forever.
114
+ - **Preserve the original, before anything replaces it.** Run this the moment
115
+ the spec file exists and **before the linking push**:
116
+
117
+ ```
118
+ skitterspec spec-sync preserve <spec>
119
+ ```
120
+
121
+ It posts the issue's current description onto the issue as a comment — the one
122
+ surface one-way sync never touches, so no push can clobber it. On the API path
123
+ it reads the description itself; without a key it prints the body and the
124
+ marker, and you post it with the Linear comment tool after checking the
125
+ comments for that marker.
126
+
127
+ **The ordering is the whole correctness condition.** Run before the push, this
128
+ keeps what the reporter filed. Run after it, it would keep the generated spec
129
+ and report success — which is why it is a step of its own here rather than a
130
+ line in the push sequence. The engine warns when it can tell it is late, but it
131
+ cannot always tell.
132
+
133
+ **It never fails the adoption.** A project that set
134
+ `intake.preserveOriginal: false`, an unreachable Linear, an issue with no
135
+ description, a comment Linear refused — every one of them exits 0 and says so.
136
+ Relay what it printed and carry on.
114
137
  - **Say what will happen** in the finish-up message. The linking step runs right
115
138
  after the spec is written, so the issue's description is replaced by the spec
116
- **then** — not on some later manual push. The reporter's words are not lost:
117
- they are quoted in the spec's **Problem** (or **Symptom**) section, and Linear
118
- keeps the original in the issue's history.
139
+ **then** — not on some later manual push. Say both halves: the description
140
+ becomes the spec, **and** the original is preserved as a comment on the same
141
+ issue, so the reporter can still read what they wrote.
142
+
143
+ **Do not send anyone to the issue's history for it.** This used to say Linear
144
+ keeps the original there, and that is true and useless: history is a diff
145
+ viewer nobody opens, it is not quotable, and it degrades to "it is in there
146
+ somewhere". The comment is the answer, and the other half is the spec's own
147
+ **Problem** (or **Symptom**) section quoting the reporter.
119
148
 
120
149
  ## 1. Establish the base version (the tag)
121
150
 
@@ -333,10 +362,14 @@ and **never auto-push git** — Linear's own automation reacts to real branch/PR
333
362
  events later. Report the Linear issue URL as part of the skill's finish-up
334
363
  message.
335
364
 
336
- **Only when all three hold**: `specs/.core/linear.config.json` exists, its
337
- `sync.fieldOwnership` includes `assignee`, and the spec carries a
365
+ **Only when all three hold**: `specs/.core/linear.config.json` exists, the repo
366
+ **owns** `assignee` in its `sync.fieldOwnership`, and the spec carries a
338
367
  `linear_identifier`. Any one missing → skip this step silently and carry on; a
339
- project that has not opted in must see no trace of assignment.
368
+ project that declined must see no trace of assignment.
369
+
370
+ Ownership is the **value**, not the key: `assignee` is owned by default, and
371
+ `"none"` is how a project declines it. Testing whether the key is *present* would
372
+ read as opted-in everywhere, since the default puts it in every config.
340
373
 
341
374
  **Never blocks, never fails the skill.** Everything below is best-effort: the
342
375
  branch is provisioned and the spec is moving either way, and an unassigned issue
@@ -517,30 +550,33 @@ this worktree is refused until a verdict is sent or
517
550
  `skitterspec spec-env review skip "<reason>"` records the decision to move on.
518
551
  The exit is always one command, and one of them is *"I am moving on"*.
519
552
 
520
- Relay the **`open:`** line rather than the bare path: a path is not clickable in
521
- any terminal, and a page nobody can open is a page nobody reads.
553
+ Relay the engine's **stack** — the `local:`, `network:` and `remote:` lines, all
554
+ three — rather than the bare `page:` path: a path is not clickable in any
555
+ terminal, and a page nobody can open is a page nobody reads. Relay the `live:`
556
+ line with it where the engine printed one, and nothing where it did not.
557
+ `.claude/rules/spec-reports.md` carries the shape, including why a rigid
558
+ contract took that line.
522
559
 
523
560
  - **Never write the review unasked**, and **never publish**. Publishing leaves
524
561
  something behind that this tooling cannot remove, so it is always an ask. A
525
562
  `file://` link is no use on a phone, and saying so **is** the ask —
526
563
  `/spec-diff` §6 owns how.
527
- **Follow the `reader:` line the engine printed — do not sniff for it.** It
528
- answers where the person reading this is sitting, and the offer changes with it:
529
-
530
- - **absent** (`unknown`) — the `file://` URL, exactly as always. **Do not warn:**
531
- unknown is the ordinary state of a local machine, and a warning there is an
532
- accusation against a healthy session.
533
- - **`local`** — the `file://` URL.
534
- - **`remote`** — the engine has already stood its local server up and put a URL
535
- the reader can open on `open:`. So there is **nothing special to say**: relay
536
- that line like any other. Any `also:` lines under it are the other addresses
537
- this machine has, offered because the best-guess one can be wrong — pass them
538
- on rather than editing them out.
539
-
540
- **Never read an environment variable to decide this** — not `SSH_CONNECTION`,
541
- not `CLAUDE_CODE_*`, not a tty check. The engine did it, reports it on that line
542
- and in `--json`, and a second implementation here could not be tested and would
543
- drift.
564
+ **The `reader:` line no longer decides anything here, and that is the point.**
565
+ It is still printed, and it is still the only place that question is answered —
566
+ but the offer does not change with it, because the stack lists every tier
567
+ whatever it says. Three reader states used to mean three different offers, and
568
+ that branching is exactly what produced a `file://` page on a session detected
569
+ `unknown`, a LAN URL for a phone off the network, and an address that changed
570
+ underneath a reader when detection flipped mid-session.
571
+
572
+ So: **relay all three tier lines, every time.** Any `also:` lines sit under
573
+ `network` — the other addresses this machine has, offered because the
574
+ best-guess one can be wrong — so pass them on rather than editing them out.
575
+
576
+ **Never read an environment variable to decide anything about the offer** — not
577
+ `SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
578
+ here for a detection to decide, and a second implementation of one could not be
579
+ tested and would drift.
544
580
 
545
581
  **Serving is the engine's to do; publishing is never.** A `remote` reader
546
582
  authorises a local server — one process, ended by one flag, leaving nothing
@@ -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`,
@@ -178,19 +178,27 @@ a state from the `list_issue_statuses` names you already have:
178
178
  automation closes them and a problem otherwise — `spec-sync doctor` warns about
179
179
  it either way, so say which it is.
180
180
 
181
- ## 7b. Should a spec's issue be assigned to whoever is building it? (optional)
181
+ ## 7b. Assignment is on — does this team want it off?
182
182
 
183
- Ask it plainly, in one line: with this on, `/spec-start` records the developer
184
- and their Linear issue is assigned to them, released again when the spec
185
- completes. Off, nothing about assignment happens at all.
183
+ Say what it does, in one line: `/spec-start` records the developer and their
184
+ Linear issue is assigned to them, released again when the spec completes. Then
185
+ ask whether to turn it **off**.
186
186
 
187
- **Offer once and take "no" for an answer.** It is off by default deliberately —
188
- a team whose PM owns assignment in Linear does not want the repo writing that
189
- field, and the cost of guessing wrong is somebody else's triage being
190
- overwritten.
187
+ **The question inverted at v16, and the reason is which mistake is recoverable.**
188
+ While it was opt-in, a repo that simply never added the line was
189
+ indistinguishable from one that had decided against it — so the only signal was
190
+ someone noticing weeks later that nobody was on the issue. On by default, a team
191
+ that does not want it says so once, here, and the answer is on the record.
191
192
 
192
- If they want it, pass **`--assign`** in step 8. Then settle who *they* are, so
193
- `/spec-start` never has to stop and ask:
193
+ **It cannot overwrite a PM's triage either way**, which is what makes the default
194
+ safe rather than merely convenient: a spec that records no assignee sends none,
195
+ and a snapshot with no assignee key means "never pushed" rather than "was null".
196
+ Assignment only ever writes specs *this repo* started.
197
+
198
+ If they want it off, pass **`--no-assign`** in step 8, and skip the rest of this
199
+ step — there is no identity to settle for a repo that does not assign.
200
+
201
+ Otherwise settle who *they* are, so `/spec-start` never has to stop and ask:
194
202
 
195
203
  ```
196
204
  skitterspec spec-sync whoami
@@ -210,7 +218,7 @@ setup.
210
218
  skitterspec spec-sync init-config \
211
219
  --team-id <uuid> [--team-key KEY] [--project-id <uuid>] \
212
220
  [--intake-label <name>] [--bug-labels a,b] [--hotfix-labels a,b] \
213
- [--state <bucket>=<name> …] [--assign] \
221
+ [--state <bucket>=<name> …] [--no-assign] \
214
222
  --states <statesfile> [--force] [--json]
215
223
  ```
216
224