@skitterbyte/skitterspec-jira 1.2.2 → 2.1.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/MIGRATION.md CHANGED
@@ -1,5 +1,133 @@
1
1
  # Migration guide
2
2
 
3
+ ## The `chore` spec kind, and per-type bodies (additive — nothing breaks)
4
+
5
+ Specs can now be **chores** (`chore-` prefix, `> **Type:** Chore`) and every
6
+ provider can map spec kinds to its own idiom. Configs without a mapping keep
7
+ working unchanged: an unmapped kind mints the provider's default type exactly
8
+ as before, and `System.Description` stays Azure's body field unless a type is
9
+ mapped away from it. `skitterspec update` ships the new skills and rules.
10
+
11
+ **Create tracker types and states before mapping them.** A mapping names
12
+ something the tracker must already have:
13
+
14
+ - **Azure Boards** — create the custom inherited type (e.g. `Chore`) and its
15
+ states in your process, then set
16
+ `azure.workItemTypeByKind: { "chore": "Chore" }`. To fill a Bug form's Repro
17
+ Steps instead of the hidden Description, set
18
+ `azure.bodyFieldByType: { "Bug": "Microsoft.VSTS.TCM.ReproSteps" }` — it
19
+ applies symmetrically to create, update, read-back and the edited-hash
20
+ compare, so `/spec-status` stays quiet after a push. Bugs minted before the
21
+ mapping keep reading their Description until the next push rewrites them.
22
+ `spec-sync doctor --check-remote` verifies every mapped type exists and
23
+ carries its body field.
24
+ - **GitHub** — `github.labelsByKind: { "chore": "chore" }` adds the kind's
25
+ label beside the spec marker.
26
+ - **Jira** — `jira.issueTypeByKind: { "bug": "Bug", "chore": "Task" }` picks
27
+ the mint type per kind; the type must exist in the project.
28
+ - **Linear** — `linear.labelsByKind: { "chore": "Chore" }` labels the mint;
29
+ the label must already exist on the team (a missing one is a one-line note,
30
+ never a failed push).
31
+
32
+ ## `@skitterbyte/skitterspec-github` v1 → v2 (tell, don't track)
33
+
34
+ Skitterspec now tells GitHub about **its own** transitions and nothing
35
+ else. It writes nothing about releases or deployments, and it never reads a
36
+ ticket's state back.
37
+
38
+ ### Breaking change 1 — The `release create|deployed|complete|reconcile` verbs are removed
39
+
40
+ They exit 1 with one line naming `spec-sync released <range> --json`. A pipeline
41
+ still calling them goes red rather than silently believing it mirrors
42
+ anything. **To migrate**, replace the step with your own script over the
43
+ release's ticket list:
44
+
45
+ ```sh
46
+ skitterspec-github spec-sync released "<previous-tag>..<tag>" --json
47
+ ```
48
+
49
+ Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
50
+ linked), so the script needs no second lookup. Set whatever GitHub field,
51
+ state or release object your process uses from that list. The checkout needs
52
+ `fetch-depth: 0` so the previous tag is visible.
53
+
54
+ ### Breaking change 2 — The `releases` block (`deployedField`, `series`) and `release.stages` are retired
55
+
56
+ The keys are ignored, like any unknown key, so a config carrying them still
57
+ loads. `spec-sync doctor` names them as unused config (a `warn`, never a
58
+ failure). Delete them when you remove the CI step.
59
+
60
+ ### Breaking change 3 — no state drift
61
+
62
+ `spec-sync status --remote` and `/spec-status` no longer compare the tracker's
63
+ state with the spec's. A ticket someone moved on GitHub is not reported, and
64
+ push still resends state only when the spec itself moves. The edited-description
65
+ warning is unchanged.
66
+
67
+ ## `@skitterbyte/skitterspec-azure-boards` v1 → v2 (tell, don't track)
68
+
69
+ Skitterspec now tells Azure Boards about **its own** transitions and nothing
70
+ else. It writes nothing about releases or deployments, and it never reads a
71
+ ticket's state back.
72
+
73
+ ### Breaking change 1 — The `release create|deployed|complete` verbs are removed
74
+
75
+ They exit 1 with one line naming `spec-sync released <range> --json`. A pipeline
76
+ still calling them goes red rather than silently believing it mirrors
77
+ anything. **To migrate**, replace the step with your own script over the
78
+ release's ticket list:
79
+
80
+ ```sh
81
+ skitterspec-azure-boards spec-sync released "<previous-tag>..<tag>" --json
82
+ ```
83
+
84
+ Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
85
+ linked), so the script needs no second lookup. Set whatever Azure Boards field,
86
+ state or release object your process uses from that list. The checkout needs
87
+ `fetch-depth: 0` so the previous tag is visible.
88
+
89
+ ### Breaking change 2 — The `releases` block (`workItemType`, `series`, `ticketTag`, `deployedField`) and `release.stages` are retired
90
+
91
+ The keys are ignored, like any unknown key, so a config carrying them still
92
+ loads. `spec-sync doctor` names them as unused config (a `warn`, never a
93
+ failure). Delete them when you remove the CI step.
94
+
95
+ ### Breaking change 3 — no state drift
96
+
97
+ `spec-sync status --remote` and `/spec-status` no longer compare the tracker's
98
+ state with the spec's. A ticket someone moved on Azure Boards is not reported, and
99
+ push still resends state only when the spec itself moves. The edited-description
100
+ warning is unchanged.
101
+
102
+ ## `@skitterbyte/skitterspec-jira` v1 → v2 (tell, don't track)
103
+
104
+ Skitterspec now tells Jira about **its own** transitions and nothing else. It
105
+ writes nothing about releases or deployments, and it never reads an issue's
106
+ status back.
107
+
108
+ ### Breaking change 1 — no status drift
109
+
110
+ `spec-sync status --remote` and `/spec-status` no longer compare Jira's status
111
+ with the spec's. An issue someone moved on Jira is not reported, and push still
112
+ transitions it only when the spec itself moves. The edited-description warning
113
+ is unchanged.
114
+
115
+ ### Breaking change 2 — `release.stages` retired
116
+
117
+ It was accepted and validated before, and never acted on. It is now ignored
118
+ like any unknown key, and `spec-sync doctor` names it as unused config (a
119
+ `warn`, never a failure). Delete it.
120
+
121
+ ### Also — `released --json` names the spec
122
+
123
+ Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
124
+ linked), so CI can record a release, for example as a fix version, without a
125
+ second lookup:
126
+
127
+ ```sh
128
+ skitterspec-jira spec-sync released "<previous-tag>..<tag>" --json
129
+ ```
130
+
3
131
  ## `@skitterbyte/skitterspec` v23 → v24 (hotfix land runs the release itself)
