@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 +170 -1
- package/README.md +3 -1
- package/assets/core/SETUP.md +1 -1
- package/assets/core/env.config.md +1 -1
- package/assets/core/jira.config.json.example +1 -0
- package/assets/core/jira.config.md +34 -6
- package/assets/rules/spec-planning.md +35 -12
- package/assets/rules/spec-reports.md +28 -2
- package/assets/skills/no-spec/SKILL.md +2 -2
- package/assets/skills/spec/SKILL.md +31 -8
- package/assets/skills/spec-bug/SKILL.md +2 -2
- package/assets/skills/spec-jira-setup/SKILL.md +2 -1
- package/assets/skills/spec-next/SKILL.md +2 -2
- package/assets/skills/spec-status/SKILL.md +27 -25
- package/assets/skills/spec-sync/SKILL.md +6 -4
- package/package.json +1 -1
- package/src/cli.js +108 -3
- package/src/env/resolve.js +11 -4
- package/src/env/review.js +79 -0
- package/src/vendor/jira/cli-sync.js +21 -12
- package/src/vendor/jira/config.js +21 -17
- package/src/vendor/provider-kit/src/config.js +101 -48
- package/src/vendor/provider-kit/src/list-assignee.js +71 -0
- package/src/vendor/provider-kit/src/list-rows.js +35 -0
- package/src/vendor/provider-kit/src/released.js +27 -77
- package/src/vendor/provider-kit/src/specs.js +89 -7
- package/src/vendor/sync-core/index.js +3 -4
- package/src/vendor/sync-core/src/compare.js +6 -6
- package/src/vendor/sync-core/src/normalize.js +60 -59
- package/src/vendor/provider-kit/src/releases.js +0 -595
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
|
-
|
|
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.
|
package/assets/core/SETUP.md
CHANGED
|
@@ -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
|
|
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
|
|
|
@@ -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.
|
|
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
|
|
48
|
-
|
|
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
|
-
|
|
61
|
-
|
|
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
|
|
496
|
-
|
|
497
|
-
|
|
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
|
|
592
|
+
Every spec is one of four types, recorded **both** in the header and the filename:
|
|
583
593
|
|
|
584
|
-
- **Header field:** `> **Type:** Feature`, `> **Type:**
|
|
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, `
|
|
588
|
-
`hotfix-<name>` for hotfixes (visible in listings;
|
|
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
|
|
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
|
|
235
|
-
line on every death turns a working loop into a
|
|
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
|
|
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`
|
|
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
|
|
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
|
|
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.
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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. **
|
|
19
|
-
|
|
20
|
-
|
|
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
|
|
24
|
-
|
|
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
|
|
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
|
|
41
|
+
connected, skip the description check (still report pending-push).
|
|
38
42
|
|
|
39
|
-
**Write the whole issue, including its `description`.**
|
|
40
|
-
|
|
41
|
-
|
|
42
|
-
|
|
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
|
|
62
|
-
|
|
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
|
-
- `⚠️` —
|
|
92
|
-
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
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
|
|
102
|
-
|
|
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
|