@skitterbyte/skitterspec-jira 2.5.1 → 2.7.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.
@@ -0,0 +1,21 @@
1
+ ---
2
+ description: What every member of an epic needs next, in which tab, and the epic page — bare uses the epic or member worktree you are in
3
+ argument-hint: "[<epic>]"
4
+ allowed-tools: Bash({{exec}} skitterspec epic status:*)
5
+ disable-model-invocation: true
6
+ ---
7
+ !`{{exec}} skitterspec epic status $ARGUMENTS`
8
+
9
+ Relay the engine output above verbatim. Add nothing and run nothing else.
10
+
11
+ **It is for coming back to the epic's tab.** Each member is built in a tab of
12
+ its own; this one is where you return to see what each needs. On a phone the
13
+ in-app browser closes to switch tabs, so the epic page's link is what you came
14
+ back for — it is the last thing printed.
15
+
16
+ **It reads, and nothing more.** It starts no server, claims no pass and runs no
17
+ member's next command: those are typed in that member's own tab. A waiting pass
18
+ it names is picked up there with `/spec-reviewed`.
19
+
20
+ **Only you can run it**, for `/spec-connect`'s reason: there is no judgement to
21
+ apply, so no model turn is spent finding one.
@@ -124,6 +124,14 @@ skip — never a flag. Putting the flag on `/commit` was the other suggestion an
124
124
  is worse: `/commit` belongs to skittership, which is why the gate is enforced
125
125
  by a hook rather than by editing that skill.
126
126
 
127
+ **`/epic` is the sixth command**, and it is user-only for the mild reason: it
128
+ pre-executes `skitterspec epic status` and relays it, so there is no judgement
129
+ to apply. It exists for the tab an epic is run from — each member is built in
130
+ a tab of its own, and on a phone the in-app browser has to close to switch
131
+ tabs, so the epic page's link has to be one command away rather than scrolled
132
+ past. Bare, it means the epic of the worktree it runs in. It reads and nothing
133
+ more: the next action it names for a member is typed in that member's tab.
134
+
127
135
  **A refusal may OFFER its own exit, and that is a different thing again.**
128
136
  Where the engine declares one, a skill relays the refusal and **then** offers it
129
137
  — once per obligation, with the choice recorded, and answered by the operator
@@ -647,17 +655,17 @@ none of them describes.
647
655
  - **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
648
656
  (architecture, code style, testing, database, etc.) rather than restating them.
649
657
 
650
- ## Spec types — Feature, Chore, Issue, Bug, Hotfix, Incident
658
+ ## Spec types — Feature, Chore, Issue, Bug, Hotfix, Incident, Epic
651
659
 
652
- Every spec is one of six types, recorded **both** in the header and the filename:
660
+ Every spec is one of seven types, recorded **both** in the header and the filename:
653
661
 
654
662
  - **Header field:** `> **Type:** Feature`, `> **Type:** Chore`,
