@skitterbyte/skitterspec-linear 18.3.1 → 19.0.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 +141 -1
- package/README.md +9 -7
- package/assets/core/SETUP.md +4 -4
- package/assets/core/linear.config.md +53 -47
- package/assets/rules/spec-planning.md +13 -3
- package/assets/rules/spec-reports.md +19 -4
- package/assets/skills/spec/SKILL.md +1 -1
- package/assets/skills/spec-bug/SKILL.md +4 -2
- package/assets/skills/spec-hotfix/SKILL.md +4 -2
- package/assets/skills/spec-linear-setup/SKILL.md +9 -35
- package/assets/skills/spec-list/SKILL.md +13 -1
- package/assets/skills/spec-next/SKILL.md +3 -1
- package/assets/skills/spec-push/SKILL.md +1 -1
- package/assets/skills/spec-status/SKILL.md +30 -26
- package/assets/skills/spec-sync/SKILL.md +6 -5
- package/package.json +1 -1
- package/src/cli.js +6 -25
- package/src/env/review.js +47 -2
- package/src/vendor/linear/api.js +20 -1
- package/src/vendor/linear/cli-sync.js +36 -267
- package/src/vendor/linear/config.js +8 -47
- package/src/vendor/linear/doctor.js +4 -66
- package/src/vendor/provider-kit/src/config.js +101 -48
- package/src/vendor/provider-kit/src/list-assignee.js +71 -0
- package/src/vendor/provider-kit/src/list-rows.js +35 -0
- package/src/vendor/provider-kit/src/released.js +27 -77
- package/src/vendor/provider-kit/src/specs.js +89 -7
- package/src/vendor/sync-core/index.js +3 -4
- package/src/vendor/sync-core/src/compare.js +6 -6
- package/src/vendor/sync-core/src/normalize.js +30 -57
- package/assets/core/ci-stages.md +0 -110
- package/src/vendor/provider-kit/src/releases.js +0 -380
package/MIGRATION.md
CHANGED
|
@@ -1,5 +1,104 @@
|
|
|
1
1
|
# Migration guide
|
|
2
2
|
|
|
3
|
+
## `@skitterbyte/skitterspec-github` v1 → v2 (tell, don't track)
|
|
4
|
+
|
|
5
|
+
Skitterspec now tells GitHub about **its own** transitions and nothing
|
|
6
|
+
else. It writes nothing about releases or deployments, and it never reads a
|
|
7
|
+
ticket's state back.
|
|
8
|
+
|
|
9
|
+
### Breaking change 1 — The `release create|deployed|complete|reconcile` verbs are removed
|
|
10
|
+
|
|
11
|
+
They exit 1 with one line naming `spec-sync released <range> --json`. A pipeline
|
|
12
|
+
still calling them goes red rather than silently believing it mirrors
|
|
13
|
+
anything. **To migrate**, replace the step with your own script over the
|
|
14
|
+
release's ticket list:
|
|
15
|
+
|
|
16
|
+
```sh
|
|
17
|
+
skitterspec-github spec-sync released "<previous-tag>..<tag>" --json
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
|
|
21
|
+
linked), so the script needs no second lookup. Set whatever GitHub field,
|
|
22
|
+
state or release object your process uses from that list. The checkout needs
|
|
23
|
+
`fetch-depth: 0` so the previous tag is visible.
|
|
24
|
+
|
|
25
|
+
### Breaking change 2 — The `releases` block (`deployedField`, `series`) and `release.stages` are retired
|
|
26
|
+
|
|
27
|
+
The keys are ignored, like any unknown key, so a config carrying them still
|
|
28
|
+
loads. `spec-sync doctor` names them as unused config (a `warn`, never a
|
|
29
|
+
failure). Delete them when you remove the CI step.
|
|
30
|
+
|
|
31
|
+
### Breaking change 3 — no state drift
|
|
32
|
+
|
|
33
|
+
`spec-sync status --remote` and `/spec-status` no longer compare the tracker's
|
|
34
|
+
state with the spec's. A ticket someone moved on GitHub is not reported, and
|
|
35
|
+
push still resends state only when the spec itself moves. The edited-description
|
|
36
|
+
warning is unchanged.
|
|
37
|
+
|
|
38
|
+
## `@skitterbyte/skitterspec-azure-boards` v1 → v2 (tell, don't track)
|
|
39
|
+
|
|
40
|
+
Skitterspec now tells Azure Boards about **its own** transitions and nothing
|
|
41
|
+
else. It writes nothing about releases or deployments, and it never reads a
|
|
42
|
+
ticket's state back.
|
|
43
|
+
|
|
44
|
+
### Breaking change 1 — The `release create|deployed|complete` verbs are removed
|
|
45
|
+
|
|
46
|
+
They exit 1 with one line naming `spec-sync released <range> --json`. A pipeline
|
|
47
|
+
still calling them goes red rather than silently believing it mirrors
|
|
48
|
+
anything. **To migrate**, replace the step with your own script over the
|
|
49
|
+
release's ticket list:
|
|
50
|
+
|
|
51
|
+
```sh
|
|
52
|
+
skitterspec-azure-boards spec-sync released "<previous-tag>..<tag>" --json
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
|
|
56
|
+
linked), so the script needs no second lookup. Set whatever Azure Boards field,
|
|
57
|
+
state or release object your process uses from that list. The checkout needs
|
|
58
|
+
`fetch-depth: 0` so the previous tag is visible.
|
|
59
|
+
|
|
60
|
+
### Breaking change 2 — The `releases` block (`workItemType`, `series`, `ticketTag`, `deployedField`) and `release.stages` are retired
|
|
61
|
+
|
|
62
|
+
The keys are ignored, like any unknown key, so a config carrying them still
|
|
63
|
+
loads. `spec-sync doctor` names them as unused config (a `warn`, never a
|
|
64
|
+
failure). Delete them when you remove the CI step.
|
|
65
|
+
|
|
66
|
+
### Breaking change 3 — no state drift
|
|
67
|
+
|
|
68
|
+
`spec-sync status --remote` and `/spec-status` no longer compare the tracker's
|
|
69
|
+
state with the spec's. A ticket someone moved on Azure Boards is not reported, and
|
|
70
|
+
push still resends state only when the spec itself moves. The edited-description
|
|
71
|
+
warning is unchanged.
|
|
72
|
+
|
|
73
|
+
## `@skitterbyte/skitterspec-jira` v1 → v2 (tell, don't track)
|
|
74
|
+
|
|
75
|
+
Skitterspec now tells Jira about **its own** transitions and nothing else. It
|
|
76
|
+
writes nothing about releases or deployments, and it never reads an issue's
|
|
77
|
+
status back.
|
|
78
|
+
|
|
79
|
+
### Breaking change 1 — no status drift
|
|
80
|
+
|
|
81
|
+
`spec-sync status --remote` and `/spec-status` no longer compare Jira's status
|
|
82
|
+
with the spec's. An issue someone moved on Jira is not reported, and push still
|
|
83
|
+
transitions it only when the spec itself moves. The edited-description warning
|
|
84
|
+
is unchanged.
|
|
85
|
+
|
|
86
|
+
### Breaking change 2 — `release.stages` retired
|
|
87
|
+
|
|
88
|
+
It was accepted and validated before, and never acted on. It is now ignored
|
|
89
|
+
like any unknown key, and `spec-sync doctor` names it as unused config (a
|
|
90
|
+
`warn`, never a failure). Delete it.
|
|
91
|
+
|
|
92
|
+
### Also — `released --json` names the spec
|
|
93
|
+
|
|
94
|
+
Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
|
|
95
|
+
linked), so CI can record a release, for example as a fix version, without a
|
|
96
|
+
second lookup:
|
|
97
|
+
|
|
98
|
+
```sh
|
|
99
|
+
skitterspec-jira spec-sync released "<previous-tag>..<tag>" --json
|
|
100
|
+
```
|
|
101
|
+
|
|
3
102
|
## `@skitterbyte/skitterspec` v23 → v24 (hotfix land runs the release itself)
|
|
4
103
|
|
|
5
104
|
### Breaking change 1 — `spec-env hotfix land` runs its steps, and holds before the carry
|
|
@@ -275,7 +374,48 @@ can run it.
|
|
|
275
374
|
committed file, so it changes for everyone who pulls and leaves that tree dirty.
|
|
276
375
|
The engine says so when it does.
|
|
277
376
|
|
|
278
|
-
## `@skitterbyte/skitterspec-linear` v18 → v19 (hotfix land runs the release itself)
|
|
377
|
+
## `@skitterbyte/skitterspec-linear` v18 → v19 (tell, don't track; hotfix land runs the release itself)
|
|
378
|
+
|
|
379
|
+
Skitterspec now tells Linear about **its own** transitions and nothing
|
|
380
|
+
else. It writes nothing about releases or deployments, and it never reads a
|
|
381
|
+
ticket's state back.
|
|
382
|
+
|
|
383
|
+
### Breaking change 1 — The `spec-sync stage` verb is removed
|
|
384
|
+
|
|
385
|
+
It exits 1 with one line naming `spec-sync released <range> --json`. A pipeline
|
|
386
|
+
still calling it goes red rather than silently believing it mirrors
|
|
387
|
+
anything. **To migrate**, replace the step with your own script over the
|
|
388
|
+
release's ticket list:
|
|
389
|
+
|
|
390
|
+
```sh
|
|
391
|
+
skitterspec-linear spec-sync released "<previous-tag>..<tag>" --json
|
|
392
|
+
```
|
|
393
|
+
|
|
394
|
+
Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
|
|
395
|
+
linked), so the script needs no second lookup. Set whatever Linear field,
|
|
396
|
+
state or release object your process uses from that list. The checkout needs
|
|
397
|
+
`fetch-depth: 0` so the previous tag is visible.
|
|
398
|
+
|
|
399
|
+
### Breaking change 2 — `release.stages` (the deployment ladder) is retired
|
|
400
|
+
|
|
401
|
+
The keys are ignored, like any unknown key, so a config carrying them still
|
|
402
|
+
loads. `spec-sync doctor` names them as unused config (a `warn`, never a
|
|
403
|
+
failure). Delete them when you remove the CI step.
|
|
404
|
+
|
|
405
|
+
### Breaking change 3 — no state drift
|
|
406
|
+
|
|
407
|
+
`spec-sync status --remote` and `/spec-status` no longer compare the tracker's
|
|
408
|
+
state with the spec's. A ticket someone moved on Linear is not reported, and
|
|
409
|
+
push still resends state only when the spec itself moves. The edited-description
|
|
410
|
+
warning is unchanged.
|
|
411
|
+
|
|
412
|
+
**A ladder rung no longer reads as `complete`.** Where a state was a
|
|
413
|
+
`release.stages` rung, the live `spec-sync list` now shows it as unmapped. To
|
|
414
|
+
keep it reading as finished, list it as an alias:
|
|
415
|
+
`"complete": ["Done", "On Test"]`. `init-config --stage` is gone too, and is
|
|
416
|
+
refused as an unknown flag.
|
|
417
|
+
|
|
418
|
+
### Also — hotfix land runs the release itself
|
|
279
419
|
|
|
280
420
|
The same change as `@skitterbyte/skitterspec` v23 → v24 above — this
|
|
281
421
|
distribution composes the same engine. Read that entry; nothing here is
|
package/README.md
CHANGED
|
@@ -93,7 +93,7 @@ them. Your `specs/` content and live `.core` config are never touched.
|
|
|
93
93
|
| `/allow-main` | Allow writes on the base branch for this session — yours to run, never Claude's |
|
|
94
94
|
| `/spec-skip` | Move on from a phase without a verdict, reason recorded — yours to run, never Claude's |
|
|
95
95
|
| `/spec-push` | Repo → Linear, one-way |
|
|
96
|
-
| `/spec-status` | Read-only
|
|
96
|
+
| `/spec-status` | Read-only report: what would push, and any edited description |
|
|
97
97
|
| `/spec-list` | What the tracker holds, with each spec's folder name |
|
|
98
98
|
| `/spec-claim` | Take a spec, hand it back, or hand it to a teammate |
|
|
99
99
|
| `/spec-sync` | The `spec-sync` engine, for CI and local runs |
|
|
@@ -109,9 +109,10 @@ what the Linear half adds on top.
|
|
|
109
109
|
|
|
110
110
|
On top of the base skills (`/spec`, `/spec-start`, `/spec-next`, isolation, …):
|
|
111
111
|
|
|
112
|
-
- **`/spec-status`** — read-only
|
|
113
|
-
update,
|
|
114
|
-
(see **Phase status** below).
|
|
112
|
+
- **`/spec-status`** — read-only report: what the next push would create /
|
|
113
|
+
update, a description someone edited in Linear since the last push, and any
|
|
114
|
+
phase whose status signals disagree (see **Phase status** below). It never
|
|
115
|
+
reads a ticket's state back. Changes nothing.
|
|
115
116
|
- **`/spec-push`** — repo → Linear, one-way. Diffs the spec against a committed
|
|
116
117
|
last-pushed snapshot and applies only what changed (issue description + state,
|
|
117
118
|
phase sub-issues), stamping the returned ids back into the spec.
|
|
@@ -198,8 +199,9 @@ description as a read-only checklist (`mapping.tasks: "checklist"`, the default;
|
|
|
198
199
|
`"none"` keeps the Goal line alone) — no issue is created per task, and a box
|
|
199
200
|
ticked in Linear is overwritten by the next push. Priority, labels, cycles and comments are **Linear-native triage** — the
|
|
200
201
|
PM's to set in Linear; one-way sync neither pushes nor reads them, so they're
|
|
201
|
-
never clobbered. A workflow-state a teammate moves in Linear is
|
|
202
|
-
|
|
202
|
+
never clobbered. A workflow-state a teammate moves in Linear is left alone —
|
|
203
|
+
skitterspec never reads state back, and push resends it only when the spec
|
|
204
|
+
itself moves. **Last-pushed snapshots**
|
|
203
205
|
(`specs/.core/linear-base/`, content hashes) are committed so push sends only what
|
|
204
206
|
changed.
|
|
205
207
|
|
|
@@ -240,7 +242,7 @@ sub-issue. `/spec-push` and `/spec-status` print the mode that resolved. See
|
|
|
240
242
|
**Which Project a spec lands in** is asked once, when the issue is first created
|
|
241
243
|
— a filterable list of your team's projects, defaulting to `linear.projectId` and
|
|
242
244
|
always offering *None*. It's passed on the create call only and never stored, so
|
|
243
|
-
re-homing a spec issue in Linear sticks: it
|
|
245
|
+
re-homing a spec issue in Linear sticks: it isn't reported and won't be moved
|
|
244
246
|
back on the next push.
|
|
245
247
|
|
|
246
248
|
**Starting from an issue** (the `intake` block in the config): `/spec SKI-123`
|
package/assets/core/SETUP.md
CHANGED
|
@@ -70,7 +70,7 @@ claude mcp list
|
|
|
70
70
|
```
|
|
71
71
|
|
|
72
72
|
> Read-only trial: use `https://mcp.linear.app/mcp/readonly` to exercise
|
|
73
|
-
> `/spec-status` (
|
|
73
|
+
> `/spec-status` (read-only report) without granting write access. `/spec-push`
|
|
74
74
|
> needs the full (writable) endpoint.
|
|
75
75
|
|
|
76
76
|
## 3. Configure — run `/spec-linear-setup`
|
|
@@ -200,7 +200,7 @@ Two ways to get there:
|
|
|
200
200
|
|
|
201
201
|
| Command | Direction | What it does |
|
|
202
202
|
|---------|-----------|--------------|
|
|
203
|
-
| `/spec-status` | — | Read-only
|
|
203
|
+
| `/spec-status` | — | Read-only report: what would push (create/update), and whether the issue's description was edited in Linear since the last push. Writes nothing. |
|
|
204
204
|
| `/spec-push` | repo → Linear | Computes a create/update plan vs the last-pushed snapshot and applies it (issue description/state, phase sub-issues), stamping new ids back into the spec. |
|
|
205
205
|
| `/spec-claim` | repo → Linear | Take a spec over, `--release` it, or hand it `--to` a teammate. Records the owner in the spec, then pushes. Needs assignment enabled (below). |
|
|
206
206
|
| `/spec-list` | Linear → you | Read-only listing of every spec Linear holds — id, title, state, who holds it and the local spec name to start it by. Filters by state, backlog order, or assignee. Writes nothing. |
|
|
@@ -221,8 +221,8 @@ have not got.
|
|
|
221
221
|
|
|
222
222
|
Tasks, priority, labels, cycles and comments are **Linear-native triage** (or
|
|
223
223
|
repo-only) — never pushed, so they're never clobbered. A workflow-state a teammate
|
|
224
|
-
moves in Linear is
|
|
225
|
-
|
|
224
|
+
moves in Linear is left alone: skitterspec never reads state back, and push
|
|
225
|
+
resends it only when the spec itself moves.
|
|
226
226
|
|
|
227
227
|
The spec is one issue and each phase a **sub-issue** (`parentId` = the spec
|
|
228
228
|
issue). The link ids live in frontmatter — `linear_identifier` on the overview,
|
|
@@ -7,7 +7,7 @@ a Linear issue and each phase a sub-issue; a phase's tasks ride along inside
|
|
|
7
7
|
that sub-issue's description as a read-only checklist. Content is
|
|
8
8
|
pushed up and never read back or merged — `/spec-push` diffs the spec against a
|
|
9
9
|
committed **last-pushed snapshot** and applies only what changed; `/spec-status`
|
|
10
|
-
is a read-only
|
|
10
|
+
is a read-only report of what would push. The `sync.fieldOwnership` map now just selects the
|
|
11
11
|
projection field set (every field is repo-owned and pushed).
|
|
12
12
|
|
|
13
13
|
**Every Linear step is gated on this file.** While `specs/.core/linear.config.json`
|
|
@@ -90,14 +90,9 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
|
|
|
90
90
|
"overviewFile": "00-overview.md"
|
|
91
91
|
},
|
|
92
92
|
|
|
93
|
-
//
|
|
94
|
-
//
|
|
95
|
-
// stage-aware path is unused. See "The deployment ladder" below.
|
|
96
|
-
//
|
|
97
|
-
// `ignorePaths` is what `released`/`stage` treat as BOOKKEEPING rather than
|
|
98
|
-
// shipped work — see "Bookkeeping commits" below. `[]` opts out.
|
|
93
|
+
// `ignorePaths` is what `released` treats as BOOKKEEPING rather than shipped
|
|
94
|
+
// work — see "Bookkeeping commits" below. `[]` opts out.
|
|
99
95
|
"release": {
|
|
100
|
-
"stages": [],
|
|
101
96
|
"ignorePaths": ["specs/"]
|
|
102
97
|
},
|
|
103
98
|
|
|
@@ -139,6 +134,32 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
|
|
|
139
134
|
}
|
|
140
135
|
```
|
|
141
136
|
|
|
137
|
+
## More than one name per bucket — read-only aliases
|
|
138
|
+
|
|
139
|
+
A board usually has more states than the four buckets: "Blocked", "Next
|
|
140
|
+
Sprint", "Released". A bucket's value may be an **array** instead of a string:
|
|
141
|
+
|
|
142
|
+
```jsonc
|
|
143
|
+
"states": {
|
|
144
|
+
"in-progress": ["Active", "Blocked"],
|
|
145
|
+
"complete": ["Closed", "Released"]
|
|
146
|
+
}
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
- **The first name is the only one push writes**, and only when the spec
|
|
150
|
+
itself moves. The rest are never written.
|
|
151
|
+
- **The rest are read as that bucket** by the listing: the live
|
|
152
|
+
`spec-sync list` hides every `complete` / `cancelled` name, `--state <bucket>`
|
|
153
|
+
matches all of them, and `spec-sync states` lists each alias under its
|
|
154
|
+
bucket.
|
|
155
|
+
- **Nothing is pulled.** An alias changes what the report *says* about a
|
|
156
|
+
ticket, never the spec.
|
|
157
|
+
- A plain string works exactly as before. An alias that also names another
|
|
158
|
+
bucket is refused at load. An alias the tracker lacks is reported by
|
|
159
|
+
`spec-sync states` but never blocks a push, because it is never written.
|
|
160
|
+
- `spec-sync status` never reads a ticket's state at all, aliased or not —
|
|
161
|
+
see "One direction" below.
|
|
162
|
+
|
|
142
163
|
## Assignment (`sync.fieldOwnership.assignee`)
|
|
143
164
|
|
|
144
165
|
**On by default since v16.** The spec issue is assigned to whoever is building
|
|
@@ -201,54 +222,37 @@ reusing the identity above rather than a second copy of it. It writes nothing,
|
|
|
201
222
|
and it says what it did not show — the count, the archived exclusion, and any
|
|
202
223
|
cap — rather than implying a completeness it never checked.
|
|
203
224
|
|
|
204
|
-
##
|
|
225
|
+
## Releases and deploys — the host project's to write
|
|
205
226
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
227
|
+
Skitterspec tells Linear about **its own** transitions: a spec starting,
|
|
228
|
+
a phase finishing, a spec completing or being cancelled. It never reads a
|
|
229
|
+
ticket's state back, and it writes nothing about releases or deployments. Where
|
|
230
|
+
a ticket goes after its spec is `complete` — on test, in prod — belongs to the
|
|
231
|
+
environment, and the project's own CI or scripts record it however they like.
|
|
210
232
|
|
|
211
|
-
|
|
212
|
-
|
|
213
|
-
"stages": [
|
|
214
|
-
{ "key": "test", "state": "On Test" },
|
|
215
|
-
{ "key": "demo", "state": "Ready for Demo" },
|
|
216
|
-
{ "key": "prod", "state": "Done" }
|
|
217
|
-
]
|
|
218
|
-
}
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
- **`key`** is what CI names (`spec-sync stage test …`); **`state`** is the
|
|
222
|
-
Linear issue state it moves to. Pipelines reference the *key*, never the state
|
|
223
|
-
name, so renaming a Linear column is one edit here rather than a hunt through
|
|
224
|
-
pipeline YAML.
|
|
225
|
-
- **Every `state` is checked against the workspace** alongside `states`, at push
|
|
226
|
-
and setup time. Linear **silently ignores** an unknown issue state, so an
|
|
227
|
-
unchecked typo would deploy cleanly and move nothing, forever.
|
|
228
|
-
- **Order is recorded, not enforced.** It drives reporting and the doctor check;
|
|
229
|
-
a rollback from test, or a hotfix going straight to prod, is legitimate and is
|
|
230
|
-
never refused.
|
|
231
|
-
- **Keys must be unique**, and a malformed entry is a hard error at load — the
|
|
232
|
-
same treatment `sync.fieldOwnership` and `mapping.phases` get.
|
|
233
|
-
- **Absent or empty = the opt-out.** Nothing about the ladder affects a project
|
|
234
|
-
that has not declared one.
|
|
233
|
+
The one release question skitterspec answers is
|
|
234
|
+
**which tickets a range contains**, because only the `Refs:` trailers know:
|
|
235
235
|
|
|
236
|
-
|
|
237
|
-
|
|
236
|
+
```sh
|
|
237
|
+
skitterspec spec-sync released "<previous-tag>..<tag>" --json
|
|
238
|
+
```
|
|
238
239
|
|
|
239
|
-
|
|
240
|
-
|
|
240
|
+
Each row carries the `ref`, its commit count, the `spec` that stamped it and its
|
|
241
|
+
`url` — `null` for a ref no spec has linked, never a guess. Pipe that into the
|
|
242
|
+
Linear API or CLI to set whatever field, label or state your process uses.
|
|
241
243
|
|
|
244
|
+
`release.stages` and the `spec-sync stage` command are **retired**: `stage`
|
|
245
|
+
exits 1 naming `released --json`, and `spec-sync doctor` flags a leftover
|
|
246
|
+
`release.stages` as unused config (a warning, never a failure).
|
|
242
247
|
|
|
243
248
|
## Bookkeeping commits (`release.ignorePaths`)
|
|
244
249
|
|
|
245
|
-
`spec-sync released`
|
|
246
|
-
|
|
250
|
+
`spec-sync released` answers "what did this release contain?" from the
|
|
251
|
+
`Refs:` trailers in the range. Left alone, that over-answers:
|
|
247
252
|
a spec's `chore(spec): complete <name>` commit carries the **same ref** as the
|
|
248
253
|
code it describes, but lands **after** the tag that shipped that code — so the
|
|
249
254
|
ticket turns up in two consecutive release ranges, once for its code and once
|
|
250
|
-
for its paperwork
|
|
251
|
-
already reached the top back down a rung.
|
|
255
|
+
for its paperwork, and anything downstream acting on the list acts twice.
|
|
252
256
|
|
|
253
257
|
`release.ignorePaths` names the repo-relative prefixes that are paperwork:
|
|
254
258
|
|
|
@@ -663,8 +667,10 @@ most specific destination. Leave a list empty and nothing routes through it.
|
|
|
663
667
|
The repo owns the spec and pushes it; there is no pull. `/spec-push` diffs the
|
|
664
668
|
current spec against the committed **last-pushed snapshot** and sends only what
|
|
665
669
|
changed — creates for unlinked items, updates for changed ones. A workflow-state a
|
|
666
|
-
teammate moves in Linear is
|
|
667
|
-
|
|
670
|
+
teammate moves in Linear is **not skitterspec's business**: it is never read
|
|
671
|
+
back or reported, and push resends State only when the spec itself moves. A
|
|
672
|
+
**description** someone edited there is reported by `/spec-status`, because
|
|
673
|
+
the next push replaces it. Priority, labels, cycles and comments are
|
|
668
674
|
Linear-native triage and are never touched. No base merge, no conflicts, no
|
|
669
675
|
`--force`.
|
|
670
676
|
|
|
@@ -492,9 +492,19 @@ missing alias.
|
|
|
492
492
|
Sync is **one-way**: the repo is the source of truth and the tracker is a
|
|
493
493
|
**generated mirror**. It ships `/spec-push` (repo→tracker; computes a create/update plan
|
|
494
494
|
against a committed last-pushed snapshot and applies it) and `/spec-status`
|
|
495
|
-
(read-only
|
|
496
|
-
|
|
497
|
-
|
|
495
|
+
(read-only — what would push, and whether someone edited a description there),
|
|
496
|
+
backed by a `spec-sync` CLI. There is no content pull — the tracker is never
|
|
497
|
+
read back or merged.
|
|
498
|
+
|
|
499
|
+
**It tells, it doesn't track.** Skitterspec sends the tracker its own
|
|
500
|
+
transitions — a spec starting, a phase finishing, a spec completing or being
|
|
501
|
+
cancelled — and nothing else. A status someone changes on the tracker is
|
|
502
|
+
theirs to have changed: it is never read back, never reported, and only
|
|
503
|
+
overwritten when the spec itself next moves. Releases and deployments are the
|
|
504
|
+
host project's to record. The one release question skitterspec answers is which
|
|
505
|
+
tickets a commit range contains (`spec-sync released <range> --json`, each row
|
|
506
|
+
with its spec and url), because only the `Refs:` trailers know. What the
|
|
507
|
+
project's CI does with that list is its own business.
|
|
498
508
|
|
|
499
509
|
**One-way means the repo wins, and it now wins *loudly*.** Those are different
|
|
500
510
|
claims and only the first was ever in doubt. A ticket's description is generated
|
|
@@ -36,7 +36,7 @@ A verdict sentence, a blank line, then a two-column table:
|
|
|
36
36
|
| **Branch** | `spec/feat-foo` · 3 commits, clean |
|
|
37
37
|
| **Built** | POST /orders handler, orders schema |
|
|
38
38
|
| **Tests** | 128 passed · dotnet test |
|
|
39
|
-
| **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 |
|
|
39
|
+
| **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/…) also [http://100.126.111.34:7760/…](http://100.126.111.34:7760/…) (tailnet) · **remote** off |
|
|
40
40
|
| **Follow-ups** | none |
|
|
41
41
|
| **Next** | `/spec-next` → phase 3 (Auth) |
|
|
42
42
|
|
|
@@ -89,6 +89,7 @@ the options may be offered after the table.
|
|
|
89
89
|
|
|
90
90
|
- **local** — [http://127.0.0.1:7760/7e9e123e7540/feat-orders](http://127.0.0.1:7760/7e9e123e7540/feat-orders)
|
|
91
91
|
- **network** — [http://192.168.0.136:7760/7e9e123e7540/feat-orders](http://192.168.0.136:7760/7e9e123e7540/feat-orders)
|
|
92
|
+
- also — [http://100.126.111.34:7760/7e9e123e7540/feat-orders](http://100.126.111.34:7760/7e9e123e7540/feat-orders) (tailnet)
|
|
92
93
|
- **remote** — off · `/spec-remote-review` turns it on
|
|
93
94
|
|
|
94
95
|
live: off — /spec-live to put it live
|
|
@@ -156,6 +157,17 @@ on. Dropping the line is what left a reader who had walked out of the house with
|
|
|
156
157
|
nothing on screen to tell them a remote page was even possible — they could not
|
|
157
158
|
ask for what they could not see.
|
|
158
159
|
|
|
160
|
+
**The `network` tier may carry alternates, and they are part of it — not a fourth tier.**
|
|
161
|
+
The engine offers the other addresses this machine has (a
|
|
162
|
+
tailnet one, for a reader off the wifi) as `also:` lines under `network`, each
|
|
163
|
+
labelled; `--json` carries them as that tier's `alternates`, labelled the same
|
|
164
|
+
way. Copy them as indented sub-bullets under the network bullet, verbatim,
|
|
165
|
+
labels included. This is not an amendment to the tier rule: the stack is the
|
|
166
|
+
engine's, copied rather than composed, and the engine was already printing
|
|
167
|
+
these — a contract that made the skill edit them out was the composing this
|
|
168
|
+
section forbids. A machine with no alternates renders the banner exactly as
|
|
169
|
+
above, minus the sub-bullet.
|
|
170
|
+
|
|
159
171
|
**Only promise a wait the transport can deliver.** The wait itself is real in
|
|
160
172
|
every case; what varies is what carries it back, not whether the run is
|
|
161
173
|
stopped. Three transports, three true sentences:
|
|
@@ -298,8 +310,11 @@ behind, and they cannot.
|
|
|
298
310
|
`fetch(location.pathname, …)`, so a page opened at `127.0.0.1:7760/…` and one
|
|
299
311
|
opened at `192.168.0.136:7760/…` reach the same server process and the same
|
|
300
312
|
pending store. One wait covers both, and a verdict pressed on either wakes the
|
|
301
|
-
same run.
|
|
302
|
-
|
|
313
|
+
same run. A `network` alternate — the `also:` tailnet address — is one more
|
|
314
|
+
door into the same room: the same server answers on it, so the wait-coverage
|
|
315
|
+
line stays true with nothing added to it. Between all of those the objection
|
|
316
|
+
does not apply — which is why they are offered, and why offering them gives
|
|
317
|
+
nothing up.
|
|
303
318
|
|
|
304
319
|
**So two things are required, and the second is what the old rule lacked.**
|
|
305
320
|
Every link is **labelled** with its tier, and one line says
|
|
@@ -410,7 +425,7 @@ behind it — say nothing rather than reporting that there was nothing to report
|
|
|
410
425
|
| `Landed` | A fast-forward, a tag, a cherry-pick. |
|
|
411
426
|
| `Worktree` | A worktree provisioned, entered, or torn down. |
|
|
412
427
|
| `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
|
|
413
|
-
| `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
|
|
428
|
+
| `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, with any `network` alternates inline after the network URL (`also <url> (tailnet)`), plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
|
|
414
429
|
| `Follow-ups` | **Always.** `none`, or one line each. |
|
|
415
430
|
| `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
|
|
416
431
|
|
|
@@ -647,7 +647,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
|
|
|
647
647
|
an update the issue already has a project (or deliberately has none), and that
|
|
648
648
|
placement is **Linear's to own**: never send `project` on an update, and never
|
|
649
649
|
record the choice in the spec file or the snapshot. A PM re-homing a spec issue
|
|
650
|
-
must not
|
|
650
|
+
must not be reported or overwritten on the next push.
|
|
651
651
|
|
|
652
652
|
1. **List the candidates.** Ask the engine:
|
|
653
653
|
`skitterspec spec-sync projects --json`. On the API path it returns the team's
|
|
@@ -448,7 +448,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
|
|
|
448
448
|
an update the issue already has a project (or deliberately has none), and that
|
|
449
449
|
placement is **Linear's to own**: never send `project` on an update, and never
|
|
450
450
|
record the choice in the spec file or the snapshot. A PM re-homing a spec issue
|
|
451
|
-
must not
|
|
451
|
+
must not be reported or overwritten on the next push.
|
|
452
452
|
|
|
453
453
|
1. **List the candidates.** Ask the engine:
|
|
454
454
|
`skitterspec spec-sync projects --json`. On the API path it returns the team's
|
|
@@ -614,7 +614,9 @@ underneath a reader when detection flipped mid-session.
|
|
|
614
614
|
|
|
615
615
|
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
616
616
|
`network` — the other addresses this machine has, offered because the
|
|
617
|
-
best-guess one can be wrong — so pass them on rather than editing them out
|
|
617
|
+
best-guess one can be wrong — so pass them on rather than editing them out: in
|
|
618
|
+
the banner they are indented sub-bullets under **network**, labels
|
|
619
|
+
(`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
|
|
618
620
|
|
|
619
621
|
**Never read an environment variable to decide anything about the offer** — not
|
|
620
622
|
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
@@ -480,7 +480,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
|
|
|
480
480
|
an update the issue already has a project (or deliberately has none), and that
|
|
481
481
|
placement is **Linear's to own**: never send `project` on an update, and never
|
|
482
482
|
record the choice in the spec file or the snapshot. A PM re-homing a spec issue
|
|
483
|
-
must not
|
|
483
|
+
must not be reported or overwritten on the next push.
|
|
484
484
|
|
|
485
485
|
1. **List the candidates.** Ask the engine:
|
|
486
486
|
`skitterspec spec-sync projects --json`. On the API path it returns the team's
|
|
@@ -625,7 +625,9 @@ underneath a reader when detection flipped mid-session.
|
|
|
625
625
|
|
|
626
626
|
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
627
627
|
`network` — the other addresses this machine has, offered because the
|
|
628
|
-
best-guess one can be wrong — so pass them on rather than editing them out
|
|
628
|
+
best-guess one can be wrong — so pass them on rather than editing them out: in
|
|
629
|
+
the banner they are indented sub-bullets under **network**, labels
|
|
630
|
+
(`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
|
|
629
631
|
|
|
630
632
|
**Never read an environment variable to decide anything about the offer** — not
|
|
631
633
|
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
@@ -147,36 +147,14 @@ never apply one they didn't agree to), and re-run with the `--state` flags. If i
|
|
|
147
147
|
made no suggestion for a bucket, **ask** which state means "finished" here rather
|
|
148
148
|
than guessing.
|
|
149
149
|
|
|
150
|
-
## 7.
|
|
150
|
+
## 7. Deploys are the project's own to record
|
|
151
151
|
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
|
|
157
|
-
|
|
158
|
-
**Ask, do not assume.** Most projects have no ladder, and an invented one is
|
|
159
|
-
worse than none: `spec-sync stage` refuses cleanly when none is declared, whereas
|
|
160
|
-
a wrong ladder is a pipeline quietly moving tickets to the wrong column. If the
|
|
161
|
-
user does not raise deployment, offer it once in a line and take "no" for an
|
|
162
|
-
answer.
|
|
163
|
-
|
|
164
|
-
If they do want one, ask for the stages **in deployment order**, and map each to
|
|
165
|
-
a state from the `list_issue_statuses` names you already have:
|
|
166
|
-
|
|
167
|
-
```
|
|
168
|
-
--stage test="On Test" --stage demo="Ready for Demo" --stage prod="Done"
|
|
169
|
-
```
|
|
170
|
-
|
|
171
|
-
- The **key** (`test`) is what a pipeline names; the **state** is the Linear
|
|
172
|
-
column. Pipelines reference the key, so renaming the column later is one edit
|
|
173
|
-
here.
|
|
174
|
-
- Order is recorded, not enforced — a rollback and a hotfix straight to prod are
|
|
175
|
-
both legitimate and are never refused.
|
|
176
|
-
- **Ask what closes an issue.** If the last rung is not a completed-type state,
|
|
177
|
-
tickets that finish the ladder never reach Done. That is fine when Linear
|
|
178
|
-
automation closes them and a problem otherwise — `spec-sync doctor` warns about
|
|
179
|
-
it either way, so say which it is.
|
|
152
|
+
Nothing to ask here. Skitterspec moves a Linear issue only at its own
|
|
153
|
+
transitions, and a spec's lifecycle ends at `complete`. Where a ticket goes
|
|
154
|
+
after that is the host project's: its CI can list a release's tickets with
|
|
155
|
+
`skitterspec spec-sync released "<previous-tag>..<tag>" --json` and set whatever
|
|
156
|
+
Linear state or label it likes. If the user asks about deploy tracking, say that
|
|
157
|
+
in one line and point at "Releases and deploys" in `linear.config.md`.
|
|
180
158
|
|
|
181
159
|
## 7b. Assignment is on — does this team want it off?
|
|
182
160
|
|
|
@@ -227,11 +205,6 @@ shows this repo's choices and keeps inheriting everything else. `--force` is
|
|
|
227
205
|
required to replace an existing config — never pass it without the user having
|
|
228
206
|
asked for a rewrite in step 1.
|
|
229
207
|
|
|
230
|
-
Every `--stage` state is checked against the workspace exactly like a bucket
|
|
231
|
-
state, and a bad one is refused the same way — as `release.stages[test]` rather
|
|
232
|
-
than `states.complete`. There is no suggestion for a rung: the vocabulary is the
|
|
233
|
-
project's own, so ask rather than guess.
|
|
234
|
-
|
|
235
208
|
**Relay the engine's report as printed.** It names the team, the project (or
|
|
236
209
|
"team only"), the intake labels, and how many state names were checked against
|
|
237
210
|
the workspace — that report is the evidence the setup is right, so don't
|
|
@@ -312,7 +285,8 @@ Then name the next step:
|
|
|
312
285
|
|
|
313
286
|
- `/spec` — write a spec; with Linear configured it offers the project picker,
|
|
314
287
|
creates the linked issue and stamps the id.
|
|
315
|
-
- `/spec-status` — read-only
|
|
288
|
+
- `/spec-status` — read-only report of what would push, the safe way to prove
|
|
289
|
+
the link works.
|
|
316
290
|
- `/spec-push` — send a spec up.
|
|
317
291
|
|
|
318
292
|
**Never ask for the API key.** `doctor`'s `key` row already reports whether one
|
|
@@ -49,6 +49,18 @@ flags themselves (`--state`, `--all`, `--next`, `--in-progress`) are
|
|
|
49
49
|
**alternatives**, and the engine refuses any two of them rather than letting one
|
|
50
50
|
win silently.
|
|
51
51
|
|
|
52
|
+
**Every row shows the board's state and the spec's own status side by side.**
|
|
53
|
+
The spec status is read from the spec's **own worktree** when one exists, so an
|
|
54
|
+
in-flight spec reads `in-progress` even on the base branch, where its folder
|
|
55
|
+
still says `backlog`. `≠ <bucket>` marks a row whose board state maps to a
|
|
56
|
+
different bucket than its spec; a state that maps to no bucket never gets one.
|
|
57
|
+
`—` means the spec is not on this machine. Relay it as printed; never "correct"
|
|
58
|
+
either column from the other. The board says where the ticket is, and the spec
|
|
59
|
+
says where the work is.
|
|
60
|
+
|
|
61
|
+
`--state` also takes a lifecycle bucket: `--state in-progress` matches every
|
|
62
|
+
board state configured for it (`states` aliases included).
|
|
63
|
+
|
|
52
64
|
`--next N` is **backlog-only and ordered**, so it does not combine with
|
|
53
65
|
`--state` or `--all`; the engine refuses that pair rather than picking a winner.
|
|
54
66
|
It reproduces Linear's own Backlog order — priority first, then the manual
|
|
@@ -58,7 +70,7 @@ then a person's arrangement rather than a ranking.
|
|
|
58
70
|
## 2. Run the engine
|
|
59
71
|
|
|
60
72
|
```
|
|
61
|
-
skitterspec spec-sync list [--state <name> …|--all] [--limit N] [--archived] [--json]
|
|
73
|
+
skitterspec spec-sync list [--state <name|bucket> …|--all] [--limit N] [--archived] [--json]
|
|
62
74
|
```
|
|
63
75
|
|
|
64
76
|
- **`transport = api`** (a key is set) → it queried Linear and printed the
|
|
@@ -583,7 +583,9 @@ underneath a reader when detection flipped mid-session.
|
|
|
583
583
|
|
|
584
584
|
So: **relay all three tier lines, every time.** Any `also:` lines sit under
|
|
585
585
|
`network` — the other addresses this machine has, offered because the
|
|
586
|
-
best-guess one can be wrong — so pass them on rather than editing them out
|
|
586
|
+
best-guess one can be wrong — so pass them on rather than editing them out: in
|
|
587
|
+
the banner they are indented sub-bullets under **network**, labels
|
|
588
|
+
(`(tailnet)`) included, exactly as `.claude/rules/spec-reports.md` shows.
|
|
587
589
|
|
|
588
590
|
**Never read an environment variable to decide anything about the offer** — not
|
|
589
591
|
`SSH_CONNECTION`, not `CLAUDE_CODE_*`, not a tty check. There is nothing left
|
|
@@ -314,7 +314,7 @@ Run this **only when minting a spec issue** — creating it for the first time.
|
|
|
314
314
|
an update the issue already has a project (or deliberately has none), and that
|
|
315
315
|
placement is **Linear's to own**: never send `project` on an update, and never
|
|
316
316
|
record the choice in the spec file or the snapshot. A PM re-homing a spec issue
|
|
317
|
-
must not
|
|
317
|
+
must not be reported or overwritten on the next push.
|
|
318
318
|
|
|
319
319
|
1. **List the candidates.** Ask the engine:
|
|
320
320
|
`skitterspec spec-sync projects --json`. On the API path it returns the team's
|