@skitterbyte/skitterspec-linear 19.5.0 → 19.6.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.
@@ -647,17 +647,17 @@ none of them describes.
647
647
  - **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
648
648
  (architecture, code style, testing, database, etc.) rather than restating them.
649
649
 
650
- ## Spec types — Feature, Chore, Issue, Bug, Hotfix, Incident
650
+ ## Spec types — Feature, Chore, Issue, Bug, Hotfix, Incident, Epic
651
651
 
652
- Every spec is one of six types, recorded **both** in the header and the filename:
652
+ Every spec is one of seven types, recorded **both** in the header and the filename:
653
653
 
654
654
  - **Header field:** `> **Type:** Feature`, `> **Type:** Chore`,
655
- `> **Type:** Issue`, `> **Type:** Bug`, `> **Type:** Hotfix`, or
656
- `> **Type:** Incident` (authoritative, greppable:
655
+ `> **Type:** Issue`, `> **Type:** Bug`, `> **Type:** Hotfix`,
656
+ `> **Type:** Incident`, or `> **Type:** Epic` (authoritative, greppable:
657
657
  `grep -rl 'Type:.*Hotfix' specs/`).
658
658
  - **Filename prefix:** `feat-<name>` for features, `chore-<name>` for chores,
659
659
  `issue-<name>` for issues, `bug-<name>` for bugs, `hotfix-<name>` for
660
- hotfixes, `incident-<name>` for incidents (visible in listings;
660
+ hotfixes, `incident-<name>` for incidents, `epic-<name>` for epics (visible in listings;
661
661
  glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
662
662
 
663
663
  A **Chore** is code work no end user sees — tooling, CI, dependency bumps,
@@ -694,6 +694,36 @@ its phases. It carries `> **Severity:**` (Azure's literal values,
694
694
  unfolds; `/spec-complete` writes `incident-log.md` from it and pushes the log
695
695
  onto the tracker item as a comment.
696
696
 
697
+ An **Epic** is a spec of specs: `epic-<name>/00-overview.md` and
698
+ **no phase files** — the one kind for which that is valid — recording why a group belongs
699
+ together and, optionally, `> **Lanes:** N`, how many members may be in flight at
700
+ once. `/spec` proposes it when the grill describes several specs and their
701
+ order. **The order lives on the members, never on the epic**: each carries
702
+ `> **Epic:** epic-<name>` and `> **Waits on:**`, and any phase file may carry
703
+ its own `Waits on:` for a wait that holds only that phase.
704
+ `skitterspec epic status <epic>` turns those headers into what can start now,
705
+ what is blocked and on what, the waves, the phase-level sync points, and the
706
+ pairs whose `Area:` overlaps (never together). A wait is met only on the base
707
+ branch — the spec in `complete/`, or that phase file reading done — and
708
+ anything it cannot see is cannot-tell, never met.
709
+
710
+ The rule is checked **where the work happens**: `/spec-start` and `/spec-next`
711
+ on a member ask `skitterspec epic check` before building, and an unmet wait
712
+ warns and offers a recorded bypass (`.claude/rules/offered-unblocks.md`) — it
713
+ never refuses, and it never lets a build pass the wait in silence. An epic
714
+ itself gets a documents-only worktree, `/spec-next` refuses it, and
715
+ `/spec-complete` refuses while a member is open, offering to complete with them
716
+ listed.
717
+
718
+ **Migrating an `issue-` plan spec to an epic.** A coordination spec written
719
+ before epics existed — waves as phases, ticked by hand — becomes one by moving
720
+ its order onto its members: rename the folder to `epic-<name>` (`git mv`), set
721
+ `> **Type:** Epic`, add `> **Epic:**` and `> **Waits on:**` to each member (and
722
+ a phase file's own `Waits on:` for a phase-level sync point), and delete the
723
+ wave phase files — `epic status` derives them. Keep the plan's Decisions: they
724
+ are the *why* the members' headers cannot say. Then check that
725
+ `skitterspec epic status <epic>` reproduces the plan you had.
726
+
697
727
  ### Kind routing — any door, the right spec
698
728
 
699
729
  `/spec` is the default door, so the kind of work someone describes does not
@@ -744,7 +774,7 @@ list to maintain, and nothing here reads a label. A ticketing provider's
744
774
  intake label routing (`intake.bugLabels` / `intake.hotfixLabels`) is a
745
775
  separate, earlier check and is unchanged by this.
746
776
 
747
- All six types share the same lifecycle folders below — type is orthogonal to
777
+ All seven types share the same lifecycle folders below — type is orthogonal to
748
778
  status.
749
779
 
750
780
  ## Header fields & State log (audit trail)
@@ -752,7 +782,7 @@ status.
752
782
  Every spec header carries:
753
783
 
754
784
  - `> **Name:**` — the spec's folder name
755
- (`feat-`/`chore-`/`issue-`/`bug-`/`hotfix-`/`incident-<kebab-name>`).
785
+ (`feat-`/`chore-`/`issue-`/`bug-`/`hotfix-`/`incident-`/`epic-<kebab-name>`).
756
786
  It's the handle you pass to `/spec-start` and the other lifecycle skills, surfaced
757
787
  in the header so it's copy-pasteable without digging for the folder name.
758
788
  - `> **Author:**` — who created the spec (set at `/spec` / `/spec-bug`, defaults
@@ -771,6 +801,14 @@ Every spec header carries:
771
801
  `incident-<name>`. The push links the two as related on the tracker
772
802
  (one-way; the repo owns the link), and `/spec-complete` on the incident
773
803
  counts the spec among its fixes. Absent on everything else.
804
+ - `> **Epic:**` — on a spec that is a **member** of an epic: `epic-<name>`.
805
+ Absent on everything else.
806
+ - `> **Waits on:**` — on an epic member: what its start waits for, as
807
+ `<spec>` (that spec complete) or `<spec> phase N` (that phase done on the base
808
+ branch), comma-separated, or `none`. A phase file may carry its own, holding
809
+ only that phase.
810
+ - `> **Lanes:**` — on an epic, optional: how many members may be in flight at
811
+ once.
774
812
 
775
813
  **Under a provider's default `pull`, these three are the tracker's** —
776
814
  `Status:`, `Developer:` and the State log — and new specs carry
@@ -223,7 +223,7 @@ shape belongs to Phase 0's label routing, which fires before any grilling has
223
223
  happened and so has nothing to lose. The full routing matrix lives in
224
224
  `.claude/rules/spec-planning.md`.
225
225
 
226
- ### Propose the kind — feature, chore or issue
226
+ ### Propose the kind — feature, chore or issue (or an epic of them)
227
227
 
228
228
  This skill writes three kinds of spec, and
229
229
  **you propose which from what the grilling defined, with a one-line reason; the user confirms or overrides.**
@@ -248,7 +248,16 @@ answer), and its commits default to `chore`/`refactor`/`ci` types with no
248
248
  still gives it a worktree, because the document needs one and the history is
249
249
  the point.
250
250
 
251
- There is no `/spec-chore` or `/spec-issue` and none should be added: one entry
251
+ **And when the grilling describes several specs and their order, it is an epic.**
252
+ An **epic** is a spec of specs: it records why a group of specs belongs together
253
+ and how many may run at once, and holds no phases of its own — its progress is
254
+ its members'. Signals: the work is plainly more than one spec, the user is
255
+ sequencing them ("this has to land before that"), or two of them would edit the
256
+ same files. Propose it as *"several specs with an order between them → epic"*,
257
+ and on a yes write the epic **and** each member as its own spec — the epic is
258
+ not a container for their phases (see **Writing an epic** below).
259
+
260
+ There is no `/spec-chore`, `/spec-issue` or `/spec-epic` and none should be added: one entry
252
261
  point, one grill, and the kind is an output of understanding the work rather
253
262
  than a door the user must pick before describing it. The kinds with their own
254
263
  doors — bug, hotfix, and the **incident**, an outage or degradation of a live
@@ -260,8 +269,9 @@ unraised is a missed watch, not a reason to write the wrong kind.
260
269
 
261
270
  ## Phase B — write the spec
262
271
 
263
- This skill is for **features, chores and issues**. For bugs, use `/spec-bug`
264
- (test-first, red→green); for a live outage, `/spec-incident`.
272
+ This skill is for **features, chores and issues**, and the **epics** that group
273
+ them. For bugs, use `/spec-bug` (test-first, red→green); for a live outage,
274
+ `/spec-incident`.
265
275
 
266
276
  ### Write it in its own worktree
267
277
 
@@ -329,8 +339,8 @@ move to, **warn, don't refuse**, and say the trailer for that commit wants
329
339
  notes. **Even a single-phase spec gets `01-….md`** — never lump phase tasks
330
340
  into `00-overview.md`. This keeps each phase easy to dive into on its own.
331
341
  - Choose a short kebab-case name and **prefix it with the kind** — `feat-` for
332
- a feature, `chore-` for a chore, `issue-` for an issue (the bug counterpart
333
- uses `bug-`, the incident one `incident-`).
342
+ a feature, `chore-` for a chore, `issue-` for an issue, `epic-` for an epic
343
+ (the bug counterpart uses `bug-`, the incident one `incident-`).
334
344
 
335
345
  **Who owns this spec's status.** Only when `specs/.core/linear.config.json` exists.
336
346
  Run `skitterspec spec-sync ownership --json` once and read both values:
@@ -373,6 +383,11 @@ the codebase, link rather than duplicate):
373
383
  > incident spec; the next push links the two as related on the tracker, and
374
384
  > `/spec-complete` on the incident counts this spec among its fixes. Omit the
375
385
  > line entirely otherwise>
386
+ > **Epic:** <epic-<name> — only when this spec is a member of an epic. Omit the
387
+ > line entirely otherwise>
388
+ > **Waits on:** <what must land first: `<spec>` (that spec complete) or
389
+ > `<spec> phase N` (that phase ✅ on the base branch), comma-separated, or
390
+ > `none`. Only on an epic member; a wait may name a spec outside the epic>
376
391
  > **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
377
392
  > is configured; omit the line entirely otherwise. A chore defaults to
378
393
  > "none: not user-facing". An empty value or a bare
@@ -474,6 +489,22 @@ order). Each phase file uses this template:
474
489
  Keep the `00-overview.md` phase index and the phase files in sync: the index row
475
490
  is the one-line summary + status; the phase file is the detail.
476
491
 
492
+ ### Writing an epic
493
+
494
+ An epic is `specs/backlog/epic-<name>/00-overview.md` and nothing else —
495
+ **no phase files**, and it is the one kind for which that is valid. Its overview takes
496
+ the template above with `> **Type:** Epic`, an optional `> **Lanes:** N` (how
497
+ many members may be in flight at once), and in place of `## Phases` a line saying
498
+ its progress is its members'. Its Decisions are the place to record **why** the
499
+ order is what it is.
500
+
501
+ The order itself is **not** written in the epic. Each member is an ordinary spec
502
+ of its own kind, written with this skill, carrying `> **Epic:** epic-<name>`
503
+ and its `> **Waits on:**` — so a member read alone says what it waits for, and
504
+ the epic can never disagree with its members about it. Write the epic first,
505
+ then each member; a member's `Area:` is what later tells two members apart as
506
+ safe or unsafe to run at once, so be specific there.
507
+
477
508
  The **State log** is the audit trail of folder/status transitions — every
478
509
  lifecycle skill (`/spec-start`, `/spec-complete`, `/spec-cancel`) appends one row
479
510
  when it moves the spec. The **Changelog** is for decisions and course-corrections
@@ -42,6 +42,25 @@ 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 epic — complete after its members
46
+
47
+ **Only for `Type: Epic` specs** (folder prefix `epic-`); every other kind
48
+ skips this in silence. An epic has no phase files, so the phase checks above
49
+ have nothing to read for it — its progress is its members'.
50
+
51
+ 1. **Check for open members.** Run `skitterspec epic status <spec> --json` and
52
+ read `members`: any whose `bucket` is not `complete` or `cancelled` is still
53
+ open. Any open member: **refuse**, naming each with its bucket, and offer to
54
+ complete anyway with them listed as outstanding — the operator answers;
55
+ record the choice in the epic's Changelog either way, naming the members
56
+ left open.
57
+ BLIND SPOT, named: a member authored on its own branch and neither landed
58
+ nor provisioned here is invisible to the engine — acceptable, for the
59
+ reason the incident check below gives (`.claude/rules/negative-checks.md`).
60
+ 2. **Its landing carries documents only.** An epic's worktree is
61
+ documents-only, so the land in step 6 moves the overview and nothing else;
62
+ every member landed — or was listed as outstanding — on its own.
63
+
45
64
  ### An incident spec — the log, and the open-fix check
46
65
 
47
66
  **Only for `Type: Incident` specs** (folder prefix `incident-`); every other
@@ -376,6 +395,16 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
376
395
  to the user; do not tear anything down.
377
396
  On a **no-op** ("already landed"), just say so and continue.
378
397
 
398
+ **When the plan carries `re-verify:` lines**, the rebase is about to bring in
399
+ something a **built** phase waited on — that phase was built without its
400
+ dependency underneath, and a clean rebase does not prove it works on top of it.
401
+ So after the rebase and **before** the fast-forward, run the project's test
402
+ command **in the worktree**. Green → carry on with the fast-forward. Red →
403
+ **stop before the fast-forward**, leaving the rebased branch where it is, relay
404
+ the failure, and end `❌`: base has not moved. A `re-verify: cannot tell` line is
405
+ relayed as information — it claims nothing, so it adds no run. (spec feat-epics,
406
+ Decision 9.)
407
+
379
408
  **Under a rolling base** (`baseBranchPattern` in `env.config.json`) the plan
380
409
  can carry two more things, and both are the engine's to say:
381
410
  - a `git -C <mainRepoPath> switch <base>` (or `switch -c … --track`) **first**,
@@ -107,7 +107,9 @@ Then, per state you are listing:
107
107
  - **Filter out phase sub-issues yourself.** The tool can filter *to* a parent
108
108
  (`parentId`) but has no "parentless" filter, so **you** must drop every issue
109
109
  that came back carrying a `parentId`. A spec issue has none; a phase sub-issue
110
- does.
110
+ does. **The one exception is an epic's member**: keep an issue whose
111
+ `parentId` is the id of an issue linked to an `epic-` spec here, and list it
112
+ indented under its epic's row. An unknown parent is dropped, as before.
111
113
  - **Page, and never cap silently.** `limit` defaults to 50 and maxes at 250;
112
114
  follow `cursor` until it runs out. If you stop early, say so on its own line
113
115
  and say what you stopped at.
@@ -116,6 +116,10 @@ A **name argument** is accepted, but it must *match* the spec in flight — it
116
116
  narrows a re-run, it does not select a different spec. A mismatch refuses,
117
117
  naming both.
118
118
 
119
+ **An epic has no phases to build.** When the spec resolved is an `epic-`, refuse
120
+ with the `⏸` block and name `skitterspec epic status <epic>` in `Next`: an
121
+ epic's work is its members', each built with `/spec-next` in its own worktree.
122
+
119
123
  ## 2. Pre-flight — the last phase is committed, and was answered
120
124
 
121
125
  Before writing any code for this phase, get the workspace clean:
@@ -181,8 +185,37 @@ Before writing any code for this phase, get the workspace clean:
181
185
  ## 3. Implement the phase
182
186
 
183
187
  Identify the **first unfinished phase** from the `00-overview.md` phase index,
184
- then open its phase file (`0N-<slug>.md`) — that file holds the tasks. Mark it
185
- started: set the phase-file heading to `🔄` and its `> **Status:**` to
188
+ then open its phase file (`0N-<slug>.md`) — that file holds the tasks.
189
+
190
+ **Ask the spec's epic before building it.** Run
191
+ `skitterspec epic check <spec> --phase <N> --json`. It answers for every spec:
192
+ one in no epic, or with nothing in its way, comes back with no warnings and
193
+ `blocked: false` — carry on in silence. Otherwise:
194
+
195
+ - **`warnings`** — a member on the same files in flight, or a wait whose
196
+ landing cannot be read. Relay each once and carry on.
197
+ - **`blocked: true`** — this phase (or the spec's start) waits on something
198
+ not yet on the base branch. Relay the `reason`, then,
199
+ **only where `offer` is present**, put its `label` and Cancel to the operator exactly as
200
+ `.claude/rules/offered-unblocks.md` describes, spending it with
201
+ `skitterspec epic check <spec> --phase <N> --offered` as you raise it.
202
+ The offer runs `skitterspec epic bypass <spec> --phase <N>`, which records the
203
+ choice in the spec's Changelog, and the build carries on. Cancel stops with
204
+ the `⏸` block — nothing was marked started. With no `offer` (it was already
205
+ raised once), stop with `⏸` and name the bypass command from the `reason` in
206
+ `Next`.
207
+
208
+ **Why it is asked here and not only at `/spec-start`.** The rule has to show up
209
+ where the work happens. In the field the sync point lived in a coordination
210
+ spec while `/spec-next` in the dependent spec's worktree — which never read it —
211
+ built the waiting phase anyway. A phase-level wait is invisible to a check made
212
+ once at the start, so each phase is asked as it is built.
213
+
214
+ **It warns; it never refuses on its own.** The operator may know an edge does
215
+ not matter for this phase, and the bypass is that knowledge on the record. What
216
+ it rules out is the silent build.
217
+
218
+ Mark it started: set the phase-file heading to `🔄` and its `> **Status:**` to
186
219
  `In progress`, and flip the matching row in the overview phase index to `🔄`.
187
220
 
188
221
  **Then sync with the tracker (only if a provider is installed).** The phase has
@@ -207,6 +207,14 @@ say, which includes every case the engine could not tell.
207
207
  issue id (`name` → title, `goal` → description, `state` via `config.states`).
208
208
  Keep each returned id against its `ref` (the phase-file basename).
209
209
  3. **Sub-issues update** → `save_issue` by `id` (title/description/state).
210
+ 4. **Put an epic member under its epic.** Only when the overview carries
211
+ `> **Epic:** epic-<name>`. Read that epic's `linear_identifier` off its own
212
+ overview (any bucket). Unlinked → say
213
+ `epic <name> is not linked yet — parent skipped (push the epic first)` and
214
+ carry on; never mint it here. Linked → read the member; when its parent is
215
+ already the epic, do nothing; otherwise `save_issue` the member with
216
+ `parentId` = the epic issue's id (it replaces any other parent), and read it back. The API path
217
+ does this itself and prints `parent set: …`.
210
218
 
211
219
  Priority, labels, cycles and comments are Linear-native triage — do **not** push
212
220
  them; they're the PM's.
@@ -477,6 +477,31 @@ conditional on it. A spec written before the project adopted gating has no heade
477
477
  and is not broken — turning this into a gate would accuse the very specs the
478
478
  feature was designed not to disturb.
479
479
 
480
+ ## 4c. Ask the spec's epic (only for an epic member)
481
+
482
+ Run `skitterspec epic check <name> --json`. It answers for every spec: one in no
483
+ epic, or with nothing in its way, comes back with no warnings and
484
+ `blocked: false` — the usual case, so say nothing then. Otherwise:
485
+
486
+ - **`warnings`** — another member of the same epic is in flight on the same
487
+ files, or a wait whose landing cannot be read. Relay each **once**, before
488
+ phase 1 starts, and **carry on**. `Area:` is what a spec says it will touch,
489
+ not what it does, so a clash is a reason to look rather than proof two specs
490
+ collide.
491
+ - **`blocked: true`** — the spec's start waits on something not yet on the
492
+ base branch. Relay the `reason`, then, **only where `offer` is present**, put
493
+ its `label` and Cancel to the operator as `.claude/rules/offered-unblocks.md`
494
+ describes, spending it with `skitterspec epic check <name> --offered` as you
495
+ raise it. The offer runs `skitterspec epic bypass <name>`, which records the
496
+ choice in the spec's Changelog, and step 6 goes ahead. Cancel ends at step
497
+ 6's **stop here** — the worktree stays provisioned, which is cheap, and phase
498
+ 1 is not built.
499
+
500
+ **This check warns and never refuses.** The operator may know a wait does not
501
+ matter for this spec, and the bypass is that knowledge on the record.
502
+ `/spec-next` asks again for each phase, because a phase can wait on something
503
+ the start does not.
504
+
480
505
  ## 5. Bring the spec's dev servers up — confirm before heavy steps
481
506
 
482
507
  **Only when the project configures host dev servers** (`env.config.json` → a
@@ -491,6 +516,11 @@ invoke it yourself.
491
516
 
492
517
  ## 6. Build phase 1
493
518
 
519
+ **An epic has no phase 1.** `spec-env up` gives it a documents-only tree (no
520
+ `setup`, no Docker) whether or not `--docs` was passed, because its work is its
521
+ members'. Skip this step and step 5, end with the block, and name
522
+ `skitterspec epic status <name>` in `Next`.
523
+
494
524
  **`checkout` mode — carry straight on into `/spec-next`** in this session: it
495
525
  marks phase 1 started, refreshes the mirror again, builds it with tests and
496
526
  reports. Do not stop and ask the operator to run it: the branch is here and they
@@ -545,7 +575,8 @@ the shape; this section carries only what is specific here.
545
575
  - `✅` — the branch is provisioned, the spec is `in-progress`, the session is
546
576
  standing in the worktree.
547
577
  - `⚠️` — provisioned, with something worth knowing (dev servers that did not
548
- come up, a mirror that did not refresh, a missing gating decision).
578
+ come up, a mirror that did not refresh, a missing gating decision, an epic
579
+ member in flight on the same files).
549
580
  - `❌` — provisioning failed part-way and left something behind. Say what, and
550
581
  where.
551
582
  - `⏸` — the gate refused: in `checkout` mode a dirty tree or someone else's
@@ -92,6 +92,16 @@ nothing else.
92
92
  On a **no-op** ("already landed on `<base>` — nothing to integrate"), just say so
93
93
  and continue — the branch has no commits base doesn't already have.
94
94
 
95
+ **When the plan carries `re-verify:` lines**, the rebase is about to bring in
96
+ something a **built** phase waited on — that phase was built without its
97
+ dependency underneath, and a clean rebase does not prove it works on top of it.
98
+ So after the rebase and **before** the fast-forward, run the project's test
99
+ command **in the worktree**. Green → carry on with the fast-forward. Red →
100
+ **stop before the fast-forward**, leaving the rebased branch where it is, relay
101
+ the failure, and end `❌`: base has not moved. A `re-verify: cannot tell` line is
102
+ relayed as information — it claims nothing, so it adds no run. (spec feat-epics,
103
+ Decision 9.)
104
+
95
105
  **Under a rolling base** (`baseBranchPattern` in `env.config.json`) the plan
96
106
  can carry two more things, and both are the engine's to say:
97
107
  - a `git -C <mainRepoPath> switch <base>` (or `switch -c … --track`) **first**,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@skitterbyte/skitterspec-linear",
3
- "version": "19.5.0",
3
+ "version": "19.6.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",