655
- `> **Type:** Issue`, `> **Type:** Bug`, `> **Type:** Hotfix`, or
656
- `> **Type:** Incident` (authoritative, greppable:
663
+ `> **Type:** Issue`, `> **Type:** Bug`, `> **Type:** Hotfix`,
664
+ `> **Type:** Incident`, or `> **Type:** Epic` (authoritative, greppable:
657
665
  `grep -rl 'Type:.*Hotfix' specs/`).
658
666
  - **Filename prefix:** `feat-<name>` for features, `chore-<name>` for chores,
659
667
  `issue-<name>` for issues, `bug-<name>` for bugs, `hotfix-<name>` for
660
- hotfixes, `incident-<name>` for incidents (visible in listings;
668
+ hotfixes, `incident-<name>` for incidents, `epic-<name>` for epics (visible in listings;
661
669
  glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
662
670
 
663
671
  A **Chore** is code work no end user sees — tooling, CI, dependency bumps,
@@ -694,6 +702,36 @@ its phases. It carries `> **Severity:**` (Azure's literal values,
694
702
  unfolds; `/spec-complete` writes `incident-log.md` from it and pushes the log
695
703
  onto the tracker item as a comment.
696
704
 
705
+ An **Epic** is a spec of specs: `epic-<name>/00-overview.md` and
706
+ **no phase files** — the one kind for which that is valid — recording why a group belongs
707
+ together and, optionally, `> **Lanes:** N`, how many members may be in flight at
708
+ once. `/spec` proposes it when the grill describes several specs and their
709
+ order. **The order lives on the members, never on the epic**: each carries
710
+ `> **Epic:** epic-<name>` and `> **Waits on:**`, and any phase file may carry
711
+ its own `Waits on:` for a wait that holds only that phase.
712
+ `skitterspec epic status <epic>` turns those headers into what can start now,
713
+ what is blocked and on what, the waves, the phase-level sync points, and the
714
+ pairs whose `Area:` overlaps (never together). A wait is met only on the base
715
+ branch — the spec in `complete/`, or that phase file reading done — and
716
+ anything it cannot see is cannot-tell, never met.
717
+
718
+ The rule is checked **where the work happens**: `/spec-start` and `/spec-next`
719
+ on a member ask `skitterspec epic check` before building, and an unmet wait
720
+ warns and offers a recorded bypass (`.claude/rules/offered-unblocks.md`) — it
721
+ never refuses, and it never lets a build pass the wait in silence. An epic
722
+ itself gets a documents-only worktree, `/spec-next` refuses it, and
723
+ `/spec-complete` refuses while a member is open, offering to complete with them
724
+ listed.
725
+
726
+ **Migrating an `issue-` plan spec to an epic.** A coordination spec written
727
+ before epics existed — waves as phases, ticked by hand — becomes one by moving
728
+ its order onto its members: rename the folder to `epic-<name>` (`git mv`), set
729
+ `> **Type:** Epic`, add `> **Epic:**` and `> **Waits on:**` to each member (and
730
+ a phase file's own `Waits on:` for a phase-level sync point), and delete the
731
+ wave phase files — `epic status` derives them. Keep the plan's Decisions: they
732
+ are the *why* the members' headers cannot say. Then check that
733
+ `skitterspec epic status <epic>` reproduces the plan you had.
734
+
697
735
  ### Kind routing — any door, the right spec
698
736
 
699
737
  `/spec` is the default door, so the kind of work someone describes does not
@@ -744,7 +782,7 @@ list to maintain, and nothing here reads a label. A ticketing provider's
744
782
  intake label routing (`intake.bugLabels` / `intake.hotfixLabels`) is a
745
783
  separate, earlier check and is unchanged by this.
746
784
 
747
- All six types share the same lifecycle folders below — type is orthogonal to
785
+ All seven types share the same lifecycle folders below — type is orthogonal to
748
786
  status.
749
787
 
750
788
  ## Header fields & State log (audit trail)
@@ -752,7 +790,7 @@ status.
752
790
  Every spec header carries:
753
791
 
754
792
  - `> **Name:**` — the spec's folder name
755
- (`feat-`/`chore-`/`issue-`/`bug-`/`hotfix-`/`incident-<kebab-name>`).
793
+ (`feat-`/`chore-`/`issue-`/`bug-`/`hotfix-`/`incident-`/`epic-<kebab-name>`).
756
794
  It's the handle you pass to `/spec-start` and the other lifecycle skills, surfaced
757
795
  in the header so it's copy-pasteable without digging for the folder name.
758
796
  - `> **Author:**` — who created the spec (set at `/spec` / `/spec-bug`, defaults
@@ -771,6 +809,14 @@ Every spec header carries:
771
809
  `incident-<name>`. The push links the two as related on the tracker
772
810
  (one-way; the repo owns the link), and `/spec-complete` on the incident
773
811
  counts the spec among its fixes. Absent on everything else.
812
+ - `> **Epic:**` — on a spec that is a **member** of an epic: `epic-<name>`.
813
+ Absent on everything else.
814
+ - `> **Waits on:**` — on an epic member: what its start waits for, as
815
+ `<spec>` (that spec complete) or `<spec> phase N` (that phase done on the base
816
+ branch), comma-separated, or `none`. A phase file may carry its own, holding
817
+ only that phase.
818
+ - `> **Lanes:**` — on an epic, optional: how many members may be in flight at
819
+ once.
774
820
 
775
821
  **Under a provider's default `pull`, these three are the tracker's** —
776
822
  `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/jira.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
@@ -372,6 +391,16 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
372
391
  to the user; do not tear anything down.
373
392
  On a **no-op** ("already landed"), just say so and continue.
374
393
 
394
+ **When the plan carries `re-verify:` lines**, the rebase is about to bring in
395
+ something a **built** phase waited on — that phase was built without its
396
+ dependency underneath, and a clean rebase does not prove it works on top of it.
397
+ So after the rebase and **before** the fast-forward, run the project's test
398
+ command **in the worktree**. Green → carry on with the fast-forward. Red →
399
+ **stop before the fast-forward**, leaving the rebased branch where it is, relay
400
+ the failure, and end `❌`: base has not moved. A `re-verify: cannot tell` line is
401
+ relayed as information — it claims nothing, so it adds no run. (spec feat-epics,
402
+ Decision 9.)
403
+
375
404
  **Under a rolling base** (`baseBranchPattern` in `env.config.json`) the plan
376
405
  can carry two more things, and both are the engine's to say:
377
406
  - a `git -C <mainRepoPath> switch <base>` (or `switch -c … --track`) **first**,
@@ -73,6 +73,10 @@ Then build one JQL query per run:
73
73
  - **Filter out phase subtasks in the query** — add
74
74
  `AND issuetype NOT IN subtaskIssueTypes()`. A spec is a standard issue; a
75
75
  phase is a subtask, and a listing that includes them buries the specs.
76
+ - **Group an epic's members under it.** A row whose `parent` is linked to an
77
+ `epic-` spec here is that epic's member: list it indented under the epic's
78
+ row, or with `(epic <id>)` after it when the epic's row is not in the
79
+ listing.
76
80
  - **Ask for the fields you print** — `summary` and `status`; the key rides on
77
81
  every result, and the browse url is `<siteUrl>/browse/<key>`.
78
82
  - **Page, and never cap silently.** Follow the tool's pagination until it runs
@@ -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
@@ -202,6 +202,15 @@ say, which includes every case the engine could not tell.
202
202
  against its `ref` (the phase-file basename).
203
203
  3. **Subtasks update** → `editJiraIssue` by key (summary/description), plus
204
204
  `transitionJiraIssue` where the status changed.
205
+ 4. **Put an epic member under its epic.** Only when the overview carries
206
+ `> **Epic:** epic-<name>`. Read that epic's `jira_identifier` off its own
207
+ overview (any bucket). Unlinked → say
208
+ `epic <name> is not linked yet — parent skipped (push the epic first)` and
209
+ carry on; never mint it here. Linked → read the member; when its parent is
210
+ already the epic, do nothing; otherwise `editJiraIssue` the member with
211
+ `parent` = the epic's key (an epic itself mints as issue type `Epic` unless
212
+ `jira.issueTypeByKind.epic` names another), and read it back. The API path
213
+ does this itself and prints `parent set: …`.
205
214
 
206
215
  Priority, labels, sprints and comments are Jira-native triage — do **not** push
207
216
  them; they're the PM's.
@@ -410,6 +410,31 @@ conditional on it. A spec written before the project adopted gating has no heade
410
410
  and is not broken — turning this into a gate would accuse the very specs the
411
411
  feature was designed not to disturb.
412
412
 
413
+ ## 4c. Ask the spec's epic (only for an epic member)
414
+
415
+ Run `skitterspec epic check <name> --json`. It answers for every spec: one in no
416
+ epic, or with nothing in its way, comes back with no warnings and
417
+ `blocked: false` — the usual case, so say nothing then. Otherwise:
418
+
419
+ - **`warnings`** — another member of the same epic is in flight on the same
420
+ files, or a wait whose landing cannot be read. Relay each **once**, before
421
+ phase 1 starts, and **carry on**. `Area:` is what a spec says it will touch,
422
+ not what it does, so a clash is a reason to look rather than proof two specs
423
+ collide.
424
+ - **`blocked: true`** — the spec's start waits on something not yet on the
425
+ base branch. Relay the `reason`, then, **only where `offer` is present**, put
426
+ its `label` and Cancel to the operator as `.claude/rules/offered-unblocks.md`
427
+ describes, spending it with `skitterspec epic check <name> --offered` as you
428
+ raise it. The offer runs `skitterspec epic bypass <name>`, which records the
429
+ choice in the spec's Changelog, and step 6 goes ahead. Cancel ends at step
430
+ 6's **stop here** — the worktree stays provisioned, which is cheap, and phase
431
+ 1 is not built.
432
+
433
+ **This check warns and never refuses.** The operator may know a wait does not
434
+ matter for this spec, and the bypass is that knowledge on the record.
435
+ `/spec-next` asks again for each phase, because a phase can wait on something
436
+ the start does not.
437
+
413
438
  ## 5. Bring the spec's dev servers up — confirm before heavy steps
414
439
 
415
440
  **Only when the project configures host dev servers** (`env.config.json` → a
@@ -424,6 +449,34 @@ invoke it yourself.
424
449
 
425
450
  ## 6. Build phase 1
426
451
 
452
+ **An epic has no phase 1.** `spec-env up` gives it a documents-only tree (no
453
+ `setup`, no Docker) whether or not `--docs` was passed, because its work is its
454
+ members'. Skip this step and step 5, and end with the block — but first ask
455
+ what the epic needs started:
456
+
457
+ ```
458
+ skitterspec epic status <name> --json
459
+ ```
460
+
461
+ Its `rows` carry each member's next action, and its `page` the epic page's
462
+ tiers. Two things go in the block, both copied from it rather than composed:
463
+
464
+ - **`Next`** names the first members to start — one `/spec-start <member>`
465
+ for each row whose `next.verb` is `start`, **in a new tab each**, and only as
466
+ many as there are free lanes (`freeLanes`; all of them when it is null). A
467
+ start qualified `no free lane` or `clashes with …` is not offered here. None
468
+ ready is a true answer: say what the first wave waits on.
469
+ - **`Review`** carries the epic page's stack — `local`, `network`, `remote`,
470
+ as `page.tiers` gives them — or, where `page.off`, the command that starts
471
+ the server. It is a page to come back to, not one to answer: nothing waits
472
+ on it, so it is the row and never the banner.
473
+
474
+ **This tab is the epic's from here.** The members are built in tabs of their
475
+ own; this one is where the operator comes back to see what each needs. On a
476
+ phone the in-app browser has to close to switch tabs, so the page link must be
477
+ one command away rather than scrolled past: **`/epic`** re-shows the table and
478
+ the page, and the block names it.
479
+
427
480
  **`checkout` mode — carry straight on into `/spec-next`** in this session: it
428
481
  marks phase 1 started, refreshes the mirror again, builds it with tests and
429
482
  reports. Do not stop and ask the operator to run it: the branch is here and they
@@ -478,7 +531,8 @@ the shape; this section carries only what is specific here.
478
531
  - `✅` — the branch is provisioned, the spec is `in-progress`, the session is
479
532
  standing in the worktree.
480
533
  - `⚠️` — provisioned, with something worth knowing (dev servers that did not
481
- come up, a mirror that did not refresh, a missing gating decision).
534
+ come up, a mirror that did not refresh, a missing gating decision, an epic
535
+ member in flight on the same files).
482
536
  - `❌` — provisioning failed part-way and left something behind. Say what, and
483
537
  where.
484
538
  - `⏸` — the gate refused: in `checkout` mode a dirty tree or someone else's
@@ -487,11 +541,15 @@ the shape; this section carries only what is specific here.
487
541
  is **not** on this list in `worktree` mode — it is an `Untouched` row on a
488
542
  `✅`.
489
543
 
490
- **Fields:** `Tracker` · `Branch` · `Spec` · `Worktree` · `Untouched` · `Follow-ups` · `Next`
544
+ **Fields:** `Tracker` · `Branch` · `Spec` · `Worktree` · `Untouched` · `Review` · `Follow-ups` · `Next`
491
545
 
492
546
  `Worktree` carries the path, because the session is now standing in it and the
493
547
  operator's next command depends on knowing that. `Next` is `/spec-next`.
494
548
 
549
+ **An epic is the one exception, both ways.** `Review` appears only for an epic,
550
+ carrying its page's stack, and its `Next` is the members to start in new tabs
551
+ — with `/epic` to bring the table and the page back (step 6).
552
+
495
553
  `Untouched` appears only when `spec-env up` reported uncommitted work that was
496
554
  not this spec's — say how much and whose, and **keep the verdict `✅`**. Nothing
497
555
  went wrong: a worktree carries nothing, so that work was never in play.
@@ -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-jira",
3
- "version": "2.5.1",
3
+ "version": "2.7.0",
4
4
  "description": "Spec-driven development for Claude Code, with one-way Jira Cloud sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Jira is a generated mirror. Install this OR the base OR the Linear superset — exactly one.",
5
5
  "keywords": [
6
6
  "claude",