4
132
 
5
133
  ### Breaking change 1 — `spec-env hotfix land` runs its steps, and holds before the carry
@@ -275,7 +403,48 @@ can run it.
275
403
  committed file, so it changes for everyone who pulls and leaves that tree dirty.
276
404
  The engine says so when it does.
277
405
 
278
- ## `@skitterbyte/skitterspec-linear` v18 → v19 (hotfix land runs the release itself)
406
+ ## `@skitterbyte/skitterspec-linear` v18 → v19 (tell, don't track; hotfix land runs the release itself)
407
+
408
+ Skitterspec now tells Linear about **its own** transitions and nothing
409
+ else. It writes nothing about releases or deployments, and it never reads a
410
+ ticket's state back.
411
+
412
+ ### Breaking change 1 — The `spec-sync stage` verb is removed
413
+
414
+ It exits 1 with one line naming `spec-sync released <range> --json`. A pipeline
415
+ still calling it goes red rather than silently believing it mirrors
416
+ anything. **To migrate**, replace the step with your own script over the
417
+ release's ticket list:
418
+
419
+ ```sh
420
+ skitterspec-linear spec-sync released "<previous-tag>..<tag>" --json
421
+ ```
422
+
423
+ Each ticket row now carries `spec` and `url` (both `null` for a ref no spec has
424
+ linked), so the script needs no second lookup. Set whatever Linear field,
425
+ state or release object your process uses from that list. The checkout needs
426
+ `fetch-depth: 0` so the previous tag is visible.
427
+
428
+ ### Breaking change 2 — `release.stages` (the deployment ladder) is retired
429
+
430
+ The keys are ignored, like any unknown key, so a config carrying them still
431
+ loads. `spec-sync doctor` names them as unused config (a `warn`, never a
432
+ failure). Delete them when you remove the CI step.
433
+
434
+ ### Breaking change 3 — no state drift
435
+
436
+ `spec-sync status --remote` and `/spec-status` no longer compare the tracker's
437
+ state with the spec's. A ticket someone moved on Linear is not reported, and
438
+ push still resends state only when the spec itself moves. The edited-description
439
+ warning is unchanged.
440
+
441
+ **A ladder rung no longer reads as `complete`.** Where a state was a
442
+ `release.stages` rung, the live `spec-sync list` now shows it as unmapped. To
443
+ keep it reading as finished, list it as an alias:
444
+ `"complete": ["Done", "On Test"]`. `init-config --stage` is gone too, and is
445
+ refused as an unknown flag.
446
+
447
+ ### Also — hotfix land runs the release itself
279
448
 
280
449
  The same change as `@skitterbyte/skitterspec` v23 → v24 above — this
281
450
  distribution composes the same engine. Read that entry; nothing here is
