@skitterbyte/skitterspec-jira 2.15.0 → 2.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. package/MIGRATION.md +27 -0
  2. package/assets/claude-md-section.md +18 -9
  3. package/assets/commands/allow-main.md +1 -2
  4. package/assets/core/SETUP.md +12 -12
  5. package/assets/core/env.config.json.example +0 -1
  6. package/assets/core/env.config.md +28 -26
  7. package/assets/hooks/main-guard.cjs +73 -6
  8. package/assets/hooks/project-guard.cjs +80 -6
  9. package/assets/hooks/review-gate.cjs +73 -6
  10. package/assets/review/page.html +10 -83
  11. package/assets/rules/commit-trailers.md +2 -2
  12. package/assets/rules/spec-planning.md +26 -22
  13. package/assets/rules/spec-reports.md +52 -52
  14. package/assets/skills/no-spec/SKILL.md +2 -2
  15. package/assets/skills/spec/SKILL.md +22 -5
  16. package/assets/skills/spec-bug/SKILL.md +18 -15
  17. package/assets/skills/spec-complete/SKILL.md +23 -1
  18. package/assets/skills/spec-diff/SKILL.md +47 -115
  19. package/assets/skills/spec-hotfix/SKILL.md +18 -15
  20. package/assets/skills/spec-init/SKILL.md +4 -2
  21. package/assets/skills/spec-next/SKILL.md +66 -41
  22. package/assets/skills/spec-park/SKILL.md +92 -0
  23. package/assets/skills/spec-resume/SKILL.md +153 -0
  24. package/assets/skills/spec-review/SKILL.md +2 -2
  25. package/assets/skills/spec-reviewed/SKILL.md +1 -8
  26. package/assets/skills/spec-sync/SKILL.md +10 -10
  27. package/assets/skills/spec-todo/SKILL.md +5 -2
  28. package/package.json +1 -1
  29. package/src/cli.js +361 -208
  30. package/src/env/bootstrap.js +3 -1
  31. package/src/env/checks.js +49 -0
  32. package/src/env/config.js +27 -7
  33. package/src/env/hooks.js +53 -4
  34. package/src/env/live.js +48 -0
  35. package/src/env/provision.js +10 -2
  36. package/src/env/resume.js +234 -0
  37. package/src/env/review.js +71 -173
  38. package/src/env/serve.js +3 -7
  39. package/src/init.js +383 -50
  40. package/src/tada/todo.js +19 -4
  41. package/src/vendor/provider-kit/src/specs.js +46 -1
  42. package/src/vendor/sync-core/src/summary.js +10 -1
  43. package/assets/commands/spec-remote-review.md +0 -37
@@ -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.
@@ -286,9 +286,9 @@ reader:
286
286
 
287
287
  - **local** — &lt;the `local:` URL&gt;
288
288
  - **network** — &lt;the `network:` URL, or off with the command that turns it on&gt;
289
- - **remote** — &lt;the `remote:` URL, or off with the command that turns it on&gt;
289
+ - **remote** — &lt;the `remote:` tailnet URL, or what that line says when there is none&gt;
290
290
 
291
- I'm holding here until you send a verdict — the wait covers local and network.
291
+ I'm holding here until you send a verdict — the wait covers &lt;the tiers the engine's `covers` names&gt;.
292
292
 
293
293
  `Commit` commits the refresh · `Request changes` works them now
294
294
 
@@ -176,14 +176,7 @@ everything a decision needs, so there is nothing to go looking for, and going
176
176
  looking is the bypass step 0 forbids. The file is right there and readable; that
177
177
  is precisely why the rule is written down rather than assumed.
178
178
 
179
- **Check the store before concluding nothing is waiting.** Only when this spec
180
- has a published page (`--json` reports a `url`): a reader off the LAN sent their
181
- pass to the artifact's own `passes` collection rather than to the engine, so an
182
- empty holding area is not an empty answer yet. Read it with the Artifact tool's
183
- `read_db`, merge the `blob` through `--notes`, and **delete the document** —
184
- `/spec-diff` §6 owns the whole sequence, including that a claim consumes.
185
-
186
- **Nothing waiting in either is an ordinary answer.** Say so and stop. Do not hunt
179
+ **Nothing waiting is an ordinary answer.** Say so and stop. Do not hunt
187
180
  through other specs, and do not treat an empty holding area as a problem — a
188
181
  `file://` page copies to the clipboard instead of sending, so mention that the
189
182
  pass may be on their clipboard waiting to be pasted, and finish.
@@ -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 a binary that is a **local devDependency**, so it
24
- is never on `PATH`. Typing `spec-sync` gives `command not found`, which reads as
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
- pnpm exec skitterspec-jira spec-sync <subcommand> [args]
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
- pnpm exec skitterspec-jira spec-sync linked [--json]
79
- pnpm exec skitterspec-jira spec-sync states [--via api|mcp] [--json]
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
- pnpm exec skitterspec-jira spec-sync verify <spec> --stored <file>
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
- pnpm exec skitterspec-jira spec-sync stamp <spec> --issue PROJ-1 [--url URL] [--sub <ref>=PROJ-2 …]
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
- pnpm exec skitterspec-jira spec-sync apply --all <bucket> [--via api|mcp] [--json]
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
- pnpm exec skitterspec-jira spec-sync ref [--json]
163
- pnpm exec skitterspec-jira spec-sync released [<range>] [--json]
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
@@ -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, or a gate armed by a phase that ended
48
- and still owes an answer. Read only for specs in flight.
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.15.0",
3
+ "version": "2.17.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",