@skitterbyte/skitterspec-jira 2.3.0 → 2.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/assets/claude-md-section.md +20 -1
- package/assets/core/env.config.json.example +1 -0
- package/assets/core/env.config.md +90 -6
- package/assets/core/jira.config.md +4 -2
- package/assets/hooks/main-guard.cjs +18 -2
- package/assets/hooks/review-gate.cjs +19 -2
- package/assets/rules/commit-trailers.md +24 -1
- package/assets/rules/spec-planning.md +81 -18
- package/assets/rules/spec-reports.md +1 -1
- package/assets/skills/spec/SKILL.md +55 -2
- package/assets/skills/spec-bug/SKILL.md +25 -1
- package/assets/skills/spec-cancel/SKILL.md +35 -0
- package/assets/skills/spec-complete/SKILL.md +113 -0
- package/assets/skills/spec-hotfix/SKILL.md +40 -2
- package/assets/skills/spec-incident/SKILL.md +22 -0
- package/assets/skills/spec-jira-setup/SKILL.md +23 -1
- package/assets/skills/spec-next/SKILL.md +9 -4
- package/assets/skills/spec-push/SKILL.md +22 -0
- package/assets/skills/spec-review/SKILL.md +32 -0
- package/assets/skills/spec-start/SKILL.md +39 -1
- package/assets/skills/spec-status/SKILL.md +18 -3
- package/assets/skills/spec-sync/SKILL.md +1 -0
- package/assets/skills/spec-to-main/SKILL.md +47 -1
- package/package.json +1 -1
- package/src/cli.js +1091 -39
- package/src/env/base.js +104 -0
- package/src/env/config.js +75 -3
- package/src/env/disposition.js +62 -0
- package/src/env/handoff.js +80 -0
- package/src/env/host.js +262 -0
- package/src/env/hotfix.js +225 -0
- package/src/env/hotfixland.js +103 -9
- package/src/env/inflight.js +95 -0
- package/src/env/integrate.js +130 -4
- package/src/env/mainguard.js +6 -0
- package/src/env/phases.js +28 -0
- package/src/env/provision.js +18 -6
- package/src/env/resolve.js +108 -9
- package/src/env/serve.js +6 -1
- package/src/env/specstate.js +101 -0
- package/src/env/teardown.js +42 -0
- package/src/vendor/jira/cli-sync.js +45 -3
- package/src/vendor/jira/config.js +17 -5
- package/src/vendor/provider-kit/index.js +4 -0
- package/src/vendor/provider-kit/src/apply.js +49 -4
- package/src/vendor/provider-kit/src/assignment.js +78 -1
- package/src/vendor/provider-kit/src/config.js +34 -1
- package/src/vendor/provider-kit/src/list-rows.js +35 -11
- package/src/vendor/provider-kit/src/released.js +14 -1
- package/src/vendor/provider-kit/src/specs.js +4 -2
- package/src/vendor/provider-kit/src/splice.js +64 -0
- package/src/vendor/provider-kit/src/status.js +137 -0
- package/src/vendor/sync-core/index.js +14 -1
- package/src/vendor/sync-core/src/compare.js +17 -5
- package/src/vendor/sync-core/src/normalize.js +50 -7
- package/src/vendor/sync-core/src/push.js +26 -2
- package/src/vendor/sync-core/src/summary.js +257 -0
|
@@ -16,7 +16,7 @@ diff as a self-contained HTML page you open locally — or publish, and read on
|
|
|
16
16
|
phone. The diff never passes through the model, so the page costs no context
|
|
17
17
|
tokens however large it is; the optional written review is the part that costs,
|
|
18
18
|
and it is offered rather than assumed. `/spec-next` writes the page at the end of
|
|
19
|
-
every phase.
|
|
19
|
+
every phase. **`skitterspec status`** lists what is in flight across worktrees.
|
|
20
20
|
|
|
21
21
|
**Handing the review back.** The page takes marks: tick `✓ accept` per file as
|
|
22
22
|
you read, note anything against a line or a whole file, answer the questions a
|
|
@@ -34,6 +34,25 @@ An accept remembers the file's content, so it lapses by itself when that file
|
|
|
34
34
|
changes again. The marks are information — nothing gates on them; the verdict is
|
|
35
35
|
the one thing you choose, once.
|
|
36
36
|
|
|
37
|
+
**The phase waits for that press.** `/spec-next` ends a phase by rendering the
|
|
38
|
+
page and then watching for your verdict, so the button is what carries the work
|
|
39
|
+
on — no command to remember. What makes that safe is not that the page is
|
|
40
|
+
unreachable (it is reachable, deliberately): it is the **serve token** in the
|
|
41
|
+
URL, 48 random bits deciding who can POST at all, plus the **window** — only a
|
|
42
|
+
pass that arrives *while the session is waiting* is claimed for you, and two
|
|
43
|
+
arrivals refuse rather than pick. Outside that window nothing is claimed
|
|
44
|
+
unasked: type `/spec-reviewed`, or `/spec-reviewed 324199` to name one exactly,
|
|
45
|
+
which matters only when two are waiting. A `file://` page has no server to talk
|
|
46
|
+
to, so it copies and you paste, as before.
|
|
47
|
+
|
|
48
|
+
**And a phase that ended owes you an answer.** The gate is armed when the page
|
|
49
|
+
is rendered at the end of a phase, and cleared by a committing verdict or by
|
|
50
|
+
`skitterspec spec-env review skip "<reason>"` — while it is armed, `/spec-next`
|
|
51
|
+
refuses to build the next phase. Mid-phase renders arm nothing, every
|
|
52
|
+
cannot-tell exits 0 and says nothing, and `review.required: false` turns it off
|
|
53
|
+
for a project. The exit is always one command; one of them is *"I am moving
|
|
54
|
+
on"*, and that reason goes on the record.
|
|
55
|
+
|
|
37
56
|
**A second opinion, when you want one** (`review.reviewers`, empty by default).
|
|
38
57
|
Point it at a code reviewer that runs from your terminal — CodeRabbit's CLI has
|
|
39
58
|
a free tier and `{ "use": "coderabbit" }` is the whole setup; anything printing
|
|
@@ -5,7 +5,7 @@ stack + host dev servers + a front-door proxy per in-progress spec).
|
|
|
5
5
|
Provisioning is folded into `/spec-start`, teardown into `/spec-complete` ·
|
|
6
6
|
`/spec-cancel`, traffic diversion is `/spec-connect`, and reading a spec's diff
|
|
7
7
|
is `/spec-diff`; the `skitterspec spec-env
|
|
8
|
-
<up|bootstrap|nospec|main|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` CLI is
|
|
8
|
+
<up|bootstrap|nospec|main|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` CLI is
|
|
9
9
|
the engine beneath them.
|
|
10
10
|
|
|
11
11
|
**Once this file is present, isolation is the default policy:** `/spec-start` gives
|
|
@@ -284,9 +284,65 @@ through to a documented conservative default; see the field notes below.
|
|
|
284
284
|
// Integration base branch — the branch specs fork from and land back onto
|
|
285
285
|
// (used by the teardown "merged?" guard and, later, the integrate step).
|
|
286
286
|
// Empty = auto-detect: origin/HEAD → main → master. Set it when your default
|
|
287
|
-
// branch isn't discoverable (e.g. no remote) or differs (trunk, develop
|
|
287
|
+
// branch isn't discoverable (e.g. no remote) or differs (trunk, develop, a
|
|
288
|
+
// release-candidate branch). An explicit value always wins — it is the pin.
|
|
288
289
|
"baseBranch": "",
|
|
289
290
|
|
|
291
|
+
// A base that ROLLS: a glob over the remote's branch names (e.g. "20??/Q?")
|
|
292
|
+
// for teams that work off a release candidate versioned per release. The
|
|
293
|
+
// base is the NEWEST match by commit date, so cutting the next rc is all it
|
|
294
|
+
// takes to move every spec onto it — no config edit per release, no message
|
|
295
|
+
// to the team. Precedence: baseBranch (pin) → this pattern → origin/HEAD →
|
|
296
|
+
// main → master.
|
|
297
|
+
// - Matched against `refs/remotes/<land.remote>/*`, never the network:
|
|
298
|
+
// `spec-env up`, `integrate` and `spec-env base` fetch first; everything
|
|
299
|
+
// else reads what the last fetch saw.
|
|
300
|
+
// - git's glob does not cross "/": "rc/*" matches rc/2026-11 but not
|
|
301
|
+
// rc/a/b. Spell each segment ("20??/Q?").
|
|
302
|
+
// - No match REFUSES, naming `spec-env base` — it never falls back to
|
|
303
|
+
// origin/HEAD, because zero matches usually means "not fetched", and
|
|
304
|
+
// the default branch is exactly where a rolling base must not land.
|
|
305
|
+
// - Newest-by-date is only right when one rc is live at a time (the next
|
|
306
|
+
// is cut after the last merges). If your rcs overlap, pin `baseBranch`.
|
|
307
|
+
// - A spec that outlived a roll lands on the new rc; the integrate plan
|
|
308
|
+
// says `retarget: forked from <old> · landing onto <new>`, and switches
|
|
309
|
+
// a primary checkout still on the old rc before the fast-forward.
|
|
310
|
+
// A pattern holding whitespace or ".." is dropped (treated as unset).
|
|
311
|
+
// `spec-env base` lists the matches, the base, and specs on an older one.
|
|
312
|
+
"baseBranchPattern": "",
|
|
313
|
+
|
|
314
|
+
// How a finished branch reaches the base branch.
|
|
315
|
+
// strategy: "ff" (default) — trunk-based: rebase + local `merge --ff-only`,
|
|
316
|
+
// exactly as always; nothing below applies.
|
|
317
|
+
// "pr" — the branch is pushed and a pull request carries it; the
|
|
318
|
+
// base branch moves only when the host merges. `spec-env
|
|
319
|
+
// integrate` then plans a rebase onto <remote>/<base> and a
|
|
320
|
+
// consent-gated push (`--push` consents; already-pushed-at-HEAD
|
|
321
|
+
// counts as consent; otherwise the plan holds), and a landed
|
|
322
|
+
// branch prints the finish — base catch-up plus the deferred
|
|
323
|
+
// `afterLand`. `--strategy ff|pr` on integrate overrides this per
|
|
324
|
+
// invocation; an unrecognised config value falls back to "ff".
|
|
325
|
+
// remote: where the branch is pushed. Default "origin".
|
|
326
|
+
// draft: mid-spec PRs open as drafts (a draft cannot be merged, so
|
|
327
|
+
// nothing downstream can close a ticket early); /spec-complete is
|
|
328
|
+
// what flips the PR to ready. Default true.
|
|
329
|
+
// specDocs: where a SPEC DOCUMENT lands under "pr". "trunk" (default) keeps
|
|
330
|
+
// today's authoring land — needs direct push for docs. "branch"
|
|
331
|
+
// has the spec ride the feature branch and land with the work's
|
|
332
|
+
// PR; the backlog is then found via the tracker listing, and the
|
|
333
|
+
// authoring worktree stays (it is the document's only copy).
|
|
334
|
+
// The merged-check and PR commands need the host's CLI — `gh` on github.com,
|
|
335
|
+
// `az` on dev.azure.com — detected from the remote URL, never configured. An
|
|
336
|
+
// unknown host (Enterprise/Server domains included) degrades to the ancestry
|
|
337
|
+
// test plus generic printed commands, and every failed lookup is a
|
|
338
|
+
// cannot-tell: teardown then HOLDS the worktree rather than guessing.
|
|
339
|
+
"land": {
|
|
340
|
+
"strategy": "ff",
|
|
341
|
+
"remote": "origin",
|
|
342
|
+
"draft": true,
|
|
343
|
+
"specDocs": "trunk"
|
|
344
|
+
},
|
|
345
|
+
|
|
290
346
|
// Teardown safety. --force overrides both. refuseTeardownIfUnpushed only
|
|
291
347
|
// blocks when the commits are ALSO unmerged into the base branch — a branch
|
|
292
348
|
// already landed on base tears down (and its branch is deleted) without
|
|
@@ -297,9 +353,12 @@ through to a documented conservative default; see the field notes below.
|
|
|
297
353
|
},
|
|
298
354
|
|
|
299
355
|
// What teardown cleans up beyond this machine. Nothing publishes a spec
|
|
300
|
-
// branch
|
|
301
|
-
//
|
|
302
|
-
// forever.
|
|
356
|
+
// branch unasked — a remote copy exists because you pushed it by hand, or
|
|
357
|
+
// because a PR-mode land pushed it behind the consent gate — and without this
|
|
358
|
+
// a completed spec leaves that merged branch on the remote forever. (Hosts
|
|
359
|
+
// that auto-delete the branch on merge make the planned delete an
|
|
360
|
+
// already-gone no-op, reported as such, never as a failure.)
|
|
361
|
+
// `deleteRemoteBranch`:
|
|
303
362
|
// "prompt" (default) — plan `git push <remote> --delete <branch>` in its own
|
|
304
363
|
// "confirm with the user first" section; /spec-complete and
|
|
305
364
|
// /spec-cancel ask before running it.
|
|
@@ -358,11 +417,36 @@ through to a documented conservative default; see the field notes below.
|
|
|
358
417
|
// `hotfix land --push`; without it the land holds before the carry. The
|
|
359
418
|
// worktree stays until `spec-env hotfix finish`. Default: built-in patch tag,
|
|
360
419
|
// carry to main, no targets.
|
|
420
|
+
//
|
|
421
|
+
// `releaseBranch` makes hotfixes BRANCH-BASED, for a team whose release line
|
|
422
|
+
// is a branch rather than a tag. Worked example — an rc flow:
|
|
423
|
+
// master takes only rc merges and hotfixes; prod is whatever it holds
|
|
424
|
+
// 2026/Q4 the current release candidate (`baseBranchPattern: "20??/Q?"`)
|
|
425
|
+
// Test/Demo/Live env branches that take merges from master — OUT OF SCOPE:
|
|
426
|
+
// merging master into them stays your pipeline's job
|
|
427
|
+
// With `"releaseBranch": "master"`, `spec-env up hotfix-<name> --docs` fetches
|
|
428
|
+
// and forks from origin/master's head and prints the header to record —
|
|
429
|
+
// `> **Base version:** master@<sha>`. `hotfix land` then rebases onto
|
|
430
|
+
// origin/master and lands ON it by `land.strategy` (`--strategy` overrides):
|
|
431
|
+
// "ff" pushes the hotfix onto master; "pr" opens a READY pull request and
|
|
432
|
+
// holds until the host merges it. The fix is then carried to the resolved base
|
|
433
|
+
// (the newest rc) — directly under "ff", through a `carry/<slug>` branch and
|
|
434
|
+
// its own ready PR under "pr". `hotfix finish` tears down once both are
|
|
435
|
+
// confirmed. Empty (the default) = the tag flow above, unchanged; a hotfix
|
|
436
|
+
// keeps landing the way its own `Base version` says it was cut.
|
|
437
|
+
//
|
|
438
|
+
// `tag` (default true) keeps the release tag on a branch-based hotfix, bumped
|
|
439
|
+
// from the newest tag the release branch has; false is for a team whose deploy
|
|
440
|
+
// is driven by the env-branch merge rather than a tag. Under "pr",
|
|
441
|
+
// `releaseWith` refuses — a squash or rebase merge leaves its tag on a commit
|
|
442
|
+
// the release branch never has — so use the built-in tag there.
|
|
361
443
|
"hotfix": {
|
|
362
444
|
"releaseWith": "",
|
|
363
445
|
"bump": "patch",
|
|
364
446
|
"cherryPickMain": true,
|
|
365
|
-
"targets": []
|
|
447
|
+
"targets": [],
|
|
448
|
+
"releaseBranch": "",
|
|
449
|
+
"tag": true
|
|
366
450
|
},
|
|
367
451
|
|
|
368
452
|
// Reading a spec's diff (`spec-env review`, `/spec-diff`).
|
|
@@ -11,14 +11,16 @@ NAMES — never a credential. Credentials live in the user-level store
|
|
|
11
11
|
| `jira.issueType` | The issue type a spec mints as. | `"Task"` |
|
|
12
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. | `{}` |
|
|
13
13
|
| `jira.subtaskType` | The type a phase mints as (must be a subtask type). | `"Subtask"` |
|
|
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
|
+
| `mapping.specFolder` / `mapping.phases` / `mapping.tasks` | Spec → issue, phase → subtask, tasks → ADF checklist. Same modes as the Linear provider (`subissue` \| `deferred` \| `inline` \| `none`; `checklist` \| `none`). | `issue` / `subissue` / `checklist` |
|
|
15
|
+
| `mapping.description` | What a ticket body carries. `"summary"`: a delimited block (summary, acceptance criteria, surfaces touched, gating, spec path) spliced in beside the team's own text, which no push touches; phase sub-issues get a block with their goal. `"spec"`: the whole overview, replacing the body (the behaviour before this key). A config without the key is `spec`, so an upgrade rewrites no ticket. | `spec` |
|
|
16
|
+
| `summary.delimiter` | How the block is marked: `"comment"` (HTML comments, hidden on the rendered ticket) or `"heading"` (a `## Skitterspec summary` heading and an end line). Provisional for this tracker until `chore-delimiter-spike-providers` measures which survives its editor. A delimiter someone edited is reported and the block is left unwritten, never guessed at. | `heading` |
|
|
15
17
|
| `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
18
|
| `statesByType.<issue type>.<bucket>` | Per-TYPE override laid over `states` — statuses belong to the type's workflow, so `{ "Service Request": { "complete": "Closed" } }` completes that type differently. A bucket set to `null` sends no status; validation checks each type against its own workflow. | `{}` |
|
|
17
19
|
| `jira.severityField` | The field id the `Severity:` header is written to (e.g. `customfield_10900`). Empty, the header stays repo-only. A fix spec's `Incident:` header adds a `Relates` issue link to its incident, once. | `""` |
|
|
18
20
|
| `auth.emailEnv` / `auth.tokenEnv` | Env-var NAMES for the email + API-token pair (basic auth). | `JIRA_EMAIL` / `JIRA_API_TOKEN` |
|
|
19
21
|
| `apply.transport` | `api` \| `mcp`, or empty for "api when credentials resolve, mcp when they don't". | `""` |
|
|
20
22
|
| `sync.baseDir` | Where last-pushed snapshots live. | `specs/.core/jira-base` |
|
|
21
|
-
| `sync.fieldOwnership` |
|
|
23
|
+
| `sync.fieldOwnership` | Who owns each field. The repo pushes `description` and `subIssues`; Jira owns `workflowState` and `assignee` (`pull`: the state is sent only on a bucket move, the assignee never projected). `"push"` restores the repo-owned behaviour; `"none"` declines a field. | content `push`, status and assignee `pull` |
|
|
22
24
|
| `release.ignorePaths` | Bookkeeping path prefixes `released` ignores, exactly as the Linear provider defines them. | `specs/`, changelogs |
|
|
23
25
|
|
|
24
26
|
Descriptions are stored as ADF (Atlassian Document Format): the adapter
|
|
@@ -117,6 +117,15 @@ function writeTarget(input) {
|
|
|
117
117
|
return null
|
|
118
118
|
}
|
|
119
119
|
|
|
120
|
+
// The engine's own refusal line, from `spec-env main check`. Pure.
|
|
121
|
+
//
|
|
122
|
+
// WHAT WOULD FOOL THIS: an engine that crashes after printing that line. The
|
|
123
|
+
// refusal is the last thing `check` writes, so a crash before it prints nothing
|
|
124
|
+
// — and one after it has already decided.
|
|
125
|
+
function isRefusal(stdout) {
|
|
126
|
+
return /^spec-env main: /m.test(stdout || '')
|
|
127
|
+
}
|
|
128
|
+
|
|
120
129
|
function main() {
|
|
121
130
|
const payload = readPayload()
|
|
122
131
|
if (!payload) allow()
|
|
@@ -145,7 +154,14 @@ function main() {
|
|
|
145
154
|
if (result.error || result.status === null) allow()
|
|
146
155
|
if (result.status !== 1) allow()
|
|
147
156
|
|
|
148
|
-
|
|
157
|
+
// EXIT 1 ALONE IS NOT A REFUSAL. Node exits 1 on an uncaught exception, so an
|
|
158
|
+
// engine that cannot even load looks exactly like one refusing — and read
|
|
159
|
+
// that way it denied every Edit and Write in the session. The positive signal
|
|
160
|
+
// is the refusal the engine PRINTS; a crash prints nothing on stdout.
|
|
161
|
+
const said = (result.stdout || '').trim()
|
|
162
|
+
if (!isRefusal(said)) allow()
|
|
163
|
+
|
|
164
|
+
deny(said)
|
|
149
165
|
}
|
|
150
166
|
|
|
151
167
|
// Guarded so the pieces above can be required and tested without the script
|
|
@@ -159,4 +175,4 @@ if (require.main === module) {
|
|
|
159
175
|
}
|
|
160
176
|
}
|
|
161
177
|
|
|
162
|
-
module.exports = { findEngine, WRITE_TOOLS, writeTarget }
|
|
178
|
+
module.exports = { findEngine, WRITE_TOOLS, writeTarget, isRefusal }
|
|
@@ -93,6 +93,15 @@ function findEngine(projectDir) {
|
|
|
93
93
|
return 'skitterspec'
|
|
94
94
|
}
|
|
95
95
|
|
|
96
|
+
// The engine's own refusal line, from `spec-env review gate --check`. Pure.
|
|
97
|
+
//
|
|
98
|
+
// WHAT WOULD FOOL THIS: an engine that crashes after printing that line. The
|
|
99
|
+
// refusal is written last, after every read has succeeded, so a crash before
|
|
100
|
+
// it prints nothing — and one after it has already decided.
|
|
101
|
+
function isRefusal(stdout) {
|
|
102
|
+
return /^spec-env review gate: /m.test(stdout || '')
|
|
103
|
+
}
|
|
104
|
+
|
|
96
105
|
function main() {
|
|
97
106
|
const payload = readPayload()
|
|
98
107
|
if (!payload) allow()
|
|
@@ -119,8 +128,16 @@ function main() {
|
|
|
119
128
|
if (result.error || result.status === null) allow()
|
|
120
129
|
if (result.status !== 1) allow()
|
|
121
130
|
|
|
131
|
+
// EXIT 1 ALONE IS NOT A REFUSAL. Node exits 1 on an uncaught exception, so an
|
|
132
|
+
// engine that cannot even load looks exactly like one saying "armed" — and
|
|
133
|
+
// once read that way it denied every Bash call in the session, the operator's
|
|
134
|
+
// own `!` commands included. The positive signal is the refusal the engine
|
|
135
|
+
// PRINTS; a crash prints nothing on stdout, so it allows.
|
|
136
|
+
const said = (result.stdout || '').trim()
|
|
137
|
+
if (!isRefusal(said)) allow()
|
|
138
|
+
|
|
122
139
|
deny(
|
|
123
|
-
|
|
140
|
+
said +
|
|
124
141
|
'\n\nThis phase is waiting on a verdict. Relay these to the operator ' +
|
|
125
142
|
'rather than choosing one: press a verdict on the page, /spec-reviewed if ' +
|
|
126
143
|
'a pass is already waiting, or /spec-skip "<reason>" to move on with the ' +
|
|
@@ -143,4 +160,4 @@ if (require.main === module) {
|
|
|
143
160
|
}
|
|
144
161
|
}
|
|
145
162
|
|
|
146
|
-
module.exports = { findEngine }
|
|
163
|
+
module.exports = { findEngine, isRefusal }
|
|
@@ -87,10 +87,33 @@ and it is cancelled along with it.
|
|
|
87
87
|
|
|
88
88
|
## Why it exists
|
|
89
89
|
|
|
90
|
-
|
|
90
|
+
In trunk mode the repo lands specs with `merge --ff-only`, so history is linear and branch
|
|
91
91
|
names never reach it. The commit message is the only artefact that survives into
|
|
92
92
|
the range a release scans, which is what lets
|
|
93
93
|
`spec-sync released <range>` report the tickets a release contains. A ref that
|
|
94
94
|
names the wrong ticket does not merely lose information — it moves a commit onto
|
|
95
95
|
another ticket's release report, which is worse than the gap it was meant to
|
|
96
96
|
close.
|
|
97
|
+
|
|
98
|
+
## Merge styles, and which range still holds the trailers
|
|
99
|
+
|
|
100
|
+
Trunk mode keeps this simple: `merge --ff-only` means linear history and every
|
|
101
|
+
trailer survives. PR mode (`land.strategy: "pr"`) hands the merge to the host,
|
|
102
|
+
and no merge style is required — teams pick their own — so the scan copes
|
|
103
|
+
per style instead:
|
|
104
|
+
|
|
105
|
+
- **Merge commits** — every branch commit survives, trailers intact. A
|
|
106
|
+
trailer-less merge commit counts as transport, never as an unreferenced gap —
|
|
107
|
+
while a merge that CARRIES a trailer still counts, because a hand merge is
|
|
108
|
+
where a ticket's only trailer sometimes lives.
|
|
109
|
+
- **Squashed feature PRs** — the branch's commits collapse into one. The
|
|
110
|
+
trailers survive when the squash message keeps the commit bodies (GitHub:
|
|
111
|
+
the "Default commit message" squash setting; Azure DevOps: keep the commit
|
|
112
|
+
descriptions in the squash message) — `released` counts every `Refs:` line
|
|
113
|
+
in the one body, so a squashed PR carrying three commits still reports three
|
|
114
|
+
tickets.
|
|
115
|
+
- **A squashed integration-to-release merge** — one commit for a whole cycle,
|
|
116
|
+
and attribution on the release branch is gone by construction. No setting
|
|
117
|
+
fixes that: point `released <range>` at the integration branch's range
|
|
118
|
+
instead, where the commits still exist. The range argument has always been
|
|
119
|
+
arbitrary, and this is what it is for.
|
|
@@ -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/Chore/Issue) 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
|
|
10
|
+
| `/spec` | (Feature/Chore/Issue) 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 — or riding the feature branch under `land.specDocs: "branch"`) |
|
|
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
|
| `/spec-incident` | (Incident) Capture a live outage as a record written during it — grill, write in flight, fixes as separate linked specs | `In Progress` | `specs/in-progress/` |
|
|
@@ -157,6 +157,9 @@ build phase 1 now? Say yes and it carries on into a bare `/spec-next`; say no an
|
|
|
157
157
|
you are already standing in the worktree, so `/spec-next` typed later does the
|
|
158
158
|
same thing. The primary checkout stays on the base branch throughout — the
|
|
159
159
|
session followed the spec, nothing was checked out anywhere.
|
|
160
|
+
That is also why the base branch reads `backlog` for a spec being built: the
|
|
161
|
+
move happened on its branch. **`skitterspec status`** reads each worktree's own
|
|
162
|
+
copy and lists what is in flight and how far along it is.
|
|
160
163
|
**`checkout`** builds the branch in the primary checkout instead: one spec at a
|
|
161
164
|
time, nowhere else to stand, and the build always carries straight on.
|
|
162
165
|
The difference is how many specs can be in flight at once.
|
|
@@ -179,7 +182,7 @@ your canonical `localhost` ports so you can test it at the normal URL
|
|
|
179
182
|
move, header edits, the code) happens on the spec's branch in the worktree; `main`
|
|
180
183
|
changes only when it merges. Teardown is folded into `/spec-complete` ·
|
|
181
184
|
`/spec-cancel`. Beneath the skills, `skitterspec spec-env
|
|
182
|
-
<up|bootstrap|nospec|main|down|prune|dev|connect|integrate|hotfix|live|review|stage|status|resolve>` is the CLI
|
|
185
|
+
<up|bootstrap|nospec|main|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` is the CLI
|
|
183
186
|
engine. `up` plans the fork;
|
|
184
187
|
**`bootstrap` then runs the worktree's own steps itself** — seeding the gitignored files, the env file, `setup`, the stack — so
|
|
185
188
|
the command a skill runs names no file, and a secrets hook that refuses any
|
|
@@ -234,6 +237,16 @@ worktree: `Commit & Start` keeps it and carries into `/spec-start`, plain
|
|
|
234
237
|
`commit` tears it down, because a spec parked in the backlog should hold no
|
|
235
238
|
checkout.
|
|
236
239
|
|
|
240
|
+
**`land.specDocs: "branch"` is the exception, taken deliberately.** Where the
|
|
241
|
+
base branch accepts no direct push even for documents, the spec rides its
|
|
242
|
+
feature branch and lands with the work's PR: both verdicts commit and skip the
|
|
243
|
+
integrate, plain `commit` keeps branch and worktree (they are the document's
|
|
244
|
+
only copy), and the backlog is found through the tracker listing rather than
|
|
245
|
+
`ls specs/backlog/` on base — the known branch-relative-bucket cost, accepted
|
|
246
|
+
because the alternative is a spec that cannot be written at all. The worktree
|
|
247
|
+
fork-point check is exempt in this mode for the hotfix's reason: the spec is
|
|
248
|
+
*supposed* to be absent from the fork point.
|
|
249
|
+
|
|
237
250
|
**What this bought is the reason it changed.** The page waits for a verdict
|
|
238
251
|
without a timeout — deliberately, because a reader walking away from a diff is
|
|
239
252
|
the normal case — and while the spec was authored in the primary checkout that
|
|
@@ -497,15 +510,60 @@ against a committed last-pushed snapshot and applies it) and `/spec-status`
|
|
|
497
510
|
backed by a `spec-sync` CLI. There is no content pull — the tracker is never
|
|
498
511
|
read back or merged.
|
|
499
512
|
|
|
500
|
-
**
|
|
501
|
-
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
|
|
507
|
-
with
|
|
508
|
-
|
|
513
|
+
**What a ticket carries is the project's choice (`mapping.description`).**
|
|
514
|
+
Under `"spec"` the issue body is the whole overview and each phase sub-issue
|
|
515
|
+
its phase file, replaced on every push — what every config written before the
|
|
516
|
+
setting existed gets. Under `"summary"`, what a new config is written with, the
|
|
517
|
+
spec stays in git and the ticket gets what a ticket is for: a delimited
|
|
518
|
+
**block** holding the spec's `## Summary`, its `## Acceptance criteria`, the
|
|
519
|
+
Impact table's surfaces, its gating and its progress (`62% · phase 3 of 4`),
|
|
520
|
+
with each sub-issue's block holding its goal and task count. Push **splices**
|
|
521
|
+
the block into whatever the description holds, so a team's own text around it
|
|
522
|
+
survives every push, and only an edit *inside* the block is drift. That is a
|
|
523
|
+
splice, not a pull: nothing outside the block is parsed, merged or written
|
|
524
|
+
back. A delimiter edited by hand is cannot-tell — the push names it and writes
|
|
525
|
+
nothing there rather than guess. `mapping.phases: "none"` drops the phase
|
|
526
|
+
objects entirely; `subissue` stays the default because assignable phases are
|
|
527
|
+
what let them run in parallel.
|
|
528
|
+
|
|
529
|
+
**The tracker owns status; the repo owns the spec.** With a provider attached,
|
|
530
|
+
a team runs its work from the board — assignment, Ready, Blocked, Cancelled and
|
|
531
|
+
Done all happen there — so a status kept in the repo as well is a copy somebody
|
|
532
|
+
has to keep in step by hand, and on the base branch it was already wrong (an
|
|
533
|
+
in-flight spec still reads `backlog` there). The split follows what each side
|
|
534
|
+
can actually know:
|
|
535
|
+
|
|
536
|
+
1. **The repo owns the content** — Problem, Decisions, phases, checkboxes,
|
|
537
|
+
Changelog. Content follows branches, lands in the same commit as its code,
|
|
538
|
+
and is read offline by the agent building it. That is why specs did not move
|
|
539
|
+
into the tracker wholesale: a ticket has no branches.
|
|
540
|
+
2. **The tracker owns status and assignee** — `sync.fieldOwnership`
|
|
541
|
+
`workflowState` and `assignee` ship as **`pull`**. Under `pull` the skills
|
|
542
|
+
write no `Status:` header, no `Developer:` line and no State log row (the
|
|
543
|
+
`spec-status-owner` seam asks `spec-sync ownership` first), `assign` writes
|
|
544
|
+
the ticket directly, and the repo stores nothing it reads.
|
|
545
|
+
3. **Buckets are code facts**, not planning status: `backlog` (not started),
|
|
546
|
+
`in-progress` (`/spec-start` ran), `complete` (landed — merged on the host
|
|
547
|
+
under PR landing), `cancelled` (torn down). Only skills that act on code move
|
|
548
|
+
them.
|
|
549
|
+
4. **The repo writes status only when it acts on code** — creation, start,
|
|
550
|
+
complete, cancel — detected as a bucket move, never on a push that merely
|
|
551
|
+
cannot tell. Under PR landing the complete transition waits for run 2: a
|
|
552
|
+
ready PR is not a merged one.
|
|
553
|
+
5. **A board that finished first is reported, never obeyed.** `spec-sync board`
|
|
554
|
+
says one line when the ticket is Done or Cancelled while the spec is still in
|
|
555
|
+
flight, naming the cleanup; `/spec-start` and `/spec-next` warn and carry on,
|
|
556
|
+
`/spec-status` reports. Nobody is obliged to sync, because nothing reads the
|
|
557
|
+
bucket as planning truth any more.
|
|
558
|
+
|
|
559
|
+
`"push"` on either field restores the repo-owned behaviour; `"none"` leaves it
|
|
560
|
+
alone entirely. Without a provider none of this applies: the header, the State
|
|
561
|
+
log and the buckets keep their meaning, because there is nowhere else for status
|
|
562
|
+
to live. Releases and deployments are the host project's to record. The one
|
|
563
|
+
release question skitterspec answers is which tickets a commit range contains
|
|
564
|
+
(`spec-sync released <range> --json`, each row with its spec and url), because
|
|
565
|
+
only the `Refs:` trailers know. What the project's CI does with that list is its
|
|
566
|
+
own business.
|
|
509
567
|
|
|
510
568
|
**One-way means the repo wins, and it now wins *loudly*.** Those are different
|
|
511
569
|
claims and only the first was ever in doubt. A ticket's description is generated
|
|
@@ -538,13 +596,14 @@ disk at all. The tracker knows both, and each row carries the spec's folder name
|
|
|
538
596
|
so `/spec-start <name>` is a copy-paste away. See the provider's own docs for
|
|
539
597
|
what it calls the command.
|
|
540
598
|
|
|
541
|
-
A provider
|
|
542
|
-
|
|
543
|
-
|
|
544
|
-
|
|
545
|
-
|
|
546
|
-
|
|
547
|
-
|
|
599
|
+
A provider also knows **who is building a spec**, and under the default `pull`
|
|
600
|
+
the ticket's assignee is the record: `/spec-start` assigns the operator only when
|
|
601
|
+
nobody holds the ticket (`assign --if-unassigned`), never reassigns anyone, and
|
|
602
|
+
leaves the assignee in place when the spec finishes — the board keeps who did
|
|
603
|
+
the work. `/spec-claim` moves ownership mid-flight — take it, hand it back, or
|
|
604
|
+
hand it to a teammate — by writing the ticket directly. Under `push` the spec
|
|
605
|
+
file is the record and the ticket the mirror, as before. See the provider's own
|
|
606
|
+
docs for both.
|
|
548
607
|
|
|
549
608
|
**Every skill that moves a spec through the lifecycle carries a seam**, so the
|
|
550
609
|
mirror keeps up without anyone remembering to push: `/spec`, `/spec-bug` and
|
|
@@ -713,6 +772,10 @@ Every spec header carries:
|
|
|
713
772
|
(one-way; the repo owns the link), and `/spec-complete` on the incident
|
|
714
773
|
counts the spec among its fixes. Absent on everything else.
|
|
715
774
|
|
|
775
|
+
**Under a provider's default `pull`, these three are the tracker's** —
|
|
776
|
+
`Status:`, `Developer:` and the State log — and new specs carry
|
|
777
|
+
`> **Tracker:** <url>` instead; see the ticketing section above. A spec that already has them keeps them as history.
|
|
778
|
+
|
|
716
779
|
Every spec also has a **State log** table — the audit trail of folder/status
|
|
717
780
|
transitions. Each lifecycle skill appends exactly one row when it changes state:
|
|
718
781
|
|
|
@@ -448,7 +448,7 @@ behind it — say nothing rather than reporting that there was nothing to report
|
|
|
448
448
|
| `Built` | What the run produced — the code, the edits, the spec written. |
|
|
449
449
|
| `Tests` | The result and the command that produced it. |
|
|
450
450
|
| `Notes` | What this run hit and handled — one short paragraph. Named `Snags` once, which announced a problem before the reader had read one; most of what belongs here is neither good nor bad, just worth knowing. A wrong turn, a guard that fired, a check of yours that turned out to be a false negative. Not a caveat on the outcome (`⚠️` and `Why` carry those) and not future work (`Follow-ups` carries that): this is what happened on the way. |
|
|
451
|
-
| `Landed` | A fast-forward, a tag, a cherry-pick. |
|
|
451
|
+
| `Landed` | A fast-forward, a tag, a cherry-pick — or in PR mode the PR itself: `PR #14 (draft) updated` · `PR #14 opened — finish after merge` · `PR #14 merged` · `held — not pushed` (a declined consent is a true outcome, not a failure). |
|
|
452
452
|
| `Worktree` | A worktree provisioned, entered, or torn down. |
|
|
453
453
|
| `Untouched` | Uncommitted work the run deliberately left alone — whose, and how much. |
|
|
454
454
|
| `Review` | The rendered diff page: files, `+`/`−`, and the stack — the same tiers the banner lists, labelled, run together with `·` because a row is one cell, with any `network` alternates inline after the network URL (`also <url> (tailnet)`), plus `live` where the engine reported one. **No question** — a row cannot be waited on, so a question in one is unanswerable by construction (see *asking implies waiting*). **Omitted entirely when the run is waiting on a verdict**: the banner after the block carries it instead, and a row saying the same thing beside it splits the reader's attention across two places. |
|
|
@@ -157,7 +157,9 @@ not write the spec until this is resolved.
|
|
|
157
157
|
asking. Verify endpoints/models/files actually exist before relying on them.
|
|
158
158
|
- Cover, at minimum, the areas that apply:
|
|
159
159
|
1. **Problem & why** — what's broken/missing, who feels it, why now.
|
|
160
|
-
2. **Scope & non-goals** — explicit out-of-scope items
|
|
160
|
+
2. **Scope & non-goals** — explicit out-of-scope items, and the
|
|
161
|
+
**acceptance criteria**: what someone checks, without reading the code,
|
|
162
|
+
to call the work done (they become `## Acceptance criteria`).
|
|
161
163
|
3. **Affected areas** — concrete files/modules/packages this touches.
|
|
162
164
|
4. **Proposed solution shape** — the chosen approach and the alternatives
|
|
163
165
|
rejected, with the reason (this becomes "Decisions").
|
|
@@ -330,6 +332,28 @@ move to, **warn, don't refuse**, and say the trailer for that commit wants
|
|
|
330
332
|
a feature, `chore-` for a chore, `issue-` for an issue (the bug counterpart
|
|
331
333
|
uses `bug-`, the incident one `incident-`).
|
|
332
334
|
|
|
335
|
+
**Who owns this spec's status.** Only when `specs/.core/jira.config.json` exists.
|
|
336
|
+
Run `skitterspec spec-sync ownership --json` once and read both values:
|
|
337
|
+
|
|
338
|
+
- **`workflowState: "pull"`** — Jira is the record of this spec's status, so
|
|
339
|
+
this skill **writes no `> **Status:**` header and appends no State log row**,
|
|
340
|
+
wherever its steps below say to. A spec this skill creates gets neither: its
|
|
341
|
+
header carries `> **Tracker:** <issue url>` instead, filled in once linking
|
|
342
|
+
has stamped the url, and its body has no `## State log` section. Readiness is
|
|
343
|
+
the spec's own content — a `Draft` is a spec whose **Open questions** is not
|
|
344
|
+
empty — so nothing is lost with the header.
|
|
345
|
+
- **`assignee: "pull"`** — Jira holds who is building it, so this skill
|
|
346
|
+
**writes no `> **Developer:**` line** either.
|
|
347
|
+
- **Anything else** — `push`, `none`, sync reported off, or the command failing
|
|
348
|
+
— is cannot-tell, and the steps below run exactly as written.
|
|
349
|
+
|
|
350
|
+
What `pull` leaves alone: the folder move (a bucket records what the repo did to
|
|
351
|
+
the code, not a planning status), the phase files and index, and the Changelog.
|
|
352
|
+
A reason a `Status:` header would have carried — a cancellation's, a knock-back
|
|
353
|
+
to Draft — goes in a dated Changelog line instead. A spec that already carries
|
|
354
|
+
any of these lines keeps them untouched: they are history, and nothing rewrites
|
|
355
|
+
them.
|
|
356
|
+
|
|
333
357
|
Use this template (keep it **as concise as possible** — no filler, no restating
|
|
334
358
|
the codebase, link rather than duplicate):
|
|
335
359
|
|
|
@@ -354,10 +378,20 @@ the codebase, link rather than duplicate):
|
|
|
354
378
|
> "none: not user-facing". An empty value or a bare
|
|
355
379
|
> "none" is not a valid outcome — see Phase A item 10>
|
|
356
380
|
|
|
381
|
+
## Summary
|
|
382
|
+
|
|
383
|
+
<1–3 sentences: what the work delivers, for someone who will never open the
|
|
384
|
+
spec — no phase breakdown, no implementation detail. With a ticketing provider
|
|
385
|
+
in summary mode this is what the ticket leads with.>
|
|
386
|
+
|
|
357
387
|
## Problem
|
|
358
388
|
|
|
359
389
|
<2–6 sentences: what's wrong/missing and why it matters. No fluff.>
|
|
360
390
|
|
|
391
|
+
## Acceptance criteria
|
|
392
|
+
|
|
393
|
+
- <an observable check, from Phase A item 2 — one per line>
|
|
394
|
+
|
|
361
395
|
## Decisions
|
|
362
396
|
|
|
363
397
|
<Numbered, confirmed decisions from Phase A. Each: the choice + one-line why,
|
|
@@ -467,6 +501,11 @@ Rules for the spec body:
|
|
|
467
501
|
- **Changelog** is mandatory and lives in the spec. Every later decision or
|
|
468
502
|
course-correction gets a dated one-line entry. Convert relative dates to
|
|
469
503
|
absolute.
|
|
504
|
+
- **`## Summary` and `## Acceptance criteria` are the ticket-facing pair.**
|
|
505
|
+
Write them for a reader on the board, not the one building it: the summary
|
|
506
|
+
says what the work delivers, each criterion is something a person can check.
|
|
507
|
+
A ticketing provider in summary mode projects exactly these (plus the
|
|
508
|
+
Impact table's surfaces, Gating and progress) and nothing else.
|
|
470
509
|
- Keep it tight. If a section adds no information, delete it.
|
|
471
510
|
|
|
472
511
|
## Phase C — finish up
|
|
@@ -550,6 +589,18 @@ on the branch you are standing on — so a spec left on its own branch would be
|
|
|
550
589
|
invisible to everyone, including the next `/spec` run. The commit goes on the
|
|
551
590
|
branch and then the branch goes onto the base:
|
|
552
591
|
|
|
592
|
+
**Unless the project set `land.specDocs: "branch"`** — the lane for a base
|
|
593
|
+
branch nobody may push, where the spec document rides the feature branch and
|
|
594
|
+
lands with the work's PR. There both verdicts commit on the branch and
|
|
595
|
+
**skip the integrate below entirely**; `commit-start` carries into
|
|
596
|
+
`/spec-start` over the same worktree exactly as ever, and plain `commit` keeps
|
|
597
|
+
the branch AND the worktree, because they are now the only copy of the
|
|
598
|
+
document. Say the trade out loud in the report's `Notes`: the backlog is found
|
|
599
|
+
through the tracker listing (or `git branch`), not `ls specs/backlog/` on base
|
|
600
|
+
— and a later `/spec-cancel` of a never-started branch-mode spec deletes the
|
|
601
|
+
branch and worktree with the spec document dying with them, no PR ever having
|
|
602
|
+
existed. Under the default `"trunk"` everything below applies unchanged.
|
|
603
|
+
|
|
553
604
|
```
|
|
554
605
|
skitterspec spec-env integrate <name>
|
|
555
606
|
```
|
|
@@ -671,7 +722,9 @@ If it's absent, skip this entirely — the spec stays local-only and the skill
|
|
|
671
722
|
behaves exactly as above. When present, link the spec you just wrote so status
|
|
672
723
|
and discussion live in Jira while the repo stays the source of truth. A spec is
|
|
673
724
|
a Jira **issue**; each phase is a **subtask**, carrying that phase's tasks in
|
|
674
|
-
its description as a read-only checklist.
|
|
725
|
+
its description as a read-only checklist. That is the `spec` description mode;
|
|
726
|
+
under `summary` (a new config's default) the issue and each sub-issue carry
|
|
727
|
+
a short block instead, and the phase's tasks stay in git.
|
|
675
728
|
|
|
676
729
|
**Linking is just the first push**, so it runs the same engine path `/spec-push`
|
|
677
730
|
does — you never create the issue by hand:
|
|
@@ -291,6 +291,28 @@ split it into phase files (`01-<slug>.md`, `02-…`) with a phase index in
|
|
|
291
291
|
`00-overview.md`, exactly like a feature spec. It starts in `in-progress`
|
|
292
292
|
because work is already underway. Keep it lean:
|
|
293
293
|
|
|
294
|
+
**Who owns this spec's status.** Only when `specs/.core/jira.config.json` exists.
|
|
295
|
+
Run `skitterspec spec-sync ownership --json` once and read both values:
|
|
296
|
+
|
|
297
|
+
- **`workflowState: "pull"`** — Jira is the record of this spec's status, so
|
|
298
|
+
this skill **writes no `> **Status:**` header and appends no State log row**,
|
|
299
|
+
wherever its steps below say to. A spec this skill creates gets neither: its
|
|
300
|
+
header carries `> **Tracker:** <issue url>` instead, filled in once linking
|
|
301
|
+
has stamped the url, and its body has no `## State log` section. Readiness is
|
|
302
|
+
the spec's own content — a `Draft` is a spec whose **Open questions** is not
|
|
303
|
+
empty — so nothing is lost with the header.
|
|
304
|
+
- **`assignee: "pull"`** — Jira holds who is building it, so this skill
|
|
305
|
+
**writes no `> **Developer:**` line** either.
|
|
306
|
+
- **Anything else** — `push`, `none`, sync reported off, or the command failing
|
|
307
|
+
— is cannot-tell, and the steps below run exactly as written.
|
|
308
|
+
|
|
309
|
+
What `pull` leaves alone: the folder move (a bucket records what the repo did to
|
|
310
|
+
the code, not a planning status), the phase files and index, and the Changelog.
|
|
311
|
+
A reason a `Status:` header would have carried — a cancellation's, a knock-back
|
|
312
|
+
to Draft — goes in a dated Changelog line instead. A spec that already carries
|
|
313
|
+
any of these lines keeps them untouched: they are history, and nothing rewrites
|
|
314
|
+
them.
|
|
315
|
+
|
|
294
316
|
```markdown
|
|
295
317
|
# Bug: <short title>
|
|
296
318
|
|
|
@@ -369,7 +391,9 @@ If it's absent, skip this entirely — the spec stays local-only and the skill
|
|
|
369
391
|
behaves exactly as above. When present, link the spec you just wrote so status
|
|
370
392
|
and discussion live in Jira while the repo stays the source of truth. A spec is
|
|
371
393
|
a Jira **issue**; each phase is a **subtask**, carrying that phase's tasks in
|
|
372
|
-
its description as a read-only checklist.
|
|
394
|
+
its description as a read-only checklist. That is the `spec` description mode;
|
|
395
|
+
under `summary` (a new config's default) the issue and each sub-issue carry
|
|
396
|
+
a short block instead, and the phase's tasks stay in git.
|
|
373
397
|
|
|
374
398
|
**Linking is just the first push**, so it runs the same engine path `/spec-push`
|
|
375
399
|
does — you never create the issue by hand:
|