@skitterbyte/skitterspec-linear 19.5.1 → 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.
- package/assets/rules/spec-planning.md +45 -7
- package/assets/skills/spec/SKILL.md +37 -6
- package/assets/skills/spec-complete/SKILL.md +29 -0
- package/assets/skills/spec-list/SKILL.md +3 -1
- package/assets/skills/spec-next/SKILL.md +35 -2
- package/assets/skills/spec-push/SKILL.md +8 -0
- package/assets/skills/spec-start/SKILL.md +32 -1
- package/assets/skills/spec-to-main/SKILL.md +10 -0
- package/package.json +1 -1
- package/src/cli.js +294 -4
- package/src/env/epic.js +541 -0
- package/src/env/inflight.js +11 -3
- package/src/env/resolve.js +18 -7
- package/src/env/specstate.js +7 -2
- package/src/vendor/linear/api.js +20 -0
- package/src/vendor/linear/cli-sync.js +45 -4
- package/src/vendor/linear/config.js +1 -1
- package/src/vendor/provider-kit/src/apply.js +24 -0
- package/src/vendor/provider-kit/src/epic-rows.js +44 -0
- package/src/vendor/sync-core/index.js +3 -1
- package/src/vendor/sync-core/src/normalize.js +91 -9
|
@@ -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
|
|
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`,
|
|
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
|
|
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
|
-
|
|
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
|
|
264
|
-
(test-first, red→green); for a live outage,
|
|
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
|
|
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.
|
|
185
|
-
|
|
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.
|
|
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",
|