@skitterbyte/skitterspec-jira 2.3.0 → 2.4.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 +20 -1
- package/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +90 -6
- package/assets/core/jira.config.md +4 -2
- package/assets/hooks/main-guard.cjs +18 -2
- package/assets/hooks/review-gate.cjs +19 -2
- package/assets/rules/commit-trailers.md +24 -1
- package/assets/rules/spec-planning.md +81 -18
- package/assets/rules/spec-reports.md +1 -1
- package/assets/skills/spec/SKILL.md +55 -2
- package/assets/skills/spec-bug/SKILL.md +25 -1
- package/assets/skills/spec-cancel/SKILL.md +35 -0
- package/assets/skills/spec-complete/SKILL.md +113 -0
- package/assets/skills/spec-hotfix/SKILL.md +40 -2
- package/assets/skills/spec-incident/SKILL.md +22 -0
- package/assets/skills/spec-jira-setup/SKILL.md +23 -1
- package/assets/skills/spec-next/SKILL.md +9 -4
- package/assets/skills/spec-push/SKILL.md +22 -0
- package/assets/skills/spec-review/SKILL.md +32 -0
- package/assets/skills/spec-start/SKILL.md +39 -1
- package/assets/skills/spec-status/SKILL.md +18 -3
- package/assets/skills/spec-sync/SKILL.md +1 -0
- package/assets/skills/spec-to-main/SKILL.md +47 -1
- package/package.json +1 -1
- package/src/cli.js +1091 -39
- package/src/env/base.js +104 -0
- package/src/env/config.js +75 -3
- package/src/env/disposition.js +62 -0
- package/src/env/handoff.js +80 -0
- package/src/env/host.js +262 -0
- package/src/env/hotfix.js +225 -0
- package/src/env/hotfixland.js +103 -9
- package/src/env/inflight.js +95 -0
- package/src/env/integrate.js +130 -4
- package/src/env/mainguard.js +6 -0
- package/src/env/phases.js +28 -0
- package/src/env/provision.js +18 -6
- package/src/env/resolve.js +108 -9
- package/src/env/serve.js +6 -1
- package/src/env/specstate.js +101 -0
- package/src/env/teardown.js +42 -0
- package/src/vendor/jira/cli-sync.js +45 -3
- package/src/vendor/jira/config.js +17 -5
- package/src/vendor/provider-kit/index.js +4 -0
- package/src/vendor/provider-kit/src/apply.js +49 -4
- package/src/vendor/provider-kit/src/assignment.js +78 -1
- package/src/vendor/provider-kit/src/config.js +34 -1
- package/src/vendor/provider-kit/src/list-rows.js +35 -11
- package/src/vendor/provider-kit/src/released.js +14 -1
- package/src/vendor/provider-kit/src/specs.js +4 -2
- package/src/vendor/provider-kit/src/splice.js +64 -0
- package/src/vendor/provider-kit/src/status.js +137 -0
- package/src/vendor/sync-core/index.js +14 -1
- package/src/vendor/sync-core/src/compare.js +17 -5
- package/src/vendor/sync-core/src/normalize.js +50 -7
- package/src/vendor/sync-core/src/push.js +26 -2
- package/src/vendor/sync-core/src/summary.js +257 -0
|
@@ -37,6 +37,28 @@ it verbatim/condensed for the header.
|
|
|
37
37
|
|
|
38
38
|
## 4. Stamp the spec
|
|
39
39
|
|
|
40
|
+
**Who owns this spec's status.** Only when `specs/.core/jira.config.json` exists.
|
|
41
|
+
Run `skitterspec spec-sync ownership --json` once and read both values:
|
|
42
|
+
|
|
43
|
+
- **`workflowState: "pull"`** — Jira is the record of this spec's status, so
|
|
44
|
+
this skill **writes no `> **Status:**` header and appends no State log row**,
|
|
45
|
+
wherever its steps below say to. A spec this skill creates gets neither: its
|
|
46
|
+
header carries `> **Tracker:** <issue url>` instead, filled in once linking
|
|
47
|
+
has stamped the url, and its body has no `## State log` section. Readiness is
|
|
48
|
+
the spec's own content — a `Draft` is a spec whose **Open questions** is not
|
|
49
|
+
empty — so nothing is lost with the header.
|
|
50
|
+
- **`assignee: "pull"`** — Jira holds who is building it, so this skill
|
|
51
|
+
**writes no `> **Developer:**` line** either.
|
|
52
|
+
- **Anything else** — `push`, `none`, sync reported off, or the command failing
|
|
53
|
+
— is cannot-tell, and the steps below run exactly as written.
|
|
54
|
+
|
|
55
|
+
What `pull` leaves alone: the folder move (a bucket records what the repo did to
|
|
56
|
+
the code, not a planning status), the phase files and index, and the Changelog.
|
|
57
|
+
A reason a `Status:` header would have carried — a cancellation's, a knock-back
|
|
58
|
+
to Draft — goes in a dated Changelog line instead. A spec that already carries
|
|
59
|
+
any of these lines keeps them untouched: they are history, and nothing rewrites
|
|
60
|
+
them.
|
|
61
|
+
|
|
40
62
|
Update the **Status** header in the entry point so the reason is visible at the
|
|
41
63
|
top:
|
|
42
64
|
|
|
@@ -75,6 +97,10 @@ Jira credentials are set (see `apply.transport` in `jira.config.md`).
|
|
|
75
97
|
complete/cancelled/reviewed in the repo regardless; the mirror is disposable
|
|
76
98
|
and the next push repairs it. Do not roll anything back, and do not stop to
|
|
77
99
|
ask.
|
|
100
|
+
- **In `/spec-complete`'s PR mode this push belongs to run 2.** Run 1 readies
|
|
101
|
+
a PR, and a ready PR is not a merged one — so skip it on run 1, even where
|
|
102
|
+
the `branch` lane committed the move to ride the PR, and run it on run 2 once
|
|
103
|
+
the host has merged. The tracker's Done lands when the work does.
|
|
78
104
|
- **Say what happened** in the skill's report: mirror updated, skipped as
|
|
79
105
|
unlinked, or failed with the reason.
|
|
80
106
|
- **There is no assignment to release here.** Assignment sync is not yet
|
|
@@ -252,6 +278,15 @@ only ordering that survives.
|
|
|
252
278
|
copy of abandoned work. Seeing no such section here is the expected case, not
|
|
253
279
|
a fault — and if the user wants the remote branch gone anyway, that is their
|
|
254
280
|
call to make explicitly, not something to tidy away on their behalf.
|
|
281
|
+
|
|
282
|
+
**In PR mode the same confirm-first section may carry the PR abandon**
|
|
283
|
+
(`gh pr close` / `az repos pr update --status abandoned`): a cancelled spec
|
|
284
|
+
must not leave a live PR behind — it is noise with a merge button on it.
|
|
285
|
+
The teardown of an open-PR spec is refused unforced (the PR is named), so
|
|
286
|
+
this line appears on the forced run the refusal led to; ask before running
|
|
287
|
+
it like the delete above, and run the abandon **before** any remote branch
|
|
288
|
+
delete — closing the PR first is what stops the host complaining about a
|
|
289
|
+
deleted source branch.
|
|
255
290
|
4. `skitterspec spec-env prune` — reap orphaned test-DB volumes that belong to no
|
|
256
291
|
live spec (leftovers from declined/aborted teardowns or manual worktree
|
|
257
292
|
removal). Show the orphan list and, **only on the user's confirmation**, run
|
|
@@ -102,6 +102,29 @@ feature was designed not to disturb.
|
|
|
102
102
|
|
|
103
103
|
- Tick all completed tasks in the phase files; flip every finished phase-file
|
|
104
104
|
heading **and** every row in the `00-overview.md` phase index to `✅`.
|
|
105
|
+
|
|
106
|
+
**Who owns this spec's status.** Only when `specs/.core/jira.config.json` exists.
|
|
107
|
+
Run `skitterspec spec-sync ownership --json` once and read both values:
|
|
108
|
+
|
|
109
|
+
- **`workflowState: "pull"`** — Jira is the record of this spec's status, so
|
|
110
|
+
this skill **writes no `> **Status:**` header and appends no State log row**,
|
|
111
|
+
wherever its steps below say to. A spec this skill creates gets neither: its
|
|
112
|
+
header carries `> **Tracker:** <issue url>` instead, filled in once linking
|
|
113
|
+
has stamped the url, and its body has no `## State log` section. Readiness is
|
|
114
|
+
the spec's own content — a `Draft` is a spec whose **Open questions** is not
|
|
115
|
+
empty — so nothing is lost with the header.
|
|
116
|
+
- **`assignee: "pull"`** — Jira holds who is building it, so this skill
|
|
117
|
+
**writes no `> **Developer:**` line** either.
|
|
118
|
+
- **Anything else** — `push`, `none`, sync reported off, or the command failing
|
|
119
|
+
— is cannot-tell, and the steps below run exactly as written.
|
|
120
|
+
|
|
121
|
+
What `pull` leaves alone: the folder move (a bucket records what the repo did to
|
|
122
|
+
the code, not a planning status), the phase files and index, and the Changelog.
|
|
123
|
+
A reason a `Status:` header would have carried — a cancellation's, a knock-back
|
|
124
|
+
to Draft — goes in a dated Changelog line instead. A spec that already carries
|
|
125
|
+
any of these lines keeps them untouched: they are history, and nothing rewrites
|
|
126
|
+
them.
|
|
127
|
+
|
|
105
128
|
- Set the **Status** header in the entry point:
|
|
106
129
|
`> **Status:** Complete (<YYYY-MM-DD>)`.
|
|
107
130
|
- Append a **State log** row:
|
|
@@ -136,6 +159,10 @@ Jira credentials are set (see `apply.transport` in `jira.config.md`).
|
|
|
136
159
|
complete/cancelled/reviewed in the repo regardless; the mirror is disposable
|
|
137
160
|
and the next push repairs it. Do not roll anything back, and do not stop to
|
|
138
161
|
ask.
|
|
162
|
+
- **In `/spec-complete`'s PR mode this push belongs to run 2.** Run 1 readies
|
|
163
|
+
a PR, and a ready PR is not a merged one — so skip it on run 1, even where
|
|
164
|
+
the `branch` lane committed the move to ride the PR, and run it on run 2 once
|
|
165
|
+
the host has merged. The tracker's Done lands when the work does.
|
|
139
166
|
- **Say what happened** in the skill's report: mirror updated, skipped as
|
|
140
167
|
unlinked, or failed with the reason.
|
|
141
168
|
- **There is no assignment to release here.** Assignment sync is not yet
|
|
@@ -288,6 +315,27 @@ in that order, and stops at the first step that fails:
|
|
|
288
315
|
**Then stop: the worktree is kept** (step 7). The branch is what the next
|
|
289
316
|
`-hotfix.N` is cut from if this deploy fails, so it waits for the deploy.
|
|
290
317
|
|
|
318
|
+
**A branch-based hotfix** (`> **Base version:** <branch>@<sha>`, from
|
|
319
|
+
`hotfix.releaseBranch`) runs the same command and the same consent ask — the
|
|
320
|
+
engine picks the path from the header. What differs is what it does:
|
|
321
|
+
|
|
322
|
+
- it **rebases** onto `<remote>/<branch>` and **lands on the release branch** by
|
|
323
|
+
`land.strategy`: under `ff` the push of the hotfix onto that branch *is* the
|
|
324
|
+
land (so the consent ask names the release branch, not only a tag); under `pr`
|
|
325
|
+
it pushes the hotfix branch and opens a **ready** PR, then holds with
|
|
326
|
+
`the PR into <branch> is open` — re-run the same command once it merges;
|
|
327
|
+
- the **tag** is optional (`hotfix.tag`): cut and pushed after the land, or not
|
|
328
|
+
at all;
|
|
329
|
+
- the **carry** goes to the resolved base — the current rc under
|
|
330
|
+
`baseBranchPattern` — directly under `ff`, through a `carry/<slug>` branch and
|
|
331
|
+
its own ready PR under `pr`.
|
|
332
|
+
|
|
333
|
+
`Landed` then names the release branch, how it landed (fast-forward, or the PR
|
|
334
|
+
and whether it merged), the tag if one was cut, and the carry. A PR still
|
|
335
|
+
waiting on its merge is a `⚠️` — the land is not done until the host says so.
|
|
336
|
+
`spec-env hotfix finish` tears it down once both the land and the carry are
|
|
337
|
+
confirmed, naming every check that is not.
|
|
338
|
+
|
|
291
339
|
### 6-feature/bug. `Type: Feature` / `Type: Bug` — rebase + fast-forward
|
|
292
340
|
|
|
293
341
|
Land the finished branch on the base branch so the work reaches `main` (or your
|
|
@@ -323,6 +371,19 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
|
|
|
323
371
|
`git -C <worktree> rebase --abort`, relay the conflict, and **stop** — leave it
|
|
324
372
|
to the user; do not tear anything down.
|
|
325
373
|
On a **no-op** ("already landed"), just say so and continue.
|
|
374
|
+
|
|
375
|
+
**Under a rolling base** (`baseBranchPattern` in `env.config.json`) the plan
|
|
376
|
+
can carry two more things, and both are the engine's to say:
|
|
377
|
+
- a `git -C <mainRepoPath> switch <base>` (or `switch -c … --track`) **first**,
|
|
378
|
+
when the primary checkout still has an older release candidate out — run it
|
|
379
|
+
in order with the rest;
|
|
380
|
+
- a `retarget: forked from <old> · landing onto <new>` line, when the rc
|
|
381
|
+
rolled while this spec was in flight. It is the land working, not a fault:
|
|
382
|
+
relay it verbatim in the `Landed` row so the reader sees where the work went.
|
|
383
|
+
|
|
384
|
+
A refusal naming `no branch matches <pattern>` means no release candidate is
|
|
385
|
+
visible — usually not fetched. Relay it, stop with `⏸`, and name
|
|
386
|
+
`skitterspec spec-env base` (it fetches and lists) as the next step.
|
|
326
387
|
3. **Run the after-land commands.** Where the plan ends with a
|
|
327
388
|
`then, in the primary checkout (<path>), run:` section — the project's
|
|
328
389
|
`afterLand`, such as a data migration — run those commands in that
|
|
@@ -342,6 +403,58 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
|
|
|
342
403
|
5. **Report** the landing (base branch, fast-forward result). It **never pushes** —
|
|
343
404
|
mention the user can `git push` the base branch themselves.
|
|
344
405
|
|
|
406
|
+
### 6-pr. PR mode (`land.strategy: "pr"`) — dispose, push, ready; finish after the merge
|
|
407
|
+
|
|
408
|
+
Completion is **two runs** here, the `hotfix land`/`finish` shape: the merge is
|
|
409
|
+
the host's act and may be days away, so the run that readies the PR cannot also
|
|
410
|
+
finalise. Which run this is, the engine says: `spec-env integrate <name>`
|
|
411
|
+
printing a `(pr)` plan is run 1; printing
|
|
412
|
+
`already landed … — finish what the merge deferred` is run 2.
|
|
413
|
+
|
|
414
|
+
**Run 1 — the last control point.** Once the PR is ready, anyone can merge from
|
|
415
|
+
the host UI and the tracker's automations act — so everything that needs a
|
|
416
|
+
person happens before the ready, in this order:
|
|
417
|
+
|
|
418
|
+
1. **Disposition pass — mandatory, before anything is pushed.** Run
|
|
419
|
+
`skitterspec spec-env disposition <name> --json`. For every unticked task,
|
|
420
|
+
non-✅ phase and surfaced follow-up it lists, the user disposes it:
|
|
421
|
+
**tick** (it was done — tick it, naming the evidence) · **spin off** (a
|
|
422
|
+
follow-on ticket minted now, linked to this one — offer `/spec` or the
|
|
423
|
+
provider's mint) · **drop** (a dated Changelog line with the reason, the
|
|
424
|
+
`none: <reason>` grammar). Batch the asking; never decide for them, and
|
|
425
|
+
never auto-create. **Refuse to ready the PR while anything is undisposed**
|
|
426
|
+
— you asked the enumeration, so it cannot also be fine. `clean` proceeds
|
|
427
|
+
with nothing asked.
|
|
428
|
+
2. **Consent, naming the target.** Ask once, plainly:
|
|
429
|
+
*"push `<branch>` and open the PR into `<base>` on `<remote>`, ready for
|
|
430
|
+
merge?"* — the base branch is named so a spec that outlived a release roll
|
|
431
|
+
is caught by the person reading a stale rc name. On a no, stop with the
|
|
432
|
+
held commands relayed.
|
|
433
|
+
3. **Run the plan.** `skitterspec spec-env integrate <name> --push` and run
|
|
434
|
+
what it prints: fetch, rebase onto `<remote>/<base>`, the push, and the PR
|
|
435
|
+
create — or, where a draft already exists, the flip-to-ready. A rebase
|
|
436
|
+
conflict aborts and stops exactly as 6-feature/bug step 2.
|
|
437
|
+
4. **Defer the finalise.** §4's bucket move follows the spec documents'
|
|
438
|
+
`land.specDocs` lane: under `trunk` leave the spec in `specs/in-progress/`
|
|
439
|
+
— run 2 moves it on base after the merge; under `branch` commit the move on
|
|
440
|
+
the branch *before* step 3 so it rides the PR. Either way
|
|
441
|
+
**the tracker's Done waits for run 2**: a ready PR is not a merged one.
|
|
442
|
+
5. **Stop, keeping the worktree.** Report
|
|
443
|
+
`Landed: PR #N opened — finish after merge` (or `ready`), spec
|
|
444
|
+
`In Progress`, worktree standing. No afterLand runs — the plan deferred it
|
|
445
|
+
— and no teardown. The merge is what un-blocks run 2; nothing here waits on
|
|
446
|
+
it.
|
|
447
|
+
|
|
448
|
+
**Run 2 — after the host merges.** `integrate` recognises the landed branch
|
|
449
|
+
(ancestry or the host's answer) and prints the finish: catch local base up and
|
|
450
|
+
the deferred `afterLand` with the land's own range. Run those, then do what run
|
|
451
|
+
1 deferred — the §4 move (trunk lane) with its State log row and commit, the
|
|
452
|
+
§5 report — then **§7 teardown runs as normal**:
|
|
453
|
+
a host-merged branch counts as landed (squash and rebase
|
|
454
|
+
merges included), and a host that auto-deleted the branch makes the remote
|
|
455
|
+
delete an already-gone no-op, never a failure. Re-test on base before calling
|
|
456
|
+
it done, exactly as 6-feature/bug step 4.
|
|
457
|
+
|
|
345
458
|
## 7. Tear down the environment (opt-in, only if configured)
|
|
346
459
|
|
|
347
460
|
**A hotfix is torn down later, by `hotfix finish`.**
|
|
@@ -148,6 +148,16 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
|
|
|
148
148
|
|
|
149
149
|
## 1. Establish the base version (the tag)
|
|
150
150
|
|
|
151
|
+
**A release BRANCH instead of a tag.** Where `env.config.json` sets
|
|
152
|
+
`hotfix.releaseBranch` (e.g. `"master"` — a team whose prod is whatever that
|
|
153
|
+
branch holds), there is **no tag to ask for**: skip the questions below and run
|
|
154
|
+
§3's `up` **without `--from`**. The engine fetches, forks from the remote's head
|
|
155
|
+
of that branch, and prints two lines — `fork:` naming the commit, and
|
|
156
|
+
`record: > **Base version:** <branch>@<sha>` — and §5 copies that `record:`
|
|
157
|
+
value into the header **verbatim**. Say which commit it forked from in one line;
|
|
158
|
+
that is the version the fix is built on. The rest of this section is the tag
|
|
159
|
+
flow, unchanged.
|
|
160
|
+
|
|
151
161
|
- **Read the arguments.** `/spec-hotfix <tag> <name>` (e.g.
|
|
152
162
|
`/spec-hotfix v33.16.4 login-crash`). An argument shaped like an issue
|
|
153
163
|
reference — letters, a hyphen, digits (`SKI-123`) —
|
|
@@ -265,6 +275,10 @@ installs `.claude/hooks/main-guard.cjs` that first write is refused outright,
|
|
|
265
275
|
and a step whose documented opening the repo will not perform is not a step. The
|
|
266
276
|
spec is written in the worktree at §5, on the branch it belongs to.
|
|
267
277
|
|
|
278
|
+
**Branch-based (`hotfix.releaseBranch`):** run the same command **without**
|
|
279
|
+
`--from` — the engine picks the release branch's head and prints the
|
|
280
|
+
`record:` line §5 copies. An explicit `--from` still wins over it.
|
|
281
|
+
|
|
268
282
|
**§5 records the same tag you passed to `--from`**, on the spec's
|
|
269
283
|
`> **Base version:**` header. That is not bookkeeping: `/spec-complete` cuts the
|
|
270
284
|
release and carries the fix off the header, so a worktree forked from one ref and
|
|
@@ -303,6 +317,28 @@ you there, so create the folder and write it here. A hotfix
|
|
|
303
317
|
is usually a single-pass fix, so the `## Fix` block can live directly in
|
|
304
318
|
`00-overview.md`. Keep it lean:
|
|
305
319
|
|
|
320
|
+
**Who owns this spec's status.** Only when `specs/.core/jira.config.json` exists.
|
|
321
|
+
Run `skitterspec spec-sync ownership --json` once and read both values:
|
|
322
|
+
|
|
323
|
+
- **`workflowState: "pull"`** — Jira is the record of this spec's status, so
|
|
324
|
+
this skill **writes no `> **Status:**` header and appends no State log row**,
|
|
325
|
+
wherever its steps below say to. A spec this skill creates gets neither: its
|
|
326
|
+
header carries `> **Tracker:** <issue url>` instead, filled in once linking
|
|
327
|
+
has stamped the url, and its body has no `## State log` section. Readiness is
|
|
328
|
+
the spec's own content — a `Draft` is a spec whose **Open questions** is not
|
|
329
|
+
empty — so nothing is lost with the header.
|
|
330
|
+
- **`assignee: "pull"`** — Jira holds who is building it, so this skill
|
|
331
|
+
**writes no `> **Developer:**` line** either.
|
|
332
|
+
- **Anything else** — `push`, `none`, sync reported off, or the command failing
|
|
333
|
+
— is cannot-tell, and the steps below run exactly as written.
|
|
334
|
+
|
|
335
|
+
What `pull` leaves alone: the folder move (a bucket records what the repo did to
|
|
336
|
+
the code, not a planning status), the phase files and index, and the Changelog.
|
|
337
|
+
A reason a `Status:` header would have carried — a cancellation's, a knock-back
|
|
338
|
+
to Draft — goes in a dated Changelog line instead. A spec that already carries
|
|
339
|
+
any of these lines keeps them untouched: they are history, and nothing rewrites
|
|
340
|
+
them.
|
|
341
|
+
|
|
306
342
|
```markdown
|
|
307
343
|
# Hotfix: <short title>
|
|
308
344
|
|
|
@@ -311,7 +347,7 @@ is usually a single-pass fix, so the `## Fix` block can live directly in
|
|
|
311
347
|
> **Status:** In Progress — fixing (red test added)
|
|
312
348
|
> **Author:** <git user.name — who reported/captured it>
|
|
313
349
|
> **Developer:** <git user.name — you, since you're fixing it now>
|
|
314
|
-
> **Base version:** <tag prod is running, e.g. v33.16.4>
|
|
350
|
+
> **Base version:** <tag prod is running, e.g. v33.16.4 — or, branch-based, the `record:` value `up` printed, e.g. master@1a2b3c4d5e6f>
|
|
315
351
|
> **Raised:** <YYYY-MM-DD (today)>
|
|
316
352
|
> **Area:** <files/modules>
|
|
317
353
|
> **Severity:** <Azure's literal values, "1 - Critical" … "4 - Low" — optional;
|
|
@@ -390,7 +426,9 @@ If it's absent, skip this entirely — the spec stays local-only and the skill
|
|
|
390
426
|
behaves exactly as above. When present, link the spec you just wrote so status
|
|
391
427
|
and discussion live in Jira while the repo stays the source of truth. A spec is
|
|
392
428
|
a Jira **issue**; each phase is a **subtask**, carrying that phase's tasks in
|
|
393
|
-
its description as a read-only checklist.
|
|
429
|
+
its description as a read-only checklist. That is the `spec` description mode;
|
|
430
|
+
under `summary` (a new config's default) the issue and each sub-issue carry
|
|
431
|
+
a short block instead, and the phase's tasks stay in git.
|
|
394
432
|
|
|
395
433
|
**Linking is just the first push**, so it runs the same engine path `/spec-push`
|
|
396
434
|
does — you never create the issue by hand:
|
|
@@ -72,6 +72,28 @@ this spec. Without isolation, write where you stand.
|
|
|
72
72
|
The spec is a folder in **`specs/in-progress/`** — never backlog — with
|
|
73
73
|
`00-overview.md` and one phase file:
|
|
74
74
|
|
|
75
|
+
**Who owns this spec's status.** Only when `specs/.core/jira.config.json` exists.
|
|
76
|
+
Run `skitterspec spec-sync ownership --json` once and read both values:
|
|
77
|
+
|
|
78
|
+
- **`workflowState: "pull"`** — Jira is the record of this spec's status, so
|
|
79
|
+
this skill **writes no `> **Status:**` header and appends no State log row**,
|
|
80
|
+
wherever its steps below say to. A spec this skill creates gets neither: its
|
|
81
|
+
header carries `> **Tracker:** <issue url>` instead, filled in once linking
|
|
82
|
+
has stamped the url, and its body has no `## State log` section. Readiness is
|
|
83
|
+
the spec's own content — a `Draft` is a spec whose **Open questions** is not
|
|
84
|
+
empty — so nothing is lost with the header.
|
|
85
|
+
- **`assignee: "pull"`** — Jira holds who is building it, so this skill
|
|
86
|
+
**writes no `> **Developer:**` line** either.
|
|
87
|
+
- **Anything else** — `push`, `none`, sync reported off, or the command failing
|
|
88
|
+
— is cannot-tell, and the steps below run exactly as written.
|
|
89
|
+
|
|
90
|
+
What `pull` leaves alone: the folder move (a bucket records what the repo did to
|
|
91
|
+
the code, not a planning status), the phase files and index, and the Changelog.
|
|
92
|
+
A reason a `Status:` header would have carried — a cancellation's, a knock-back
|
|
93
|
+
to Draft — goes in a dated Changelog line instead. A spec that already carries
|
|
94
|
+
any of these lines keeps them untouched: they are history, and nothing rewrites
|
|
95
|
+
them.
|
|
96
|
+
|
|
75
97
|
```markdown
|
|
76
98
|
# Incident: <short title>
|
|
77
99
|
|
|
@@ -119,13 +119,35 @@ Then settle the four bucket→status names against that list:
|
|
|
119
119
|
Each answer that differs from the defaults becomes a `--state <bucket>=<name>`
|
|
120
120
|
flag in step 6.
|
|
121
121
|
|
|
122
|
+
## 5b. What does a ticket carry?
|
|
123
|
+
|
|
124
|
+
Ask once, with the recommendation first — this decides what the team sees on
|
|
125
|
+
every ticket, so it is theirs to choose rather than a default to inherit:
|
|
126
|
+
|
|
127
|
+
- **`summary`** *(recommended — what `init-config` writes)* — the ticket holds a
|
|
128
|
+
short delimited block: the spec's summary, its acceptance criteria, the
|
|
129
|
+
surfaces it touches, its gating and its progress. Push splices that block in
|
|
130
|
+
beside whatever the team writes, which no push ever touches. The spec itself
|
|
131
|
+
stays in git.
|
|
132
|
+
- **`spec`** — the whole overview is the ticket body, replaced on every push.
|
|
133
|
+
Pass `--description spec` to `init-config`.
|
|
134
|
+
|
|
135
|
+
Jira's block is marked with a heading for now (`summary.delimiter`), provisional
|
|
136
|
+
until a measured run settles which delimiter Jira's editor keeps.
|
|
137
|
+
|
|
138
|
+
Then name the phase mode, without asking unless they raise it:
|
|
139
|
+
`mapping.phases` stays `subissue` — one assignable sub-issue per phase, which
|
|
140
|
+
is what lets phases run in parallel. `deferred` (minted at `/spec-start`),
|
|
141
|
+
`inline` and `none` (no sub-issues at all) are one edit to the file away.
|
|
142
|
+
|
|
122
143
|
## 6. Write it
|
|
123
144
|
|
|
124
145
|
```
|
|
125
146
|
skitterspec spec-sync init-config \
|
|
126
147
|
--site-url https://<site>.atlassian.net --project-key PROJ \
|
|
127
148
|
[--issue-type Task] [--subtask-type Subtask] \
|
|
128
|
-
[--state <bucket>=<name> …] [--force] [--json]
|
|
149
|
+
[--state <bucket>=<name> …] [--force] [--json] \
|
|
150
|
+
[--description summary|spec]
|
|
129
151
|
```
|
|
130
152
|
|
|
131
153
|
The engine writes **only the keys that differ from the defaults**, so the file
|
|
@@ -193,10 +193,15 @@ once it is over. Without a provider this is a no-op and nothing below changes.
|
|
|
193
193
|
**Only when `specs/.core/jira.config.json` exists** and the spec carries a
|
|
194
194
|
`jira_identifier`. Otherwise skip this step — no config means zero change.
|
|
195
195
|
|
|
196
|
-
- **No pull
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
196
|
+
- **No pull — one look at the board, before building.** Nothing is brought
|
|
197
|
+
down. Run `skitterspec spec-sync board <spec>`: it reads Jira and writes nothing to
|
|
198
|
+
the spec, and it is **silent** unless the issue says Done or Cancelled while
|
|
199
|
+
this spec is still in flight. When it prints a line, relay it once as a
|
|
200
|
+
warning — this session holds the branch, so the cleanup it names is the
|
|
201
|
+
operator's to choose — and **carry on with the build**. Never run that
|
|
202
|
+
cleanup and never refuse on it. A status someone moved anywhere else is the
|
|
203
|
+
board doing its job, and the next push sends a state only when the spec
|
|
204
|
+
itself changes bucket.
|
|
200
205
|
- **Refresh the mirror now, without asking.** Run `/spec-push`. The spec has just
|
|
201
206
|
moved to `in-progress` and its phase to `🔄` — both real state changes, and the
|
|
202
207
|
tracker is a generated mirror of them. This holds under **both**
|
|
@@ -20,6 +20,13 @@ skill computes what changed since the last push and applies it — it never read
|
|
|
20
20
|
Jira content back or merges. A person editing the mirror in Jira will see it
|
|
21
21
|
overwritten on the next push.
|
|
22
22
|
|
|
23
|
+
**That is `mapping.description: "spec"`.** Under `"summary"` (what a new
|
|
24
|
+
config is written with) the issue and each sub-issue carry a delimited
|
|
25
|
+
**block** instead — summary, acceptance criteria, surfaces, gating and
|
|
26
|
+
progress for the spec; goal and task count for a phase — spliced in beside
|
|
27
|
+
whatever the team wrote in Jira, which is never overwritten. Only the block
|
|
28
|
+
is the repo's, so only an edit inside it is reported.
|
|
29
|
+
|
|
23
30
|
**Opt-in**: only runs when `specs/.core/jira.config.json` exists. If absent,
|
|
24
31
|
tell the user how to enable Jira sync and stop.
|
|
25
32
|
|
|
@@ -148,6 +155,21 @@ configured `jira.projectKey` by construction.
|
|
|
148
155
|
|
|
149
156
|
## 4a. Apply it yourself — the MCP path (order matters)
|
|
150
157
|
|
|
158
|
+
**In summary mode, every body you write is the engine's splice — never the plan's text on its own.**
|
|
159
|
+
Only when the plan's `descriptionMode` is
|
|
160
|
+
`summary` (it is always present; `spec` needs none of this). There
|
|
161
|
+
the plan's `description` and each sub-issue's `goal` are a **block**, and the
|
|
162
|
+
issue's body is the block *plus the team's text around it*. Writing the block
|
|
163
|
+
alone deletes that text. So, for each object you are about to write:
|
|
164
|
+
|
|
165
|
+
1. Save the body Jira holds now to a file — an empty file for one you are
|
|
166
|
+
creating.
|
|
167
|
+
2. `skitterspec spec-sync splice <spec> --live <file>` for the spec issue, or
|
|
168
|
+
`… --phase <ref>` for a phase's sub-issue.
|
|
169
|
+
3. Write **exactly what it prints**. A non-zero exit printed nothing and means
|
|
170
|
+
a delimiter was edited by hand: skip that object's body, write its other
|
|
171
|
+
fields, and name it in the report. Never compose the splice yourself.
|
|
172
|
+
|
|
151
173
|
**First, check whether you are about to overwrite someone.** On the API path
|
|
152
174
|
`apply` does this for itself, off the read-back it already makes. On the MCP
|
|
153
175
|
path nothing has read the issue yet, so ask before you write:
|
|
@@ -43,6 +43,11 @@ trust the spec's own wording — verify:
|
|
|
43
43
|
- **Decisions still valid.** Re-check each `## Decisions` entry against the
|
|
44
44
|
current architecture and `.claude/rules/*.md`. Flag any that now conflict with
|
|
45
45
|
how the codebase actually works (a changed convention, a superseded approach).
|
|
46
|
+
- **The ticket-facing pair.** A spec with no `## Summary` or no
|
|
47
|
+
`## Acceptance criteria` is not broken — older specs predate both — but where
|
|
48
|
+
a ticketing provider pushes summaries the ticket falls back to the Problem's
|
|
49
|
+
first paragraph and shows no definition of done. Offer to write the missing
|
|
50
|
+
one(s) in step 3, with a draft; never add them unasked.
|
|
46
51
|
- **New constraints.** Note rules/patterns introduced since the spec was written
|
|
47
52
|
that it must now honour (e.g. a new required field, a new error type, a new
|
|
48
53
|
pattern the rest of the code now follows).
|
|
@@ -96,6 +101,29 @@ resolve it by reading the code, do that instead of asking.
|
|
|
96
101
|
- Add a dated **Changelog** entry summarising the review (e.g. `- <date> —
|
|
97
102
|
Reviewed vs codebase: retargeted Phase 2 onto X, dropped Y (removed), ticked Z
|
|
98
103
|
(already done)`).
|
|
104
|
+
|
|
105
|
+
**Who owns this spec's status.** Only when `specs/.core/jira.config.json` exists.
|
|
106
|
+
Run `skitterspec spec-sync ownership --json` once and read both values:
|
|
107
|
+
|
|
108
|
+
- **`workflowState: "pull"`** — Jira is the record of this spec's status, so
|
|
109
|
+
this skill **writes no `> **Status:**` header and appends no State log row**,
|
|
110
|
+
wherever its steps below say to. A spec this skill creates gets neither: its
|
|
111
|
+
header carries `> **Tracker:** <issue url>` instead, filled in once linking
|
|
112
|
+
has stamped the url, and its body has no `## State log` section. Readiness is
|
|
113
|
+
the spec's own content — a `Draft` is a spec whose **Open questions** is not
|
|
114
|
+
empty — so nothing is lost with the header.
|
|
115
|
+
- **`assignee: "pull"`** — Jira holds who is building it, so this skill
|
|
116
|
+
**writes no `> **Developer:**` line** either.
|
|
117
|
+
- **Anything else** — `push`, `none`, sync reported off, or the command failing
|
|
118
|
+
— is cannot-tell, and the steps below run exactly as written.
|
|
119
|
+
|
|
120
|
+
What `pull` leaves alone: the folder move (a bucket records what the repo did to
|
|
121
|
+
the code, not a planning status), the phase files and index, and the Changelog.
|
|
122
|
+
A reason a `Status:` header would have carried — a cancellation's, a knock-back
|
|
123
|
+
to Draft — goes in a dated Changelog line instead. A spec that already carries
|
|
124
|
+
any of these lines keeps them untouched: they are history, and nothing rewrites
|
|
125
|
+
them.
|
|
126
|
+
|
|
99
127
|
- **Status:** if drift is minor, leave status as-is. If a `Ready` spec needs real
|
|
100
128
|
re-grooming, knock it back to `Draft` (set `> **Status:** Draft` and append a
|
|
101
129
|
**State log** row).
|
|
@@ -119,6 +147,10 @@ Jira credentials are set (see `apply.transport` in `jira.config.md`).
|
|
|
119
147
|
complete/cancelled/reviewed in the repo regardless; the mirror is disposable
|
|
120
148
|
and the next push repairs it. Do not roll anything back, and do not stop to
|
|
121
149
|
ask.
|
|
150
|
+
- **In `/spec-complete`'s PR mode this push belongs to run 2.** Run 1 readies
|
|
151
|
+
a PR, and a ready PR is not a merged one — so skip it on run 1, even where
|
|
152
|
+
the `branch` lane committed the move to ride the PR, and run it on run 2 once
|
|
153
|
+
the host has merged. The tracker's Done lands when the work does.
|
|
122
154
|
- **Say what happened** in the skill's report: mirror updated, skipped as
|
|
123
155
|
unlinked, or failed with the reason.
|
|
124
156
|
- **There is no assignment to release here.** Assignment sync is not yet
|
|
@@ -152,6 +152,14 @@ render says so. On **`--plan`** this step does not run at all.
|
|
|
152
152
|
1. **Provision.** Run `skitterspec spec-env up <name>` — a planner, so run the
|
|
153
153
|
`to provision, run:` commands it prints and confirm they succeeded.
|
|
154
154
|
|
|
155
|
+
**Under a rolling base** (`baseBranchPattern`) `up` fetches first, and where
|
|
156
|
+
the primary checkout is not on the newest release candidate the plan says
|
|
157
|
+
`fork: <base> (the base — the primary checkout is on <old>)` and forks from
|
|
158
|
+
it. Relay that line in the `Branch` row. A refusal naming
|
|
159
|
+
`no branch matches <pattern>` means no release candidate is visible —
|
|
160
|
+
usually not fetched: relay it, stop with `⏸`, and name
|
|
161
|
+
`skitterspec spec-env base` (it fetches and lists) as the next step.
|
|
162
|
+
|
|
155
163
|
2. **Trust the worktree.** `spec-env up` wrote the printed `trusted:` root into
|
|
156
164
|
`.claude/settings.local.json`, but that file does not hot-reload in this
|
|
157
165
|
session — run **`/add-dir <trusted root>`** before editing into the worktree,
|
|
@@ -255,6 +263,29 @@ branch is already here.
|
|
|
255
263
|
|
|
256
264
|
- `git mv "specs/backlog/<name>" "specs/in-progress/<name>"` if it isn't there
|
|
257
265
|
already (`mkdir -p specs/in-progress` first). Use `git mv` to keep history.
|
|
266
|
+
|
|
267
|
+
**Who owns this spec's status.** Only when `specs/.core/jira.config.json` exists.
|
|
268
|
+
Run `skitterspec spec-sync ownership --json` once and read both values:
|
|
269
|
+
|
|
270
|
+
- **`workflowState: "pull"`** — Jira is the record of this spec's status, so
|
|
271
|
+
this skill **writes no `> **Status:**` header and appends no State log row**,
|
|
272
|
+
wherever its steps below say to. A spec this skill creates gets neither: its
|
|
273
|
+
header carries `> **Tracker:** <issue url>` instead, filled in once linking
|
|
274
|
+
has stamped the url, and its body has no `## State log` section. Readiness is
|
|
275
|
+
the spec's own content — a `Draft` is a spec whose **Open questions** is not
|
|
276
|
+
empty — so nothing is lost with the header.
|
|
277
|
+
- **`assignee: "pull"`** — Jira holds who is building it, so this skill
|
|
278
|
+
**writes no `> **Developer:**` line** either.
|
|
279
|
+
- **Anything else** — `push`, `none`, sync reported off, or the command failing
|
|
280
|
+
— is cannot-tell, and the steps below run exactly as written.
|
|
281
|
+
|
|
282
|
+
What `pull` leaves alone: the folder move (a bucket records what the repo did to
|
|
283
|
+
the code, not a planning status), the phase files and index, and the Changelog.
|
|
284
|
+
A reason a `Status:` header would have carried — a cancellation's, a knock-back
|
|
285
|
+
to Draft — goes in a dated Changelog line instead. A spec that already carries
|
|
286
|
+
any of these lines keeps them untouched: they are history, and nothing rewrites
|
|
287
|
+
them.
|
|
288
|
+
|
|
258
289
|
- Set the **Status** header: `> **Status:** In Progress — Phase 1 (started <YYYY-MM-DD>)`.
|
|
259
290
|
- Set **Developer** if it is still `—` (`git config user.name`).
|
|
260
291
|
|
|
@@ -270,6 +301,12 @@ carries a `jira_identifier`. Either missing → **skip**, in one line
|
|
|
270
301
|
(`not linked to Jira — /spec-push to mirror it`), and carry on. Nothing else in
|
|
271
302
|
this step changes.
|
|
272
303
|
|
|
304
|
+
**Ask the board first.** Run `skitterspec spec-sync board <spec>`. It is silent
|
|
305
|
+
unless Jira already says Done or Cancelled for this issue; when it prints a
|
|
306
|
+
line, relay it once as a warning and **carry on** — you are the one about to hold
|
|
307
|
+
this branch, so the cleanup it names is yours to choose, and nothing here runs it
|
|
308
|
+
or refuses on it.
|
|
309
|
+
|
|
273
310
|
**Refresh the mirror now, without asking.** Run `/spec-push`. The spec has just
|
|
274
311
|
moved to `in-progress/` — a real state change, and the tracker is a generated
|
|
275
312
|
mirror of it. (The developer stamped beside it stays a repo-side record:
|
|
@@ -340,7 +377,8 @@ destroyed: that skill relays the refusal and offers both ways out. Nothing to do
|
|
|
340
377
|
here beyond knowing it is no longer dead code.
|
|
341
378
|
|
|
342
379
|
A spec ideally arrives `Ready` from `/spec`; a `Draft` works too — sanity-check
|
|
343
|
-
it is well-formed first.
|
|
380
|
+
it is well-formed first. Where the spec keeps no `Status:` header (the tracker
|
|
381
|
+
owns its status), a non-empty **Open questions** section is what marks a Draft.
|
|
344
382
|
|
|
345
383
|
- **Report anything left waiting, and claim none of it.** Ask the engine once:
|
|
346
384
|
|
|
@@ -19,9 +19,12 @@ Read-only. Reports two things and writes nothing:
|
|
|
19
19
|
since the last push? The next push replaces it, so this is worth reading
|
|
20
20
|
first.
|
|
21
21
|
|
|
22
|
-
**Status is not compared
|
|
23
|
-
own transitions and
|
|
24
|
-
theirs to have moved, and push resends State only when the spec itself
|
|
22
|
+
**Status is not compared — with one exception.** Skitterspec tells Jira about
|
|
23
|
+
its own transitions and does not mirror a status back: a card someone moved by
|
|
24
|
+
hand is theirs to have moved, and push resends State only when the spec itself
|
|
25
|
+
changes bucket. The exception is the one difference the repo can act on — the
|
|
26
|
+
issue says Done or Cancelled while the spec is still in flight — which §3c
|
|
27
|
+
asks about, and reports without acting.
|
|
25
28
|
|
|
26
29
|
The repo is the source of truth; Jira is a generated mirror, so there is no
|
|
27
30
|
per-field "conflict" — only "what would the next push send" and "did someone
|
|
@@ -80,6 +83,18 @@ does not yet. Say so, name the two keys, and stop. Do not attempt the rewrite by
|
|
|
80
83
|
hand — the identifiers live in frontmatter, snapshot filenames and the keys
|
|
81
84
|
inside those snapshots, and a hand edit misses some.
|
|
82
85
|
|
|
86
|
+
## 3c. Has the board finished it?
|
|
87
|
+
|
|
88
|
+
```
|
|
89
|
+
skitterspec spec-sync board <spec>
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Silent unless Jira says Done or Cancelled while this spec is in `backlog` or
|
|
93
|
+
`in-progress`; then one line naming the cleanup (`/spec-complete` or
|
|
94
|
+
`/spec-cancel`). Relay that line as it is.
|
|
95
|
+
**Report it; never offer or run the cleanup** — this skill is read-only, and
|
|
96
|
+
the branch may be someone else's to close. Silence, an unlinked spec and an unreadable issue all say nothing.
|
|
97
|
+
|
|
83
98
|
## 4. Report
|
|
84
99
|
|
|
85
100
|
Relay the engine's output **verbatim, above the block** — it is the answer, and
|
|
@@ -47,6 +47,7 @@ In a project that installs the Jira superset the binary is
|
|
|
47
47
|
| "what shipped in this release?", "which tickets does CI mark deployed?" | `released` — `--json` for a script; recording deploys is the project's own |
|
|
48
48
|
| "is any of this wired up?", "why isn't sync working?" | `doctor` — scaffold, isolation, tracker and credentials in one |
|
|
49
49
|
| "set my Jira credentials", "am I authenticated?" | `credentials <status\|set\|unset>` |
|
|
50
|
+
| "did someone close this on the board?", "is Jira ahead of the repo?" | `board <spec>` — silent unless Jira says Done/Cancelled where the spec is not; relay its cleanup, never run it |
|
|
50
51
|
| push one spec, or "what would push?" | **defer** — see below |
|
|
51
52
|
|
|
52
53
|
The Linear provider's `retarget`, `reattach`, `stage`, `whoami`, `users`,
|