package/README.md CHANGED
@@ -37,7 +37,9 @@ skitterspec-jira spec-sync credentials set
37
37
  every layer.
38
38
 
39
39
  Not yet shipped for Jira (the Linear superset has them): assignment/`/spec-claim`,
40
- the release-stage ladder, `retarget`, `reattach`, `spec-sanitise`.
40
+ `retarget`, `reattach`, `spec-sanitise`. Releases and deploys are the host
41
+ project's to record on every provider: `spec-sync released <range> --json`
42
+ lists a range's tickets for its CI to act on.
41
43
 
42
44
  This package's `bin/`, `src/` and `assets/` are composed at build time from the
43
45
  skitterspec monorepo — see the repo for sources and development.
@@ -114,7 +114,7 @@ every configured status exists in the project's workflows.
114
114
  `/spec-push <spec>` computes the plan, applies it, stamps the returned keys
115
115
  into the spec's frontmatter (`jira_identifier` / `jira_url` /
116
116
  `jira_issue_id`), verifies the round-trip by words, and records the snapshot
117
- later drift is measured against. From then on the lifecycle skills keep the
117
+ later pushes diff against. From then on the lifecycle skills keep the
118
118
  mirror fresh on their own.
119
119
 
120
120
  ---
@@ -580,7 +580,7 @@ through to a documented conservative default; see the field notes below.
580
580
  - `{repo}` — primary checkout dir basename (e.g. `skitterspec`).
581
581
  - `{repoSlug}` — `{repo}` lower-cased, non-alphanumerics collapsed to `-`
582
582
  (safe for a `COMPOSE_PROJECT_NAME`).
583
- - `{slug}` — the spec slug (folder name minus its `feat-`/`bug-` prefix).
583
+ - `{slug}` — the spec slug (folder name minus its `feat-`/`bug-`/`hotfix-`/`chore-` prefix).
584
584
 
585
585
  ## Pruning orphaned test-DB volumes
586
586
 
@@ -3,6 +3,7 @@
3
3
  "siteUrl": "https://your-site.atlassian.net",
4
4
  "projectKey": "PROJ",
5
5
  "issueType": "Task",
6
+ "issueTypeByKind": {},
6
7
  "subtaskType": "Subtask"
7
8
  },
