@skitterbyte/skitterspec-jira 2.14.0 → 2.16.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 +12 -0
- package/assets/core/SETUP.md +12 -12
- package/assets/core/env.config.md +25 -3
- package/assets/hooks/main-guard.cjs +73 -6
- package/assets/hooks/project-guard.cjs +80 -6
- package/assets/hooks/review-gate.cjs +73 -6
- package/assets/review/page.html +2 -1
- package/assets/rules/commit-trailers.md +2 -2
- package/assets/rules/offered-unblocks.md +22 -0
- package/assets/rules/spec-planning.md +12 -1
- package/assets/skills/no-spec/SKILL.md +5 -0
- package/assets/skills/spec/SKILL.md +20 -3
- package/assets/skills/spec-bug/SKILL.md +8 -2
- package/assets/skills/spec-complete/SKILL.md +28 -2
- package/assets/skills/spec-diff/SKILL.md +5 -0
- package/assets/skills/spec-hotfix/SKILL.md +8 -2
- package/assets/skills/spec-idea/SKILL.md +5 -0
- package/assets/skills/spec-init/SKILL.md +4 -2
- package/assets/skills/spec-next/SKILL.md +18 -0
- package/assets/skills/spec-park/SKILL.md +92 -0
- package/assets/skills/spec-resume/SKILL.md +153 -0
- package/assets/skills/spec-start/SKILL.md +6 -2
- package/assets/skills/spec-sync/SKILL.md +10 -10
- package/assets/skills/spec-to-main/SKILL.md +5 -1
- package/assets/skills/spec-todo/SKILL.md +5 -2
- package/package.json +1 -1
- package/src/cli.js +311 -15
- package/src/env/base.js +21 -5
- package/src/env/basepin.js +62 -0
- package/src/env/bootstrap.js +3 -1
- package/src/env/checks.js +49 -0
- package/src/env/config.js +48 -1
- package/src/env/hooks.js +53 -4
- package/src/env/provision.js +10 -2
- package/src/env/resolve.js +66 -13
- package/src/env/resume.js +234 -0
- package/src/env/review.js +4 -1
- package/src/env/serve.js +3 -0
- package/src/ideacmd.js +11 -1
- package/src/init.js +287 -49
- package/src/tada/todo.js +19 -4
- package/src/vendor/provider-kit/src/specs.js +46 -1
- package/src/vendor/sync-core/src/summary.js +10 -1
|
@@ -35,8 +35,14 @@ Then:
|
|
|
35
35
|
|
|
36
36
|
1. **Exclude what's already adopted.** Run `skitterspec spec-sync linked --json`
|
|
37
37
|
and drop any issue whose identifier is already stamped on a spec. If the user
|
|
38
|
-
named such an issue directly,
|
|
39
|
-
|
|
38
|
+
named such an issue directly, it already has a spec, and one issue never
|
|
39
|
+
becomes two specs. **Offer `/spec-resume <ref>`** instead, carrying the rest
|
|
40
|
+
of what they wrote as its message: feedback on shipped work, or "the deploy
|
|
41
|
+
is out", belongs to the spec that is already in flight. Confirm it, as kind
|
|
42
|
+
routing does (`.claude/rules/spec-planning.md`), and invoke it in-session on
|
|
43
|
+
a yes. On a no, stop and name the spec. That spec may exist only on its
|
|
44
|
+
branch, which `linked` reads too, so a missing `specs/` folder here is not
|
|
45
|
+
evidence that the issue is free.
|
|
40
46
|
2. **Read the issue** with the discovered issue-read tool (`getJiraIssue`):
|
|
41
47
|
title, description, labels, reporter, URL. If Jira isn't connected, say so
|
|
42
48
|
and offer to carry on without it — a spec written from the user's own
|
|
@@ -35,11 +35,32 @@ Before marking complete, confirm the work is actually finished:
|
|
|
35
35
|
- If genuinely incomplete work remains, **stop and tell the user** rather than
|
|
36
36
|
forcing completion. Offer to finish it (`/spec-next`) or to complete with the
|
|
37
37
|
remaining items explicitly listed as deferred.
|
|
38
|
+
- **Report any blocker still standing; never refuse over one.** Run
|
|
39
|
+
`skitterspec spec-env resume <spec> --json` and read `blockers`. Each
|
|
40
|
+
`> **Blocked on:**` line still in the spec goes in the report's `Notes`,
|
|
41
|
+
quoted with its `until` date where it has one. A spec can finish with a wait
|
|
42
|
+
still written down: the soak may have been dropped, or the deploy may have
|
|
43
|
+
happened without anyone saying so. The line staying in the completed spec is
|
|
44
|
+
the record of that, and nothing is gated on it. With none, say nothing.
|
|
38
45
|
- **Check for pre-existing uncommitted changes — before you touch anything.**
|
|
39
46
|
Run `git status`. Anything already uncommitted is the *user's* work (a
|
|
40
47
|
half-finished phase, a stray fix) and must not be swept into the completion
|
|
41
48
|
commit: offer `/commit` and **stop**. Everything this skill writes in steps 3–4
|
|
42
49
|
is its own, and step 4 commits that.
|
|
50
|
+
- **Run the project's completion checks**, once the suite is green:
|
|
51
|
+
|
|
52
|
+
```
|
|
53
|
+
skitterspec spec-env checks <spec>
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
It runs each `complete.checks` command from `env.config.json` in the spec's
|
|
57
|
+
worktree — the project's own end-of-spec questions, such as a docs report —
|
|
58
|
+
and always exits 0. Relay what each printed into `Notes`. A check marked
|
|
59
|
+
`failed` makes the run `⚠️`; it **never stops the completion or the land**,
|
|
60
|
+
because a check's output is a reason to look again, not proof of a fault.
|
|
61
|
+
Where a check names a fix you can make now (re-read a page, then record it),
|
|
62
|
+
offer it — the operator answers. `no completion checks configured` is the
|
|
63
|
+
usual answer and says nothing in the report.
|
|
43
64
|
|
|
44
65
|
|
|
45
66
|
### An epic — complete after its members
|
|
@@ -274,7 +295,8 @@ the shape; this section carries only what is specific here.
|
|
|
274
295
|
|
|
275
296
|
`Notes` carries the after-land commands step 6 ran, and where, and any it
|
|
276
297
|
skipped because the land matched no `when` — or, on a failure, the command that failed and the ones that did not run. A project with
|
|
277
|
-
no `afterLand` says nothing about it.
|
|
298
|
+
no `afterLand` says nothing about it. It also carries what each completion
|
|
299
|
+
check reported (§2) — a project with none says nothing about them either.
|
|
278
300
|
|
|
279
301
|
**Report this spec and no other.** A completion is the moment it is most
|
|
280
302
|
tempting to survey what is left — what else is in flight, what is in the
|
|
@@ -435,7 +457,11 @@ is finished — e.g. to run a later phase in CI or a shared test env? Use
|
|
|
435
457
|
relay it verbatim in the `Landed` row so the reader sees where the work went.
|
|
436
458
|
|
|
437
459
|
A refusal naming `no branch matches <pattern>` means no release candidate is
|
|
438
|
-
visible
|
|
460
|
+
visible. Where it carries an `offer:` line it is the gap between release
|
|
461
|
+
branches: relay it, then offer it as `.claude/rules/offered-unblocks.md`
|
|
462
|
+
describes — its label and Cancel — and on the pick run
|
|
463
|
+
`skitterspec spec-env base --use-fallback` and retry the land. With no offer
|
|
464
|
+
it is usually not fetched: relay it, stop with `⏸`, and name
|
|
439
465
|
`skitterspec spec-env base` (it fetches and lists) as the next step.
|
|
440
466
|
3. **Run the after-land commands.** Where the plan ends with a
|
|
441
467
|
`then, in the primary checkout (<path>), run:` section — the project's
|
|
@@ -470,6 +470,11 @@ skitterspec spec-env review <spec> --run-reviewers # …and run review.reviewe
|
|
|
470
470
|
skitterspec spec-env review serve # every spec, on localhost
|
|
471
471
|
```
|
|
472
472
|
|
|
473
|
+
A refusal naming `no branch matches <pattern>` that carries an `offer:` line
|
|
474
|
+
is the gap between release branches: relay it, then offer it as
|
|
475
|
+
`.claude/rules/offered-unblocks.md` describes — its label and Cancel — and on
|
|
476
|
+
the pick run `skitterspec spec-env base --use-fallback` and render again.
|
|
477
|
+
|
|
473
478
|
**`--run-reviewers` is opt-in here, and a BARE `/spec-diff` MUST NOT PASS IT.**
|
|
474
479
|
`/spec-next` runs the project's configured reviewers once per phase, where the
|
|
475
480
|
cost is paid against work that is finished. This skill answers at any point,
|
|
@@ -42,8 +42,14 @@ Then:
|
|
|
42
42
|
|
|
43
43
|
1. **Exclude what's already adopted.** Run `skitterspec spec-sync linked --json`
|
|
44
44
|
and drop any issue whose identifier is already stamped on a spec. If the user
|
|
45
|
-
named such an issue directly,
|
|
46
|
-
|
|
45
|
+
named such an issue directly, it already has a spec, and one issue never
|
|
46
|
+
becomes two specs. **Offer `/spec-resume <ref>`** instead, carrying the rest
|
|
47
|
+
of what they wrote as its message: feedback on shipped work, or "the deploy
|
|
48
|
+
is out", belongs to the spec that is already in flight. Confirm it, as kind
|
|
49
|
+
routing does (`.claude/rules/spec-planning.md`), and invoke it in-session on
|
|
50
|
+
a yes. On a no, stop and name the spec. That spec may exist only on its
|
|
51
|
+
branch, which `linked` reads too, so a missing `specs/` folder here is not
|
|
52
|
+
evidence that the issue is free.
|
|
47
53
|
2. **Read the issue** with the discovered issue-read tool (`getJiraIssue`):
|
|
48
54
|
title, description, labels, reporter, URL. If Jira isn't connected, say so
|
|
49
55
|
and offer to carry on without it — a spec written from the user's own
|
|
@@ -62,6 +62,11 @@ branch and that is always the operator's call.
|
|
|
62
62
|
**A refused capture loses nothing.** The engine prints the text back. Put it in
|
|
63
63
|
the `Why` row verbatim so the user can copy it.
|
|
64
64
|
|
|
65
|
+
A refusal naming `no branch matches <pattern>` that carries an `offer:` line
|
|
66
|
+
is the gap between release branches: relay it, then offer it as
|
|
67
|
+
`.claude/rules/offered-unblocks.md` describes — its label and Cancel — and on
|
|
68
|
+
the pick run `skitterspec spec-env base --use-fallback` and retry.
|
|
69
|
+
|
|
65
70
|
## 3. List
|
|
66
71
|
|
|
67
72
|
```
|
|
@@ -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 **twenty 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
36
|
`spec-reviewed` (pick up a review you approved on that page),
|
|
37
|
-
`spec-epic-next` (name the epic member that can start now),
|
|
37
|
+
`spec-epic-next` (name the epic member that can start now),
|
|
38
|
+
`spec-resume` (back into a spec in flight, by name or ticket),
|
|
39
|
+
`spec-park` (record what a spec in flight is waiting on), `spec-to-main`,
|
|
38
40
|
`spec-complete`, `spec-cancel`, `spec-tada` (a ta-da list of what got done),
|
|
39
41
|
`spec-todo` (where you left off, and what is ahead), `spec-idea` (an idea
|
|
40
42
|
parked without a spec),
|
|
@@ -215,6 +215,24 @@ once at the start, so each phase is asked as it is built.
|
|
|
215
215
|
not matter for this phase, and the bypass is that knowledge on the record. What
|
|
216
216
|
it rules out is the silent build.
|
|
217
217
|
|
|
218
|
+
**Then ask whether the spec is parked.** Run
|
|
219
|
+
`skitterspec spec-env resume <spec> --json` and read `blocking`. It is the
|
|
220
|
+
`> **Blocked on:**` line that holds this build: the spec's own line, or this
|
|
221
|
+
phase's. A line on a later phase is not this build's business, and the engine
|
|
222
|
+
leaves it out.
|
|
223
|
+
|
|
224
|
+
- **`blocking: null`**: carry on in silence. This is the usual case.
|
|
225
|
+
- **Anything else**: stop with the `⏸` block before marking anything started.
|
|
226
|
+
`Why` quotes the blocker, with its `until` date where it has one. `Next` is
|
|
227
|
+
`/spec-resume <spec> <what happened>`, which is the exit. It hears that the
|
|
228
|
+
condition is met, clears the line on the record, and builds.
|
|
229
|
+
|
|
230
|
+
**No bypass is offered here, and none is needed.** Unlike an epic wait, a
|
|
231
|
+
blocker is a condition only a person can judge (a deploy, another project's
|
|
232
|
+
release, a week in prod), so the person who knows it is met says so to
|
|
233
|
+
`/spec-resume`, and that clears it with a Changelog line. A build past one
|
|
234
|
+
without a word would be exactly the silent step this check exists to stop.
|
|
235
|
+
|
|
218
236
|
Mark it started: set the phase-file heading to `🔄` and its `> **Status:**` to
|
|
219
237
|
`In progress`, and flip the matching row in the overview phase index to `🔄`.
|
|
220
238
|
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec-park
|
|
3
|
+
description: Park a spec in flight on something outside the repo — a deploy, another project's release, a soak period — by recording a `Blocked on:` line on the spec or one of its phases, committed on its branch. The worktree stays. `/spec-resume` is how you come back. Use when the user says "/spec-park", "park this until…", "we're waiting on the deploy", "this is blocked on <thing>", or a phase cannot go on until something happens elsewhere.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /spec-park — record why a spec is waiting
|
|
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
|
+
A spec that stops for a reason outside the repo looks, from the outside, just
|
|
14
|
+
like one somebody abandoned. This skill writes the reason down where every
|
|
15
|
+
other skill reads it: `/spec-resume` shows it first, `/spec-next` stops before
|
|
16
|
+
building past it, and `/spec-todo` and the ticket both say *parked* rather than
|
|
17
|
+
*stalled*.
|
|
18
|
+
|
|
19
|
+
The argument is `"<reason>" [--until YYYY-MM-DD] [--phase N] [<spec>]`.
|
|
20
|
+
|
|
21
|
+
## 1. Find the spec
|
|
22
|
+
|
|
23
|
+
Ask the engine, with the spec named or, bare, the one you are standing in:
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
skitterspec spec-env resume [<spec>] --json
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
**Only an in-progress spec is parked.** On `ok: false`, relay `refused` and stop
|
|
30
|
+
with `⏸`. A backlog spec has not started, so there is nothing to wait in the
|
|
31
|
+
middle of. A spec with no worktree here is still parked, on its branch, after
|
|
32
|
+
`/spec-resume` has put it back on this machine. Say that in `Next` rather
|
|
33
|
+
than writing into a tree that is not there.
|
|
34
|
+
|
|
35
|
+
**A reason is required.** A bare `/spec-park` asks for one and writes nothing.
|
|
36
|
+
"Blocked" with no reason is the silence this exists to replace. The reason is
|
|
37
|
+
what the person coming back acts on.
|
|
38
|
+
|
|
39
|
+
## 2. Write the line
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
> **Blocked on:** <reason> (until <YYYY-MM-DD>)
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The `(until …)` is optional, and is the only part anything reads as data: past
|
|
46
|
+
that date `/spec-todo` says the wait has run out. Write a date only when one
|
|
47
|
+
was given. Never infer one from "a week".
|
|
48
|
+
|
|
49
|
+
- **No `--phase`:** the line goes in `00-overview.md`'s header block, after
|
|
50
|
+
the last `> **…:**` line. It holds every phase.
|
|
51
|
+
- **`--phase N`:** it goes in `0N-<slug>.md`'s header, under the
|
|
52
|
+
`> Spec: …` line. It holds that phase only. Earlier phases still build.
|
|
53
|
+
|
|
54
|
+
**A line already there is replaced, not doubled.** Say in `Notes` what it
|
|
55
|
+
said before. That is history worth keeping, so it also gets a dated Changelog
|
|
56
|
+
line: `- <date> — Parked: <reason>` (or `Re-parked: …, was <old>`).
|
|
57
|
+
|
|
58
|
+
## 3. Commit it on the spec's branch
|
|
59
|
+
|
|
60
|
+
Inside the spec's worktree. Use `skitterspec spec-env stage <spec>` for the
|
|
61
|
+
`owned` paths, and commit pathspec-bounded on both halves as
|
|
62
|
+
`docs(spec): park <spec> — <reason, short>`, with the `Refs:` trailer
|
|
63
|
+
(`spec-sync ref`) when there is a ticket.
|
|
64
|
+
|
|
65
|
+
**Only the spec's own documents.** Uncommitted work belonging to the phase in
|
|
66
|
+
progress is left exactly as it is, and reported in `Untouched`. Parking is not
|
|
67
|
+
a reason to commit half a phase.
|
|
68
|
+
|
|
69
|
+
**The worktree stays.** A wait is usually days, and `/spec-resume` rebuilds a
|
|
70
|
+
worktree only when one is actually missing.
|
|
71
|
+
|
|
72
|
+
**The ticket hears about it on the next push.** Where a provider is installed,
|
|
73
|
+
run `/spec-push` now: the summary block carries the blocker. It is never
|
|
74
|
+
fatal, and the board's Status is never set from here, because the tracker owns
|
|
75
|
+
status.
|
|
76
|
+
|
|
77
|
+
## Report
|
|
78
|
+
|
|
79
|
+
End with the block defined in `.claude/rules/spec-reports.md`.
|
|
80
|
+
|
|
81
|
+
**Verdicts**
|
|
82
|
+
|
|
83
|
+
- `✅`: the line is written and committed.
|
|
84
|
+
- `⏸`: refused (not in progress, no reason, no worktree here). Nothing
|
|
85
|
+
changed.
|
|
86
|
+
|
|
87
|
+
**Fields:** `Tracker` · `Spec` · `Built` · `Notes` · `Untouched` ·
|
|
88
|
+
`Follow-ups` · `Next`
|
|
89
|
+
|
|
90
|
+
`Built` quotes the line as written and where it went (spec, or phase N). `Next`
|
|
91
|
+
is `/spec-resume <spec> <what happened>` for whoever comes back, written the way
|
|
92
|
+
they would type it.
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec-resume
|
|
3
|
+
description: Go back into a spec that is already in flight, by its name or its ticket (#N), without starting anything. Rebuilds its worktree when this machine has none, moves the session there, shows what it is blocked on, then acts on the message given with it — feedback on shipped work, "the deploy is out", a question. Use when the user says "/spec-resume", "back to <spec>", "pick up #N again", or reports on a spec that is already in progress.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /spec-resume — back into a spec in flight
|
|
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
|
+
Some specs wait on things outside the repo: a deploy, another project's
|
|
14
|
+
release, a phase that has to run in prod for a week. This skill is how you come
|
|
15
|
+
back to one. **It is not a start.** It moves no bucket, assigns nobody, touches
|
|
16
|
+
no tracker status and builds nothing itself. `/spec-start` puts a spec in
|
|
17
|
+
flight, and `/spec-next` builds a phase. This skill puts you back where the
|
|
18
|
+
spec is, then does what the message asks.
|
|
19
|
+
|
|
20
|
+
The argument is `<name|#N> [message]`. The first word is the spec, and
|
|
21
|
+
everything after it, a leading `-` or `—` dropped, is the message.
|
|
22
|
+
|
|
23
|
+
## 1. Ask the engine
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
skitterspec spec-env resume <name|#N> --json
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
It reads every copy of the spec it can see: this checkout, each worktree, and
|
|
30
|
+
each spec branch, local then remote-tracking, never fetched. That matters
|
|
31
|
+
because the base branch reads `backlog` for the whole life of a spec, and under
|
|
32
|
+
`land.specDocs: "branch"` an in-flight spec may exist only on its branch.
|
|
33
|
+
|
|
34
|
+
- **`ok: false`.** Relay the `refused` text and stop with `⏸`. It covers a
|
|
35
|
+
name or ticket that matches nothing (it never guesses the nearest), a spec in
|
|
36
|
+
`backlog` (`Next` is `/spec-start <name>`), one already complete or
|
|
37
|
+
cancelled, and one with no branch anywhere to resume from.
|
|
38
|
+
- **`ok: true`.** Carry on. `blockers`, `progress` and `identifier` are read
|
|
39
|
+
in step 3.
|
|
40
|
+
|
|
41
|
+
## 2. Get into its worktree
|
|
42
|
+
|
|
43
|
+
**Only when the project has per-spec isolation** (`specs/.core/env.config.json`).
|
|
44
|
+
Without it there is no worktree, so you are already where the spec is. Skip to
|
|
45
|
+
step 3.
|
|
46
|
+
|
|
47
|
+
**Bring the review server up first, from the primary checkout**, exactly as
|
|
48
|
+
`/spec-start` §2b does: `skitterspec spec-env review serve --host 0.0.0.0`.
|
|
49
|
+
Say nothing when it is already up. If it can't start, say so in one line and
|
|
50
|
+
carry on.
|
|
51
|
+
|
|
52
|
+
**When `commands` is non-empty, this machine has no worktree for the spec.**
|
|
53
|
+
That is the expected path, not an edge case: a spec parked on another machine,
|
|
54
|
+
or pruned while it waited. Run the `commands` as printed, then the `then`
|
|
55
|
+
commands, with the `cd` in front, as `/spec-start` step 3 does:
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
cd "<worktree.path>" && skitterspec spec-env bootstrap <spec>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The commands attach the spec's own branch, local or tracked from the remote.
|
|
62
|
+
**Never add a `-b` of your own.** A fresh fork would hand back an empty tree with
|
|
63
|
+
the work out of reach, and the engine refused that case already.
|
|
64
|
+
|
|
65
|
+
**When `commands` is empty, the worktree is there.** `cd` into `worktree.path`
|
|
66
|
+
unless the session is already standing in it.
|
|
67
|
+
|
|
68
|
+
**Then confirm the move landed.** `skitterspec spec-env resolve` with no
|
|
69
|
+
argument must name this spec, the same positive signal `/spec-start` asks for.
|
|
70
|
+
If it names anything else, stop with `❌`, print the path, and write nothing.
|
|
71
|
+
|
|
72
|
+
## 3. Show where it stands
|
|
73
|
+
|
|
74
|
+
Before acting on the message, read the spec's `00-overview.md` and the phase
|
|
75
|
+
file for `progress.current` (else the first unfinished one). Then put any
|
|
76
|
+
`blockers` in front of the reader, one per line, with the `until` date where it
|
|
77
|
+
has one. A blocker is the most important thing a resumed spec can say: it is
|
|
78
|
+
why the spec stopped.
|
|
79
|
+
|
|
80
|
+
## 4. Act on the message
|
|
81
|
+
|
|
82
|
+
**No message: report and stop.** `Next` is `/spec-next` (or the blocker, if
|
|
83
|
+
one stands in its way).
|
|
84
|
+
|
|
85
|
+
**With a message, read it against the spec and decide what it is asking.**
|
|
86
|
+
This is judgment, not a template. A message is usually one of these, and can
|
|
87
|
+
be several:
|
|
88
|
+
|
|
89
|
+
- **A blocker's condition is met.** For example: "LSC is released", "it has
|
|
90
|
+
been live a week". Where the message plainly says so, remove that
|
|
91
|
+
`> **Blocked on:**` line and add a dated Changelog line naming what cleared
|
|
92
|
+
it. Where you cannot tell whether it is met, **ask once**: "this was blocked
|
|
93
|
+
on `<text>`, is that done?". Never clear a blocker in silence.
|
|
94
|
+
- **A question about the spec.** For example: "now LSC is out, what do we need
|
|
95
|
+
to test?". Answer it from the spec's own phases, tasks and Decisions, and
|
|
96
|
+
quote the tasks rather than paraphrasing them. Write nothing.
|
|
97
|
+
- **Feedback on the work this spec shipped.** For example: "the toast says why,
|
|
98
|
+
but the record stays on screen and delete does nothing". Turn it into tasks:
|
|
99
|
+
add them to the current `🔄` phase, or, when every phase is `✅`, to a new
|
|
100
|
+
phase file plus an index row (`/spec-next` §4's rule for new work). Add a
|
|
101
|
+
dated Changelog line quoting the report.
|
|
102
|
+
- **Work outside this spec.** For example: a different feature, or a defect in
|
|
103
|
+
code the spec never touched. Propose the right door with a one-line reason,
|
|
104
|
+
confirm first, as `.claude/rules/spec-planning.md`'s kind routing does. A
|
|
105
|
+
defect goes to `/spec-bug`; new behaviour goes to `/spec`. On a no, carry
|
|
106
|
+
on with whatever part of the message was this spec's.
|
|
107
|
+
|
|
108
|
+
**Commit what you wrote to the spec before building anything.** Use
|
|
109
|
+
`skitterspec spec-env stage <spec>` and its `owned` paths, pathspec-bounded on
|
|
110
|
+
both the `add` and the `commit`, as `docs(spec): resume <spec> — <what changed>`
|
|
111
|
+
with the `Refs:` trailer when there is a ticket. `/spec-next` §2 refuses to
|
|
112
|
+
build on an uncommitted tree, and these edits are the spec's own documents, not
|
|
113
|
+
a phase's work.
|
|
114
|
+
|
|
115
|
+
**Then build, if the message asked for work.** Hand off to a bare
|
|
116
|
+
**`/spec-next`**: it resolves this spec from the worktree you are standing in,
|
|
117
|
+
honours the review gate, builds the first unfinished phase (which now holds the
|
|
118
|
+
new tasks), and ends on its own review page. That is the only way this skill
|
|
119
|
+
writes code. A gate that `/spec-next` refuses on is relayed as it says. It is
|
|
120
|
+
never stepped past.
|
|
121
|
+
|
|
122
|
+
**Where the message cleared a blocker and asked for nothing more**, do not
|
|
123
|
+
build on that alone. Offer it instead: "build phase N now?", recommending yes,
|
|
124
|
+
the same question `/spec-start` step 6 asks. A blocker clearing is a reason the
|
|
125
|
+
work can go on, not an instruction to do it now.
|
|
126
|
+
|
|
127
|
+
## 5. Report
|
|
128
|
+
|
|
129
|
+
**When step 4 handed off to `/spec-next`, emit no block here.** That skill
|
|
130
|
+
ends with its own block, and two blocks for one run is the noise the contract
|
|
131
|
+
exists to remove.
|
|
132
|
+
|
|
133
|
+
Otherwise, end with the block defined in `.claude/rules/spec-reports.md`.
|
|
134
|
+
|
|
135
|
+
**Verdicts**
|
|
136
|
+
|
|
137
|
+
- `✅`: the session is standing in the spec's worktree and the message, if
|
|
138
|
+
any, was answered.
|
|
139
|
+
- `⚠️`: resumed, with something worth knowing. For example, a blocker still
|
|
140
|
+
stands, or bootstrap failed a step that does not stop the reading.
|
|
141
|
+
- `❌`: provisioning or the move failed part-way. Name what was left and
|
|
142
|
+
where.
|
|
143
|
+
- `⏸`: the engine refused. Nothing was provisioned and nothing moved.
|
|
144
|
+
|
|
145
|
+
**Fields:** `Tracker` · `Spec` · `Built` · `Notes` · `Worktree` ·
|
|
146
|
+
`Follow-ups` · `Next`
|
|
147
|
+
|
|
148
|
+
`Spec` is the bucket and progress (`2 of 4 done, phase 3 in progress`).
|
|
149
|
+
`Worktree` is the path, and says **entered** or **provisioned**. `Built` lists
|
|
150
|
+
what the message added to the spec (tasks, a cleared blocker), and is absent
|
|
151
|
+
when nothing was written. `Notes` carries any blocker still standing, quoted.
|
|
152
|
+
`Next` is `/spec-next` when the spec is ready to build, or the blocker when one
|
|
153
|
+
stands in the way.
|
|
@@ -156,8 +156,12 @@ render says so. On **`--plan`** this step does not run at all.
|
|
|
156
156
|
the primary checkout is not on the newest release candidate the plan says
|
|
157
157
|
`fork: <base> (the base — the primary checkout is on <old>)` and forks from
|
|
158
158
|
it. Relay that line in the `Branch` row. A refusal naming
|
|
159
|
-
`no branch matches <pattern>` means no release candidate is visible
|
|
160
|
-
|
|
159
|
+
`no branch matches <pattern>` means no release candidate is visible. Where
|
|
160
|
+
it carries an `offer:` line it is the gap between release branches: relay
|
|
161
|
+
it, then offer it as `.claude/rules/offered-unblocks.md` describes — its
|
|
162
|
+
label and Cancel — and on the pick run
|
|
163
|
+
`skitterspec spec-env base --use-fallback` and re-run `up`. With no offer it
|
|
164
|
+
is usually not fetched: relay it, stop with `⏸`, and name
|
|
161
165
|
`skitterspec spec-env base` (it fetches and lists) as the next step.
|
|
162
166
|
|
|
163
167
|
2. **Trust the worktree.** `spec-env up` wrote the printed `trusted:` root into
|
|
@@ -20,13 +20,13 @@ tell the user how to enable Jira sync and stop.
|
|
|
20
20
|
|
|
21
21
|
## The invocation — always state it
|
|
22
22
|
|
|
23
|
-
`spec-sync` is a subcommand of
|
|
24
|
-
is never on `PATH
|
|
23
|
+
`spec-sync` is a subcommand of the provider binary, not a program of its own,
|
|
24
|
+
so it is never on `PATH` by itself. Typing `spec-sync` gives `command not found`, which reads as
|
|
25
25
|
a broken install rather than a wrong invocation. Always run it — and always show
|
|
26
26
|
the user you ran it — in full:
|
|
27
27
|
|
|
28
28
|
```
|
|
29
|
-
|
|
29
|
+
{{exec}} skitterspec-jira spec-sync <subcommand> [args]
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
In a project that installs the Jira superset the binary is
|
|
@@ -75,8 +75,8 @@ Say which skill you're handing to and stop; don't reimplement either.
|
|
|
75
75
|
## 3. The read-only subcommands
|
|
76
76
|
|
|
77
77
|
```
|
|
78
|
-
|
|
79
|
-
|
|
78
|
+
{{exec}} skitterspec-jira spec-sync linked [--json]
|
|
79
|
+
{{exec}} skitterspec-jira spec-sync states [--via api|mcp] [--json]
|
|
80
80
|
```
|
|
81
81
|
|
|
82
82
|
- **`linked`** is offline: which specs carry a `jira_identifier`, their bucket,
|
|
@@ -99,7 +99,7 @@ pnpm exec skitterspec-jira spec-sync states [--via api|mcp] [--json]
|
|
|
99
99
|
## 4. `verify` — check what the tracker actually stored
|
|
100
100
|
|
|
101
101
|
```
|
|
102
|
-
|
|
102
|
+
{{exec}} skitterspec-jira spec-sync verify <spec> --stored <file>
|
|
103
103
|
```
|
|
104
104
|
|
|
105
105
|
`--stored` is **what Jira currently holds**, read back over MCP:
|
|
@@ -120,7 +120,7 @@ markdown at the boundary, so the comparison is words, not bytes.
|
|
|
120
120
|
## 5. `stamp` — the manual escape hatch
|
|
121
121
|
|
|
122
122
|
```
|
|
123
|
-
|
|
123
|
+
{{exec}} skitterspec-jira spec-sync stamp <spec> --issue PROJ-1 [--url URL] [--sub <ref>=PROJ-2 …]
|
|
124
124
|
```
|
|
125
125
|
|
|
126
126
|
Writes the keys into the spec's frontmatter without touching Jira. For adopting
|
|
@@ -131,7 +131,7 @@ mint a duplicate, so read the values back to the user before writing.
|
|
|
131
131
|
## 6. `apply --all <bucket>` — bulk, and the one with real blast radius
|
|
132
132
|
|
|
133
133
|
```
|
|
134
|
-
|
|
134
|
+
{{exec}} skitterspec-jira spec-sync apply --all <bucket> [--via api|mcp] [--json]
|
|
135
135
|
```
|
|
136
136
|
|
|
137
137
|
**Confirm before running, and state creates and updates separately.** They are
|
|
@@ -159,8 +159,8 @@ its object exists, so an interrupted run continues rather than duplicating.
|
|
|
159
159
|
## 7. `ref` and `released` — tickets in commits
|
|
160
160
|
|
|
161
161
|
```
|
|
162
|
-
|
|
163
|
-
|
|
162
|
+
{{exec}} skitterspec-jira spec-sync ref [--json]
|
|
163
|
+
{{exec}} skitterspec-jira spec-sync released [<range>] [--json]
|
|
164
164
|
```
|
|
165
165
|
|
|
166
166
|
`ref` prints the ticket for the branch you are on, so a commit can carry
|
|
@@ -112,7 +112,11 @@ can carry two more things, and both are the engine's to say:
|
|
|
112
112
|
relay it verbatim in the `Landed` row so the reader sees where the work went.
|
|
113
113
|
|
|
114
114
|
A refusal naming `no branch matches <pattern>` means no release candidate is
|
|
115
|
-
visible
|
|
115
|
+
visible. Where it carries an `offer:` line it is the gap between release
|
|
116
|
+
branches: relay it, then offer it as `.claude/rules/offered-unblocks.md`
|
|
117
|
+
describes — its label and Cancel — and on the pick run
|
|
118
|
+
`skitterspec spec-env base --use-fallback` and retry the land. With no offer it
|
|
119
|
+
is usually not fetched: relay it, stop with `⏸`, and name
|
|
116
120
|
`skitterspec spec-env base` (it fetches and lists) as the next step.
|
|
117
121
|
|
|
118
122
|
**Then run the after-land commands.** Where the plan ends with a
|
|
@@ -44,8 +44,11 @@ What the lines mean:
|
|
|
44
44
|
stopped.
|
|
45
45
|
- `in flight:` — where the spec stands now, and its next action.
|
|
46
46
|
- `finished:` — the specs that day completed or cancelled, by name.
|
|
47
|
-
- `blocked:` — a review verdict waiting,
|
|
48
|
-
and still owes an answer
|
|
47
|
+
- `blocked:` — a review verdict waiting, a gate armed by a phase that ended
|
|
48
|
+
and still owes an answer, or a spec **parked** on something outside the repo
|
|
49
|
+
(its `Blocked on:` line, naming `/spec-resume`). A parked spec whose
|
|
50
|
+
`until` date has arrived says *ready to resume*. Read only for specs in
|
|
51
|
+
flight.
|
|
49
52
|
- `ideas:` — how many ideas are waiting for the `(here)` project. It is a count,
|
|
50
53
|
never the next action: `/spec-idea` lists them, and the line is absent when
|
|
51
54
|
there are none or the count could not be read.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skitterbyte/skitterspec-jira",
|
|
3
|
-
"version": "2.
|
|
3
|
+
"version": "2.16.0",
|
|
4
4
|
"description": "Spec-driven development for Claude Code, with one-way Jira Cloud sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Jira is a generated mirror. Install this OR the base OR the Linear superset — exactly one.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|