@skitterbyte/skitterspec-jira 2.7.0 → 2.9.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.
Files changed (45) hide show
  1. package/assets/claude-md-section.md +6 -0
  2. package/assets/core/env.config.json.example +5 -0
  3. package/assets/core/env.config.md +26 -5
  4. package/assets/review/page.html +9 -0
  5. package/assets/rules/spec-planning.md +65 -12
  6. package/assets/rules/spec-reports.md +8 -1
  7. package/assets/skills/spec/SKILL.md +31 -14
  8. package/assets/skills/spec-cancel/SKILL.md +7 -0
  9. package/assets/skills/spec-complete/SKILL.md +6 -0
  10. package/assets/skills/spec-epic-next/SKILL.md +83 -0
  11. package/assets/skills/spec-init/SKILL.md +35 -3
  12. package/assets/skills/spec-next/SKILL.md +38 -1
  13. package/assets/skills/spec-start/SKILL.md +2 -2
  14. package/assets/skills/spec-tada/SKILL.md +153 -0
  15. package/bin/skitterspec-jira.js +5 -0
  16. package/package.json +1 -1
  17. package/src/cli.js +473 -25
  18. package/src/env/config.js +57 -6
  19. package/src/env/epic.js +69 -19
  20. package/src/env/epicpage.js +87 -39
  21. package/src/env/epicread.js +41 -3
  22. package/src/env/integrate.js +48 -1
  23. package/src/env/nextaction.js +78 -1
  24. package/src/env/project.js +54 -3
  25. package/src/env/projectedit.js +148 -0
  26. package/src/env/resolve.js +1 -0
  27. package/src/env/review.js +21 -3
  28. package/src/env/serve.js +44 -8
  29. package/src/env/specbranches.js +120 -0
  30. package/src/env/teardown.js +18 -3
  31. package/src/gating.js +16 -4
  32. package/src/init.js +11 -3
  33. package/src/tada/commits.js +145 -0
  34. package/src/tada/digest.js +260 -0
  35. package/src/tada/format.js +37 -0
  36. package/src/tada/page.js +213 -0
  37. package/src/tada/repo.js +102 -0
  38. package/src/tada/serve.js +127 -0
  39. package/src/tada/specs.js +146 -0
  40. package/src/tada/transcripts.js +258 -0
  41. package/src/tada/window.js +156 -0
  42. package/src/vendor/provider-kit/src/apply.js +25 -1
  43. package/src/vendor/sync-core/src/compare.js +10 -2
  44. package/src/vendor/sync-core/src/push.js +14 -3
  45. /package/assets/commands/{epic.md → spec-epic.md} +0 -0
@@ -17,6 +17,12 @@ phone. The diff never passes through the model, so the page costs no context
17
17
  tokens however large it is; the optional written review is the part that costs,
18
18
  and it is offered rather than assumed. `/spec-next` writes the page at the end of
19
19
  every phase. **`skitterspec status`** lists what is in flight across worktrees.
20
+ At the end of the day, **`/spec-tada`** is the ta-da list: what you did across
21
+ every project, grouped by spec — what landed, what was explored, what is still
22
+ in flight — ending in a three-line standup (`skitterspec tada` is the engine).
23
+ It covers the projects that share this one's `project.category`;
24
+ **`skitterspec project`** shows and sets the name and category, and
25
+ `/spec-init` asks for both.
20
26
 
21
27
  **Handing the review back.** The page takes marks: tick `✓ accept` per file as
22
28
  you read, note anything against a line or a whole file, answer the questions a
