@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.
- package/assets/claude-md-section.md +6 -0
- package/assets/core/env.config.json.example +5 -0
- package/assets/core/env.config.md +26 -5
- package/assets/review/page.html +9 -0
- package/assets/rules/spec-planning.md +65 -12
- package/assets/rules/spec-reports.md +8 -1
- package/assets/skills/spec/SKILL.md +31 -14
- package/assets/skills/spec-cancel/SKILL.md +7 -0
- package/assets/skills/spec-complete/SKILL.md +6 -0
- package/assets/skills/spec-epic-next/SKILL.md +83 -0
- package/assets/skills/spec-init/SKILL.md +35 -3
- package/assets/skills/spec-next/SKILL.md +38 -1
- package/assets/skills/spec-start/SKILL.md +2 -2
- package/assets/skills/spec-tada/SKILL.md +153 -0
- package/bin/skitterspec-jira.js +5 -0
- package/package.json +1 -1
- package/src/cli.js +473 -25
- package/src/env/config.js +57 -6
- package/src/env/epic.js +69 -19
- package/src/env/epicpage.js +87 -39
- package/src/env/epicread.js +41 -3
- package/src/env/integrate.js +48 -1
- package/src/env/nextaction.js +78 -1
- package/src/env/project.js +54 -3
- package/src/env/projectedit.js +148 -0
- package/src/env/resolve.js +1 -0
- package/src/env/review.js +21 -3
- package/src/env/serve.js +44 -8
- package/src/env/specbranches.js +120 -0
- package/src/env/teardown.js +18 -3
- package/src/gating.js +16 -4
- package/src/init.js +11 -3
- package/src/tada/commits.js +145 -0
- package/src/tada/digest.js +260 -0
- package/src/tada/format.js +37 -0
- package/src/tada/page.js +213 -0
- package/src/tada/repo.js +102 -0
- package/src/tada/serve.js +127 -0
- package/src/tada/specs.js +146 -0
- package/src/tada/transcripts.js +258 -0
- package/src/tada/window.js +156 -0
- package/src/vendor/provider-kit/src/apply.js +25 -1
- package/src/vendor/sync-core/src/compare.js +10 -2
- package/src/vendor/sync-core/src/push.js +14 -3
- /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
|
|
333
|
-
//
|
|
334
|
-
//
|
|
335
|
-
//
|
|
336
|
-
//
|
|
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
|
}
|
package/assets/review/page.html
CHANGED
|
@@ -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
|
|
249
|
-
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
|
|
253
|
-
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
|
|
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.
|
|
733
|
-
|
|
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
|
|
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
|
|
624
|
-
|
|
625
|
-
|
|
626
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
631
|
-
|
|
632
|
-
|
|
633
|
-
|
|
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
|
-
|
|
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 **
|
|
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),
|
|
37
|
-
`spec-
|
|
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
|