@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
package/MIGRATION.md
CHANGED
|
@@ -1,5 +1,203 @@
|
|
|
1
1
|
# Migration guide
|
|
2
2
|
|
|
3
|
+
## `@skitterbyte/skitterspec` v21 → v22 (a review port per repo, and every render serves)
|
|
4
|
+
|
|
5
|
+
### Breaking change 1 — `review.serveOnRemote` is now `review.serve`
|
|
6
|
+
|
|
7
|
+
**Every render now stands the review server up**, and hands back an `http://`
|
|
8
|
+
URL instead of a `file://` one. It used to serve only when it detected that you
|
|
9
|
+
were reading from somewhere else — and that detection reads three environment
|
|
10
|
+
variables, so a plain local terminal got a `file://` page. A `file://` page has
|
|
11
|
+
**no server to POST to**, so the verdict buttons on it had nowhere to go: the
|
|
12
|
+
press-a-button-and-the-work-continues loop was missing from exactly the sessions
|
|
13
|
+
that are easiest to use.
|
|
14
|
+
|
|
15
|
+
**Which interfaces it listens on is `review.allowNetwork`** — see breaking
|
|
16
|
+
change 3, below. The change here is narrower than it looks: `file://` →
|
|
17
|
+
`http://127.0.0.1`, a page that opens on the machine holding it and, unlike
|
|
18
|
+
`file://`, can answer. Serving more never means listening wider; that is one
|
|
19
|
+
setting, and it is not this one.
|
|
20
|
+
|
|
21
|
+
**What to change.** `review.serveOnRemote: false` is still read as the new
|
|
22
|
+
`review.serve: "never"`, so a config that turned serving off keeps working. The
|
|
23
|
+
key is renamed because the old name would now claim to govern remote renders
|
|
24
|
+
while governing every one of them:
|
|
25
|
+
|
|
26
|
+
```jsonc
|
|
27
|
+
// specs/.core/env.config.json — before
|
|
28
|
+
"review": { "serveOnRemote": false }
|
|
29
|
+
// after
|
|
30
|
+
"review": { "serve": "never" }
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
`serveOnRemote: true` needs no translation — `"always"` is the default and does
|
|
34
|
+
what it did. Note what `"never"` costs you: the page falls back to `file://`,
|
|
35
|
+
and its buttons copy a command for you to paste rather than sending anything.
|
|
36
|
+
|
|
37
|
+
**A render that could not serve now says why** — `review.serve is "never"`, or
|
|
38
|
+
the failure naming the port to free — on the `open:` line and in `--json` as
|
|
39
|
+
`notServed`. A `file://` link with nothing said about it used to be the ordinary
|
|
40
|
+
outcome; now it can only mean the ask did not land.
|
|
41
|
+
|
|
42
|
+
**A spec with no worktree is served too.** A spec you have only just written has
|
|
43
|
+
no branch of its own, and the served route used to refuse it — so its page
|
|
44
|
+
existed and 404'd. It is now served as its own documents, listed in the index,
|
|
45
|
+
and accepts a verdict.
|
|
46
|
+
|
|
47
|
+
### Breaking change 2 — a review port per repo
|
|
48
|
+
|
|
49
|
+
**`review.servePort` now defaults to `"auto"`, not `7777`.** A repo that does
|
|
50
|
+
not pin the key moves to a port derived from its own path —
|
|
51
|
+
`7700 + hash(realpath(repoRoot)) % 100` — the first time `spec-env review serve`
|
|
52
|
+
starts after the upgrade.
|
|
53
|
+
|
|
54
|
+
**The one-time break is a link, and only a link.** A review page open on a
|
|
55
|
+
phone at that moment points at `7777`, and `7777` is no longer this repo's
|
|
56
|
+
server. The verdict you press there goes nowhere. **Re-render the page** —
|
|
57
|
+
`/spec-diff`, or `/spec-next`'s own render — and the new link works. Nothing on
|
|
58
|
+
disk is lost, no pass is dropped, and this happens once.
|
|
59
|
+
|
|
60
|
+
**Why not simply keep 7777.** It was shared by every repo on the machine, so the
|
|
61
|
+
second repo to start was refused, whoever hit that passed `--port`, and the
|
|
62
|
+
links they had already handed out pointed at another repo's daemon — a `404`,
|
|
63
|
+
reported in a grey line in the page footer. A derived port is stable for a given
|
|
64
|
+
tree across a restart, a reboot and a `--stop`, which is what a link handed out
|
|
65
|
+
yesterday needs.
|
|
66
|
+
|
|
67
|
+
### To keep a fixed port
|
|
68
|
+
|
|
69
|
+
Pin it, and nothing derives:
|
|
70
|
+
|
|
71
|
+
```jsonc
|
|
72
|
+
// specs/.core/env.config.json
|
|
73
|
+
"review": { "servePort": 7777 }
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
An explicit number always wins, exactly as it did before. Pin one when you want
|
|
77
|
+
a port you can memorise, or when two repos happen to derive the same one — a
|
|
78
|
+
hundred slots is a small chance of that, not no chance, and the server still
|
|
79
|
+
refuses a busy port rather than moving itself aside.
|
|
80
|
+
|
|
81
|
+
`spec-env review serve --status` now prints the port **and which of the three chose it** —
|
|
82
|
+
`--port`, `review.servePort`, or the derivation.
|
|
83
|
+
|
|
84
|
+
### Breaking change 3 — the reader no longer decides the bind: `review.allowNetwork` does
|
|
85
|
+
|
|
86
|
+
**Two new keys, and one of them changes a default.** The engine used to guess
|
|
87
|
+
where you were reading and pick a surface for you. It guessed wrong three
|
|
88
|
+
separate ways in one day — a `file://` page on a session detected `unknown`, a
|
|
89
|
+
LAN URL for a phone that had left the network, and an address that changed
|
|
90
|
+
underneath a reader when detection flipped mid-session. So it stopped guessing:
|
|
91
|
+
every render now lists every tier, labelled, in a fixed order.
|
|
92
|
+
|
|
93
|
+
```jsonc
|
|
94
|
+
// specs/.core/env.config.json — the new keys, with their defaults
|
|
95
|
+
"review": {
|
|
96
|
+
"allowNetwork": true, // the server binds every interface, so the page opens on your phone
|
|
97
|
+
"allowRemote": false // publishing is permitted at all — it permits, it never publishes
|
|
98
|
+
}
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
**`allowNetwork` defaults to `true`, and that is the behaviour change to read before upgrading.**
|
|
102
|
+
Before, a local or unknown reader got a loopback bind and a
|
|
103
|
+
remote one got every interface; now the setting decides, and its default is the
|
|
104
|
+
wide bind — which is what a remote reader already got, applied to every render.
|
|
105
|
+
The URL still carries the **serve token**, 48 random bits minted per server,
|
|
106
|
+
which remains the only thing deciding who can POST a verdict. A machine you
|
|
107
|
+
would rather not expose sets `"allowNetwork": false`, and `network:` then reads
|
|
108
|
+
`off` with the command that turns it back on.
|
|
109
|
+
|
|
110
|
+
**`allowRemote` defaults to `false`** and permits publishing without performing
|
|
111
|
+
it — a published page is one skitterspec cannot delete, so it stays an explicit
|
|
112
|
+
ask either way.
|
|
113
|
+
|
|
114
|
+
**`review.reader` still exists** and now decides only how a page's location is
|
|
115
|
+
*worded*. It no longer chooses the bind and no longer chooses which tiers appear.
|
|
116
|
+
|
|
117
|
+
### `/spec-remote-review` — a new slash command
|
|
118
|
+
|
|
119
|
+
Toggles `review.allowRemote`, and takes `on`/`off` when you would rather say
|
|
120
|
+
which. It exists because a render's `remote:` line has to name something you can
|
|
121
|
+
act on, and `skitterspec spec-env review allow remote` is not what anyone
|
|
122
|
+
reconstructs from a page they are reading on a phone. `init` and `update`
|
|
123
|
+
install it with the other commands; like them it is user-only, so nothing but you
|
|
124
|
+
can run it.
|
|
125
|
+
|
|
126
|
+
**It writes `specs/.core/env.config.json` in the primary checkout** — a
|
|
127
|
+
committed file, so it changes for everyone who pulls and leaves that tree dirty.
|
|
128
|
+
The engine says so when it does.
|
|
129
|
+
|
|
130
|
+
## `@skitterbyte/skitterspec-linear` v16 → v17 (a review port per repo, and every render serves)
|
|
131
|
+
|
|
132
|
+
The same two changes as `@skitterbyte/skitterspec` v21 → v22 above — this
|
|
133
|
+
distribution composes the same engine. Read that entry; nothing here is
|
|
134
|
+
Linear-specific.
|
|
135
|
+
|
|
136
|
+
**If you are coming from v15, read the v15 → v16 entry below as well.** 16.0.0
|
|
137
|
+
was bumped in the repo and never published, so npm went 15 → 17 and both
|
|
138
|
+
entries apply to you.
|
|
139
|
+
|
|
140
|
+
## `@skitterbyte/skitterspec-linear` v15 → v16 (assignment is on by default)
|
|
141
|
+
|
|
142
|
+
### Breaking change
|
|
143
|
+
|
|
144
|
+
**A spec's Linear issue is now assigned to whoever is building it.**
|
|
145
|
+
`sync.fieldOwnership.assignee` defaults to `"push"`; it was absent
|
|
146
|
+
before, and absent meant inert. From this version `/spec-start` stamps the
|
|
147
|
+
developer on the spec and the push assigns the issue, and `/spec-complete`
|
|
148
|
+
releases it — on every repo that has not said otherwise.
|
|
149
|
+
|
|
150
|
+
**To decline it**, one line in `specs/.core/linear.config.json`:
|
|
151
|
+
|
|
152
|
+
```jsonc
|
|
153
|
+
"sync": {
|
|
154
|
+
"fieldOwnership": {
|
|
155
|
+
"assignee": "none"
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
```
|
|
159
|
+
|
|
160
|
+
`none` is a new value in the ownership enum (`both|pull|push|none`) and means
|
|
161
|
+
*this repo does not own the field*: nothing is written, no hash is recorded in a
|
|
162
|
+
snapshot, and `spec-sync status` prints no assignee line — identical in every
|
|
163
|
+
respect to the old behaviour of never listing it. It has to be a value rather
|
|
164
|
+
than an omitted key, because the map merges **per key** onto the defaults: once
|
|
165
|
+
a field is owned by default, there is nothing an absent key can subtract.
|
|
166
|
+
|
|
167
|
+
**An explicit `"assignee": "push"` you already had is now redundant and harmless.**
|
|
168
|
+
Nothing rewrites it and nothing needs to.
|
|
169
|
+
|
|
170
|
+
### It cannot overwrite a PM's triage, and that is by construction
|
|
171
|
+
|
|
172
|
+
The concern this default has to answer is whether upgrading re-assigns or
|
|
173
|
+
un-assigns issues someone else owns. It cannot, for two reasons that predate it:
|
|
174
|
+
|
|
175
|
+
- **A spec that records no assignee sends none.** Only a spec the repo itself
|
|
176
|
+
stamped is ever pushed, so an issue a PM assigned in Linear is left alone.
|
|
177
|
+
- **A snapshot with no assignee key means "never pushed", not "was null".** Every
|
|
178
|
+
spec linked before this existed has exactly such a snapshot, and the diff emits
|
|
179
|
+
a *clear* only against an assignee it has a recorded hash for.
|
|
180
|
+
|
|
181
|
+
So the flip widens who gets **assigned** — specs you start from now on — and
|
|
182
|
+
cannot widen who gets **unassigned**. There is a regression test pinning this
|
|
183
|
+
(`sync-assignee-projection.test.js`, "THE UPGRADE CASE").
|
|
184
|
+
|
|
185
|
+
### `spec-sync init-config --assign` is gone; `--no-assign` replaces it
|
|
186
|
+
|
|
187
|
+
The flag's meaning inverted with the default, so it is removed rather than kept
|
|
188
|
+
as a silent no-op — a flag that still parses and does nothing would read as
|
|
189
|
+
"assignment configured" to anyone who wrote it before v16. `--assign` now fails
|
|
190
|
+
as an unknown flag, which is the louder and more useful answer. `--no-assign`
|
|
191
|
+
writes the `"none"` opt-out above.
|
|
192
|
+
|
|
193
|
+
### `spec-sync assign` now refuses a field the repo does not own
|
|
194
|
+
|
|
195
|
+
Previously it stamped the frontmatter in any repo and printed
|
|
196
|
+
`next: push it, so Linear agrees` — while `toFieldSet` dropped the field, so the
|
|
197
|
+
push never carried it. It now refuses, naming `sync.fieldOwnership.assignee` and
|
|
198
|
+
the value that enables it. Only `/spec-claim` enforced this before, so a script
|
|
199
|
+
or a direct CLI call got the untrue sentence.
|
|
200
|
+
|
|
3
201
|
## `@skitterbyte/skitterspec` v20 → v21 (the gate installs, and asking implies waiting)
|
|
4
202
|
|
|
5
203
|
If you upgraded to v20 and the commit gate never once fired, this is why. Two
|
|
@@ -21,6 +219,26 @@ The upgrade migrates you: your existing `PreToolUse` entry has its path
|
|
|
21
219
|
added all survive — and the retired `review-gate.js` is deleted. If you edited
|
|
22
220
|
that file yourself it is **kept**, with a warning, and left for you to remove.
|
|
23
221
|
|
|
222
|
+
**Check whether you already had a `review-gate.cjs` of your own.** `.cjs` is the
|
|
223
|
+
obvious way to work around the v20 crash, so anyone who fixed it by hand most
|
|
224
|
+
likely picked this exact filename — and this upgrade is the moment skitterspec
|
|
225
|
+
starts managing that path. A file already sitting there is **kept**, the real
|
|
226
|
+
hook is therefore never installed, and `review-gate.js` is pruned out from under
|
|
227
|
+
it. A hand-written shim that only `require`d the old script then fails open, so
|
|
228
|
+
the gate is silently absent under an update that reported success.
|
|
229
|
+
|
|
230
|
+
Two lines settle it:
|
|
231
|
+
|
|
232
|
+
```
|
|
233
|
+
head -3 .claude/hooks/review-gate.cjs # ours opens with a 'use strict' + a doc comment
|
|
234
|
+
npx @skitterbyte/skitterspec update --check # a line naming this path means yours was kept
|
|
235
|
+
```
|
|
236
|
+
|
|
237
|
+
If it is yours, take ours — `npx @skitterbyte/skitterspec update --force`, or
|
|
238
|
+
delete the file and re-run `update`. Later versions report this case in its own
|
|
239
|
+
words rather than as `your edit — kept`, but the manifest records the path after
|
|
240
|
+
the first upgrade, so that wording cannot reach anyone who has already run one.
|
|
241
|
+
|
|
24
242
|
### Bug fix
|
|
25
243
|
|
|
26
244
|
**`skitterspec update` now registers the hook.** v20's notes said `init` and
|
package/README.md
CHANGED
|
@@ -69,6 +69,42 @@ Add `--diff` to see those changes as a unified diff before deciding whether to
|
|
|
69
69
|
re-apply your edits on top, or `--force` to take the package version and lose
|
|
70
70
|
them. Your `specs/` content and live `.core` config are never touched.
|
|
71
71
|
|
|
72
|
+
## Everything it ships
|
|
73
|
+
|
|
74
|
+
<!-- commands:start -->
|
|
75
|
+
| | |
|
|
76
|
+
|---|---|
|
|
77
|
+
| `/spec` | Grill to a shared understanding, then write a groomed spec |
|
|
78
|
+
| `/spec-bug` | Reproduce with a failing test, then drive it red→green |
|
|
79
|
+
| `/spec-hotfix` | Fix the released version: fork from a tag, land by tag + cherry-pick |
|
|
80
|
+
| `/no-spec` | Work that genuinely has no spec — on its own branch all the same |
|
|
81
|
+
| `/spec-review` | Re-validate a spec against the code; refresh what drifted |
|
|
82
|
+
| `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 |
|
|
83
|
+
| `/spec-next` | Build the next phase of the spec in flight |
|
|
84
|
+
| `/spec-diff` | Read what a phase changed, on a page you can mark up |
|
|
85
|
+
| `/spec-reviewed` | Pick up a verdict pressed when nothing was waiting for it |
|
|
86
|
+
| `/spec-to-main` | Land the branch mid-spec, without finishing it |
|
|
87
|
+
| `/spec-complete` | Verify, land, tear down |
|
|
88
|
+
| `/spec-cancel` | Record why, stamp the header, tear down |
|
|
89
|
+
| `/spec-init` | Bootstrap or repair the workflow in a project |
|
|
90
|
+
| `/spec-connect` | Point your canonical `localhost` ports at one spec's stack |
|
|
91
|
+
| `/spec-live` | Check one spec out in the primary checkout, so your running server reloads it |
|
|
92
|
+
| `/spec-remote-review` | Permit (or forbid) reviewing from off your network |
|
|
93
|
+
| `/allow-main` | Allow writes on the base branch for this session — yours to run, never Claude's |
|
|
94
|
+
| `/spec-skip` | Move on from a phase without a verdict, reason recorded — yours to run, never Claude's |
|
|
95
|
+
| `/spec-push` | Repo → Linear, one-way |
|
|
96
|
+
| `/spec-status` | Read-only drift report |
|
|
97
|
+
| `/spec-list` | What the tracker holds, with each spec's folder name |
|
|
98
|
+
| `/spec-claim` | Take a spec, hand it back, or hand it to a teammate |
|
|
99
|
+
| `/spec-sync` | The `spec-sync` engine, for CI and local runs |
|
|
100
|
+
| `/spec-linear-setup` | Connect this repo to a Linear team |
|
|
101
|
+
<!-- commands:end -->
|
|
102
|
+
|
|
103
|
+
**The whole base is here**, because this is a strict superset — install this
|
|
104
|
+
*instead of* `@skitterbyte/skitterspec`, never alongside it. The base README
|
|
105
|
+
documents the review loop, the gate and the `review.*` keys; everything below is
|
|
106
|
+
what the Linear half adds on top.
|
|
107
|
+
|
|
72
108
|
## What the superset adds
|
|
73
109
|
|
|
74
110
|
On top of the base skills (`/spec`, `/spec-start`, `/spec-next`, isolation, …):
|
|
@@ -126,7 +162,7 @@ a question it cannot answer itself or a failure at the moment it happens:
|
|
|
126
162
|
| **Branch** | `spec/feat-orders` · 3 commits, clean |
|
|
127
163
|
| **Built** | POST /orders handler, orders schema |
|
|
128
164
|
| **Tests** | 128 passed · npm test |
|
|
129
|
-
| **Review** | 7 files, +212 −18 · [
|
|
165
|
+
| **Review** | 7 files, +212 −18 · **local** [http://127.0.0.1:7760/…](http://127.0.0.1:7760/…) · **network** [http://192.168.0.136:7760/…](http://192.168.0.136:7760/…) · **remote** off |
|
|
130
166
|
| **Follow-ups** | none |
|
|
131
167
|
| **Next** | `/spec-next` → phase 3 (Auth) |
|
|
132
168
|
|
|
@@ -20,24 +20,48 @@ every phase.
|
|
|
20
20
|
|
|
21
21
|
**Handing the review back.** The page takes marks: tick `✓ accept` per file as
|
|
22
22
|
you read, note anything against a line or a whole file, answer the questions a
|
|
23
|
-
written review asked — then **end it in a decision**.
|
|
24
|
-
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
you
|
|
28
|
-
the engine, which **holds** it and shows a six-digit code.
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
23
|
+
written review asked — then **end it in a decision**. At the end of a phase the
|
|
24
|
+
buttons are `✓ Commit`, `✓ Commit & Continue` (commit, then build the next
|
|
25
|
+
phase), `↺ Request changes` and `… Discuss first`. A spec that has just been
|
|
26
|
+
written gets `✓ Commit & Start` instead — the `commit-start` verdict, which is
|
|
27
|
+
the `commit && /spec-start` you would otherwise type. A **served** page hands
|
|
28
|
+
the pass to the engine, which **holds** it and shows a six-digit code. Committing
|
|
29
|
+
is unavailable while a note is open — you asked for something, so it cannot also
|
|
30
|
+
be fine — and it hands off to your own commit skill (`review.commitWith`,
|
|
31
|
+
`/commit` by default) rather than a copy living here. Fixes come back as
|
|
32
|
+
resolutions, so the next render shows each note struck through with what changed.
|
|
33
|
+
An accept remembers the file's content, so it lapses by itself when that file
|
|
34
|
+
changes again. The marks are information — nothing gates on them; the verdict is
|
|
35
|
+
the one thing you choose, once.
|
|
36
|
+
|
|
37
|
+
**A second opinion, when you want one** (`review.reviewers`, empty by default).
|
|
38
|
+
Point it at a code reviewer that runs from your terminal — CodeRabbit's CLI has
|
|
39
|
+
a free tier and `{ "use": "coderabbit" }` is the whole setup; anything printing
|
|
40
|
+
[rdjsonl](https://github.com/reviewdog/reviewdog) works too — and its findings
|
|
41
|
+
land on the page beside your own notes, each badged with the tool that found it
|
|
42
|
+
and linked to the line it is about. `/spec-next` runs them once per phase;
|
|
43
|
+
`/spec-diff --reviewers` is the mid-phase ask. **They never block a commit** —
|
|
44
|
+
reply to one and your reply does, because then a person has asked for something.
|
|
45
|
+
A reviewer that could not run says `did not run — <why>` rather than passing as
|
|
46
|
+
clean, because on the page you commit from those two must not look alike.
|
|
47
|
+
Adding one sends your diff to whatever the command talks to, which is why the
|
|
48
|
+
list starts empty and `init` never writes one.
|
|
49
|
+
|
|
50
|
+
**Above the verdicts sits one line that is not a verdict.** `▶ Put it live`
|
|
51
|
+
commits the phase, checks the branch out where your dev server can see it, and
|
|
52
|
+
hands you back the same page with the same options — so you can judge the change
|
|
53
|
+
by *using* it, not only by reading it. It clears no gate: you have looked at it
|
|
54
|
+
running and concluded nothing, so the phase still owes an answer.
|
|
55
|
+
|
|
56
|
+
**Every render lists where the page can be read**, labelled, in a fixed order —
|
|
57
|
+
`local`, `network`, `remote` — each either a URL or the one command that turns it
|
|
58
|
+
on, plus a `live:` line saying whether the change is also running. `local` and
|
|
59
|
+
`network` are two doors into one room: the same server and the same waiting
|
|
60
|
+
verdict, so one wait covers both. `remote` is a published page, a second store —
|
|
61
|
+
a verdict there needs `/spec-reviewed`, and it stays off until someone types
|
|
62
|
+
**`/spec-remote-review`**, which toggles it. Publishing is permitted by that
|
|
63
|
+
command, never performed by it: a published page is one this tooling cannot
|
|
64
|
+
remove.
|
|
41
65
|
|
|
42
66
|
**One ending.** Every spec skill finishes with the same block — a verdict
|
|
43
67
|
(`✅` · `⚠️` · `❌` · `⏸`), then a table of the fields that skill declares,
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Allow writes on the base branch for this session — bare allows it with no reason, a reason records why, `off` clears it
|
|
3
|
+
argument-hint: "[<reason> | off]"
|
|
4
|
+
allowed-tools: Bash({{exec}} skitterspec spec-env main allow:*)
|
|
5
|
+
disable-model-invocation: true
|
|
6
|
+
---
|
|
7
|
+
!`{{exec}} skitterspec spec-env main allow $ARGUMENTS`
|
|
8
|
+
|
|
9
|
+
Relay the engine output above verbatim. Add nothing and run nothing else.
|
|
10
|
+
|
|
11
|
+
**Only you can run this, and that is the whole guard.** The main-guard hook
|
|
12
|
+
refuses an `Edit` or a `Write` in the primary checkout while it sits on the base
|
|
13
|
+
branch, and it names two exits: move the work with `/no-spec` or `/spec-start`,
|
|
14
|
+
or have you lift the guard. Claude can take the first exit on its own and can
|
|
15
|
+
never take the second — a guard the model can lift is decoration, which is the
|
|
16
|
+
same line `/spec-reviewed` draws.
|
|
17
|
+
|
|
18
|
+
**Give it a reason.** `/allow-main fixing the lockfile by hand` records why; bare
|
|
19
|
+
records `none given`. The reason is the part a reviewer can argue with, exactly
|
|
20
|
+
as with a `Gating:` header — and it is what you will read when you wonder later
|
|
21
|
+
why the base branch has an uncommitted file on it.
|
|
22
|
+
|
|
23
|
+
**It lapses with the session where it can.** The allow is recorded against this
|
|
24
|
+
session, so it ends when the session does. Where the harness exposes no session
|
|
25
|
+
id it degrades to a repo-wide allow that outlives the session and is cleared only
|
|
26
|
+
by `/allow-main off`; the engine says which kind you got, so do not read a bare
|
|
27
|
+
"allowed" as temporary.
|
|
28
|
+
|
|
29
|
+
**It is machine-local and gitignored.** Unlike `/spec-remote-review`, this writes
|
|
30
|
+
nothing anyone else pulls: it is your decision about your checkout, not the
|
|
31
|
+
project's policy. The project-wide switch is `guards.mainIsLandingZone` in
|
|
32
|
+
`specs/.core/env.config.json`, and turning that off is a different, committed
|
|
33
|
+
decision.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Permit or forbid publishing a review for a reader off your network — bare toggles it, `on`/`off` set it explicitly
|
|
3
|
+
argument-hint: "[on | off]"
|
|
4
|
+
allowed-tools: Bash({{exec}} skitterspec spec-env review allow remote:*)
|
|
5
|
+
disable-model-invocation: true
|
|
6
|
+
---
|
|
7
|
+
!`{{exec}} skitterspec spec-env review allow remote --set "$ARGUMENTS"`
|
|
8
|
+
|
|
9
|
+
Relay the engine output above verbatim. Add nothing and run nothing else.
|
|
10
|
+
|
|
11
|
+
**Bare toggles.** That is the common case: you are looking at a render whose
|
|
12
|
+
`remote:` line says which way it currently is, and what you want is the other
|
|
13
|
+
one. `on` and `off` are there for when you are not looking at it.
|
|
14
|
+
|
|
15
|
+
**It permits publishing; it publishes nothing.** A published page is one
|
|
16
|
+
skitterspec cannot delete, so publishing stays an explicit ask
|
|
17
|
+
(`/spec-diff` §6) — and a verdict pressed on one needs `/spec-reviewed`, because
|
|
18
|
+
nothing pushes from an artifact's store into a conversation.
|
|
19
|
+
|
|
20
|
+
**It writes a committed file.** `specs/.core/env.config.json` in the primary
|
|
21
|
+
checkout, whichever tree you ran this from — so it changes for everyone who
|
|
22
|
+
pulls and leaves that tree dirty. The engine says so; do not soften it.
|
|
@@ -0,0 +1,24 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Move on from a phase without a verdict, with the reason on the record — clears the review gate
|
|
3
|
+
argument-hint: "\"<reason>\""
|
|
4
|
+
allowed-tools: Bash({{exec}} skitterspec spec-env review skip:*)
|
|
5
|
+
disable-model-invocation: true
|
|
6
|
+
---
|
|
7
|
+
!`{{exec}} skitterspec spec-env review skip "$ARGUMENTS"`
|
|
8
|
+
|
|
9
|
+
Relay the engine output above verbatim. Add nothing and run nothing else.
|
|
10
|
+
|
|
11
|
+
**It refuses with no reason, and that refusal is the feature.** A skip with no
|
|
12
|
+
reason is indistinguishable from nobody having looked — where
|
|
13
|
+
`none: additive, nothing to revert` is a decision a reviewer can argue with. If
|
|
14
|
+
the engine asked for a reason, relay that and stop; do not supply one on the
|
|
15
|
+
operator's behalf.
|
|
16
|
+
|
|
17
|
+
**It is one of exactly two exits**, and the other is a committing verdict on the
|
|
18
|
+
page. Nothing else discharges a phase's obligation — not a mid-run `Continue`,
|
|
19
|
+
not an action, not a render.
|
|
20
|
+
|
|
21
|
+
**Only you can run it.** Like `/allow-main`, this lifts a guard aimed at Claude,
|
|
22
|
+
so Claude must not be able to lift it. `/spec-connect` and `/spec-live` are
|
|
23
|
+
user-only for the milder reason that there is no judgement to apply; this one is
|
|
24
|
+
user-only because of who the guard is for.
|
package/assets/core/SETUP.md
CHANGED
|
@@ -234,18 +234,22 @@ Sections listed in `sync.localOnlySections` (default: **State log**, **Changelog
|
|
|
234
234
|
**Open questions**) are stripped from the pushed description — they never leave
|
|
235
235
|
the repo.
|
|
236
236
|
|
|
237
|
-
### Assignment (
|
|
237
|
+
### Assignment (on by default)
|
|
238
238
|
|
|
239
|
-
|
|
240
|
-
|
|
241
|
-
|
|
242
|
-
— see **Assignment** in `linear.config.md` for the full
|
|
239
|
+
The spec issue is assigned to whoever is building it: `/spec-start` records them,
|
|
240
|
+
and the issue is released automatically when the spec completes. To decline it,
|
|
241
|
+
set `"assignee": "none"` in `sync.fieldOwnership` (or pass `--no-assign` to
|
|
242
|
+
`spec-sync init-config`) — see **Assignment** in `linear.config.md` for the full
|
|
243
|
+
rules.
|
|
244
|
+
|
|
245
|
+
It cannot overwrite an assignment a PM made in Linear: a spec that records nobody
|
|
246
|
+
sends nothing, and only an assignee this repo pushed is ever cleared.
|
|
243
247
|
|
|
244
248
|
You do not configure *who you are*: it comes from your own API key. Check it
|
|
245
249
|
with `skitterspec spec-sync whoami` (`--set` overrides it if the key is shared or
|
|
246
250
|
a bot's), and `skitterspec spec-sync users <name-or-email>` looks somebody up.
|
|
247
251
|
`skitterspec spec-sync doctor` reports the resolved identity, and stays quiet
|
|
248
|
-
about it in a project that
|
|
252
|
+
about it in a project that declined the field.
|
|
249
253
|
|
|
250
254
|
## 7. What to commit
|
|
251
255
|
|
|
@@ -40,10 +40,13 @@
|
|
|
40
40
|
},
|
|
41
41
|
"review": {
|
|
42
42
|
"reader": "detect",
|
|
43
|
-
"servePort":
|
|
44
|
-
"
|
|
43
|
+
"servePort": "auto",
|
|
44
|
+
"serve": "always",
|
|
45
|
+
"allowNetwork": true,
|
|
46
|
+
"allowRemote": false,
|
|
45
47
|
"commitWith": "/commit",
|
|
46
|
-
"required": true
|
|
48
|
+
"required": true,
|
|
49
|
+
"reviewers": []
|
|
47
50
|
},
|
|
48
51
|
"live": {
|
|
49
52
|
"migrations": []
|