8
9
  "states": {
@@ -9,6 +9,7 @@ NAMES — never a credential. Credentials live in the user-level store
9
9
  | `jira.siteUrl` | The Jira Cloud site (`https://<site>.atlassian.net`). Also keys the credentials-store entry. | `""` |
10
10
  | `jira.projectKey` | Where spec issues land — the identifier prefix (`PROJ-123`). Jira's project is the analogue of Linear's team; placement is decided here, once. | `""` |
11
11
  | `jira.issueType` | The issue type a spec mints as. | `"Task"` |
12
+ | `jira.issueTypeByKind` | The mint type per spec kind (`feature`/`bug`/`hotfix`/`chore`, from the folder prefix), falling back to `jira.issueType` — `{ "bug": "Bug" }` files bug specs as Jira Bugs. The type must exist in the project before mapping it. | `{}` |
12
13
  | `jira.subtaskType` | The type a phase mints as (must be a subtask type). | `"Subtask"` |
13
14
  | `mapping.specFolder` / `mapping.phases` / `mapping.tasks` | Spec → issue, phase → subtask, tasks → ADF checklist. Same modes as the Linear provider (`subissue` \| `deferred` \| `inline`; `checklist` \| `none`). | `issue` / `subissue` / `checklist` |
14
15
  | `states.<bucket>` | The Jira STATUS name for each lifecycle bucket. Must match the project's workflow statuses exactly; moves are applied by workflow transition, and an unreachable status refuses loudly. `cancelled` defaults to `Done` because default Jira workflows carry no Cancelled status. Pick work statuses, not pipeline stages — see **Choosing your status map** below. | see example |
@@ -16,7 +17,7 @@ NAMES — never a credential. Credentials live in the user-level store
16
17
  | `apply.transport` | `api` \| `mcp`, or empty for "api when credentials resolve, mcp when they don't". | `""` |
17
18
  | `sync.baseDir` | Where last-pushed snapshots live. | `specs/.core/jira-base` |
18
19
  | `sync.fieldOwnership` | Which projection fields push (`description`, `subIssues`, `workflowState`, `assignee`; `"none"` declines one). | all `push` |
19
- | `release.stages` / `release.ignorePaths` | The deployment ladder and bookkeeping path prefixes, exactly as the Linear provider defines them. | `[]` / `specs/`, changelogs |
20
+ | `release.ignorePaths` | Bookkeeping path prefixes `released` ignores, exactly as the Linear provider defines them. | `specs/`, changelogs |
20
21
 
21
22
  Descriptions are stored as ADF (Atlassian Document Format): the adapter
22
23
  renders markdown to ADF on push and reduces ADF back to text on read-back, so
@@ -24,6 +25,31 @@ verification compares words, not bytes. Phase checklists render as live ADF
24
25
  task lists — still a read-only mirror: a box ticked in Jira is overwritten on
25
26
  the next push.
26
27
 
28
+ ## More than one name per bucket — read-only aliases
29
+
30
+ A board usually has more states than the four buckets: "Blocked", "Next
31
+ Sprint", "Released". A bucket's value may be an **array** instead of a string:
32
+
33
+ ```jsonc
34
+ "states": {
35
+ "in-progress": ["Active", "Blocked"],
36
+ "complete": ["Closed", "Released"]
37
+ }
38
+ ```
39
+
40
+ - **The first name is the only one push writes**, and only when the spec
41
+ itself moves. The rest are never written.
42
+ - **The rest are read as that bucket** wherever a listing interprets a status.
43
+ The array is parsed and validated like every other provider's, so one config
44
+ shape works across all of them. `spec-sync status` never reads a ticket's
45
+ status at all: skitterspec tells Jira about its own transitions and nothing
46
+ else.
47
+ - **Nothing is pulled.** An alias changes what the report *says* about a
48
+ ticket, never the spec.
49
+ - A plain string works exactly as before. An alias that also names another
50
+ bucket is refused at load. An alias the tracker lacks is reported by
51
+ `spec-sync states` but never blocks a push, because it is never written.
52
+
27
53
  ## Choosing your status map
28
54
 
29
55
  Map the four buckets to **work** statuses, never to deployment stages. The
@@ -44,8 +70,9 @@ the map honest:
44
70
  type keeps the pipeline — subtasks genuinely have no delivery lifecycle, and
45
71
  Jira lets you say so structurally.
46
72
  - **Track "which release contains this" with fix versions** — the Releases
47
- hub, the analogue of what `spec-sync released` computes from `Refs:`
48
- trailers. (Available on every plan; in the current "Spaces" UI it is not a
73
+ hub. Your CI can fill it from `spec-sync released "<prev>..<tag>" --json`,
74
+ which lists the tickets a range contains from their `Refs:` trailers, each
75
+ with its spec and url. (Available on every plan; in the current "Spaces" UI it is not a
49
76
  Features toggle but a **tab** — add it with `+` in the space's tab bar.)
50
77
  - **Let CI/CD integrations stamp environment position** (the deployments
51
78
  panel), so it never needs to be a status at all.
@@ -56,6 +83,7 @@ status's board category, the closest match when one is missing, and the
56
83
  one-line remap. Run it whenever the wiring feels uncertain; it changes
57
84
  nothing.
58
85
 
59
- Walking the parent through pipeline stages at *release* time is the
60
- `release.stages` ladder — deferred in this provider's v1 — not a job for the
61
- lifecycle skills.
86
+ Walking the parent through pipeline stages at *release* time is the host
87
+ project's job, not skitterspec's: it writes nothing about releases or
88
+ deployments on any provider. A leftover `release.stages` is flagged by
89
+ `spec-sync doctor` as unused config.
@@ -7,7 +7,7 @@ and lifecycle stay consistent. Each sets a status on the spec header
7
7
 
8
8
  | Skill | Purpose | Status | Folder |
9
9
  |-------|---------|--------|--------|
10
- | `/spec` | (Feature) Grill to a clear shared understanding, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch, by a fast-forward) |
10
+ | `/spec` | (Feature/Chore) Grill to a clear shared understanding, propose the kind, write a groomed spec in its own worktree, then land it on the verdict | `Ready` (or `Draft`) | `specs/backlog/` (on the base branch, by a fast-forward) |
11
11
  | `/spec-bug` | (Bug) Reproduce with a failing test, capture spec, drive red→green | `In Progress` | `specs/in-progress/` |
12
12
  | `/spec-hotfix` | (Hotfix) Fork a worktree from a release tag, red→green, land by tag + cherry-pick | `In Progress` | `specs/in-progress/` |
13
13
  | `/no-spec` | Work that genuinely has no spec — its own branch, worktree, page and land. Writes no spec and moves nothing through the lifecycle | `—` | (none) |
@@ -492,9 +492,19 @@ missing alias.
492
492
  Sync is **one-way**: the repo is the source of truth and the tracker is a
493
493
  **generated mirror**. It ships `/spec-push` (repo→tracker; computes a create/update plan
494
494
  against a committed last-pushed snapshot and applies it) and `/spec-status`
495
- (read-only drift report — what would push, and whether the tracker's
496
- workflow-state drifted), backed by a `spec-sync` CLI. There is no content pull —
497
- the tracker is never read back or merged.
495
+ (read-only — what would push, and whether someone edited a description there),
496
+ backed by a `spec-sync` CLI. There is no content pull — the tracker is never
497
+ read back or merged.
498
+
499
+ **It tells, it doesn't track.** Skitterspec sends the tracker its own
500
+ transitions — a spec starting, a phase finishing, a spec completing or being
501
+ cancelled — and nothing else. A status someone changes on the tracker is
502
+ theirs to have changed: it is never read back, never reported, and only
503
+ overwritten when the spec itself next moves. Releases and deployments are the
504
+ host project's to record. The one release question skitterspec answers is which
505
+ tickets a commit range contains (`spec-sync released <range> --json`, each row
506
+ with its spec and url), because only the `Refs:` trailers know. What the
507
+ project's CI does with that list is its own business.
498
508
 
499
509
  **One-way means the repo wins, and it now wins *loudly*.** Those are different
500
510
  claims and only the first was ever in doubt. A ticket's description is generated
@@ -577,23 +587,36 @@ none of them describes.
577
587
  - **Other rules specs must honour:** link the relevant `.claude/rules/*.md`
578
588
  (architecture, code style, testing, database, etc.) rather than restating them.
579
589
 
580
- ## Spec types — Feature, Bug, Hotfix
590
+ ## Spec types — Feature, Chore, Bug, Hotfix
581
591
 
582
- Every spec is one of three types, recorded **both** in the header and the filename:
592
+ Every spec is one of four types, recorded **both** in the header and the filename:
583
593
 
584
- - **Header field:** `> **Type:** Feature`, `> **Type:** Bug`, or
585
- `> **Type:** Hotfix` (authoritative, greppable:
594
+ - **Header field:** `> **Type:** Feature`, `> **Type:** Chore`,
595
+ `> **Type:** Bug`, or `> **Type:** Hotfix` (authoritative, greppable:
586
596
  `grep -rl 'Type:.*Hotfix' specs/`).
587
- - **Filename prefix:** `feat-<name>` for features, `bug-<name>` for bugs,
588
- `hotfix-<name>` for hotfixes (visible in listings; glob-safe — never use
589
- `[BUG]`/`[FEATURE]` brackets).
597
+ - **Filename prefix:** `feat-<name>` for features, `chore-<name>` for chores,
598
+ `bug-<name>` for bugs, `hotfix-<name>` for hotfixes (visible in listings;
599
+ glob-safe — never use `[BUG]`/`[FEATURE]` brackets).
600
+
601
+ A **Chore** is work no end user sees — tooling, CI, dependency bumps, internal
602
+ refactors. The line: anything that is not work end users see or functions they
603
+ use within the app is a chore; everything user-facing is a feature. There is no
604
+ separate entry skill — `/spec` **proposes** feature or chore from what the
605
+ grilling defined, with a one-line reason, and the user confirms. A chore
606
+ defaults its `Gating:` to `none: not user-facing` (where gating is configured),
607
+ and its commits default to `chore`/`refactor`/`ci` types with **no**
608
+ `Release-Note:` footer — a chore is by definition not user-visible, so it has
609
+ no release note to write. Feature specs keep `feat`; bug specs keep `fix`.
610
+ Where a ticketing provider maps kinds to tracker types (e.g. Azure's
611
+ `workItemTypeByKind`), the chore mapping is what keeps tooling work off the
612
+ customer-facing release ladder.
590
613
 
591
614
  A **Hotfix** is a Bug fixed against a **released tag** rather than `main`: it
592
615
  carries an extra `> **Base version:** <tag>` header, forks its worktree from that
593
616
  tag, and lands by tagging a new patch + cherry-picking onto `main` (never a
594
617
  fast-forward merge). `/spec-live` refuses a hotfix — test it with `/spec-connect`.
595
618
 
596
- All three types share the same lifecycle folders below — type is orthogonal to
619
+ All four types share the same lifecycle folders below — type is orthogonal to
597
620
  status.
598
621
 
599
622
  ## Header fields & State log (audit trail)
@@ -231,8 +231,34 @@ again on the **same** `--since`. Not a fresh one — a pass that arrived during
231
231
  the gap is still inside the original window, and re-arming on a new timestamp
232
232
  would strand exactly that pass.
233
233
 
234
- **Say nothing when you do it.** Nothing happened and the window is unchanged; a
235
- line on every death turns a working loop into a stream of non-events.
234
+ **Say as little as the harness allows when you do it.** Nothing happened and
235
+ the window is unchanged; a line on every death turns a working loop into a
236
+ stream of non-events. Where the harness lets a turn end on the tool call, the
237
+ tool call is the whole turn. Where it insists on visible text — Claude Code
238
+ does, after a monitor event — that text is one fixed line,
239
+ `Still waiting for the verdict.`, and nothing else: not the spec, not the age,
240
+ not the links. The wait's own start line arriving as an event is answered the
241
+ same way.
242
+
243
+ **Every fifth re-arm, show the banner again.** Even one line per re-arm adds
244
+ up: over a long idle they push the verdict line and the banner's links out of
245
+ sight, and a reader who comes back has to scroll for the URL that lets them
246
+ answer. So `review wait` counts the starts on each window, and on every fifth
247
+ re-arm its start line is followed by `re-show: banner (re-arm N)` and the stack.
248
+ Relay that as the run's **verdict line** — copied from the block when it is
249
+ still in context, dropped rather than reconstructed when it is not — and then
250
+ **the banner** in its current state, with its stack copied from the `re-show:`
251
+ lines. Not the table: that would be a second block.
252
+
253
+ **A count here, not an age**, and the bound below is unaffected. What buries
254
+ the banner is how many re-arms have scrolled past it, and a death every five
255
+ minutes and one every forty-five push it up the same distance each. The age of
256
+ the window still decides when to stop.
257
+
258
+ **And it is not a third control after the block.** It is the banner this file
259
+ already defines, repeated in whatever state it is in — past the bound, that is
260
+ the degraded sentence below. No block is repeated, so nothing follows a second
261
+ one, and nothing about the banner's shape changes.
236
262
 
237
263
  **An operator who stopped it is not a death** — re-arming over a deliberate
238
264
  stop makes the wait unstoppable, which is worse than a wait that stops. But a
@@ -142,8 +142,8 @@ because writing it means reading the diff, and that spend is the user's call.
142
142
 
143
143
  **A watch that dies is re-armed on the same window**, silently and bounded by
144
144
  the age of that window — `.claude/rules/spec-reports.md` carries the contract,
145
- including when to stop and what the banner says instead. Do not restate it
146
- here.
145
+ including when to stop, what the banner says instead, and when the
146
+ engine's `re-show:` brings the banner back. Do not restate it here.
147
147
 
148
148
  ```
149
149
  skitterspec spec-env review <name> --claim-since <the timestamp> --json
@@ -188,9 +188,31 @@ not write the spec until this is resolved.
188
188
  Stop grilling when there are no unresolved branches that would change the spec.
189
189
  Briefly play back the agreed understanding before writing.
190
190
 
191
+ ### Propose the kind — feature or chore
192
+
193
+ This skill writes two kinds of spec, and
194
+ **you propose which from what the grilling defined, with a one-line reason; the user confirms or overrides.**
195
+ The
196
+ line that decides it: a **chore** is anything that is not work end users see or
197
+ functions they use within the app — tooling, CI, dependency bumps, internal
198
+ refactors. Everything user-facing is a **feature**. So the proposal reads like
199
+ *"no user-visible surface → chore"* or *"adds an endpoint users call → feature"*.
200
+
201
+ The kind is recorded twice, and both follow from the answer: the folder prefix
202
+ (`feat-` / `chore-`) and the `> **Type:**` header (`Feature` / `Chore`). A chore
203
+ also defaults its `Gating:` to `none: not user-facing` (only when gating is
204
+ configured — offer the default, let the user override it like any other
205
+ answer), and its commits default to `chore`/`refactor`/`ci` types with no
206
+ `Release-Note:` (see `.claude/rules/spec-planning.md`).
207
+
208
+ There is no `/spec-chore` and none should be added: one entry point, one grill,
209
+ and the kind is an output of understanding the work rather than a door the user
210
+ must pick before describing it.
211
+
191
212
  ## Phase B — write the spec
192
213
 
193
- This skill is for **features**. For bugs, use `/spec-bug` (test-first, red→green).
214
+ This skill is for **features and chores**. For bugs, use `/spec-bug`
215
+ (test-first, red→green).
194
216
 
195
217
  ### Write it in its own worktree
196
218
 
@@ -257,8 +279,8 @@ move to, **warn, don't refuse**, and say the trailer for that commit wants
257
279
  that phase's goal, its task checkboxes (tests included), and any phase-specific
258
280
  notes. **Even a single-phase spec gets `01-….md`** — never lump phase tasks
259
281
  into `00-overview.md`. This keeps each phase easy to dive into on its own.
260
- - Choose a short kebab-case name and **prefix it `feat-`** (the bug counterpart
261
- uses `bug-`).
282
+ - Choose a short kebab-case name and **prefix it with the kind** — `feat-` for
283
+ a feature, `chore-` for a chore (the bug counterpart uses `bug-`).
262
284
 
263
285
  Use this template (keep it **as concise as possible** — no filler, no restating
264
286
  the codebase, link rather than duplicate):
@@ -266,8 +288,8 @@ the codebase, link rather than duplicate):
266
288
  ```markdown
267
289
  # <Feature title>
268
290
 
269
- > **Type:** Feature
270
- > **Name:** feat-<kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
291
+ > **Type:** <Feature or Chore — the kind proposed after Phase A>
292
+ > **Name:** <feat- or chore-><kebab-name> (the spec folder name — the handle you paste into `/spec-start`)
271
293
  > **Status:** Ready — not started
272
294
  > **Author:** <git user.name — `git config user.name`>
273
295
  > **Developer:** —
@@ -276,7 +298,8 @@ the codebase, link rather than duplicate):
276
298
  > **Stack:** <worktree — or "worktree + docker" if it touches the DB/stateful
277
299
  > services; only acted on when isolation is enabled — see Phase A item 9>
278
300
  > **Gating:** <flag name — or "none: <one-line reason>". Only when release gating
279
- > is configured; omit the line entirely otherwise. An empty value or a bare
301
+ > is configured; omit the line entirely otherwise. A chore defaults to
302
+ > "none: not user-facing". An empty value or a bare
280
303
  > "none" is not a valid outcome — see Phase A item 10>
281
304
 
282
305
  ## Problem
@@ -538,8 +561,8 @@ the verdict — and the reader's conclusion is about what the page showed them.
538
561
 
539
562
  **A watch that dies is re-armed on the same window**, silently and bounded by
540
563
  the age of that window — `.claude/rules/spec-reports.md` carries the contract,
541
- including when to stop and what the banner says instead. Do not restate it
542
- here.
564
+ including when to stop, what the banner says instead, and when the
565
+ engine's `re-show:` brings the banner back. Do not restate it here.
543
566
 
544
567
  ```
545
568
  skitterspec spec-env review <spec> --docs --claim-since <the timestamp> --json
@@ -484,8 +484,8 @@ and the routing on the verdict is `/spec-diff` §2 and §4, as it is everywhere.
484
484
 
485
485
  **A watch that dies is re-armed on the same window**, silently and bounded by
486
486
  the age of that window — `.claude/rules/spec-reports.md` carries the contract,
487
- including when to stop and what the banner says instead. Do not restate it
488
- here.
487
+ including when to stop, what the banner says instead, and when the
488
+ engine's `re-show:` brings the banner back. Do not restate it here.
489
489
 
490
490
  **Why this skill arms as well as waits.** Waiting is what any offer does;
491
491
  **arming** asserts an obligation that outlives the turn, and belongs only to
@@ -189,7 +189,8 @@ Then name the next step:
189
189
 
190
190
  - `/spec` — write a spec; with Jira configured it creates the linked issue in
191
191
  the configured project and stamps the key.
192
- - `/spec-status` — read-only drift report, the safe way to prove the link works.
192
+ - `/spec-status` — read-only report of what would push, the safe way to prove
193
+ the link works.
193
194
  - `/spec-push` — send a spec up.
194
195
 
195
196
  Mention what setup did **not** configure, so the defaults aren't mistaken for
@@ -497,8 +497,8 @@ reading — and that is the gap the whole gate exists to close.
497
497
 
498
498
  **A watch that dies is re-armed on the same window**, silently and bounded by
499
499
  the age of that window — `.claude/rules/spec-reports.md` carries the contract,
500
- including when to stop and what the banner says instead. Do not restate it
501
- here.
500
+ including when to stop, what the banner says instead, and when the
501
+ engine's `re-show:` brings the banner back. Do not restate it here.
502
502
 
503
503
  Then **end your turn**. Do not poll it and do not hold the turn open: the
504
504
  point is that the reader has the terminal back while they read.
@@ -1,10 +1,10 @@
1
1
  ---
2
2
  name: spec-status
3
- description: Show a spec's one-way sync status against Jira — a read-only drift report naming what would push, and whether the tracker's status has drifted from the spec's. Changes nothing. Opt-in — needs specs/.core/jira.config.json. Use when the user says "/spec-status", "is this spec in sync with Jira", "what would push", or "show spec sync status".
3
+ description: Show a spec's one-way sync status against Jira — a read-only report naming what would push, and whether someone edited the issue's description since the last push. Changes nothing. Opt-in — needs specs/.core/jira.config.json. Use when the user says "/spec-status", "is this spec in sync with Jira", "what would push", or "show spec sync status".
4
4
  disable-model-invocation: true
5
5
  ---
6
6
 
7
- # /spec-status — one-way sync drift report
7
+ # /spec-status — one-way sync report
8
8
 
9
9
  > Stay silent while this runs — speak only to ask something you cannot answer
10
10
  > yourself, or to report a failure at the moment it happens. Read
@@ -15,13 +15,17 @@ Read-only. Reports two things and writes nothing:
15
15
 
16
16
  1. **Pending push** — has the spec changed since the last push (is there an issue
17
17
  description/state or any phase subtask to create or update)?
18
- 2. **State drift** — does Jira's issue status differ from the spec's status?
19
- (The repo wins on the next push; this is just a heads-up, e.g. a card moved
20
- on the board.)
18
+ 2. **Description edited** — did someone edit the issue's description on Jira
19
+ since the last push? The next push replaces it, so this is worth reading
20
+ first.
21
+
22
+ **Status is not compared, deliberately.** Skitterspec tells Jira about its
23
+ own transitions and never reads a status back: a card someone moved by hand is
24
+ theirs to have moved, and push resends State only when the spec itself moves.
21
25
 
22
26
  The repo is the source of truth; Jira is a generated mirror, so there is no
23
- per-field "conflict" — only "what would the next push send" and "did the mirror
24
- drift".
27
+ per-field "conflict" — only "what would the next push send" and "did someone
28
+ write over the mirror's text".
25
29
 
26
30
  **Opt-in**: only runs when `specs/.core/jira.config.json` exists. If absent,
27
31
  tell the user how to enable Jira sync and stop.
@@ -30,18 +34,16 @@ tell the user how to enable Jira sync and stop.
30
34
 
31
35
  Use the argument, else the spec in context; ask if unclear.
32
36
 
33
- ## 2. Fetch the Jira issue (optional, for drift)
37
+ ## 2. Fetch the Jira issue (optional, for the description check)
34
38
 
35
39
  If the spec has a `jira_identifier`, discover the Jira MCP read tool
36
40
  (`getJiraIssue`) and write the issue JSON to a temp file. If Jira isn't
37
- connected, skip the drift lines (still report pending-push).
41
+ connected, skip the description check (still report pending-push).
38
42
 
39
- **Write the whole issue, including its `description`.** The engine reports two
40
- independent kinds of drift off that one file: the status someone moved, and the
41
- **description someone edited**. Write only the status fields and the second
42
- check has nothing to look at — and it says nothing rather than guessing, so the
43
- loss is silent. Keep `url` too: it is what the description line points the
44
- reader at.
43
+ **Write the whole issue, including its `description`.** That is the field the
44
+ check reads; without it the check has nothing to look at — and it says nothing
45
+ rather than guessing, so the loss is silent. Keep `url` too: it is what the
46
+ description line points the reader at.
45
47
 
46
48
  **The description itself never enters the conversation.** The engine hashes it
47
49
  and compares hashes; what it prints is *that* the text changed, plus where to
@@ -58,8 +60,9 @@ skitterspec spec-sync status <spec> [--remote <issuefile>] [--workspace-states <
58
60
  ```
59
61
 
60
62
  - Reports `push: pending — N to create, M to update` or `up to date`.
61
- - With `--remote`, adds a `drift:` line comparing Jira's issue status to the
62
- spec's status.
63
+ - With `--remote`, adds a `drift:` line when the issue's description was
64
+ edited on Jira since the last push, and nothing otherwise. It never
65
+ reports the issue's state.
63
66
  - With `--workspace-states`, fails loudly if a configured status name isn't in
64
67
  the project (no workflow transition could ever reach it, so the push would
65
68
  refuse at apply time).
@@ -88,18 +91,17 @@ the shape; this section carries only what is specific here.
88
91
  **Verdicts**
89
92
 
90
93
  - `✅` — in sync; nothing would push.
91
- - `⚠️` — drift: N objects would push, Jira's status was moved by hand, or the
92
- issue's **description** was edited on Jira since the last push. None is an
93
- error — the repo wins on the next push — but all are the reason someone ran
94
- this. **Say which**, since the three call for different things: a pending push
95
- is routine, a moved status is usually someone else's automation, and an edited
96
- description means a person wrote something that the next push replaces.
94
+ - `⚠️` — N objects would push, or the issue's **description** was edited on
95
+ Jira since the last push. Neither is an error, but both are the reason
96
+ someone ran this. **Say which**, since they call for different things: a
97
+ pending push is routine, and an edited description means a person wrote
98
+ something that the next push replaces.
97
99
  - `⏸` — no config, or the spec is not linked. Nothing to compare.
98
100
 
99
101
  **Fields:** `Tracker` · `Follow-ups` · `Next`
100
102
 
101
- `Tracker` is the drift in one line — what would push, and whether the tracker's
102
- status diverged. `Next` is `/spec-push` when a push is pending, and nothing to
103
+ `Tracker` is the answer in one line — what would push, and whether the
104
+ description was edited. `Next` is `/spec-push` when a push is pending, and nothing to
103
105
  do when it is not.
104
106
 
105
107
  A **`phases: <mode>`** line names the phase mode that resolved for this spec's