@skitterbyte/skitterspec-linear 19.0.0 → 19.2.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 +71 -0
- package/README.md +1 -0
- package/assets/core/env.config.md +1 -1
- package/assets/core/linear.config.json.example +2 -1
- package/assets/core/linear.config.md +16 -1
- package/assets/rules/spec-planning.md +52 -11
- package/assets/rules/spec-reports.md +28 -2
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +47 -8
- package/assets/skills/spec-bug/SKILL.md +6 -2
- package/assets/skills/spec-complete/SKILL.md +39 -0
- package/assets/skills/spec-hotfix/SKILL.md +4 -0
- package/assets/skills/spec-incident/SKILL.md +142 -0
- package/assets/skills/spec-init/SKILL.md +2 -1
- package/assets/skills/spec-next/SKILL.md +2 -2
- package/package.json +1 -1
- package/src/cli.js +108 -3
- package/src/env/resolve.js +12 -4
- package/src/env/review.js +79 -0
- package/src/vendor/linear/api.js +37 -2
- package/src/vendor/linear/cli-sync.js +119 -3
- package/src/vendor/linear/config.js +35 -3
- package/src/vendor/provider-kit/src/config.js +44 -0
- package/src/vendor/sync-core/index.js +4 -1
- package/src/vendor/sync-core/src/normalize.js +137 -16
package/MIGRATION.md
CHANGED
|
@@ -1,5 +1,76 @@
|
|
|
1
1
|
# Migration guide
|
|
2
2
|
|
|
3
|
+
## `issue` and `incident` spec kinds, per-type states, incident log (additive — nothing breaks)
|
|
4
|
+
|
|
5
|
+
Specs can now be **issues** (`issue-` prefix — non-code work done as recorded
|
|
6
|
+
manual steps) and **incidents** (`incident-` prefix, captured live by the new
|
|
7
|
+
`/spec-incident` skill; `/spec-complete` ends one by writing `incident-log.md`
|
|
8
|
+
and posting it onto the tracker item as a comment, via the new
|
|
9
|
+
`spec-sync comment <spec> --file <f>` verb). A lifecycle bucket can map to a
|
|
10
|
+
different state per work item type (`statesByType` on Azure Boards and Jira)
|
|
11
|
+
or per spec kind (`statesByKind` on GitHub and Linear), both top-level beside
|
|
12
|
+
`states`, with `null` meaning "send no state" — and the pre-write check now
|
|
13
|
+
validates each type's effective states against **that type's own** list, so a
|
|
14
|
+
state only one type lacks refuses before anything is written. On Azure and
|
|
15
|
+
Jira, `spec-sync states --json` now prints a per-type map
|
|
16
|
+
(`{ "<type>": [names] }`); a flat array from an older file is still accepted
|
|
17
|
+
and checked as the union. A fix spec can carry
|
|
18
|
+
`> **Incident:** incident-<name>` (linked as related on push) and
|
|
19
|
+
`> **Severity:**` (`1 - Critical` … `4 - Low`). Configs without any of the new
|
|
20
|
+
keys behave exactly as before, and `skitterspec update` ships the new skill
|
|
21
|
+
and rules.
|
|
22
|
+
|
|
23
|
+
Consumer config, by provider:
|
|
24
|
+
|
|
25
|
+
- **Azure Boards** —
|
|
26
|
+
`azure.workItemTypeByKind: { "issue": "Issue", "incident": "Incident" }`,
|
|
27
|
+
plus
|
|
28
|
+
`statesByType: { "Issue": { "complete": "Closed" }, "Incident": { "backlog": null, "complete": "Closed" } }`.
|
|
29
|
+
Severity writes the built-in `Microsoft.VSTS.Common.Severity` — nothing to
|
|
30
|
+
configure; a type without the field skips it with a note. The incident link
|
|
31
|
+
is `System.LinkTypes.Related`.
|
|
32
|
+
- **GitHub** — `github.labelsByKind` accepts the new kinds;
|
|
33
|
+
`statesByKind: { "issue": { "complete": "Done" } }` routes a kind's board
|
|
34
|
+
Status (`null` sends none); `github.severityLabels: { "2": "sev-high" }`
|
|
35
|
+
maps the header's leading digit to a label. The incident rides in the
|
|
36
|
+
generated body as a `Related incident: #N` line.
|
|
37
|
+
- **Jira** — `jira.issueTypeByKind` accepts the new kinds; `statesByType`
|
|
38
|
+
keys by issue type; `jira.severityField` names the field to write (e.g.
|
|
39
|
+
`customfield_10900`). The incident link is a `Relates` issue link, added
|
|
40
|
+
once.
|
|
41
|
+
- **Linear** — `linear.labelsByKind` accepts the new kinds; `statesByKind`
|
|
42
|
+
keys by spec kind; `linear.severityLabels` maps digits to team labels. The
|
|
43
|
+
incident link is a related-issue relation.
|
|
44
|
+
|
|
45
|
+
## The `chore` spec kind, and per-type bodies (additive — nothing breaks)
|
|
46
|
+
|
|
47
|
+
Specs can now be **chores** (`chore-` prefix, `> **Type:** Chore`) and every
|
|
48
|
+
provider can map spec kinds to its own idiom. Configs without a mapping keep
|
|
49
|
+
working unchanged: an unmapped kind mints the provider's default type exactly
|
|
50
|
+
as before, and `System.Description` stays Azure's body field unless a type is
|
|
51
|
+
mapped away from it. `skitterspec update` ships the new skills and rules.
|
|
52
|
+
|
|
53
|
+
**Create tracker types and states before mapping them.** A mapping names
|
|
54
|
+
something the tracker must already have:
|
|
55
|
+
|
|
56
|
+
- **Azure Boards** — create the custom inherited type (e.g. `Chore`) and its
|
|
57
|
+
states in your process, then set
|
|
58
|
+
`azure.workItemTypeByKind: { "chore": "Chore" }`. To fill a Bug form's Repro
|
|
59
|
+
Steps instead of the hidden Description, set
|
|
60
|
+
`azure.bodyFieldByType: { "Bug": "Microsoft.VSTS.TCM.ReproSteps" }` — it
|
|
61
|
+
applies symmetrically to create, update, read-back and the edited-hash
|
|
62
|
+
compare, so `/spec-status` stays quiet after a push. Bugs minted before the
|
|
63
|
+
mapping keep reading their Description until the next push rewrites them.
|
|
64
|
+
`spec-sync doctor --check-remote` verifies every mapped type exists and
|
|
65
|
+
carries its body field.
|
|
66
|
+
- **GitHub** — `github.labelsByKind: { "chore": "chore" }` adds the kind's
|
|
67
|
+
label beside the spec marker.
|
|
68
|
+
- **Jira** — `jira.issueTypeByKind: { "bug": "Bug", "chore": "Task" }` picks
|
|
69
|
+
the mint type per kind; the type must exist in the project.
|
|
70
|
+
- **Linear** — `linear.labelsByKind: { "chore": "Chore" }` labels the mint;
|
|
71
|
+
the label must already exist on the team (a missing one is a one-line note,
|
|
72
|
+
never a failed push).
|
|
73
|
+
|
|
3
74
|
## `@skitterbyte/skitterspec-github` v1 → v2 (tell, don't track)
|
|
4
75
|
|
|
5
76
|
Skitterspec now tells GitHub about **its own** transitions and nothing
|
package/README.md
CHANGED
|
@@ -77,6 +77,7 @@ them. Your `specs/` content and live `.core` config are never touched.
|
|
|
77
77
|
| `/spec` | Grill to a shared understanding, then write a groomed spec |
|
|
78
78
|
| `/spec-bug` | Reproduce with a failing test, then drive it red→green |
|
|
79
79
|
| `/spec-hotfix` | Fix the released version: fork from a tag, land by tag + cherry-pick |
|
|
80
|
+
| `/spec-incident` | Capture a live outage as a record written during it, fixes linked |
|
|
80
81
|
| `/no-spec` | Work that genuinely has no spec — on its own branch all the same |
|
|
81
82
|
| `/spec-review` | Re-validate a spec against the code; refresh what drifted |
|
|
82
83
|
| `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 |
|
|
@@ -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
|
|
|
@@ -34,7 +34,17 @@ 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
|
+
// issue/incident, from the folder prefix), applied
|
|
40
|
+
// at mint — e.g. { "chore": "Chore" }. The label
|
|
41
|
+
// must already exist on the team; a missing one is
|
|
42
|
+
// a one-line note, never a failed push
|
|
43
|
+
"severityLabels": {} // one label per Severity: header digit
|
|
44
|
+
// ("2 - High" → "2") — e.g. { "2": "Sev High" },
|
|
45
|
+
// applied at mint. Unset, the header stays
|
|
46
|
+
// repo-only. A fix spec's Incident: header adds a
|
|
47
|
+
// related-issue relation to its incident
|
|
38
48
|
},
|
|
39
49
|
|
|
40
50
|
// Issue intake: `/spec <ISSUE-REF>` adopts any issue; `/spec --from-issue`
|
|
@@ -85,6 +95,11 @@ absence). A `sync.fieldOwnership` value outside `both|pull|push|none` is a hard
|
|
|
85
95
|
"cancelled": "Canceled"
|
|
86
96
|
},
|
|
87
97
|
|
|
98
|
+
// Per-KIND override laid over `states` (Linear has no work item types, so
|
|
99
|
+
// the spec's kind keys it) — e.g. { "issue": { "complete": "Done" } }. A
|
|
100
|
+
// bucket set to null sends no state; a bucket an entry lacks falls through.
|
|
101
|
+
"statesByKind": {},
|
|
102
|
+
|
|
88
103
|
// The spec's entry-point file the local snapshot + frontmatter live in.
|
|
89
104
|
"snapshot": {
|
|
90
105
|
"overviewFile": "00-overview.md"
|
|
@@ -7,9 +7,10 @@ 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/Issue) 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
|
+
| `/spec-incident` | (Incident) Capture a live outage as a record written during it — grill, write in flight, fixes as separate linked specs | `In Progress` | `specs/in-progress/` |
|
|
13
14
|
| `/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) |
|
|
14
15
|
| `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
|
|
15
16
|
| `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 | `In Progress` | `specs/in-progress/` |
|
|
@@ -587,30 +588,62 @@ none of them describes.
|
|
|
587
588
|
- **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
|
|
588
589
|
(architecture, code style, testing, database, etc.) rather than restating them.
|
|
589
590
|
|
|
590
|
-
## Spec types — Feature, Bug, Hotfix
|
|
591
|
+
## Spec types — Feature, Chore, Issue, Bug, Hotfix, Incident
|
|
591
592
|
|
|
592
|
-
Every spec is one of
|
|
593
|
+
Every spec is one of six types, recorded **both** in the header and the filename:
|
|
593
594
|
|
|
594
|
-
- **Header field:** `> **Type:** Feature`, `> **Type:**
|
|
595
|
-
`> **Type:** Hotfix
|
|
595
|
+
- **Header field:** `> **Type:** Feature`, `> **Type:** Chore`,
|
|
596
|
+
`> **Type:** Issue`, `> **Type:** Bug`, `> **Type:** Hotfix`, or
|
|
597
|
+
`> **Type:** Incident` (authoritative, greppable:
|
|
596
598
|
`grep -rl 'Type:.*Hotfix' specs/`).
|
|
597
|
-
- **Filename prefix:** `feat-<name>` for features, `
|
|
598
|
-
`
|
|
599
|
-
`
|
|
599
|
+
- **Filename prefix:** `feat-<name>` for features, `chore-<name>` for chores,
|
|
600
|
+
`issue-<name>` for issues, `bug-<name>` for bugs, `hotfix-<name>` for
|
|
601
|
+
hotfixes, `incident-<name>` for incidents (visible in listings;
|
|
602
|
+
glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
|
|
603
|
+
|
|
604
|
+
A **Chore** is code work no end user sees — tooling, CI, dependency bumps,
|
|
605
|
+
internal refactors. An **Issue** is work with **no code change at all** —
|
|
606
|
+
in-app configuration, a data fix, a support task — written as a spec of manual
|
|
607
|
+
steps so there is a record and a history; everything user-facing that changes
|
|
608
|
+
code is a feature. There is no
|
|
609
|
+
separate entry skill for either — `/spec` **proposes** feature, chore or issue
|
|
610
|
+
from what the
|
|
611
|
+
grilling defined, with a one-line reason, and the user confirms. A chore
|
|
612
|
+
defaults its `Gating:` to `none: not user-facing` (where gating is configured),
|
|
613
|
+
and its commits default to `chore`/`refactor`/`ci` types with **no**
|
|
614
|
+
`Release-Note:` footer — a chore is by definition not user-visible, so it has
|
|
615
|
+
no release note to write. An issue defaults its `Gating:` to `none: no code`
|
|
616
|
+
and its commits to `docs` with no `Release-Note:`, and it closes when the spec
|
|
617
|
+
completes — nothing is released. Feature specs keep `feat`; bug specs keep
|
|
618
|
+
`fix`.
|
|
619
|
+
Where a ticketing provider maps kinds to tracker types (e.g. Azure's
|
|
620
|
+
`workItemTypeByKind`), the chore mapping is what keeps tooling work off the
|
|
621
|
+
customer-facing release ladder.
|
|
600
622
|
|
|
601
623
|
A **Hotfix** is a Bug fixed against a **released tag** rather than `main`: it
|
|
602
624
|
carries an extra `> **Base version:** <tag>` header, forks its worktree from that
|
|
603
625
|
tag, and lands by tagging a new patch + cherry-picking onto `main` (never a
|
|
604
626
|
fast-forward merge). `/spec-live` refuses a hotfix — test it with `/spec-connect`.
|
|
605
627
|
|
|
606
|
-
|
|
628
|
+
An **Incident** is an outage or degradation of a live service, captured by
|
|
629
|
+
**`/spec-incident`** during the outage, so it starts straight in
|
|
630
|
+
`specs/in-progress/`. It is a record, not delivery work: its fixes are
|
|
631
|
+
separate hotfix, bug, chore or issue specs, each carrying
|
|
632
|
+
`> **Incident:** incident-<name>` so the push links them, and they are never
|
|
633
|
+
its phases. It carries `> **Severity:**` (Azure's literal values,
|
|
634
|
+
`1 - Critical` … `4 - Low`) and a `## Timeline` appended to as the incident
|
|
635
|
+
unfolds; `/spec-complete` writes `incident-log.md` from it and pushes the log
|
|
636
|
+
onto the tracker item as a comment.
|
|
637
|
+
|
|
638
|
+
All six types share the same lifecycle folders below — type is orthogonal to
|
|
607
639
|
status.
|
|
608
640
|
|
|
609
641
|
## Header fields & State log (audit trail)
|
|
610
642
|
|
|
611
643
|
Every spec header carries:
|
|
612
644
|
|
|
613
|
-
- `> **Name:**` — the spec's folder name
|
|
645
|
+
- `> **Name:**` — the spec's folder name
|
|
646
|
+
(`feat-`/`chore-`/`issue-`/`bug-`/`hotfix-`/`incident-<kebab-name>`).
|
|
614
647
|
It's the handle you pass to `/spec-start` and the other lifecycle skills, surfaced
|
|
615
648
|
in the header so it's copy-pasteable without digging for the folder name.
|
|
616
649
|
- `> **Author:**` — who created the spec (set at `/spec` / `/spec-bug`, defaults
|
|
@@ -621,6 +654,14 @@ Every spec header carries:
|
|
|
621
654
|
**only when `specs/.core/gating.config.json` exists**: a flag name, or
|
|
622
655
|
`none: <one-line reason>`. Absent entirely in a project that has not adopted
|
|
623
656
|
gating.
|
|
657
|
+
- `> **Severity:**` — on bug, hotfix and incident specs, optional except where
|
|
658
|
+
`/spec-incident` grills it: Azure's literal values
|
|
659
|
+
(`1 - Critical` … `4 - Low`). The push writes it where the provider has a
|
|
660
|
+
home for it; absent, nothing is sent.
|
|
661
|
+
- `> **Incident:**` — on a spec that is a **fix** for an open incident:
|
|
662
|
+
`incident-<name>`. The push links the two as related on the tracker
|
|
663
|
+
(one-way; the repo owns the link), and `/spec-complete` on the incident
|
|
664
|
+
counts the spec among its fixes. Absent on everything else.
|
|
624
665
|
|
|
625
666
|
Every spec also has a **State log** table — the audit trail of folder/status
|
|
626
667
|
transitions. Each lifecycle skill appends exactly one row when it changes state:
|
|
@@ -655,7 +696,7 @@ When asked for a plan, implementation strategy, or feature breakdown:
|
|
|
655
696
|
|
|
656
697
|
```
|
|
657
698
|
specs/backlog/ Ready (or Draft) specs (/spec)
|
|
658
|
-
specs/in-progress/ under active implementation (/spec-start, /spec-bug)
|
|
699
|
+
specs/in-progress/ under active implementation (/spec-start, /spec-bug, /spec-incident)
|
|
659
700
|
specs/complete/ finished (/spec-complete)
|
|
660
701
|
specs/cancelled/ abandoned, with a reason on the header (/spec-cancel)
|
|
661
702
|
specs/.core/ project rules — ALWAYS APPLY, never moved
|
|
@@ -231,8 +231,34 @@ again on the **same** `--since`. Not a fresh one — a pass that arrived during
|
|
|
231
231
|
the gap is still inside the original window, and re-arming on a new timestamp
|
|
232
232
|
would strand exactly that pass.
|
|
233
233
|
|
|
234
|
-
**Say
|
|
235
|
-
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.
|
|
236
262
|
|
|
237
263
|
**An operator who stopped it is not a death** — re-arming over a deliberate
|
|
238
264
|
stop makes the wait unstoppable, which is worse than a wait that stops. But a
|
|
@@ -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
|
|
@@ -188,9 +188,42 @@ not write the spec until this is resolved.
|
|
|
188
188
|
Stop grilling when there are no unresolved branches that would change the spec.
|
|
189
189
|
Briefly play back the agreed understanding before writing.
|
|
190
190
|
|
|
191
|
+
### Propose the kind — feature, chore or issue
|
|
192
|
+
|
|
193
|
+
This skill writes three kinds of spec, and
|
|
194
|
+
**you propose which from what the grilling defined, with a one-line reason; the user confirms or overrides.**
|
|
195
|
+
The
|
|
196
|
+
lines that decide it: a **chore** is code work no end user sees — tooling, CI,
|
|
197
|
+
dependency bumps, internal refactors. An **issue** is work with
|
|
198
|
+
**no code change at all** — in-app configuration, a data fix, a support task —
|
|
199
|
+
written as a spec of manual steps so there is a record and a history.
|
|
200
|
+
Everything user-facing that changes code is a **feature**. So the proposal
|
|
201
|
+
reads like *"no user-visible surface → chore"*, *"no code change, manual
|
|
202
|
+
steps → issue"* or *"adds an endpoint users call → feature"*.
|
|
203
|
+
|
|
204
|
+
The kind is recorded twice, and both follow from the answer: the folder prefix
|
|
205
|
+
(`feat-` / `chore-` / `issue-`) and the `> **Type:**` header
|
|
206
|
+
(`Feature` / `Chore` / `Issue`). A chore
|
|
207
|
+
also defaults its `Gating:` to `none: not user-facing` (only when gating is
|
|
208
|
+
configured — offer the default, let the user override it like any other
|
|
209
|
+
answer), and its commits default to `chore`/`refactor`/`ci` types with no
|
|
210
|
+
`Release-Note:` (see `.claude/rules/spec-planning.md`). An issue defaults its
|
|
211
|
+
`Gating:` to `none: no code`, and its commits to `docs` with no
|
|
212
|
+
`Release-Note:` — its phases are manual steps, not code, though `/spec-start`
|
|
213
|
+
still gives it a worktree, because the document needs one and the history is
|
|
214
|
+
the point.
|
|
215
|
+
|
|
216
|
+
There is no `/spec-chore` or `/spec-issue` and none should be added: one entry
|
|
217
|
+
point, one grill, and the kind is an output of understanding the work rather
|
|
218
|
+
than a door the user must pick before describing it. The one kind with its own
|
|
219
|
+
door is the **incident** — an outage or degradation of a live service, which
|
|
220
|
+
needs a different grill and starts mid-flight — so when the grilling uncovers
|
|
221
|
+
one, hand off to **`/spec-incident`** rather than writing it here.
|
|
222
|
+
|
|
191
223
|
## Phase B — write the spec
|
|
192
224
|
|
|
193
|
-
This skill is for **features**. For bugs, use `/spec-bug`
|
|
225
|
+
This skill is for **features, chores and issues**. For bugs, use `/spec-bug`
|
|
226
|
+
(test-first, red→green); for a live outage, `/spec-incident`.
|
|
194
227
|
|
|
195
228
|
### Write it in its own worktree
|
|
196
229
|
|
|
@@ -257,8 +290,9 @@ move to, **warn, don't refuse**, and say the trailer for that commit wants
|
|
|
257
290
|
that phase's goal, its task checkboxes (tests included), and any phase-specific
|
|
258
291
|
notes. **Even a single-phase spec gets `01-….md`** — never lump phase tasks
|
|
259
292
|
into `00-overview.md`. This keeps each phase easy to dive into on its own.
|
|
260
|
-
- Choose a short kebab-case name and **prefix it
|
|
261
|
-
|
|
293
|
+
- Choose a short kebab-case name and **prefix it with the kind** — `feat-` for
|
|
294
|
+
a feature, `chore-` for a chore, `issue-` for an issue (the bug counterpart
|
|
295
|
+
uses `bug-`, the incident one `incident-`).
|
|
262
296
|
|
|
263
297
|
Use this template (keep it **as concise as possible** — no filler, no restating
|
|
264
298
|
the codebase, link rather than duplicate):
|
|
@@ -266,8 +300,8 @@ the codebase, link rather than duplicate):
|
|
|
266
300
|
```markdown
|
|
267
301
|
# <Feature title>
|
|
268
302
|
|
|
269
|
-
> **Type:** Feature
|
|
270
|
-
> **Name:** feat
|
|
303
|
+
> **Type:** <Feature, Chore or Issue — the kind proposed after Phase A>
|
|
304
|
+
> **Name:** <feat-, chore- or issue-><kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
|
|
271
305
|
> **Status:** Ready — not started
|
|
272
306
|
> **Author:** <git user.name — `git config user.name`>
|
|
273
307
|
> **Developer:** —
|
|
@@ -275,8 +309,13 @@ the codebase, link rather than duplicate):
|
|
|
275
309
|
> **Area:** <comma-separated files/modules this touches>
|
|
276
310
|
> **Stack:** <worktree — or "worktree + docker" if it touches the DB/stateful
|
|
277
311
|
> services; only acted on when isolation is enabled — see Phase A item 9>
|
|
312
|
+
> **Incident:** <incident-<name> — only when this spec is a fix for an open
|
|
313
|
+
> incident spec; the next push links the two as related on the tracker, and
|
|
314
|
+
> `/spec-complete` on the incident counts this spec among its fixes. Omit the
|
|
315
|
+
> line entirely otherwise>
|
|
278
316
|
> **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
|
|
279
|
-
> is configured; omit the line entirely otherwise.
|
|
317
|
+
> is configured; omit the line entirely otherwise. A chore defaults to
|
|
318
|
+
> "none: not user-facing". An empty value or a bare
|
|
280
319
|
> "none" is not a valid outcome — see Phase A item 10>
|
|
281
320
|
|
|
282
321
|
## Problem
|
|
@@ -538,8 +577,8 @@ the verdict — and the reader's conclusion is about what the page showed them.
|
|
|
538
577
|
|
|
539
578
|
**A watch that dies is re-armed on the same window**, silently and bounded by
|
|
540
579
|
the age of that window — `.claude/rules/spec-reports.md` carries the contract,
|
|
541
|
-
including when to stop
|
|
542
|
-
here.
|
|
580
|
+
including when to stop, what the banner says instead, and when the
|
|
581
|
+
engine's `re-show:` brings the banner back. Do not restate it here.
|
|
543
582
|
|
|
544
583
|
```
|
|
545
584
|
skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json
|
|
@@ -269,6 +269,10 @@ because work is already underway. Keep it lean:
|
|
|
269
269
|
> **Developer:** <git user.name — you, since you're fixing it now>
|
|
270
270
|
> **Raised:** <YYYY-MM-DD (today)>
|
|
271
271
|
> **Area:** <files/modules>
|
|
272
|
+
> **Severity:** <Azure's literal values, "1 - Critical" … "4 - Low" — optional;
|
|
273
|
+
> the push writes it where the provider has a home for it. Omit otherwise>
|
|
274
|
+
> **Incident:** <incident-<name> — only when this bug is a fix for an open
|
|
275
|
+
> incident spec; the next push links the two as related. Omit otherwise>
|
|
272
276
|
> **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
|
|
273
277
|
> is configured; omit the line entirely otherwise>
|
|
274
278
|
|
|
@@ -571,8 +575,8 @@ and the routing on the verdict is `/spec-diff` §2 and §4, as it is everywhere.
|
|
|
571
575
|
|
|
572
576
|
**A watch that dies is re-armed on the same window**, silently and bounded by
|
|
573
577
|
the age of that window — `.claude/rules/spec-reports.md` carries the contract,
|
|
574
|
-
including when to stop
|
|
575
|
-
here.
|
|
578
|
+
including when to stop, what the banner says instead, and when the
|
|
579
|
+
engine's `re-show:` brings the banner back. Do not restate it here.
|
|
576
580
|
|
|
577
581
|
**Why this skill arms as well as waits.** Waiting is what any offer does;
|
|
578
582
|
**arming** asserts an obligation that outlives the turn, and belongs only to
|
|
@@ -42,6 +42,45 @@ Before marking complete, confirm the work is actually finished:
|
|
|
42
42
|
is its own, and step 4 commits that.
|
|
43
43
|
|
|
44
44
|
|
|
45
|
+
### An incident spec — the log, and the open-fix check
|
|
46
|
+
|
|
47
|
+
**Only for `Type: Incident` specs** (folder prefix `incident-`); every other
|
|
48
|
+
kind skips this in silence.
|
|
49
|
+
|
|
50
|
+
1. **Check for open linked fixes.** Grep `specs/backlog/` and
|
|
51
|
+
`specs/in-progress/` for specs carrying `> **Incident:** <this spec's name>`.
|
|
52
|
+
Any hit is a fix still open: **refuse**, naming each one, and offer to
|
|
53
|
+
complete anyway with it listed as outstanding in the log — the operator
|
|
54
|
+
answers; record the choice in the spec's Changelog either way.
|
|
55
|
+
BLIND SPOT, named: a fix spec authored but not yet landed on the base branch
|
|
56
|
+
is invisible to this grep — acceptable, because `/spec`'s committing
|
|
57
|
+
verdicts land authored specs on the base
|
|
58
|
+
(`.claude/rules/negative-checks.md`).
|
|
59
|
+
2. **Write `incident-log.md`** into the spec folder — the stakeholder- and
|
|
60
|
+
support-facing record, built from the spec and its linked fixes:
|
|
61
|
+
summary · severity · timeline (started, detected, mitigated, resolved) ·
|
|
62
|
+
impact (who, what, for how long) · root cause · the fixes (each linked
|
|
63
|
+
spec, its ticket, and the release it shipped in — `spec-sync released`
|
|
64
|
+
answers that where a provider is installed; a fix completed but not yet
|
|
65
|
+
released is listed as such) · what went well and what didn't · follow-ups,
|
|
66
|
+
each offered as a `/spec` on the spot.
|
|
67
|
+
3. **Push the log onto the incident item as a comment** (only when a provider
|
|
68
|
+
is installed and the spec is linked):
|
|
69
|
+
|
|
70
|
+
```
|
|
71
|
+
skitterspec spec-sync comment <spec> --file specs/in-progress/<spec>/incident-log.md
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
A comment, deliberately: the item's description is generated from the spec,
|
|
75
|
+
so a log written there would be clobbered by the next push — comments are
|
|
76
|
+
the one surface one-way sync never touches. The command exits 0 on every
|
|
77
|
+
cannot-tell (unlinked, offline, no credentials) and says so; relay the line
|
|
78
|
+
and finish either way — the log in the repo is the record.
|
|
79
|
+
|
|
80
|
+
Completion then proceeds as normal: the per-type state map decides what the
|
|
81
|
+
tracker is sent (an Incident completes to whatever `statesByType` names for
|
|
82
|
+
it), and steps 3–7 below are unchanged.
|
|
83
|
+
|
|
45
84
|
### Release gating (only when configured)
|
|
46
85
|
|
|
47
86
|
**Only when `specs/.core/gating.config.json` exists.** Run
|
|
@@ -293,6 +293,10 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
|
|
|
293
293
|
> **Base version:** <tag prod is running, e.g. v33.16.4>
|
|
294
294
|
> **Raised:** <YYYY-MM-DD (today)>
|
|
295
295
|
> **Area:** <files/modules>
|
|
296
|
+
> **Severity:** <Azure's literal values, "1 - Critical" … "4 - Low" — optional;
|
|
297
|
+
> the push writes it where the provider has a home for it. Omit otherwise>
|
|
298
|
+
> **Incident:** <incident-<name> — only when this hotfix is a fix for an open
|
|
299
|
+
> incident spec; the next push links the two as related. Omit otherwise>
|
|
296
300
|
> **Gating:** <pre-filled "none: hotfix — restoring released behaviour"; only
|
|
297
301
|
> when release gating is configured, and overridable — see below>
|
|
298
302
|
|
|
@@ -0,0 +1,142 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec-incident
|
|
3
|
+
description: Capture a live incident — an outage or degradation of a running service — as an Incident-type spec written during the outage. Grills for what is down, since when, who is affected, severity and what was tried, then writes the spec straight into specs/in-progress/ with a Timeline appended to as it unfolds. Fixes are separate linked specs, never phases. Use when the user says "/spec-incident", "we have an outage", "prod is down and I need an incident record", or asks to track an incident.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /spec-incident — capture a live incident
|
|
7
|
+
|
|
8
|
+
> Stay silent while this runs — speak only to ask something you cannot answer
|
|
9
|
+
> yourself, or to report a failure at the moment it happens. Read
|
|
10
|
+
> `.claude/rules/spec-reports.md` before reporting; it defines the block this
|
|
11
|
+
> skill ends with.
|
|
12
|
+
|
|
13
|
+
An **incident** is an outage or degradation of a live service. It is not
|
|
14
|
+
delivery work: the fixes are separate hotfix, bug, chore or issue specs, each
|
|
15
|
+
linked back to it, and this spec is the **record** — what happened, when, to
|
|
16
|
+
whom, and what was done. It is written **during** the outage, so it starts in
|
|
17
|
+
`specs/in-progress/`, there is no backlog stop and no review page to wait on:
|
|
18
|
+
speed matters, and the record is reviewed at completion, when
|
|
19
|
+
`/spec-complete` writes the incident log from it.
|
|
20
|
+
|
|
21
|
+
**This skill is not the response.** Mitigating comes first, and nothing here
|
|
22
|
+
blocks it — the grill is short, the spec is small, and everything else is
|
|
23
|
+
appended as it happens.
|
|
24
|
+
|
|
25
|
+
## 1. Grill — short, and only what the record needs
|
|
26
|
+
|
|
27
|
+
Ask for exactly these, batched, with nothing speculative:
|
|
28
|
+
|
|
29
|
+
1. **What is down or degraded** — the service, and how it is failing.
|
|
30
|
+
2. **Since when** — first report, and detection time where they differ.
|
|
31
|
+
3. **Who is affected** — which users or systems, and how badly.
|
|
32
|
+
4. **Severity** — Azure's literal values: `1 - Critical`, `2 - High`,
|
|
33
|
+
`3 - Medium`, `4 - Low`. Propose one from the impact described; the user
|
|
34
|
+
confirms.
|
|
35
|
+
5. **What has been tried** — anything already attempted, and its effect.
|
|
36
|
+
|
|
37
|
+
A root cause is **not** grilled: nobody has it yet, and the Timeline is where
|
|
38
|
+
the investigation lands as it happens.
|
|
39
|
+
|
|
40
|
+
## 2. Write it, in flight
|
|
41
|
+
|
|
42
|
+
Pick a short kebab name prefixed `incident-` (e.g. `incident-api-outage`).
|
|
43
|
+
|
|
44
|
+
**With per-spec isolation** (`specs/.core/env.config.json` present), provision
|
|
45
|
+
before writing, exactly as `/spec` Phase B does: run
|
|
46
|
+
`skitterspec spec-env up <name> --docs`, run the commands it prints, `cd` into
|
|
47
|
+
the worktree, and confirm with a bare `skitterspec spec-env resolve` naming
|
|
48
|
+
this spec. Without isolation, write where you stand.
|
|
49
|
+
|
|
50
|
+
The spec is a folder in **`specs/in-progress/`** — never backlog — with
|
|
51
|
+
`00-overview.md` and one phase file:
|
|
52
|
+
|
|
53
|
+
```markdown
|
|
54
|
+
# Incident: <short title>
|
|
55
|
+
|
|
56
|
+
> **Type:** Incident
|
|
57
|
+
> **Name:** incident-<kebab-name>
|
|
58
|
+
> **Status:** In Progress — live (started <YYYY-MM-DD>)
|
|
59
|
+
> **Author:** <git user.name>
|
|
60
|
+
> **Developer:** <git user.name — whoever is running the incident>
|
|
61
|
+
> **Raised:** <YYYY-MM-DD (today)>
|
|
62
|
+
> **Severity:** <1 - Critical … 4 - Low>
|
|
63
|
+
> **Gating:** <pre-filled "none: incident record, no code"; only when release
|
|
64
|
+
> gating is configured, omit otherwise>
|
|
65
|
+
|
|
66
|
+
## Impact
|
|
67
|
+
|
|
68
|
+
<who is affected, what is failing, since when — from the grill>
|
|
69
|
+
|
|
70
|
+
## Timeline
|
|
71
|
+
|
|
72
|
+
- <YYYY-MM-DD HH:MM> — <first report / detected / what was tried / what changed>
|
|
73
|
+
|
|
74
|
+
## Fixes
|
|
75
|
+
|
|
76
|
+
<one line per fix spec as they are opened — see step 4. "None yet" until then.>
|
|
77
|
+
|
|
78
|
+
## State log
|
|
79
|
+
|
|
80
|
+
| Date | Status | Folder | By |
|
|
81
|
+
|------|--------|--------|----|
|
|
82
|
+
| <YYYY-MM-DD> | In Progress | in-progress | <author> |
|
|
83
|
+
|
|
84
|
+
## Changelog
|
|
85
|
+
|
|
86
|
+
- <YYYY-MM-DD> — Incident captured.
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
The phase file `01-response.md` holds the response as tasks — mitigate,
|
|
90
|
+
diagnose, open fix specs, verify recovery — manual steps, not code. Commits in
|
|
91
|
+
this spec default to `docs` with no `Release-Note:`.
|
|
92
|
+
|
|
93
|
+
## 3. Link to the tracker (only if a provider is installed)
|
|
94
|
+
|
|
95
|
+
Run the provider's linking push exactly as `/spec` Phase E describes — the
|
|
96
|
+
spec is already in `in-progress`, so the mint lands in the incident's
|
|
97
|
+
in-flight state (with Azure's `statesByType`, an Incident is created Active
|
|
98
|
+
and never sent New; the `Severity:` header is written where the provider has a
|
|
99
|
+
home for it). No provider, or an unreachable tracker, is one line and the
|
|
100
|
+
record stands in the repo.
|
|
101
|
+
|
|
102
|
+
## 4. Run the incident from the spec
|
|
103
|
+
|
|
104
|
+
- **Append to the Timeline** as things happen — dated lines, cheap and often.
|
|
105
|
+
- **Fixes are separate specs**: a prod-version fix is `/spec-hotfix`, a
|
|
106
|
+
mainline defect `/spec-bug`, tooling `/spec` (chore), manual remediation
|
|
107
|
+
`/spec` (issue). Each fix spec carries `> **Incident:** incident-<name>` in
|
|
108
|
+
its header, which the next push turns into a related link on the tracker.
|
|
109
|
+
They are never phases of this spec.
|
|
110
|
+
- **Mid-incident board states stay manual**: skitterspec writes states at
|
|
111
|
+
lifecycle moves only, so moving the ticket to a Mitigated-style state during
|
|
112
|
+
the outage is done on the board, and the next push leaves it until the spec
|
|
113
|
+
itself moves.
|
|
114
|
+
|
|
115
|
+
## 5. End of the outage is not the end of the spec
|
|
116
|
+
|
|
117
|
+
When the service is recovered, say so in the Timeline and keep the spec in
|
|
118
|
+
flight until the record is complete — root cause written, fixes linked.
|
|
119
|
+
`/spec-complete` is the ending: it writes `incident-log.md` from this spec and
|
|
120
|
+
its linked fixes, refuses while a linked fix is still open (and offers to
|
|
121
|
+
complete anyway with it listed as outstanding), and pushes the log onto the
|
|
122
|
+
incident item as a comment.
|
|
123
|
+
|
|
124
|
+
## Report
|
|
125
|
+
|
|
126
|
+
End with the block defined in `.claude/rules/spec-reports.md`. That file
|
|
127
|
+
carries the shape; this section carries only what is specific here.
|
|
128
|
+
|
|
129
|
+
**Verdicts**
|
|
130
|
+
|
|
131
|
+
- `✅` — the incident spec is written, in flight, and (where a provider is
|
|
132
|
+
installed) linked.
|
|
133
|
+
- `⚠️` — written and in flight, with something worth knowing (a mint that
|
|
134
|
+
failed, a worktree that could not be provisioned so it was written in
|
|
135
|
+
place).
|
|
136
|
+
- `⏸` — the grill could not establish what is down, so nothing was written.
|
|
137
|
+
|
|
138
|
+
**Fields:** `Tracker` · `Branch` · `Spec` · `Built` · `Worktree` ·
|
|
139
|
+
`Follow-ups` · `Next`
|
|
140
|
+
|
|
141
|
+
`Next` is the response itself — the first task of `01-response.md` — never a
|
|
142
|
+
review page: nothing here waits on a verdict while a service is down.
|
|
@@ -27,8 +27,9 @@ clobber customised content. Finish with a summary of created vs already-present.
|
|
|
27
27
|
> **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
|
|
28
28
|
> `--reset` (reset needs `--yes`) drive the stronger actions.
|
|
29
29
|
|
|
30
|
-
The system is **
|
|
30
|
+
The system is **fourteen skills**: `spec` (feature, chore or issue), `spec-bug` (bug),
|
|
31
31
|
`spec-hotfix` (a bug fixed on a released tag),
|
|
32
|
+
`spec-incident` (a live outage, recorded as it happens),
|
|
32
33
|
`no-spec` (work that genuinely has none — off the base branch all the same),
|
|
33
34
|
`spec-review`, `spec-start`,
|
|
34
35
|
`spec-next`, `spec-diff` (read a spec's diff as a page),
|
|
@@ -506,8 +506,8 @@ reading — and that is the gap the whole gate exists to close.
|
|
|
506
506
|
|
|
507
507
|
**A watch that dies is re-armed on the same window**, silently and bounded by
|
|
508
508
|
the age of that window — `.claude/rules/spec-reports.md` carries the contract,
|
|
509
|
-
including when to stop
|
|
510
|
-
here.
|
|
509
|
+
including when to stop, what the banner says instead, and when the
|
|
510
|
+
engine's `re-show:` brings the banner back. Do not restate it here.
|
|
511
511
|
|
|
512
512
|
Then **end your turn**. Do not poll it and do not hold the turn open: the
|
|
513
513
|
point is that the reader has the terminal back while they read.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skitterbyte/skitterspec-linear",
|
|
3
|
-
"version": "19.
|
|
3
|
+
"version": "19.2.0",
|
|
4
4
|
"description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|