@skitterbyte/skitterspec-linear 18.3.1 → 19.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 +170 -1
- package/README.md +9 -7
- package/assets/core/SETUP.md +4 -4
- package/assets/core/env.config.md +1 -1
- package/assets/core/linear.config.json.example +2 -1
- package/assets/core/linear.config.md +59 -48
- package/assets/rules/spec-planning.md +35 -12
- package/assets/rules/spec-reports.md +47 -6
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +32 -9
- package/assets/skills/spec-bug/SKILL.md +6 -4
- 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 +5 -3
- 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 +114 -28
- package/src/env/resolve.js +11 -4
- package/src/env/review.js +126 -2
- package/src/vendor/linear/api.js +30 -1
- package/src/vendor/linear/cli-sync.js +64 -269
- package/src/vendor/linear/config.js +30 -49
- 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 +60 -59
- 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,133 @@
|
|
|
1
1
|
# Migration guide
|
|
2
2
|
|
|
3
|
+
## The `chore` spec kind, and per-type bodies (additive — nothing breaks)
|
|
4
|
+
|
|
5
|
+
Specs can now be **chores** (`chore-` prefix, `> **Type:** Chore`) and every
|
|
6
|
+
provider can map spec kinds to its own idiom. Configs without a mapping keep
|
|
7
|
+
working unchanged: an unmapped kind mints the provider's default type exactly
|
|
8
|
+
as before, and `System.Description` stays Azure's body field unless a type is
|
|
9
|
+
mapped away from it. `skitterspec update` ships the new skills and rules.
|
|
10
|
+
|
|
11
|
+
**Create tracker types and states before mapping them.** A mapping names
|
|
12
|
+
something the tracker must already have:
|
|
13
|
+
|
|
14
|
+
- **Azure Boards** — create the custom inherited type (e.g. `Chore`) and its
|
|
15
|
+
states in your process, then set
|
|
16
|
+
`azure.workItemTypeByKind: { "chore": "Chore" }`. To fill a Bug form's Repro
|
|
17
|
+
Steps instead of the hidden Description, set
|
|
18
|
+
`azure.bodyFieldByType: { "Bug": "Microsoft.VSTS.TCM.ReproSteps" }` — it
|
|
19
|
+
applies symmetrically to create, update, read-back and the edited-hash
|
|
20
|
+
compare, so `/spec-status` stays quiet after a push. Bugs minted before the
|
|
21
|
+
mapping keep reading their Description until the next push rewrites them.
|
|
22
|
+
`spec-sync doctor --check-remote` verifies every mapped type exists and
|
|
23
|
+
carries its body field.
|
|
24
|
+
- **GitHub** — `github.labelsByKind: { "chore": "chore" }` adds the kind's
|
|
25
|
+
label beside the spec marker.
|
|
26
|
+
- **Jira** — `jira.issueTypeByKind: { "bug": "Bug", "chore": "Task" }` picks
|
|
27
|
+
the mint type per kind; the type must exist in the project.
|
|
28
|
+
- **Linear** — `linear.labelsByKind: { "chore": "Chore" }` labels the mint;
|
|
29
|
+
the label must already exist on the team (a missing one is a one-line note,
|
|
30
|
+
never a failed push).
|
|
31
|
+
|
|
32
|
+
## `@skitterbyte/skitterspec-github` v1 → v2 (tell, don't track)
|
|
33
|
+
|
|
34
|
+
Skitterspec now tells GitHub about **its own** transitions and nothing
|
|
35
|
+
else. It writes nothing about releases or deployments, and it never reads a
|
|
36
|
+
ticket's state back.
|
|
37
|
+
|
|
38
|
+
### Breaking change 1 — The `release create|deployed|complete|reconcile` verbs are removed
|
|
39
|
+
|
|
40
|
+
They exit 1 with one line naming `spec-sync released <range> --json`. A pipeline
|
|
41
|
+
still calling them goes red rather than silently believing it mirrors
|
|
42
|
+
anything. **To migrate**, replace the step with your own script over the
|
|
43
|
+
release's ticket list:
|
|
44
|
+
|
|
45
|
+
```sh
|
|
46
|
+
skitterspec-github spec-sync released "<previous-tag>..<tag>" --json
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
|
|
50
|
+
linked), so the script needs no second lookup. Set whatever GitHub field,
|
|
51
|
+
state or release object your process uses from that list. The checkout needs
|
|
52
|
+
`fetch-depth: 0` so the previous tag is visible.
|
|
53
|
+
|
|
54
|
+
### Breaking change 2 — The `releases` block (`deployedField`, `series`) and `release.stages` are retired
|
|
55
|
+
|
|
56
|
+
The keys are ignored, like any unknown key, so a config carrying them still
|
|
57
|
+
loads. `spec-sync doctor` names them as unused config (a `warn`, never a
|
|
58
|
+
failure). Delete them when you remove the CI step.
|
|
59
|
+
|
|
60
|
+
### Breaking change 3 — no state drift
|
|
61
|
+
|
|
62
|
+
`spec-sync status --remote` and `/spec-status` no longer compare the tracker's
|
|
63
|
+
state with the spec's. A ticket someone moved on GitHub is not reported, and
|
|
64
|
+
push still resends state only when the spec itself moves. The edited-description
|
|
65
|
+
warning is unchanged.
|
|
66
|
+
|
|
67
|
+
## `@skitterbyte/skitterspec-azure-boards` v1 → v2 (tell, don't track)
|
|
68
|
+
|
|
69
|
+
Skitterspec now tells Azure Boards about **its own** transitions and nothing
|
|
70
|
+
else. It writes nothing about releases or deployments, and it never reads a
|
|
71
|
+
ticket's state back.
|
|
72
|
+
|
|
73
|
+
### Breaking change 1 — The `release create|deployed|complete` verbs are removed
|
|
74
|
+
|
|
75
|
+
They exit 1 with one line naming `spec-sync released <range> --json`. A pipeline
|
|
76
|
+
still calling them goes red rather than silently believing it mirrors
|
|
77
|
+
anything. **To migrate**, replace the step with your own script over the
|
|
78
|
+
release's ticket list:
|
|
79
|
+
|
|
80
|
+
```sh
|
|
81
|
+
skitterspec-azure-boards spec-sync released "<previous-tag>..<tag>" --json
|
|
82
|
+
```
|
|
83
|
+
|
|
84
|
+
Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
|
|
85
|
+
linked), so the script needs no second lookup. Set whatever Azure Boards field,
|
|
86
|
+
state or release object your process uses from that list. The checkout needs
|
|
87
|
+
`fetch-depth: 0` so the previous tag is visible.
|
|
88
|
+
|
|
89
|
+
### Breaking change 2 — The `releases` block (`workItemType`, `series`, `ticketTag`, `deployedField`) and `release.stages` are retired
|
|
90
|
+
|
|
91
|
+
The keys are ignored, like any unknown key, so a config carrying them still
|
|
92
|
+
loads. `spec-sync doctor` names them as unused config (a `warn`, never a
|
|
93
|
+
failure). Delete them when you remove the CI step.
|
|
94
|
+
|
|
95
|
+
### Breaking change 3 — no state drift
|
|
96
|
+
|
|
97
|
+
`spec-sync status --remote` and `/spec-status` no longer compare the tracker's
|
|
98
|
+
state with the spec's. A ticket someone moved on Azure Boards is not reported, and
|
|
99
|
+
push still resends state only when the spec itself moves. The edited-description
|
|
100
|
+
warning is unchanged.
|
|
101
|
+
|
|
102
|
+
## `@skitterbyte/skitterspec-jira` v1 → v2 (tell, don't track)
|
|
103
|
+
|
|
104
|
+
Skitterspec now tells Jira about **its own** transitions and nothing else. It
|
|
105
|
+
writes nothing about releases or deployments, and it never reads an issue's
|
|
106
|
+
status back.
|
|
107
|
+
|
|
108
|
+
### Breaking change 1 — no status drift
|
|
109
|
+
|
|
110
|
+
`spec-sync status --remote` and `/spec-status` no longer compare Jira's status
|
|
111
|
+
with the spec's. An issue someone moved on Jira is not reported, and push still
|
|
112
|
+
transitions it only when the spec itself moves. The edited-description warning
|
|
113
|
+
is unchanged.
|
|
114
|
+
|
|
115
|
+
### Breaking change 2 — `release.stages` retired
|
|
116
|
+
|
|
117
|
+
It was accepted and validated before, and never acted on. It is now ignored
|
|
118
|
+
like any unknown key, and `spec-sync doctor` names it as unused config (a
|
|
119
|
+
`warn`, never a failure). Delete it.
|
|
120
|
+
|
|
121
|
+
### Also — `released --json` names the spec
|
|
122
|
+
|
|
123
|
+
Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
|
|
124
|
+
linked), so CI can record a release, for example as a fix version, without a
|
|
125
|
+
second lookup:
|
|
126
|
+
|
|
127
|
+
```sh
|
|
128
|
+
skitterspec-jira spec-sync released "<previous-tag>..<tag>" --json
|
|
129
|
+
```
|
|
130
|
+
|
|
3
131
|
## `@skitterbyte/skitterspec` v23 → v24 (hotfix land runs the release itself)
|
|
4
132
|
|
|
5
133
|
### Breaking change 1 — `spec-env hotfix land` runs its steps, and holds before the carry
|
|
@@ -275,7 +403,48 @@ can run it.
|
|
|
275
403
|
committed file, so it changes for everyone who pulls and leaves that tree dirty.
|
|
276
404
|
The engine says so when it does.
|
|
277
405
|
|
|
278
|
-
## `@skitterbyte/skitterspec-linear` v18 → v19 (hotfix land runs the release itself)
|
|
406
|
+
## `@skitterbyte/skitterspec-linear` v18 → v19 (tell, don't track; hotfix land runs the release itself)
|
|
407
|
+
|
|
408
|
+
Skitterspec now tells Linear about **its own** transitions and nothing
|
|
409
|
+
else. It writes nothing about releases or deployments, and it never reads a
|
|
410
|
+
ticket's state back.
|
|
411
|
+
|
|
412
|
+
### Breaking change 1 — The `spec-sync stage` verb is removed
|
|
413
|
+
|
|
414
|
+
It exits 1 with one line naming `spec-sync released <range> --json`. A pipeline
|
|
415
|
+
still calling it goes red rather than silently believing it mirrors
|
|
416
|
+
anything. **To migrate**, replace the step with your own script over the
|
|
417
|
+
release's ticket list:
|
|
418
|
+
|
|
419
|
+
```sh
|
|
420
|
+
skitterspec-linear spec-sync released "<previous-tag>..<tag>" --json
|
|
421
|
+
```
|
|
422
|
+
|
|
423
|
+
Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
|
|
424
|
+
linked), so the script needs no second lookup. Set whatever Linear field,
|
|
425
|
+
state or release object your process uses from that list. The checkout needs
|
|
426
|
+
`fetch-depth: 0` so the previous tag is visible.
|
|
427
|
+
|
|
428
|
+
### Breaking change 2 — `release.stages` (the deployment ladder) is retired
|
|
429
|
+
|
|
430
|
+
The keys are ignored, like any unknown key, so a config carrying them still
|
|
431
|
+
loads. `spec-sync doctor` names them as unused config (a `warn`, never a
|
|
432
|
+
failure). Delete them when you remove the CI step.
|
|
433
|
+
|
|
434
|
+
### Breaking change 3 — no state drift
|
|
435
|
+
|
|
436
|
+
`spec-sync status --remote` and `/spec-status` no longer compare the tracker's
|
|
437
|
+
state with the spec's. A ticket someone moved on Linear is not reported, and
|
|
438
|
+
push still resends state only when the spec itself moves. The edited-description
|
|
439
|
+
warning is unchanged.
|
|
440
|
+
|
|
441
|
+
**A ladder rung no longer reads as `complete`.** Where a state was a
|
|
442
|
+
`release.stages` rung, the live `spec-sync list` now shows it as unmapped. To
|
|
443
|
+
keep it reading as finished, list it as an alias:
|
|
444
|
+
`"complete": ["Done", "On Test"]`. `init-config --stage` is gone too, and is
|
|
445
|
+
refused as an unknown flag.
|
|
446
|
+
|
|
447
|
+
### Also — hotfix land runs the release itself
|
|
279
448
|
|
|
280
449
|
The same change as `@skitterbyte/skitterspec` v23 → v24 above — this
|
|
281
450
|
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,
|
|
@@ -580,7 +580,7 @@ through to a documented conservative default; see the field notes below.
|
|
|
580
580
|
- `{repo}` — primary checkout dir basename (e.g. `skitterspec`).
|
|
581
581
|
- `{repoSlug}` — `{repo}` lower-cased, non-alphanumerics collapsed to `-`
|
|
582
582
|
(safe for a `COMPOSE_PROJECT_NAME`).
|
|
583
|
-
- `{slug}` — the spec slug (folder name minus its `feat-`/`bug-` prefix).
|
|
583
|
+
- `{slug}` — the spec slug (folder name minus its `feat-`/`bug-`/`hotfix-`/`chore-` prefix).
|
|
584
584
|
|
|
585
585
|
## Pruning orphaned test-DB volumes
|
|
586
586
|
|
|
@@ -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`
|
|
@@ -34,7 +34,12 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
|
|
|
34
34
|
"teamKey": "", // human-facing key, e.g. "ENG" — the RECORDED key;
|
|
35
35
|
// see "Renaming a team" below (optional)
|
|
36
36
|
"teamId": "", // Linear team UUID (the issue's team)
|
|
37
|
-
"projectId": ""
|
|
37
|
+
"projectId": "", // DEFAULT for the project picker (see below)
|
|
38
|
+
"labelsByKind": {} // one label per spec kind (feature/bug/hotfix/chore,
|
|
39
|
+
// from the folder prefix), applied at mint —
|
|
40
|
+
// e.g. { "chore": "Chore" }. The label must already
|
|
41
|
+
// exist on the team; a missing one is a one-line
|
|
42
|
+
// note, never a failed push
|
|
38
43
|
},
|
|
39
44
|
|
|
40
45
|
// Issue intake: `/spec <ISSUE-REF>` adopts any issue; `/spec --from-issue`
|
|
@@ -90,14 +95,9 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
|
|
|
90
95
|
"overviewFile": "00-overview.md"
|
|
91
96
|
},
|
|
92
97
|
|
|
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.
|
|
98
|
+
// `ignorePaths` is what `released` treats as BOOKKEEPING rather than shipped
|
|
99
|
+
// work — see "Bookkeeping commits" below. `[]` opts out.
|
|
99
100
|
"release": {
|
|
100
|
-
"stages": [],
|
|
101
101
|
"ignorePaths": ["specs/"]
|
|
102
102
|
},
|
|
103
103
|
|
|
@@ -139,6 +139,32 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
|
|
|
139
139
|
}
|
|
140
140
|
```
|
|
141
141
|
|
|
142
|
+
## More than one name per bucket — read-only aliases
|
|
143
|
+
|
|
144
|
+
A board usually has more states than the four buckets: "Blocked", "Next
|
|
145
|
+
Sprint", "Released". A bucket's value may be an **array** instead of a string:
|
|
146
|
+
|
|
147
|
+
```jsonc
|
|
148
|
+
"states": {
|
|
149
|
+
"in-progress": ["Active", "Blocked"],
|
|
150
|
+
"complete": ["Closed", "Released"]
|
|
151
|
+
}
|
|
152
|
+
```
|
|
153
|
+
|
|
154
|
+
- **The first name is the only one push writes**, and only when the spec
|
|
155
|
+
itself moves. The rest are never written.
|
|
156
|
+
- **The rest are read as that bucket** by the listing: the live
|
|
157
|
+
`spec-sync list` hides every `complete` / `cancelled` name, `--state <bucket>`
|
|
158
|
+
matches all of them, and `spec-sync states` lists each alias under its
|
|
159
|
+
bucket.
|
|
160
|
+
- **Nothing is pulled.** An alias changes what the report *says* about a
|
|
161
|
+
ticket, never the spec.
|
|
162
|
+
- A plain string works exactly as before. An alias that also names another
|
|
163
|
+
bucket is refused at load. An alias the tracker lacks is reported by
|
|
164
|
+
`spec-sync states` but never blocks a push, because it is never written.
|
|
165
|
+
- `spec-sync status` never reads a ticket's state at all, aliased or not —
|
|
166
|
+
see "One direction" below.
|
|
167
|
+
|
|
142
168
|
## Assignment (`sync.fieldOwnership.assignee`)
|
|
143
169
|
|
|
144
170
|
**On by default since v16.** The spec issue is assigned to whoever is building
|
|
@@ -201,54 +227,37 @@ reusing the identity above rather than a second copy of it. It writes nothing,
|
|
|
201
227
|
and it says what it did not show — the count, the archived exclusion, and any
|
|
202
228
|
cap — rather than implying a completeness it never checked.
|
|
203
229
|
|
|
204
|
-
##
|
|
230
|
+
## Releases and deploys — the host project's to write
|
|
205
231
|
|
|
206
|
-
|
|
207
|
-
|
|
208
|
-
|
|
209
|
-
|
|
232
|
+
Skitterspec tells Linear about **its own** transitions: a spec starting,
|
|
233
|
+
a phase finishing, a spec completing or being cancelled. It never reads a
|
|
234
|
+
ticket's state back, and it writes nothing about releases or deployments. Where
|
|
235
|
+
a ticket goes after its spec is `complete` — on test, in prod — belongs to the
|
|
236
|
+
environment, and the project's own CI or scripts record it however they like.
|
|
210
237
|
|
|
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.
|
|
238
|
+
The one release question skitterspec answers is
|
|
239
|
+
**which tickets a range contains**, because only the `Refs:` trailers know:
|
|
235
240
|
|
|
236
|
-
|
|
237
|
-
|
|
241
|
+
```sh
|
|
242
|
+
skitterspec spec-sync released "<previous-tag>..<tag>" --json
|
|
243
|
+
```
|
|
238
244
|
|
|
239
|
-
|
|
240
|
-
|
|
245
|
+
Each row carries the `ref`, its commit count, the `spec` that stamped it and its
|
|
246
|
+
`url` — `null` for a ref no spec has linked, never a guess. Pipe that into the
|
|
247
|
+
Linear API or CLI to set whatever field, label or state your process uses.
|
|
241
248
|
|
|
249
|
+
`release.stages` and the `spec-sync stage` command are **retired**: `stage`
|
|
250
|
+
exits 1 naming `released --json`, and `spec-sync doctor` flags a leftover
|
|
251
|
+
`release.stages` as unused config (a warning, never a failure).
|
|
242
252
|
|
|
243
253
|
## Bookkeeping commits (`release.ignorePaths`)
|
|
244
254
|
|
|
245
|
-
`spec-sync released`
|
|
246
|
-
|
|
255
|
+
`spec-sync released` answers "what did this release contain?" from the
|
|
256
|
+
`Refs:` trailers in the range. Left alone, that over-answers:
|
|
247
257
|
a spec's `chore(spec): complete <name>` commit carries the **same ref** as the
|
|
248
258
|
code it describes, but lands **after** the tag that shipped that code — so the
|
|
249
259
|
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.
|
|
260
|
+
for its paperwork, and anything downstream acting on the list acts twice.
|
|
252
261
|
|
|
253
262
|
`release.ignorePaths` names the repo-relative prefixes that are paperwork:
|
|
254
263
|
|
|
@@ -663,8 +672,10 @@ most specific destination. Leave a list empty and nothing routes through it.
|
|
|
663
672
|
The repo owns the spec and pushes it; there is no pull. `/spec-push` diffs the
|
|
664
673
|
current spec against the committed **last-pushed snapshot** and sends only what
|
|
665
674
|
changed — creates for unlinked items, updates for changed ones. A workflow-state a
|
|
666
|
-
teammate moves in Linear is
|
|
667
|
-
|
|
675
|
+
teammate moves in Linear is **not skitterspec's business**: it is never read
|
|
676
|
+
back or reported, and push resends State only when the spec itself moves. A
|
|
677
|
+
**description** someone edited there is reported by `/spec-status`, because
|
|
678
|
+
the next push replaces it. Priority, labels, cycles and comments are
|
|
668
679
|
Linear-native triage and are never touched. No base merge, no conflicts, no
|
|
669
680
|
`--force`.
|
|
670
681
|
|
|
@@ -7,7 +7,7 @@ and lifecycle stay consistent. Each sets a status on the spec header
|
|
|
7
7
|
|
|
8
8
|
| Skill | Purpose | Status | Folder |
|
|
9
9
|
|-------|---------|--------|--------|
|
|
10
|
-
| `/spec` | (Feature) Grill to a clear shared understanding, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch, by a fast-forward) |
|
|
10
|
+
| `/spec` | (Feature/Chore) Grill to a clear shared understanding, propose the kind, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch, by a fast-forward) |
|
|
11
11
|
| `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
|
|
12
12
|
| `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag + cherry-pick | `In Progress` | `specs/in-progress/` |
|
|
13
13
|
| `/no-spec` | Work that genuinely has no spec — its own branch, worktree, page and land. Writes no spec and moves nothing through the lifecycle | `—` | (none) |
|
|
@@ -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
|
|
@@ -577,23 +587,36 @@ none of them describes.
|
|
|
577
587
|
- **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
|
|
578
588
|
(architecture, code style, testing, database, etc.) rather than restating them.
|
|
579
589
|
|
|
580
|
-
## Spec types — Feature, Bug, Hotfix
|
|
590
|
+
## Spec types — Feature, Chore, Bug, Hotfix
|
|
581
591
|
|
|
582
|
-
Every spec is one of
|
|
592
|
+
Every spec is one of four types, recorded **both** in the header and the filename:
|
|
583
593
|
|
|
584
|
-
- **Header field:** `> **Type:** Feature`, `> **Type:**
|
|
585
|
-
`> **Type:** Hotfix` (authoritative, greppable:
|
|
594
|
+
- **Header field:** `> **Type:** Feature`, `> **Type:** Chore`,
|
|
595
|
+
`> **Type:** Bug`, or `> **Type:** Hotfix` (authoritative, greppable:
|
|
586
596
|
`grep -rl 'Type:.*Hotfix' specs/`).
|
|
587
|
-
- **Filename prefix:** `feat-<name>` for features, `
|
|
588
|
-
`hotfix-<name>` for hotfixes (visible in listings;
|
|
589
|
-
`[BUG]`/`[FEATURE]` brackets).
|
|
597
|
+
- **Filename prefix:** `feat-<name>` for features, `chore-<name>` for chores,
|
|
598
|
+
`bug-<name>` for bugs, `hotfix-<name>` for hotfixes (visible in listings;
|
|
599
|
+
glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
|
|
600
|
+
|
|
601
|
+
A **Chore** is work no end user sees — tooling, CI, dependency bumps, internal
|
|
602
|
+
refactors. The line: anything that is not work end users see or functions they
|
|
603
|
+
use within the app is a chore; everything user-facing is a feature. There is no
|
|
604
|
+
separate entry skill — `/spec` **proposes** feature or chore from what the
|
|
605
|
+
grilling defined, with a one-line reason, and the user confirms. A chore
|
|
606
|
+
defaults its `Gating:` to `none: not user-facing` (where gating is configured),
|
|
607
|
+
and its commits default to `chore`/`refactor`/`ci` types with **no**
|
|
608
|
+
`Release-Note:` footer — a chore is by definition not user-visible, so it has
|
|
609
|
+
no release note to write. Feature specs keep `feat`; bug specs keep `fix`.
|
|
610
|
+
Where a ticketing provider maps kinds to tracker types (e.g. Azure's
|
|
611
|
+
`workItemTypeByKind`), the chore mapping is what keeps tooling work off the
|
|
612
|
+
customer-facing release ladder.
|
|
590
613
|
|
|
591
614
|
A **Hotfix** is a Bug fixed against a **released tag** rather than `main`: it
|
|
592
615
|
carries an extra `> **Base version:** <tag>` header, forks its worktree from that
|
|
593
616
|
tag, and lands by tagging a new patch + cherry-picking onto `main` (never a
|
|
594
617
|
fast-forward merge). `/spec-live` refuses a hotfix — test it with `/spec-connect`.
|
|
595
618
|
|
|
596
|
-
All
|
|
619
|
+
All four types share the same lifecycle folders below — type is orthogonal to
|
|
597
620
|
status.
|
|
598
621
|
|
|
599
622
|
## Header fields & State log (audit trail)
|
|
@@ -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:
|
|
@@ -219,8 +231,34 @@ again on the **same** `--since`. Not a fresh one — a pass that arrived during
|
|
|
219
231
|
the gap is still inside the original window, and re-arming on a new timestamp
|
|
220
232
|
would strand exactly that pass.
|
|
221
233
|
|
|
222
|
-
**Say
|
|
223
|
-
line on every death turns a working loop into a
|
|
234
|
+
**Say as little as the harness allows when you do it.** Nothing happened and
|
|
235
|
+
the window is unchanged; a line on every death turns a working loop into a
|
|
236
|
+
stream of non-events. Where the harness lets a turn end on the tool call, the
|
|
237
|
+
tool call is the whole turn. Where it insists on visible text — Claude Code
|
|
238
|
+
does, after a monitor event — that text is one fixed line,
|
|
239
|
+
`Still waiting for the verdict.`, and nothing else: not the spec, not the age,
|
|
240
|
+
not the links. The wait's own start line arriving as an event is answered the
|
|
241
|
+
same way.
|
|
242
|
+
|
|
243
|
+
**Every fifth re-arm, show the banner again.** Even one line per re-arm adds
|
|
244
|
+
up: over a long idle they push the verdict line and the banner's links out of
|
|
245
|
+
sight, and a reader who comes back has to scroll for the URL that lets them
|
|
246
|
+
answer. So `review wait` counts the starts on each window, and on every fifth
|
|
247
|
+
re-arm its start line is followed by `re-show: banner (re-arm N)` and the stack.
|
|
248
|
+
Relay that as the run's **verdict line** — copied from the block when it is
|
|
249
|
+
still in context, dropped rather than reconstructed when it is not — and then
|
|
250
|
+
**the banner** in its current state, with its stack copied from the `re-show:`
|
|
251
|
+
lines. Not the table: that would be a second block.
|
|
252
|
+
|
|
253
|
+
**A count here, not an age**, and the bound below is unaffected. What buries
|
|
254
|
+
the banner is how many re-arms have scrolled past it, and a death every five
|
|
255
|
+
minutes and one every forty-five push it up the same distance each. The age of
|
|
256
|
+
the window still decides when to stop.
|
|
257
|
+
|
|
258
|
+
**And it is not a third control after the block.** It is the banner this file
|
|
259
|
+
already defines, repeated in whatever state it is in — past the bound, that is
|
|
260
|
+
the degraded sentence below. No block is repeated, so nothing follows a second
|
|
261
|
+
one, and nothing about the banner's shape changes.
|
|
224
262
|
|
|
225
263
|
**An operator who stopped it is not a death** — re-arming over a deliberate
|
|
226
264
|
stop makes the wait unstoppable, which is worse than a wait that stops. But a
|
|
@@ -298,8 +336,11 @@ behind, and they cannot.
|
|
|
298
336
|
`fetch(location.pathname, …)`, so a page opened at `127.0.0.1:7760/…` and one
|
|
299
337
|
opened at `192.168.0.136:7760/…` reach the same server process and the same
|
|
300
338
|
pending store. One wait covers both, and a verdict pressed on either wakes the
|
|
301
|
-
same run.
|
|
302
|
-
|
|
339
|
+
same run. A `network` alternate — the `also:` tailnet address — is one more
|
|
340
|
+
door into the same room: the same server answers on it, so the wait-coverage
|
|
341
|
+
line stays true with nothing added to it. Between all of those the objection
|
|
342
|
+
does not apply — which is why they are offered, and why offering them gives
|
|
343
|
+
nothing up.
|
|
303
344
|
|
|
304
345
|
**So two things are required, and the second is what the old rule lacked.**
|
|
305
346
|
Every link is **labelled** with its tier, and one line says
|
|
@@ -410,7 +451,7 @@ behind it — say nothing rather than reporting that there was nothing to report
|
|
|
410
451
|
| `Landed` | A fast-forward, a tag, a cherry-pick. |
|
|
411
452
|
| `Worktree` | A worktree provisioned, entered, or torn down. |
|
|
412
453
|
| `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. |
|
|
454
|
+
| `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
455
|
| `Follow-ups` | **Always.** `none`, or one line each. |
|
|
415
456
|
| `Next` | **Last.** The single next action for this work — runnable from the state the run leaves behind. |
|
|
416
457
|
|
|
@@ -142,8 +142,8 @@ because writing it means reading the diff, and that spend is the user's call.
|
|
|
142
142
|
|
|
143
143
|
**A watch that dies is re-armed on the same window**, silently and bounded by
|
|
144
144
|
the age of that window — `.claude/rules/spec-reports.md` carries the contract,
|
|
145
|
-
including when to stop
|
|
146
|
-
here.
|
|
145
|
+
including when to stop, what the banner says instead, and when the
|
|
146
|
+
engine's `re-show:` brings the banner back. Do not restate it here.
|
|
147
147
|
|
|
148
148
|
```
|
|
149
149
|
skitterspec spec-env review <name> --claim-since <the timestamp> --json
|