@@ -1,5 +1,9 @@
1
1
  {
2
2
  "mode": "worktree",
3
+ "project": {
4
+ "name": "",
5
+ "category": ""
6
+ },
3
7
  "worktree": {
4
8
  "root": "../{repo}-wt",
5
9
  "folderPattern": "{slug}"
@@ -49,6 +53,7 @@
49
53
  "allowRemote": false,
50
54
  "commitWith": "/commit",
51
55
  "required": true,
56
+ "projectName": "",
52
57
  "reviewers": []
53
58
  },
54
59
  "live": {
@@ -65,6 +65,18 @@ through to a documented conservative default; see the field notes below.
65
65
  // Not to be confused with `seedFiles.mode`, which is "symlink" | "copy".
66
66
  "mode": "worktree",
67
67
 
68
+ // What this project is called and which group it belongs to.
69
+ "project": {
70
+ "name": "", // heads every generated page — reviews, the
71
+ // served index, the epic page, the ta-da page.
72
+ // Empty: the primary checkout's folder name. Read
73
+ // before the superseded `review.projectName`.
74
+ "category": "" // a free label — "work", "personal", a client.
75
+ // `skitterspec tada` run here reports only the
76
+ // projects with the same category (compared
77
+ // case-insensitively); empty here reports all.
78
+ },
79
+
68
80
  "worktree": {
69
81
  "root": "../{repo}-wt", // dir that holds all spec worktrees; sibling of
70
82
  // the primary checkout, never nested inside it.
@@ -329,11 +341,15 @@ through to a documented conservative default; see the field notes below.
329
341
  // draft: mid-spec PRs open as drafts (a draft cannot be merged, so
330
342
  // nothing downstream can close a ticket early); /spec-complete is
331
343
  // what flips the PR to ready. Default true.
332
- // specDocs: where a SPEC DOCUMENT lands under "pr". "trunk" (default) keeps
333
- // today's authoring land — needs direct push for docs. "branch"
334
- // has the spec ride the feature branch and land with the work's
335
- // PR; the backlog is then found via the tracker listing, and the
336
- // authoring worktree stays (it is the document's only copy).
344
+ // specDocs: where a SPEC DOCUMENT lands. "trunk" keeps the authoring land
345
+ // — needs direct push for docs under "pr". "branch" has the spec
346
+ // ride its feature branch and land with the work; the backlog is
347
+ // then found via the tracker listing, and the authoring worktree
348
+ // stays (it is the document's only copy). Default "trunk" —
349
+ // unless a ticketing provider is configured (its config file in
350
+ // specs/.core/) and this key is unset, under either strategy:
351
+ // then "branch", because the tracker already is the backlog.
352
+ // Setting the key, to either value, always wins.
337
353
  // The merged-check and PR commands need the host's CLI — `gh` on github.com,
338
354
  // `az` on dev.azure.com — detected from the remote URL, never configured. An
339
355
  // unknown host (Enterprise/Server domains included) degrades to the ancestry
@@ -564,6 +580,10 @@ through to a documented conservative default; see the field notes below.
564
580
  // because a commit made under rules nobody configured must not read as one
565
581
  // made under /commit.
566
582
  //
583
+ // `projectName` is SUPERSEDED by `project.name` and still read beneath it,
584
+ // so a config that set it keeps its name. Set `project.name` instead.
585
+ // Default: "".
586
+ //
567
587
  // THERE IS NO OFF SWITCH. `"none"` existed and was removed: it produced a
568
588
  // verdict that records itself and does nothing, which is the one thing a
569
589
  // review page must not offer — a review is the guard in front of an action.
@@ -657,6 +677,7 @@ through to a documented conservative default; see the field notes below.
657
677
  "serve": "always",
658
678
  "commitWith": "/commit",
659
679
  "required": true,
680
+ "projectName": "",
660
681
  "reviewers": []
661
682
  }
662
683
  }
@@ -120,6 +120,7 @@ body {
120
120
 
121
121
  header { margin-bottom: 1rem; }
122
122
  h1 { font-size: 1.3rem; margin: 0 0 .3rem; overflow-wrap: anywhere; }
123
+ .eyebrow { color: var(--muted); font-size: .8rem; margin: 0 0 .15rem; overflow-wrap: anywhere; }
123
124
  .sub { color: var(--muted); font-size: .85rem; margin: 0; overflow-wrap: anywhere; }
124
125
  .sub .sep { opacity: .5; padding: 0 .35rem; }
125
126
  .a { color: var(--add-mark); }
@@ -833,6 +834,7 @@ a.ticket:hover { border-color: var(--accent); }
833
834
  <body>
834
835
  <div class="wrap" id="wrap">
835
836
  <header>
837
+ <p class="eyebrow" id="project" hidden></p>
836
838
  <h1 id="title"></h1>
837
839
  <p class="sub" id="sub"></p>
838
840
  <div class="controls">
@@ -3311,6 +3313,13 @@ a.ticket:hover { border-color: var(--accent); }
3311
3313
  // --- header --------------------------------------------------------------
3312
3314
  var titleEl = document.getElementById('title')
3313
3315
  titleEl.textContent = data.title
3316
+ // The project this page belongs to, above the heading. textContent, never
3317
+ // markup: the name comes from a config file and the page is served.
3318
+ if (data.project) {
3319
+ var projectEl = document.getElementById('project')
3320
+ projectEl.textContent = data.project
3321
+ projectEl.hidden = false
3322
+ }
3314
3323
  /**
3315
3324
  * The tracker ticket, beside the title and linked where there is a url.
3316
3325
  *
@@ -16,9 +16,11 @@ and lifecycle stay consistent. Each sets a status on the spec header
16
16
  | `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 | `In Progress` | `specs/in-progress/` |
17
17
  | `/spec-next` | Build the next phase of the spec this session is in (re-run per phase) | `In Progress` (unchanged) | (unchanged) |
18
18
  | `/spec-reviewed` | Pick up a review approved on the page — offered by its code, claimed on your word | (unchanged) | (unchanged) |
19
+ | `/spec-epic-next` | Name the epic member that can start now, as the `/spec-start` to type in a new tab — a picker when several can; reads only | (unchanged) | (unchanged) |
19
20
  | `/spec-to-main` | Land the branch on the base (rebase + ff) **without** finishing — for running the work in CI / a shared env mid-spec; repeatable | `In Progress` (unchanged) | (unchanged) |
20
21
  | `/spec-complete` | Verify all phases done + tests green; land + tear down | `Complete` | `specs/complete/` |
21
22
  | `/spec-cancel` | Record progress, stamp a reason on the header; tear down | `Cancelled` | `specs/cancelled/` |
23
+ | `/spec-tada` | A ta-da list — recap what you did in Claude Code over a window, across every project, by project then spec, ending in a standup. Read-only | (unchanged) | (unchanged) |
22
24
  | `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
23
25
 
24
26
  **Skills vs commands.** The table above lists **skills** — Claude reads them and
@@ -71,6 +73,28 @@ branch. Beneath it, `skitterspec spec-env nospec <name>` records the branch —
71
73
  and that record is what makes a name with nothing under `specs/**` resolvable by
72
74
  `review`, `integrate`, `down` and a bare `resolve`.
73
75
 
76
+ **`/spec-tada` reads, and moves nothing.** It is in the table because it
77
+ reports in the unit the table is about — a spec — but it changes no status,
78
+ writes no file and commits nothing. `skitterspec tada` reads Claude Code's own
79
+ transcripts down to the prompts a person typed and folds each session into
80
+ the **repo** it worked in, so a session that moved into `../<repo>-wt/<slug>`
81
+ is that repo's work, not a project of its own. A commit already on the base
82
+ branch is attributed by the spec folder it touched or its `Refs:` ticket, never
83
+ by a branch that happens to contain it — a spec branch cut this afternoon
84
+ contains all of this morning. It is model-invocable, because "what did I do
85
+ today?" should reach it.
86
+
87
+ **A report covers one category.** `project.category` in `env.config.json`
88
+ decides which projects share a report — only those with the category of the
89
+ repo it runs from, and an uncategorised project is in nobody's but its own
90
+ (`--all-projects` takes everything). `project.name` is what heads the page,
91
+ and every review page, with the repo folder as the fallback.
92
+ `skitterspec project` shows both and sets them (`--name`, `--category`) by
93
+ editing only those values; `--categories` lists what your other projects
94
+ already use, so one category is not spelled two ways. `/spec-init` asks for
95
+ both — on an existing config through a `/no-spec` branch, since the base
96
+ branch is a landing zone.
97
+
74
98
  **`/allow-main` is the fourth command.** It is user-only for a different reason
75
99
  from the other three: `/spec-connect`, `/spec-live` and `/spec-remote-review`
76
100
  are marked that way because there is no judgment to apply. This one is marked that
@@ -124,7 +148,7 @@ skip — never a flag. Putting the flag on `/commit` was the other suggestion an
124
148
  is worse: `/commit` belongs to skittership, which is why the gate is enforced
125
149
  by a hook rather than by editing that skill.
126
150
 
127
- **`/epic` is the sixth command**, and it is user-only for the mild reason: it
151
+ **`/spec-epic` is the sixth command**, and it is user-only for the mild reason: it
128
152
  pre-executes `skitterspec epic status` and relays it, so there is no judgement
129
153
  to apply. It exists for the tab an epic is run from — each member is built in
130
154
  a tab of its own, and on a phone the in-app browser has to close to switch
@@ -245,15 +269,18 @@ worktree: `Commit & Start` keeps it and carries into `/spec-start`, plain
245
269
  `commit` tears it down, because a spec parked in the backlog should hold no
246
270
  checkout.
247
271
 
248
- **`land.specDocs: "branch"` is the exception, taken deliberately.** Where the
249
- base branch accepts no direct push even for documents, the spec rides its
250
- feature branch and lands with the work's PR: both verdicts commit and skip the
251
- integrate, plain `commit` keeps branch and worktree (they are the document's
252
- only copy), and the backlog is found through the tracker listing rather than
253
- `ls specs/backlog/` on base — the known branch-relative-bucket cost, accepted
254
- because the alternative is a spec that cannot be written at all. The worktree
255
- fork-point check is exempt in this mode for the hotfix's reason: the spec is
256
- *supposed* to be absent from the fork point.
272
+ **`land.specDocs: "branch"` is the exception — and the default with a tracker.**
273
+ The spec rides its feature branch and lands with the work: both verdicts commit
274
+ and skip the integrate, plain `commit` keeps branch and worktree (they are the
275
+ document's only copy), and the backlog is found through the tracker listing
276
+ rather than `ls specs/backlog/` on base. It began as the lane for a base branch
277
+ that accepts no direct push even for documents. It is now also what a project
278
+ gets by default once a ticketing provider is configured and the key is unset,
279
+ under either landing strategy: the ticket already exists and the board already
280
+ owns status, so a land whose only purpose was findability buys nothing. Setting
281
+ the key, to either value, always wins. The worktree fork-point check is exempt
282
+ in this mode for the hotfix's reason: the spec is *supposed* to be absent from
283
+ the fork point.
257
284
 
258
285
  **What this bought is the reason it changed.** The page waits for a verdict
259
286
  without a timeout — deliberately, because a reader walking away from a diff is
@@ -729,8 +756,26 @@ its order onto its members: rename the folder to `epic-<name>` (`git mv`), set
729
756
  `> **Type:** Epic`, add `> **Epic:**` and `> **Waits on:**` to each member (and
730
757
  a phase file's own `Waits on:` for a phase-level sync point), and delete the
731
758
  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.
759
+ are the *why* the members' headers cannot say.
760
+
761
+ **A phase that is not a wave becomes a member.** A test pass, a review, a
762
+ manual step the plan held as a phase is its own spec of the kind its work is —
763
+ usually an **Issue** (manual steps, no code) — with `> **Epic:**` and its own
764
+ `> **Waits on:**`; whatever waited on that phase waits on the member instead.
765
+ An epic holds no phases, because it holds no check it cannot observe.
766
+
767
+ **Do it off the base branch, and check it before it lands.** The conversion is
768
+ documents only, so it is a `/no-spec` branch. From that worktree,
769
+ `skitterspec epic status <epic> --here` reads the members and headers as the
770
+ branch has them — uncommitted edits included — while a wait still counts as met
771
+ only on the base branch, so you can confirm it reproduces the plan you had
772
+ before landing it.
773
+
774
+ **The epic's first push retires the wave sub-issues.** An epic has no phases,
775
+ so every phase sub-issue its snapshot still remembers is a leftover of the plan
776
+ it was converted from: the push closes each as not planned and unlinks it from
777
+ the epic's issue, leaving the members as its only sub-issues. A tracker that
778
+ cannot retire one names it, to close by hand.
734
779
 
735
780
  ### Kind routing — any door, the right spec
736
781
 
@@ -888,6 +933,14 @@ status also lives in the tracker when a ticketing provider is linked. (There are
888
933
  no `00-index.md` summary files — the folder tree, headers, and State logs are
889
934
  queried directly.)
890
935
 
936
+ Under `land.specDocs: "branch"` a spec is not on the base branch until its
937
+ work lands, so `specs/backlog/` there misses it. `gating check` and
938
+ `epic status` therefore also read the spec folders each spec branch changed —
939
+ local branches, then remote-tracking ones as of the last fetch, never
940
+ fetching — and a branch copy wins over the base copy unless the base branch
941
+ has already finished that spec. A branch copy can make an epic member visible;
942
+ it never meets a wait, which is still read only off the base branch.
943
+
891
944
  ## Rules
892
945
 
893
946
  - If a spec already exists, update it — don't rewrite from scratch.
@@ -144,6 +144,13 @@ mentioning. The whole reason the stack exists is that the engine was being asked
144
144
  to guess where the reader was sitting, and it guessed wrong three separate ways
145
145
  in one day; a skill re-deciding that in prose is the same guess one layer up.
146
146
 
147
+ **And it holds outside a skill too.** Whenever you relay engine output that
148
+ carries a stack — `epic status` asked in passing, a `resolve`, an answer to a
149
+ question — pass on every tier, every `also:` line with its label, and the
150
+ `remote` line, never the one URL that looked like the answer. An agent asked
151
+ about an epic once replied with the member list and the loopback link alone,
152
+ and the reader on a phone was left with nothing they could open.
153
+
147
154
  **Three tiers, always all three, in this order.**
148
155
 
149
156
  | Tier | Is | Off when |
@@ -448,7 +455,7 @@ behind it — say nothing rather than reporting that there was nothing to report
448
455
  | `Built` | What the run produced — the code, the edits, the spec written. |
449
456
  | `Tests` | The result and the command that produced it. |
450
457
  | `Notes` | What this run hit and handled — one short paragraph. Named `Snags` once, which announced a problem before the reader had read one; most of what belongs here is neither good nor bad, just worth knowing. A wrong turn, a guard that fired, a check of yours that turned out to be a false negative. Not a caveat on the outcome (`⚠️` and `Why` carry those) and not future work (`Follow-ups` carries that): this is what happened on the way. |
451
- | `Landed` | A fast-forward, a tag, a cherry-pick — or in PR mode the PR itself: `PR #14 (draft) updated` · `PR #14 opened — finish after merge` · `PR #14 merged` · `held — not pushed` (a declined consent is a true outcome, not a failure). |
458
+ | `Landed` | A fast-forward, a tag, a cherry-pick — or in PR mode the PR itself: `PR #14 (draft) updated` · `PR #14 opened — finish after merge` · `PR #14 merged` · `held — not pushed` (a declined consent is a true outcome, not a failure) · `not pushed · <command> publishes it` (a push suggested rather than asked, as `/spec`'s branch lane does). |
452
459
  | `Worktree` | A worktree provisioned, entered, or torn down. |
453
460
  | `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
454
461
  | `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, with any `network` alternates inline after the network URL (`also <url> (tailnet)`), plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
@@ -257,7 +257,7 @@ same files. Propose it as *"several specs with an order between them → epic"*,
257
257
  and on a yes write the epic **and** each member as its own spec — the epic is
258
258
  not a container for their phases (see **Writing an epic** below).
259
259
 
260
- There is no `/spec-chore`, `/spec-issue` or `/spec-epic` and none should be added: one entry
260
+ There is no `/spec-chore`, `/spec-issue` or epic-writing door and none should be added (`/spec-epic` reads an epic's status; it writes nothing): one entry
261
261
  point, one grill, and the kind is an output of understanding the work rather
262
262
  than a door the user must pick before describing it. The kinds with their own
263
263
  doors — bug, hotfix, and the **incident**, an outage or degradation of a live
@@ -620,23 +620,40 @@ on the branch you are standing on — so a spec left on its own branch would be
620
620
  invisible to everyone, including the next `/spec` run. The commit goes on the
621
621
  branch and then the branch goes onto the base:
622
622
 
623
- **Unless the project set `land.specDocs: "branch"`** — the lane for a base
624
- branch nobody may push, where the spec document rides the feature branch and
625
- lands with the work's PR. There both verdicts commit on the branch and
626
- **skip the integrate below entirely**; `commit-start` carries into
627
- `/spec-start` over the same worktree exactly as ever, and plain `commit` keeps
628
- the branch AND the worktree, because they are now the only copy of the
629
- document. Say the trade out loud in the report's `Notes`: the backlog is found
630
- through the tracker listing (or `git branch`), not `ls specs/backlog/` on base
631
- — and a later `/spec-cancel` of a never-started branch-mode spec deletes the
632
- branch and worktree with the spec document dying with them, no PR ever having
633
- existed. Under the default `"trunk"` everything below applies unchanged.
623
+ **Unless `land.specDocs` is `"branch"`** — set so in `env.config.json`, or
624
+ left unset in a project with a ticketing provider configured (its config file
625
+ under `specs/.core/`), where it is the default because the tracker already is
626
+ the backlog. It is the lane where the spec document rides its feature branch
627
+ and lands with the work. There both verdicts commit on the branch and
628
+ **touch no base at all**; `commit-start` carries into `/spec-start` over the
629
+ same worktree exactly as ever, and plain `commit` keeps the branch AND the
630
+ worktree, because they are the document's working copy. What the lane does
631
+ instead of landing is **publish the branch**, because an unpushed spec branch
632
+ is on one machine and nowhere else — the ticket's summary cannot rebuild it.
633
+
634
+ **The same command answers both lanes; you do not choose between them:**
634
635
 
635
636
  ```
636
- skitterspec spec-env integrate <name>
637
+ skitterspec spec-env integrate <name> --docs
637
638
  ```
638
639
 
639
- It plans a rebase onto the base branch in the worktree, then a
640
+ Under `"trunk"` it prints the ordinary land, unchanged. Under `"branch"` it
641
+ says `spec docs ride the branch` and plans one push of the spec's branch,
642
+ consent-gated like every push in this workflow: already on the remote at HEAD
643
+ is honoured and runs nothing; otherwise it holds the push.
644
+ **Do not ask, and do not run it** — a suggestion is not a question.
645
+ Report `Landed` as `not pushed`, with the held command it printed beside it as
646
+ the way to publish, so it sits in the table for the reader to take or leave. A
647
+ question here interrupted the end of an authoring run for something that can
648
+ wait until the reader chooses to. Already on the remote reports
649
+ `pushed <remote>/<branch>`. A clone with no such remote prints that the branch
650
+ stays local; report that as the `Landed` row.
651
+
652
+ Say the trade in the report's `Notes`: the backlog is found through the
653
+ tracker listing (or the spec branches), not `ls specs/backlog/` on base. Under
654
+ `"trunk"` everything below applies unchanged.
655
+
656
+ Under `"trunk"` it plans a rebase onto the base branch in the worktree, then a
640
657
  `merge --ff-only` in the primary checkout — run the commands it prints. It
641
658
  refuses on a dirty tree, which is correct here: the commit ran first, so anything
642
659
  still uncommitted at this point is not this spec's and the land must not proceed.
@@ -279,6 +279,13 @@ only ordering that survives.
279
279
  a fault — and if the user wants the remote branch gone anyway, that is their
280
280
  call to make explicitly, not something to tidy away on their behalf.
281
281
 
282
+ **One unlanded branch does get the section: a never-started spec under `land.specDocs: "branch"`**, whose branch holds nothing but its own
283
+ documents. Its remote copy backs up only the spec being cancelled — the
284
+ ticket keeps the record — and left there it goes on reading as backlog to
285
+ every check that scans spec branches. Ask exactly as above. On a no, say in
286
+ the report that the branch stays on the remote and will still read as
287
+ backlog until someone deletes it.
288
+
282
289
  **In PR mode the same confirm-first section may carry the PR abandon**
283
290
  (`gh pr close` / `az repos pr update --status abandoned`): a cancelled spec
284
291
  must not leave a live PR behind — it is noise with a merge button on it.
@@ -265,6 +265,12 @@ least: the reader has just finished something and cannot tell whether a line
265
265
  about another spec followed from it. `Next` is one action for this spec, and
266
266
  `/spec-list` is where the wider picture lives if they want it.
267
267
 
268
+ **An epic member is the one exception to that `Next`.** When the spec carries
269
+ `> **Epic:**`, its own work is done and the next thing for that work is its
270
+ epic's: `Next` is **`/spec-epic-next`**, which names the member that can start
271
+ now. Name the command and nothing else — which members are ready is that
272
+ skill's to read, and listing them here is the survey this section forbids.
273
+
268
274
  `Landed` says how, because the two ways differ: a fast-forward names the base
269
275
  and the commit, a hotfix names the release tag, whether it was pushed, and the
270
276
  `main` carry — and a release tag that has not been pushed is a `⚠️`, not a `✅`. `Worktree` says
@@ -0,0 +1,83 @@
1
+ ---
2
+ name: spec-epic-next
3
+ description: Find the member of an epic that can start now and name the `/spec-start` to run for it in a new tab — asking which when several can, and saying why when none can. Reads only; it starts, provisions and moves nothing. Bare, it uses the epic or member worktree you are standing in. Use when the user says "/spec-epic-next", "start the next spec in the epic", "what's next in this epic", or has just completed an epic member.
4
+ ---
5
+
6
+ # /spec-epic-next — which epic member to start next
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 epic's members are built in tabs of their own, and the tab this runs in
14
+ stays whatever it was — the epic's coordinator, or a member that just finished.
15
+ So this skill **picks and prints**: its answer is `/spec-start <member>` to
16
+ type **in a new tab**. It writes nothing, provisions nothing, and moves no
17
+ session. Starting the member is `/spec-start`'s job, in that tab.
18
+
19
+ ## 1. Ask the engine
20
+
21
+ ```
22
+ skitterspec epic status [<epic>] --json
23
+ ```
24
+
25
+ Pass the epic when the invocation names one. Bare, the engine resolves it from
26
+ the worktree you are standing in — the epic's own, or a member's (its
27
+ `> **Epic:**` header). When it resolves nothing (`epic: null`), stop with `⏸`
28
+ and name `/spec-epic-next <epic>` in `Next`, with the epics its `inFlight`
29
+ lists as the candidates. **Never pick an epic from conversation**: a
30
+ spec discussed is not the epic in hand, and the engine already knows where you
31
+ are standing.
32
+
33
+ Read its `steps`, `groups` and `freeLanes`. A step whose `where` is `new-tab`
34
+ is a member that may start now, in a free lane; its `command` is the
35
+ `/spec-start` to type and its `caution` any clash. Do not re-derive that from
36
+ `rows` or the headers. The engine decides what can start and caps it at the
37
+ free lanes, and it is the same answer the epic page and `/spec-epic` print.
38
+ Any second answer could disagree with them.
39
+
40
+ ## 2. Route on what it said
41
+
42
+ **Every member done.** The only step has `where: epic`, and its `command` is
43
+ `/spec-complete <epic>`. Say so, `✅`.
44
+
45
+ **No free lane.** `freeLanes` is `0` and `groups.ready` is not empty. Stop with
46
+ `⏸`: the lanes are the cap the epic chose, and this skill does not offer a way
47
+ past it. Name the members in `groups.inFlight`, which are what is holding the
48
+ lanes. The in-tab steps say what each needs to finish.
49
+
50
+ **Nothing ready.** `groups.ready` is empty. Stop with `⏸` and name what each
51
+ member in `groups.waiting` waits on (its row's `next.why`). A member the engine
52
+ could not read is in `waiting` with its reason, never in `ready`
53
+ (`.claude/rules/negative-checks.md`), so quote that reason rather than
54
+ treating the wait as met.
55
+
56
+ **One start step.** Name it. `Next` is its `command`, in a new tab, with its
57
+ `caution` beside it.
58
+
59
+ **Several start steps.** Offer a picker — one option per start step, plus
60
+ Cancel — and **never choose for them**. A member with a `caution` is listed
61
+ **with** its clash, not filtered out: `Area:` is what a spec says it will
62
+ touch, and `/spec-start` §4c raises the clash again when it starts. The engine
63
+ already puts the start with no clash first, so keep its order. A choice ends
64
+ `✅` with that member in `Next`; Cancel ends `⏸`.
65
+
66
+ ## Report
67
+
68
+ End with the block defined in `.claude/rules/spec-reports.md`. That file carries
69
+ the shape; this section carries only what is specific here.
70
+
71
+ **Verdicts**
72
+
73
+ - `✅` — a member was named or picked, or every member is done and the epic
74
+ itself is next.
75
+ - `⏸` — no free lane, nothing ready, a wait it cannot read, no epic resolved,
76
+ or the picker cancelled. Nothing changed — and nothing ever does here.
77
+
78
+ **Fields:** `Spec` · `Follow-ups` · `Next`
79
+
80
+ `Spec` names the epic and how far along it is, from the engine's
81
+ `progress` (`N of M done · K in flight`). `Next` is `/spec-start <member>` **in a new tab**, or on a `⏸` the
82
+ thing that would unblock it. Where several are startable the picker is the
83
+ control after the block, and `Next` names it.
@@ -27,14 +27,16 @@ 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 **fourteen skills**: `spec` (feature, chore or issue), `spec-bug` (bug),
30
+ The system is **sixteen skills**: `spec` (feature, chore or issue), `spec-bug` (bug),
31
31
  `spec-hotfix` (a bug fixed on a released tag),
32
32
  `spec-incident` (a live outage, recorded as it happens),
33
33
  `no-spec` (work that genuinely has none — off the base branch all the same),
34
34
  `spec-review`, `spec-start`,
35
35
  `spec-next`, `spec-diff` (read a spec's diff as a page),
36
- `spec-reviewed` (pick up a review you approved on that page), `spec-to-main`,
37
- `spec-complete`, `spec-cancel`, and this `spec-init`. The lifecycle is `backlog → in-progress → complete / cancelled`,
36
+ `spec-reviewed` (pick up a review you approved on that page),
37
+ `spec-epic-next` (name the epic member that can start now), `spec-to-main`,
38
+ `spec-complete`, `spec-cancel`, `spec-tada` (a ta-da list of what got done),
39
+ and this `spec-init`. The lifecycle is `backlog → in-progress → complete / cancelled`,
38
40
  with `.core` holding always-apply project rules.
39
41
 
40
42
  ## 0. Workspace mode (only when adopting isolation)
@@ -59,6 +61,36 @@ path, and records the answer on each spec. Leave it off and nothing appears:
59
61
  no question, no header, no check. Off is a perfectly good answer for a project
60
62
  that does not use flags.
61
63
 
64
+ ## 0c. Project name and category (only with isolation)
65
+
66
+ Two values in `env.config.json` that the rest of the tooling reads:
67
+ `project.name` heads every generated page (reviews, `/spec-tada`), and
68
+ `project.category` decides which projects share a `/spec-tada` report — a
69
+ project with no category is left out of everyone else's. Ask both, together:
70
+
71
+ - **Name** — default the repo folder's name, which is also what is used when it
72
+ is left empty. Accept it unless the operator wants another.
73
+ - **Category** — run `skitterspec project --categories` and offer what it
74
+ lists, most-used first, so `work` is not typed as `Work stuff` in the next
75
+ repo and splits a report in two. Then offer to **type a new one**, and to
76
+ **leave it empty** (this project stays out of every categorised report).
77
+
78
+ Where the answer goes depends on whether the file exists yet:
79
+
80
+ - **A fresh adoption** — pass them to the command that creates the file:
81
+ `skitterspec init --isolation --name "<name>" --category <category>`.
82
+ - **`env.config.json` already exists** — the change is work, and the base
83
+ branch is a landing zone, so make it on a `/no-spec` branch
84
+ (`project-settings`): run `skitterspec project --name "<name>" --category
85
+ <category>` in that worktree, which edits only those two values, then land
86
+ it on the verdict as `/no-spec` does. Never write it in the primary checkout
87
+ on the base branch.
88
+
89
+ `skitterspec project` with no flags shows what is set now and where each value
90
+ comes from — read it first on a re-run, and skip the question when both are
91
+ already what the operator wants. Without isolation there is no
92
+ `env.config.json` and the command refuses to create one, so skip this step.
93
+
62
94
  ## 1. Folders
63
95
 
64
96
  Create any that are missing; drop a `.gitkeep` into ones that would otherwise be
@@ -297,11 +297,46 @@ Then build it, following the project rules in `.claude/rules/*.md` and `CLAUDE.m
297
297
  - Never hardcode dates in tests; never run destructive commands against a real
298
298
  database — use the project's test database only.
299
299
 
300
+ ### Manual steps — list them, then ask
301
+
302
+ Some tasks are a person's to do: every task in an **Issue** spec, and any task
303
+ you cannot perform yourself — operate a UI, check a device, confirm something
304
+ on a board, run a manual test pass. That is a **judgment**, not a marker: there
305
+ is no `(manual)` tag to look for, and a spec written before this rule has none.
306
+
307
+ Build the tasks before the first manual one as usual. Then **stop at it** and
308
+ print **every remaining manual step of this phase, verbatim and numbered**, as a
309
+ plain markdown list in the conversation — never fenced, and
310
+ **never only the phase file's path**. A pointer to the file sends the reader
311
+ out of the terminal to find out what to do, which is the failure this exists to
312
+ fix; the steps themselves are what they act on.
313
+
314
+ Then ask one question, with three answers:
315
+
316
+ - **All done** — tick those steps and carry on to the end of the phase.
317
+ - **Some failed** — the picker cannot list the steps (it holds four options and
318
+ a phase can hold more), so ask in prose which numbers failed and what
319
+ happened. Write a dated note under each failed task, leave it unticked, tick
320
+ the rest. Where what happened is a defect, offer **`/spec-bug`** — confirm,
321
+ never switch.
322
+ - **Not yet** — tick nothing.
323
+
324
+ This is the mid-run question `.claude/rules/spec-reports.md` already allows —
325
+ whether a person did something is a question you cannot answer yourself — so it
326
+ needs no new shape in the report.
327
+
328
+ **Some failed or Not yet leaves the phase `🔄`, and stops the run there.** Code
329
+ tasks after an unconfirmed step are not built past it, and the phase did not
330
+ end: **skip §4's done-marking and §5 entirely** — no page, no arm, no wait.
331
+ End `⚠️` and name `/spec-next` in `Next`; it re-lists the same unticked steps.
332
+
300
333
  ## 4. Record progress
301
334
 
302
335
  - In the **phase file**: tick completed tasks (`- [x]`), flip its heading to `✅`,
303
336
  and set its `> **Status:**` to `Done`.
304
337
  - In **`00-overview.md`**: flip the matching phase-index row to `✅`.
338
+ - A manual step answered **Some failed** keeps its box unticked with its note,
339
+ and the phase is not marked done (§3, *Manual steps*).
305
340
  - If anything changed from the plan (a decision, a deviation, a discovered
306
341
  constraint), add a dated **Changelog** entry in `00-overview.md`.
307
342
  - If new work surfaced, add it as tasks to the appropriate phase file (or add a
@@ -645,7 +680,9 @@ the shape; this section carries only what is specific here.
645
680
 
646
681
  - `✅` — the phase is built and its tests are green.
647
682
  - `⚠️` — built and green, with something worth knowing (a mirror that did not
648
- refresh, a deviation from the plan).
683
+ refresh, a deviation from the plan) — or stopped at manual steps answered
684
+ **Some failed** or **Not yet**: the phase stays `🔄`, `Notes` says which steps
685
+ are open, and `Next` is `/commit, then /spec-next` to pick them up.
649
686
  - `❌` — the phase's tests are red, or it stopped part-way. Quote the failure.
650
687
  - `⏸` — no spec in flight, or the name given does not match the one that is.
651
688
 
@@ -474,7 +474,7 @@ tiers. Two things go in the block, both copied from it rather than composed:
474
474
  **This tab is the epic's from here.** The members are built in tabs of their
475
475
  own; this one is where the operator comes back to see what each needs. On a
476
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
477
+ one command away rather than scrolled past: **`/spec-epic`** re-shows the table and
478
478
  the page, and the block names it.
479
479
 
480
480
  **`checkout` mode — carry straight on into `/spec-next`** in this session: it
@@ -548,7 +548,7 @@ operator's next command depends on knowing that. `Next` is `/spec-next`.
548
548
 
549
549
  **An epic is the one exception, both ways.** `Review` appears only for an epic,
550
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).
551
+ — with `/spec-epic` to bring the table and the page back (step 6).
552
552
 
553
553
  `Untouched` appears only when `spec-env up` reported uncommitted work that was
554
554
  not this spec's — say how much and whose, and **keep the verdict `✅`**. Nothing