@skitterbyte/skitterspec-linear 19.3.0 → 19.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/linear.config.json.example +2 -2
- package/assets/core/linear.config.md +49 -16
- 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 +36 -3
- package/assets/skills/spec-cancel/SKILL.md +37 -0
- package/assets/skills/spec-claim/SKILL.md +41 -2
- package/assets/skills/spec-complete/SKILL.md +115 -0
- package/assets/skills/spec-hotfix/SKILL.md +51 -4
- package/assets/skills/spec-incident/SKILL.md +22 -0
- package/assets/skills/spec-linear-setup/SKILL.md +23 -1
- package/assets/skills/spec-next/SKILL.md +12 -5
- package/assets/skills/spec-push/SKILL.md +22 -0
- package/assets/skills/spec-review/SKILL.md +34 -0
- package/assets/skills/spec-start/SKILL.md +50 -3
- 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/linear/cli-sync.js +55 -6
- package/src/vendor/linear/config.js +27 -21
- package/src/vendor/linear/doctor.js +2 -0
- 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
|
@@ -193,10 +193,15 @@ once it is over. Without a provider this is a no-op and nothing below changes.
|
|
|
193
193
|
**Only when `specs/.core/linear.config.json` exists** and the spec carries a
|
|
194
194
|
`linear_identifier`. Otherwise skip this step — no config means zero change.
|
|
195
195
|
|
|
196
|
-
- **No pull
|
|
197
|
-
|
|
198
|
-
|
|
199
|
-
|
|
196
|
+
- **No pull — one look at the board, before building.** Nothing is brought
|
|
197
|
+
down. Run `skitterspec spec-sync board <spec>`: it reads Linear and writes nothing to
|
|
198
|
+
the spec, and it is **silent** unless the issue says Done or Cancelled while
|
|
199
|
+
this spec is still in flight. When it prints a line, relay it once as a
|
|
200
|
+
warning — this session holds the branch, so the cleanup it names is the
|
|
201
|
+
operator's to choose — and **carry on with the build**. Never run that
|
|
202
|
+
cleanup and never refuse on it. A status someone moved anywhere else is the
|
|
203
|
+
board doing its job, and the next push sends a state only when the spec
|
|
204
|
+
itself changes bucket.
|
|
200
205
|
- **Refresh the mirror now, without asking.** Run `/spec-push`. The spec has just
|
|
201
206
|
moved to `in-progress` and its phase to `🔄` — both real state changes, and the
|
|
202
207
|
tracker is a generated mirror of them. This holds under **both**
|
|
@@ -212,7 +217,9 @@ once it is over. Without a provider this is a no-op and nothing below changes.
|
|
|
212
217
|
`assignee` (it does by default; `"none"` declines it). If the spec records nobody and
|
|
213
218
|
`skitterspec spec-sync whoami --json` answers, stamp it with
|
|
214
219
|
`skitterspec spec-sync assign <spec> --to <id> --name "<name>"` and let the
|
|
215
|
-
push above carry it. If identity is unknown, skip it in silence.
|
|
220
|
+
push above carry it. If identity is unknown, skip it in silence. Where
|
|
221
|
+
`spec-sync ownership` reports `assignee: pull`, add `--if-unassigned`: the
|
|
222
|
+
ticket is the record there, so it is assigned only when nobody holds it.
|
|
216
223
|
**Do not prompt**: an assignment question in the middle of a build is an
|
|
217
224
|
interruption with no deadline, and `/spec-claim` answers it whenever the
|
|
218
225
|
operator likes.
|
|
@@ -20,6 +20,13 @@ own (the sub-issue's title and state). This skill computes what changed since
|
|
|
20
20
|
the last push and applies it — it never reads Linear content back or merges. A
|
|
21
21
|
person editing the mirror in Linear will see it overwritten on the next push.
|
|
22
22
|
|
|
23
|
+
**That is `mapping.description: "spec"`.** Under `"summary"` (what a new
|
|
24
|
+
config is written with) the issue and each sub-issue carry a delimited
|
|
25
|
+
**block** instead — summary, acceptance criteria, surfaces, gating and
|
|
26
|
+
progress for the spec; goal and task count for a phase — spliced in beside
|
|
27
|
+
whatever the team wrote in Linear, which is never overwritten. Only the block
|
|
28
|
+
is the repo's, so only an edit inside it is reported.
|
|
29
|
+
|
|
23
30
|
**Opt-in**: only runs when `specs/.core/linear.config.json` exists. If absent,
|
|
24
31
|
tell the user how to enable Linear sync and stop.
|
|
25
32
|
|
|
@@ -155,6 +162,21 @@ the chosen project through as `--project <id>`.
|
|
|
155
162
|
|
|
156
163
|
## 4a. Apply it yourself — the MCP path (order matters)
|
|
157
164
|
|
|
165
|
+
**In summary mode, every body you write is the engine's splice — never the plan's text on its own.**
|
|
166
|
+
Only when the plan's `descriptionMode` is
|
|
167
|
+
`summary` (it is always present; `spec` needs none of this). There
|
|
168
|
+
the plan's `description` and each sub-issue's `goal` are a **block**, and the
|
|
169
|
+
issue's body is the block *plus the team's text around it*. Writing the block
|
|
170
|
+
alone deletes that text. So, for each object you are about to write:
|
|
171
|
+
|
|
172
|
+
1. Save the body Linear holds now to a file — an empty file for one you are
|
|
173
|
+
creating.
|
|
174
|
+
2. `skitterspec spec-sync splice <spec> --live <file>` for the spec issue, or
|
|
175
|
+
`… --phase <ref>` for a phase's sub-issue.
|
|
176
|
+
3. Write **exactly what it prints**. A non-zero exit printed nothing and means
|
|
177
|
+
a delimiter was edited by hand: skip that object's body, write its other
|
|
178
|
+
fields, and name it in the report. Never compose the splice yourself.
|
|
179
|
+
|
|
158
180
|
**First, check whether you are about to overwrite someone.** On the API path
|
|
159
181
|
`apply` does this for itself, off the read-back it already makes. On the MCP
|
|
160
182
|
path nothing has read the issue yet, so ask before you write:
|
|
@@ -43,6 +43,11 @@ trust the spec's own wording — verify:
|
|
|
43
43
|
- **Decisions still valid.** Re-check each `## Decisions` entry against the
|
|
44
44
|
current architecture and `.claude/rules/*.md`. Flag any that now conflict with
|
|
45
45
|
how the codebase actually works (a changed convention, a superseded approach).
|
|
46
|
+
- **The ticket-facing pair.** A spec with no `## Summary` or no
|
|
47
|
+
`## Acceptance criteria` is not broken — older specs predate both — but where
|
|
48
|
+
a ticketing provider pushes summaries the ticket falls back to the Problem's
|
|
49
|
+
first paragraph and shows no definition of done. Offer to write the missing
|
|
50
|
+
one(s) in step 3, with a draft; never add them unasked.
|
|
46
51
|
- **New constraints.** Note rules/patterns introduced since the spec was written
|
|
47
52
|
that it must now honour (e.g. a new required field, a new error type, a new
|
|
48
53
|
pattern the rest of the code now follows).
|
|
@@ -96,6 +101,29 @@ resolve it by reading the code, do that instead of asking.
|
|
|
96
101
|
- Add a dated **Changelog** entry summarising the review (e.g. `- <date> —
|
|
97
102
|
Reviewed vs codebase: retargeted Phase 2 onto X, dropped Y (removed), ticked Z
|
|
98
103
|
(already done)`).
|
|
104
|
+
|
|
105
|
+
**Who owns this spec's status.** Only when `specs/.core/linear.config.json` exists.
|
|
106
|
+
Run `skitterspec spec-sync ownership --json` once and read both values:
|
|
107
|
+
|
|
108
|
+
- **`workflowState: "pull"`** — Linear is the record of this spec's status, so
|
|
109
|
+
this skill **writes no `> **Status:**` header and appends no State log row**,
|
|
110
|
+
wherever its steps below say to. A spec this skill creates gets neither: its
|
|
111
|
+
header carries `> **Tracker:** <issue url>` instead, filled in once linking
|
|
112
|
+
has stamped the url, and its body has no `## State log` section. Readiness is
|
|
113
|
+
the spec's own content — a `Draft` is a spec whose **Open questions** is not
|
|
114
|
+
empty — so nothing is lost with the header.
|
|
115
|
+
- **`assignee: "pull"`** — Linear holds who is building it, so this skill
|
|
116
|
+
**writes no `> **Developer:**` line** either.
|
|
117
|
+
- **Anything else** — `push`, `none`, sync reported off, or the command failing
|
|
118
|
+
— is cannot-tell, and the steps below run exactly as written.
|
|
119
|
+
|
|
120
|
+
What `pull` leaves alone: the folder move (a bucket records what the repo did to
|
|
121
|
+
the code, not a planning status), the phase files and index, and the Changelog.
|
|
122
|
+
A reason a `Status:` header would have carried — a cancellation's, a knock-back
|
|
123
|
+
to Draft — goes in a dated Changelog line instead. A spec that already carries
|
|
124
|
+
any of these lines keeps them untouched: they are history, and nothing rewrites
|
|
125
|
+
them.
|
|
126
|
+
|
|
99
127
|
- **Status:** if drift is minor, leave status as-is. If a `Ready` spec needs real
|
|
100
128
|
re-grooming, knock it back to `Draft` (set `> **Status:** Draft` and append a
|
|
101
129
|
**State log** row).
|
|
@@ -118,6 +146,10 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
|
|
|
118
146
|
and **finish the operation anyway**. The spec is complete/cancelled/reviewed in
|
|
119
147
|
the repo regardless; the mirror is disposable and the next push repairs it.
|
|
120
148
|
Do not roll anything back, and do not stop to ask.
|
|
149
|
+
- **In `/spec-complete`'s PR mode this push belongs to run 2.** Run 1 readies
|
|
150
|
+
a PR, and a ready PR is not a merged one — so skip it on run 1, even where
|
|
151
|
+
the `branch` lane committed the move to ride the PR, and run it on run 2 once
|
|
152
|
+
the host has merged. The tracker's Done lands when the work does.
|
|
121
153
|
- **Say what happened** in the skill's report: mirror updated, skipped as
|
|
122
154
|
unlinked, or failed with the reason.
|
|
123
155
|
- **There is no unassign step, and that is not an omission.** Where the repo owns
|
|
@@ -126,6 +158,8 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
|
|
|
126
158
|
releases the issue, and the push above carries it like any other field. The
|
|
127
159
|
`linear_assignee_id` stamp and the `> **Developer:**` header both stay put:
|
|
128
160
|
they record who actioned the work, which outlives who is holding it.
|
|
161
|
+
Under `assignee: pull` the projection carries no assignee at all, so the
|
|
162
|
+
issue keeps it: the board records who did the work.
|
|
129
163
|
|
|
130
164
|
### Why it sits here
|
|
131
165
|
|
|
@@ -152,6 +152,14 @@ render says so. On **`--plan`** this step does not run at all.
|
|
|
152
152
|
1. **Provision.** Run `skitterspec spec-env up <name>` — a planner, so run the
|
|
153
153
|
`to provision, run:` commands it prints and confirm they succeeded.
|
|
154
154
|
|
|
155
|
+
**Under a rolling base** (`baseBranchPattern`) `up` fetches first, and where
|
|
156
|
+
the primary checkout is not on the newest release candidate the plan says
|
|
157
|
+
`fork: <base> (the base — the primary checkout is on <old>)` and forks from
|
|
158
|
+
it. Relay that line in the `Branch` row. A refusal naming
|
|
159
|
+
`no branch matches <pattern>` means no release candidate is visible —
|
|
160
|
+
usually not fetched: relay it, stop with `⏸`, and name
|
|
161
|
+
`skitterspec spec-env base` (it fetches and lists) as the next step.
|
|
162
|
+
|
|
155
163
|
2. **Trust the worktree.** `spec-env up` wrote the printed `trusted:` root into
|
|
156
164
|
`.claude/settings.local.json`, but that file does not hot-reload in this
|
|
157
165
|
session — run **`/add-dir <trusted root>`** before editing into the worktree,
|
|
@@ -255,6 +263,29 @@ branch is already here.
|
|
|
255
263
|
|
|
256
264
|
- `git mv "specs/backlog/<name>" "specs/in-progress/<name>"` if it isn't there
|
|
257
265
|
already (`mkdir -p specs/in-progress` first). Use `git mv` to keep history.
|
|
266
|
+
|
|
267
|
+
**Who owns this spec's status.** Only when `specs/.core/linear.config.json` exists.
|
|
268
|
+
Run `skitterspec spec-sync ownership --json` once and read both values:
|
|
269
|
+
|
|
270
|
+
- **`workflowState: "pull"`** — Linear is the record of this spec's status, so
|
|
271
|
+
this skill **writes no `> **Status:**` header and appends no State log row**,
|
|
272
|
+
wherever its steps below say to. A spec this skill creates gets neither: its
|
|
273
|
+
header carries `> **Tracker:** <issue url>` instead, filled in once linking
|
|
274
|
+
has stamped the url, and its body has no `## State log` section. Readiness is
|
|
275
|
+
the spec's own content — a `Draft` is a spec whose **Open questions** is not
|
|
276
|
+
empty — so nothing is lost with the header.
|
|
277
|
+
- **`assignee: "pull"`** — Linear holds who is building it, so this skill
|
|
278
|
+
**writes no `> **Developer:**` line** either.
|
|
279
|
+
- **Anything else** — `push`, `none`, sync reported off, or the command failing
|
|
280
|
+
— is cannot-tell, and the steps below run exactly as written.
|
|
281
|
+
|
|
282
|
+
What `pull` leaves alone: the folder move (a bucket records what the repo did to
|
|
283
|
+
the code, not a planning status), the phase files and index, and the Changelog.
|
|
284
|
+
A reason a `Status:` header would have carried — a cancellation's, a knock-back
|
|
285
|
+
to Draft — goes in a dated Changelog line instead. A spec that already carries
|
|
286
|
+
any of these lines keeps them untouched: they are history, and nothing rewrites
|
|
287
|
+
them.
|
|
288
|
+
|
|
258
289
|
- Set the **Status** header: `> **Status:** In Progress — Phase 1 (started <YYYY-MM-DD>)`.
|
|
259
290
|
- Set **Developer** if it is still `—` (`git config user.name`).
|
|
260
291
|
|
|
@@ -294,6 +325,12 @@ is a cosmetic gap that `/spec-claim` closes later.
|
|
|
294
325
|
skitterspec spec-sync assign <spec> --to <user-id> --name "<display name>"
|
|
295
326
|
```
|
|
296
327
|
|
|
328
|
+
**Where `spec-sync ownership` reports `assignee: pull`**, the issue is the
|
|
329
|
+
record and the spec file is not: add `--if-unassigned`. It writes Linear
|
|
330
|
+
directly, claims the issue only when nobody holds it, and stamps nothing —
|
|
331
|
+
so step 4 has no header to leave alone, since under `pull` no `Developer:`
|
|
332
|
+
line was written.
|
|
333
|
+
|
|
297
334
|
4. **Leave `> **Developer:**` as `git config user.name`** — the step above this
|
|
298
335
|
seam already set it, and this seam must not overwrite it with the tracker's
|
|
299
336
|
display name.
|
|
@@ -315,12 +352,15 @@ is a cosmetic gap that `/spec-claim` closes later.
|
|
|
315
352
|
|
|
316
353
|
**Nothing is pushed here.** `assign` writes the repo only, and the refresh these
|
|
317
354
|
skills already run sends it. Assignment is an ordinary field of the projection,
|
|
318
|
-
not a side errand with its own network call.
|
|
355
|
+
not a side errand with its own network call. Under `pull` the
|
|
356
|
+
`assign` call is itself the write, so there is nothing for a push to carry.
|
|
319
357
|
|
|
320
358
|
**There is no unassign step anywhere.** The projection derives the assignee from
|
|
321
359
|
the spec's lifecycle bucket, so `/spec-complete` and `/spec-cancel` release the
|
|
322
360
|
issue through the push they already make. The stamp deliberately stays in the
|
|
323
|
-
file: who actioned the work outlives who is currently holding it.
|
|
361
|
+
file: who actioned the work outlives who is currently holding it. Under `pull`
|
|
362
|
+
the projection carries no assignee at all, so finishing a spec leaves it on
|
|
363
|
+
the issue: the board keeps who did the work.
|
|
324
364
|
|
|
325
365
|
- Append a **State log** row: `| <YYYY-MM-DD> | In Progress | in-progress | <git user.name> |`.
|
|
326
366
|
|
|
@@ -329,6 +369,12 @@ carries a `linear_identifier`. Either missing → **skip**, in one line
|
|
|
329
369
|
(`not linked to Linear — /spec-push to mirror it`), and carry on. Nothing else in
|
|
330
370
|
this step changes.
|
|
331
371
|
|
|
372
|
+
**Ask the board first.** Run `skitterspec spec-sync board <spec>`. It is silent
|
|
373
|
+
unless Linear already says Done or Cancelled for this issue; when it prints a
|
|
374
|
+
line, relay it once as a warning and **carry on** — you are the one about to hold
|
|
375
|
+
this branch, so the cleanup it names is yours to choose, and nothing here runs it
|
|
376
|
+
or refuses on it.
|
|
377
|
+
|
|
332
378
|
**Refresh the mirror now, without asking.** Run `/spec-push`. The spec has just
|
|
333
379
|
moved to `in-progress/` and been stamped with a developer — two real state
|
|
334
380
|
changes, and the tracker is a generated mirror of them. It costs one engine call
|
|
@@ -398,7 +444,8 @@ destroyed: that skill relays the refusal and offers both ways out. Nothing to do
|
|
|
398
444
|
here beyond knowing it is no longer dead code.
|
|
399
445
|
|
|
400
446
|
A spec ideally arrives `Ready` from `/spec`; a `Draft` works too — sanity-check
|
|
401
|
-
it is well-formed first.
|
|
447
|
+
it is well-formed first. Where the spec keeps no `Status:` header (the tracker
|
|
448
|
+
owns its status), a non-empty **Open questions** section is what marks a Draft.
|
|
402
449
|
|
|
403
450
|
- **Report anything left waiting, and claim none of it.** Ask the engine once:
|
|
404
451
|
|
|
@@ -19,9 +19,12 @@ Read-only. Reports two things and writes nothing:
|
|
|
19
19
|
since the last push? The next push replaces it, so this is worth reading
|
|
20
20
|
first.
|
|
21
21
|
|
|
22
|
-
**Status is not compared
|
|
23
|
-
own transitions and
|
|
24
|
-
theirs to have moved, and push resends State only when the spec itself
|
|
22
|
+
**Status is not compared — with one exception.** Skitterspec tells Linear about
|
|
23
|
+
its own transitions and does not mirror a status back: a card someone moved by
|
|
24
|
+
hand is theirs to have moved, and push resends State only when the spec itself
|
|
25
|
+
changes bucket. The exception is the one difference the repo can act on — the
|
|
26
|
+
issue says Done or Cancelled while the spec is still in flight — which §3c
|
|
27
|
+
asks about, and reports without acting.
|
|
25
28
|
|
|
26
29
|
The repo is the source of truth; Linear is a generated mirror, so there is no
|
|
27
30
|
per-field "conflict" — only "what would the next push send" and "did someone
|
|
@@ -84,6 +87,18 @@ Read-only until `--yes`. Do not attempt the rewrite by hand — the identifiers
|
|
|
84
87
|
live in frontmatter, snapshot filenames and the keys inside those snapshots, and
|
|
85
88
|
a hand edit misses some (it has, twice).
|
|
86
89
|
|
|
90
|
+
## 3c. Has the board finished it?
|
|
91
|
+
|
|
92
|
+
```
|
|
93
|
+
skitterspec spec-sync board <spec>
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Silent unless Linear says Done or Cancelled while this spec is in `backlog` or
|
|
97
|
+
`in-progress`; then one line naming the cleanup (`/spec-complete` or
|
|
98
|
+
`/spec-cancel`). Relay that line as it is.
|
|
99
|
+
**Report it; never offer or run the cleanup** — this skill is read-only, and
|
|
100
|
+
the branch may be someone else's to close. Silence, an unlinked spec and an unreadable issue all say nothing.
|
|
101
|
+
|
|
87
102
|
## 4. Report
|
|
88
103
|
|
|
89
104
|
Relay the engine's output **verbatim, above the block** — it is the answer, and
|
|
@@ -51,6 +51,7 @@ In a project that installs the Linear superset the binary is
|
|
|
51
51
|
| "set my Linear key", "am I authenticated?" | `credentials <status\|set\|unset>` |
|
|
52
52
|
| "who am I in Linear?", "why is it assigning the wrong person?" | `whoami` — `--set` for a shared or bot key |
|
|
53
53
|
| "who's on this team?", "find Jane's user id" | `users <name-or-email>` |
|
|
54
|
+
| "did someone close this on the board?", "is Linear ahead of the repo?" | `board <spec>` — silent unless Linear says Done/Cancelled where the spec is not; relay its cleanup, never run it |
|
|
54
55
|
| push one spec, or "what would push?" | **defer** — see below |
|
|
55
56
|
|
|
56
57
|
**With no argument, run `linked`.** It is the repo-wide overview, it is
|
|
@@ -28,6 +28,11 @@ fast-forward leaves `base == branch`, the operation is
|
|
|
28
28
|
**idempotent and repeatable**: new commits put the branch ahead of base again,
|
|
29
29
|
and you can run `/spec-to-main` as many times as you like.
|
|
30
30
|
|
|
31
|
+
**In PR mode** (`land.strategy: "pr"` in `env.config.json`) the destination is
|
|
32
|
+
the host, not the local base: this skill becomes *push the branch and open or
|
|
33
|
+
update the DRAFT pull request* — same intent (get the work into CI / the shared
|
|
34
|
+
env), new transport. §4b replaces §4 there; everything else holds unchanged.
|
|
35
|
+
|
|
31
36
|
## 0. Preconditions — when this applies
|
|
32
37
|
|
|
33
38
|
- **Isolation must be on** (`specs/.core/env.config.json` exists **and** the spec
|
|
@@ -87,6 +92,19 @@ nothing else.
|
|
|
87
92
|
On a **no-op** ("already landed on `<base>` — nothing to integrate"), just say so
|
|
88
93
|
and continue — the branch has no commits base doesn't already have.
|
|
89
94
|
|
|
95
|
+
**Under a rolling base** (`baseBranchPattern` in `env.config.json`) the plan
|
|
96
|
+
can carry two more things, and both are the engine's to say:
|
|
97
|
+
- a `git -C <mainRepoPath> switch <base>` (or `switch -c … --track`) **first**,
|
|
98
|
+
when the primary checkout still has an older release candidate out — run it
|
|
99
|
+
in order with the rest;
|
|
100
|
+
- a `retarget: forked from <old> · landing onto <new>` line, when the rc
|
|
101
|
+
rolled while this spec was in flight. It is the land working, not a fault:
|
|
102
|
+
relay it verbatim in the `Landed` row so the reader sees where the work went.
|
|
103
|
+
|
|
104
|
+
A refusal naming `no branch matches <pattern>` means no release candidate is
|
|
105
|
+
visible — usually not fetched. Relay it, stop with `⏸`, and name
|
|
106
|
+
`skitterspec spec-env base` (it fetches and lists) as the next step.
|
|
107
|
+
|
|
90
108
|
**Then run the after-land commands.** Where the plan ends with a
|
|
91
109
|
`then, in the primary checkout (<path>), run:` section — the project's
|
|
92
110
|
`afterLand`, such as a data migration — run those commands in that directory,
|
|
@@ -99,6 +117,28 @@ land made elsewhere leaves them pending here.
|
|
|
99
117
|
that failed and the ones that did not run, and it **never undoes the land**.
|
|
100
118
|
No section, nothing to run, and nothing to say about it.
|
|
101
119
|
|
|
120
|
+
## 4b. PR mode — push the branch, keep the PR a draft
|
|
121
|
+
|
|
122
|
+
When the plan's heading reads `(pr)`, run
|
|
123
|
+
`skitterspec spec-env integrate <name> --draft` instead and run what it prints:
|
|
124
|
+
a fetch, a rebase onto `<remote>/<base>`, and — this is the consent gate — the
|
|
125
|
+
push and PR-create under its own `with your consent` section.
|
|
126
|
+
**Ask before pushing**: ask once, plainly, naming the remote and that the PR
|
|
127
|
+
opens as a draft. On a yes, re-run with `--push` added and run the single printed list; on
|
|
128
|
+
a no, relay the held commands and stop — the work is rebased and ready, and the
|
|
129
|
+
user can push it themselves.
|
|
130
|
+
|
|
131
|
+
- **The draft is the point.** A draft cannot be merged and the tracker's
|
|
132
|
+
automations read it as in-progress, so nothing downstream can close the
|
|
133
|
+
ticket early. `/spec-complete` is what flips it to ready.
|
|
134
|
+
- A `pr:` line saying the PR is already open means the push updates it —
|
|
135
|
+
nothing more to create, and that is the repeatable case.
|
|
136
|
+
- **No after-land commands run here.** The plan defers them ("after-land
|
|
137
|
+
commands are deferred: base moves when the host merges") — the completion run
|
|
138
|
+
that follows the merge owns them. §5's re-test on base does not apply either:
|
|
139
|
+
base has not moved; CI on the PR is the check this land exists for.
|
|
140
|
+
- A **rebase conflict** aborts and stops exactly as §4.
|
|
141
|
+
|
|
102
142
|
## 5. Re-test on base, then report
|
|
103
143
|
|
|
104
144
|
- Run the project's test command **from the primary checkout** — base must be
|
|
@@ -111,7 +151,9 @@ No section, nothing to run, and nothing to say about it.
|
|
|
111
151
|
to Complete, `git mv` the spec, or tear down the worktree/stack.
|
|
112
152
|
**The spec stays `In Progress` and the worktree stays put.**
|
|
113
153
|
- It **never pushes** — say the user can `git push` the base branch themselves to
|
|
114
|
-
trigger CI / the shared env.
|
|
154
|
+
trigger CI / the shared env. (PR mode is not an exception to the stance but to
|
|
155
|
+
the mechanics: there the push *is* the land, and it runs only behind §4b's
|
|
156
|
+
explicit consent — never silently.)
|
|
115
157
|
- `Next` points the way forward: `/spec-next` to continue the remaining phases
|
|
116
158
|
(you'll keep committing on the same branch and can `/spec-to-main` again), and
|
|
117
159
|
`/spec-complete` when every phase is genuinely done — it will land the final
|
|
@@ -135,6 +177,10 @@ the shape; this section carries only what is specific here.
|
|
|
135
177
|
skipped because the land matched no `when` — or the one that failed and the ones that did not run. Nothing about it when none are
|
|
136
178
|
configured.
|
|
137
179
|
|
|
180
|
+
`Landed` in PR mode names the host, not the base: `PR #14 (draft) opened` or
|
|
181
|
+
`PR #14 (draft) updated` — and `held — not pushed` when §4b's consent was
|
|
182
|
+
declined, because an unpushed rebase is a true outcome, not a failure.
|
|
183
|
+
|
|
138
184
|
**No `Spec` field, deliberately.** This skill changes no status and moves no
|
|
139
185
|
folder, and a `Spec` line here would read as though it had. The spec stays
|
|
140
186
|
`In Progress` and the worktree stays standing — if that needs saying, the
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skitterbyte/skitterspec-linear",
|
|
3
|
-
"version": "19.
|
|
3
|
+
"version": "19.4.0",
|
|
4
4
|
"description": "Spec-driven development for Claude Code, with one-way Linear sync — a superset of @skitterbyte/skitterspec: the base filesystem workflow plus /spec-status · /spec-push and the spec-sync CLI. The repo is canonical; Linear is a generated mirror. Install this OR the base, not both.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"claude",
|