@skitterbyte/skitterspec-linear 19.11.0 → 19.13.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/README.md +1 -0
- package/assets/core/env.config.md +5 -0
- package/assets/core/linear.config.md +7 -0
- package/assets/rules/spec-planning.md +12 -0
- package/assets/rules/spec-reports.md +15 -0
- package/assets/skills/spec/SKILL.md +30 -0
- package/assets/skills/spec-cancel/SKILL.md +22 -4
- package/assets/skills/spec-complete/SKILL.md +34 -6
- package/assets/skills/spec-idea/SKILL.md +115 -0
- package/assets/skills/spec-init/SKILL.md +3 -2
- package/assets/skills/spec-review/SKILL.md +22 -4
- package/assets/skills/spec-todo/SKILL.md +3 -0
- package/bin/skitterspec-linear.js +8 -0
- package/package.json +1 -1
- package/src/cli.js +81 -27
- package/src/env/config.js +7 -0
- package/src/env/projectguard.js +1 -1
- package/src/env/review.js +66 -1
- package/src/env/reviewers.js +5 -4
- package/src/env/supervise.js +71 -9
- package/src/idea.js +190 -0
- package/src/ideacmd.js +242 -0
- package/src/tada/todo.js +6 -1
- package/src/vendor/linear/api.js +3 -1
- package/src/vendor/linear/cli-sync.js +165 -14
- package/src/vendor/linear/config.js +3 -1
- package/src/vendor/provider-kit/src/apply.js +90 -5
package/README.md
CHANGED
|
@@ -90,6 +90,7 @@ them. Your `specs/` content and live `.core` config are never touched.
|
|
|
90
90
|
| `/spec-cancel` | Record why, stamp the header, tear down |
|
|
91
91
|
| `/spec-tada` | A ta-da list: what you did today, by project and by spec, plus a standup |
|
|
92
92
|
| `/spec-todo` | Where you left off on your last working day, what is open and what is waiting on you |
|
|
93
|
+
| `/spec-idea` | Capture an idea without specing it — in the tracker or `specs/ideas.md` — and list or drop the ones waiting |
|
|
93
94
|
| `/spec-init` | Bootstrap or repair the workflow in a project |
|
|
94
95
|
| `/spec-connect` | Point your canonical `localhost` ports at one spec's stack |
|
|
95
96
|
| `/spec-live` | Check one spec out in the primary checkout, so your running server reloads it |
|
|
@@ -523,6 +523,11 @@ through to a documented conservative default; see the field notes below.
|
|
|
523
523
|
// "local" — you are at the machine holding the page; it binds 127.0.0.1.
|
|
524
524
|
// "remote" — you are not; it binds every interface so the page opens.
|
|
525
525
|
// "detect" — work it out (the default); cannot-tell binds 127.0.0.1.
|
|
526
|
+
// SKITTERSPEC_READER=local|remote in the environment outranks this key: a
|
|
527
|
+
// wrapper that runs the engine on another machine (a VM's `prlctl exec`)
|
|
528
|
+
// speaks for that machine alone. A reader on another machine — this key or
|
|
529
|
+
// that variable set to "remote", or ssh — gets no `local` tier while
|
|
530
|
+
// `network` has a URL, since 127.0.0.1 is the engine's machine.
|
|
526
531
|
// An explicit "local"/"remote" is BELIEVED WITHOUT SNIFFING: you know where
|
|
527
532
|
// you are reading, and no signal outranks being told. Detection is only the
|
|
528
533
|
// default, and it has three outcomes rather than two — local, remote, and
|
|
@@ -708,6 +708,13 @@ could have waited.
|
|
|
708
708
|
miss that production is broken. `/spec-hotfix` checks neither; it is already the
|
|
709
709
|
most specific destination. Leave a list empty and nothing routes through it.
|
|
710
710
|
|
|
711
|
+
## Ideas — `intake.ideaLabel`
|
|
712
|
+
|
|
713
|
+
`/spec-idea` files an idea as an issue in the configured team that carries
|
|
714
|
+
`intake.ideaLabel` (`"idea"` by default) and belongs to no project. The label
|
|
715
|
+
must already exist in the team. `/spec KEY-N` adopts an idea like any other
|
|
716
|
+
issue, and `spec-sync idea drop` moves one to the team's cancelled state.
|
|
717
|
+
|
|
711
718
|
## One direction — nothing to reconcile
|
|
712
719
|
|
|
713
720
|
The repo owns the spec's content and pushes it; nothing is merged back.
|
|
@@ -12,6 +12,7 @@ and lifecycle stay consistent. Each sets a status on the spec header
|
|
|
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/` |
|
|
14
14
|
| `/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) |
|
|
15
|
+
| `/spec-idea` | Capture an idea without specing it — in the tracker when the provider holds ideas, else `specs/ideas.md` on the base branch; bare lists, `--drop` discards. `/spec idea:<id>` or `/spec #N` promotes one | `—` | (none) |
|
|
15
16
|
| `/spec-review` | Re-validate a spec against the codebase; refresh stale parts | `—` | (unchanged) |
|
|
16
17
|
| `/spec-start` | Put a spec in flight — provision its branch, then build phase 1 | `In Progress` | `specs/in-progress/` |
|
|
17
18
|
| `/spec-next` | Build the next phase of the spec this session is in (re-run per phase) | `In Progress` (unchanged) | (unchanged) |
|
|
@@ -74,6 +75,17 @@ branch. Beneath it, `skitterspec spec-env nospec <name>` records the branch —
|
|
|
74
75
|
and that record is what makes a name with nothing under `specs/**` resolvable by
|
|
75
76
|
`review`, `integrate`, `down` and a bare `resolve`.
|
|
76
77
|
|
|
78
|
+
**`/spec-idea` is the door before `/spec`.** `/spec` grills until there is a
|
|
79
|
+
spec, which is right for work and wrong for a passing thought. This skill files
|
|
80
|
+
the thought as it stands, somewhere the team can see. An idea is not a spec,
|
|
81
|
+
so it has no folder, no status and no branch. It lives in the tracker when the
|
|
82
|
+
provider can hold ideas (an issue kept off the board, which `/spec #N` already
|
|
83
|
+
adopts), and otherwise in `specs/ideas.md`. That file is committed straight
|
|
84
|
+
onto the base branch by `skitterspec idea`, using plumbing, so no checkout is
|
|
85
|
+
switched or left dirty, and it is never pushed for you. A configured provider
|
|
86
|
+
that does not declare an idea store is cannot-tell: capture refuses and hands
|
|
87
|
+
the text back, rather than putting one idea in each store.
|
|
88
|
+
|
|
77
89
|
**`/spec-tada` reads, and moves nothing.** It is in the table because it
|
|
78
90
|
reports in the unit the table is about — a spec — but it changes no status,
|
|
79
91
|
writes no file and commits nothing. `skitterspec tada` reads Claude Code's own
|
|
@@ -164,6 +164,21 @@ on. Dropping the line is what left a reader who had walked out of the house with
|
|
|
164
164
|
nothing on screen to tell them a remote page was even possible — they could not
|
|
165
165
|
ask for what they could not see.
|
|
166
166
|
|
|
167
|
+
**One exception: a reader on another machine sees no `local` line.** This is
|
|
168
|
+
the third amendment, and it argues from the rule's own reason. The rule keeps a
|
|
169
|
+
line so the reader can see a door they could ask to have opened. But when the
|
|
170
|
+
engine runs on one machine and the reader is on another — a wrapper running it
|
|
171
|
+
inside a VM, or an ssh session — `127.0.0.1` is the engine's machine, not the
|
|
172
|
+
reader's. That door never opens, whatever anyone asks. It was also first in the
|
|
173
|
+
stack, the link habit reaches for, and it cost a timeout on every review. So the
|
|
174
|
+
engine hides it, on a signal someone set on purpose: `SKITTERSPEC_READER=remote`
|
|
175
|
+
(`local` outranks ssh), the committed `review.reader`, or ssh. It hides it only
|
|
176
|
+
when `network` has a URL to take its place; otherwise the line stays and says
|
|
177
|
+
it is unreachable. Detection decides nothing here, and nor does the skill. A
|
|
178
|
+
tier marked `hidden` in `--json` is absent from the printed stack, so copying
|
|
179
|
+
the stack still produces the right banner. The holding line names the engine's
|
|
180
|
+
`covers` — *the wait covers network* — never a door the stack did not show.
|
|
181
|
+
|
|
167
182
|
**The `network` tier may carry alternates, and they are part of it — not a fourth tier.**
|
|
168
183
|
The engine offers the other addresses this machine has (a
|
|
169
184
|
tailnet one, for a reader off the wifi) as `also:` lines under `network`, each
|
|
@@ -140,6 +140,36 @@ it happens differs (`/spec` writes the spec in Phase B, `/spec-bug` in its step
|
|
|
140
140
|
somewhere". The comment is the answer, and the other half is the spec's own
|
|
141
141
|
**Problem** (or **Symptom**) section quoting the reporter.
|
|
142
142
|
|
|
143
|
+
## Phase 0b — start from an idea (only when asked)
|
|
144
|
+
|
|
145
|
+
**Only when the invocation names an idea** with `idea:<id>`, a handle that
|
|
146
|
+
`/spec-idea` lists for an idea kept in `specs/ideas.md`. An idea kept in the
|
|
147
|
+
tracker is an ordinary issue, so `/spec #N` adopts it through Phase 0 above,
|
|
148
|
+
and nothing here applies to it.
|
|
149
|
+
|
|
150
|
+
1. **Read it.** Run `skitterspec idea list --json` and find the entry whose
|
|
151
|
+
`id` matches. If none does, **stop** and say so: an id that matches nothing
|
|
152
|
+
is never stood in for by the nearest one.
|
|
153
|
+
2. **Seed, don't skip, the grill.** The idea's title becomes the working spec
|
|
154
|
+
title, and its body becomes the starting material for **Problem**. Quote it
|
|
155
|
+
rather than paraphrasing it away. An idea is a thought, not a groomed
|
|
156
|
+
requirement, so grill it as hard as anything else.
|
|
157
|
+
3. **Retire it once the spec exists — never before.** The idea is dropped
|
|
158
|
+
after the spec reaches somewhere it can be found. With isolation, that is
|
|
159
|
+
once a committing verdict has committed it (and landed it, under
|
|
160
|
+
`"trunk"`). Without isolation, it is once the spec is written. Run:
|
|
161
|
+
|
|
162
|
+
```
|
|
163
|
+
skitterspec idea drop <id> --reason "promoted to <spec-name>"
|
|
164
|
+
```
|
|
165
|
+
|
|
166
|
+
It commits onto the base branch by itself, so it needs no pathspec and has
|
|
167
|
+
no part in the spec's own commit. A drop that is refused leaves the idea
|
|
168
|
+
listed. Say so in `Notes` and carry on: a stale idea is a nuisance, but a
|
|
169
|
+
lost one is the failure this exists to prevent.
|
|
170
|
+
**A run that writes no spec drops nothing** — a `⏸` grill and a
|
|
171
|
+
`discuss` verdict both leave the idea where it was.
|
|
172
|
+
|
|
143
173
|
## Phase A — reach a clear shared understanding (grill first)
|
|
144
174
|
|
|
145
175
|
Interview the user until requirement AND proposed solution are unambiguous. Do
|
|
@@ -96,10 +96,20 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
|
|
|
96
96
|
and **finish the operation anyway**. The spec is complete/cancelled/reviewed in
|
|
97
97
|
the repo regardless; the mirror is disposable and the next push repairs it.
|
|
98
98
|
Do not roll anything back, and do not stop to ask.
|
|
99
|
-
- **In `/spec-complete`'s PR mode
|
|
100
|
-
|
|
101
|
-
|
|
102
|
-
|
|
99
|
+
- **In `/spec-complete`'s PR mode the Done waits for run 2.** Run 1 readies a
|
|
100
|
+
PR, and a ready PR is not a merged one. Which run pushes depends on the
|
|
101
|
+
`land.specDocs` lane:
|
|
102
|
+
- **`trunk`** — skip it on run 1. Run 2 moves the spec on base, so it pushes
|
|
103
|
+
there in this step's usual place, before its own commit.
|
|
104
|
+
- **`branch`** — run 1 commits the move to ride the PR, so push **here**,
|
|
105
|
+
holding the state: `spec-sync apply <spec> --plan <file> --hold-state`.
|
|
106
|
+
Everything but the Done goes now, and the snapshot is written as if the
|
|
107
|
+
Done had gone too, so it rides the PR. Run 2 sends it once the host has
|
|
108
|
+
merged: `spec-sync apply <spec> --send-held`, which needs no plan and
|
|
109
|
+
leaves the snapshot untouched. Over MCP, apply by hand and end run 1 with
|
|
110
|
+
`spec-sync record <spec> --held`.
|
|
111
|
+
|
|
112
|
+
The tracker's Done lands when the work does.
|
|
103
113
|
- **Say what happened** in the skill's report: mirror updated, skipped as
|
|
104
114
|
unlinked, or failed with the reason.
|
|
105
115
|
- **There is no unassign step, and that is not an omission.** Where the repo owns
|
|
@@ -123,6 +133,14 @@ In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
|
|
|
123
133
|
snapshot under `specs/.core/`. Push after the commit instead and both are left
|
|
124
134
|
uncommitted, which makes `spec-env integrate` refuse to land the branch.
|
|
125
135
|
|
|
136
|
+
**PR mode keeps both halves by splitting the push across the runs.** In the
|
|
137
|
+
`branch` lane the commit happens in run 1, and run 2 only has the base branch,
|
|
138
|
+
where nothing is left to commit a snapshot to. An unsplit push there left a
|
|
139
|
+
modified snapshot on base after every completion. `--hold-state` writes run 2's
|
|
140
|
+
snapshot in run 1, and `--send-held` then moves only the state. If it says
|
|
141
|
+
nothing was held (a run 1 from before this), it sends the whole plan and names
|
|
142
|
+
the snapshot it leaves modified. Relay that line.
|
|
143
|
+
|
|
126
144
|
The snapshot is reached **by name**, not by breadth. It is a declared
|
|
127
145
|
`spec.companionPaths` entry (`specs/.core/linear-base/{identifier}.base.json`),
|
|
128
146
|
so `spec-env stage` returns it among this spec's owned paths and the commit below
|
|
@@ -177,10 +177,20 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
|
|
|
177
177
|
and **finish the operation anyway**. The spec is complete/cancelled/reviewed in
|
|
178
178
|
the repo regardless; the mirror is disposable and the next push repairs it.
|
|
179
179
|
Do not roll anything back, and do not stop to ask.
|
|
180
|
-
- **In `/spec-complete`'s PR mode
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
180
|
+
- **In `/spec-complete`'s PR mode the Done waits for run 2.** Run 1 readies a
|
|
181
|
+
PR, and a ready PR is not a merged one. Which run pushes depends on the
|
|
182
|
+
`land.specDocs` lane:
|
|
183
|
+
- **`trunk`** — skip it on run 1. Run 2 moves the spec on base, so it pushes
|
|
184
|
+
there in this step's usual place, before its own commit.
|
|
185
|
+
- **`branch`** — run 1 commits the move to ride the PR, so push **here**,
|
|
186
|
+
holding the state: `spec-sync apply <spec> --plan <file> --hold-state`.
|
|
187
|
+
Everything but the Done goes now, and the snapshot is written as if the
|
|
188
|
+
Done had gone too, so it rides the PR. Run 2 sends it once the host has
|
|
189
|
+
merged: `spec-sync apply <spec> --send-held`, which needs no plan and
|
|
190
|
+
leaves the snapshot untouched. Over MCP, apply by hand and end run 1 with
|
|
191
|
+
`spec-sync record <spec> --held`.
|
|
192
|
+
|
|
193
|
+
The tracker's Done lands when the work does.
|
|
184
194
|
- **Say what happened** in the skill's report: mirror updated, skipped as
|
|
185
195
|
unlinked, or failed with the reason.
|
|
186
196
|
- **There is no unassign step, and that is not an omission.** Where the repo owns
|
|
@@ -204,6 +214,14 @@ In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
|
|
|
204
214
|
snapshot under `specs/.core/`. Push after the commit instead and both are left
|
|
205
215
|
uncommitted, which makes `spec-env integrate` refuse to land the branch.
|
|
206
216
|
|
|
217
|
+
**PR mode keeps both halves by splitting the push across the runs.** In the
|
|
218
|
+
`branch` lane the commit happens in run 1, and run 2 only has the base branch,
|
|
219
|
+
where nothing is left to commit a snapshot to. An unsplit push there left a
|
|
220
|
+
modified snapshot on base after every completion. `--hold-state` writes run 2's
|
|
221
|
+
snapshot in run 1, and `--send-held` then moves only the state. If it says
|
|
222
|
+
nothing was held (a run 1 from before this), it sends the whole plan and names
|
|
223
|
+
the snapshot it leaves modified. Relay that line.
|
|
224
|
+
|
|
207
225
|
The snapshot is reached **by name**, not by breadth. It is a declared
|
|
208
226
|
`spec.companionPaths` entry (`specs/.core/linear-base/{identifier}.base.json`),
|
|
209
227
|
so `spec-env stage` returns it among this spec's owned paths and the commit below
|
|
@@ -478,6 +496,10 @@ person happens before the ready, in this order:
|
|
|
478
496
|
— run 2 moves it on base after the merge; under `branch` commit the move on
|
|
479
497
|
the branch *before* step 3 so it rides the PR. Either way
|
|
480
498
|
**the tracker's Done waits for run 2**: a ready PR is not a merged one.
|
|
499
|
+
Under `branch` the §4 tracker step still runs here, but holding the state
|
|
500
|
+
(`--hold-state`, as the step says), so the snapshot run 2 would write is in
|
|
501
|
+
the commit that rides the PR. Otherwise run 2 leaves it modified on the base
|
|
502
|
+
branch, where nothing is left to commit it to.
|
|
481
503
|
5. **Stop, keeping the worktree.** Report
|
|
482
504
|
`Landed: PR #N opened — finish after merge` (or `ready`), spec
|
|
483
505
|
`In Progress`, worktree standing. No afterLand runs — the plan deferred it
|
|
@@ -487,13 +509,19 @@ person happens before the ready, in this order:
|
|
|
487
509
|
**Run 2 — after the host merges.** `integrate` recognises the landed branch
|
|
488
510
|
(ancestry or the host's answer) and prints the finish: catch local base up and
|
|
489
511
|
the deferred `afterLand` with the land's own range. Run those, then do what run
|
|
490
|
-
1 deferred — the §4 move (trunk lane) with its State log row and commit,
|
|
491
|
-
|
|
512
|
+
1 deferred — the §4 move (trunk lane) with its State log row and commit, or
|
|
513
|
+
under `branch` the held state alone (`--send-held`, which writes nothing to the
|
|
514
|
+
tree), the §5 report — then **§7 teardown runs as normal**:
|
|
492
515
|
a host-merged branch counts as landed (squash and rebase
|
|
493
516
|
merges included), and a host that auto-deleted the branch makes the remote
|
|
494
517
|
delete an already-gone no-op, never a failure. Re-test on base before calling
|
|
495
518
|
it done, exactly as 6-feature/bug step 4.
|
|
496
519
|
|
|
520
|
+
Where `--send-held` reports that nothing was held — a run 1 from before the
|
|
521
|
+
hold existed — it has sent the whole plan, and its line names the snapshot it
|
|
522
|
+
left modified on base. Put that in the report's `Notes`: only the operator can
|
|
523
|
+
choose where that file goes.
|
|
524
|
+
|
|
497
525
|
## 7. Tear down the environment (opt-in, only if configured)
|
|
498
526
|
|
|
499
527
|
**A hotfix is torn down later, by `hotfix finish`.**
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec-idea
|
|
3
|
+
description: Capture an idea for a future spec without specing it — one step, no grilling — somewhere the team can see it (the tracker when a provider holds ideas, else specs/ideas.md on the base branch). Bare, it lists the ideas waiting; --drop discards one. Use when the user says "/spec-idea", "note this idea", "park this for later", "add to the ideas list", "what ideas do we have", or wants to get a thought down without writing a spec.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /spec-idea — capture now, spec later
|
|
7
|
+
|
|
8
|
+
> Stay silent while this runs — speak only to ask something you cannot answer
|
|
9
|
+
> yourself, or to report a failure at the moment it happens. Read
|
|
10
|
+
> `.claude/rules/spec-reports.md` before reporting; it defines the block this
|
|
11
|
+
> skill ends with.
|
|
12
|
+
|
|
13
|
+
`/spec` grills until there is a spec. That is right for work and wrong for a
|
|
14
|
+
passing thought, which then gets specced too early or not written down at all.
|
|
15
|
+
This skill is the other door: it files the thought as it stands, and the grill
|
|
16
|
+
happens later, when someone promotes it with `/spec`.
|
|
17
|
+
|
|
18
|
+
**The engine decides where an idea lives — never you.** `skitterspec idea`
|
|
19
|
+
uses the tracker when the installed provider holds ideas (an issue kept off the
|
|
20
|
+
board), and `specs/ideas.md` on the base branch when there is no provider or
|
|
21
|
+
the provider says it cannot. A configured provider that says nothing is
|
|
22
|
+
cannot-tell, and the engine refuses rather than splitting ideas across two
|
|
23
|
+
stores. Relay what it decided; do not second-guess it.
|
|
24
|
+
|
|
25
|
+
## 1. Pick the mode from the arguments
|
|
26
|
+
|
|
27
|
+
| Invocation | Mode |
|
|
28
|
+
|------------|------|
|
|
29
|
+
| `/spec-idea <text>` | capture |
|
|
30
|
+
| `/spec-idea` (bare), "what ideas do we have" | list |
|
|
31
|
+
| `/spec-idea --drop <ref> [reason]` | drop |
|
|
32
|
+
|
|
33
|
+
## 2. Capture
|
|
34
|
+
|
|
35
|
+
**Ask nothing by default.** Getting the thought out of someone's head is the
|
|
36
|
+
whole point, and every question is a reason not to bother.
|
|
37
|
+
|
|
38
|
+
**One judgement, made once.** Read the text. If it is asking for design rather
|
|
39
|
+
than recording a thought — questions addressed to you, "suggestions welcome",
|
|
40
|
+
several alternatives left open for someone to weigh — it wants the grill now.
|
|
41
|
+
Offer the choice once, with a picker:
|
|
42
|
+
|
|
43
|
+
- **Grill it now with `/spec`.** Invoke `/spec` and seed it with the text. The
|
|
44
|
+
idea is not filed, because the spec will record it.
|
|
45
|
+
- **File it as an idea.** File it exactly as typed.
|
|
46
|
+
|
|
47
|
+
A short or rough thought is not a design question. When in doubt, file it: an
|
|
48
|
+
idea can always be promoted, but a grill that nobody asked for is the cost this
|
|
49
|
+
skill exists to remove.
|
|
50
|
+
|
|
51
|
+
To file it, pass the text as **one argument**, newlines included. The first
|
|
52
|
+
line becomes the title and the rest becomes the body:
|
|
53
|
+
|
|
54
|
+
```
|
|
55
|
+
skitterspec idea add "<text>" --json
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
**Never push.** On the file store the engine commits onto the base branch and
|
|
59
|
+
prints the push instead of running it, because a push publishes the base
|
|
60
|
+
branch and that is always the operator's call.
|
|
61
|
+
|
|
62
|
+
**A refused capture loses nothing.** The engine prints the text back. Put it in
|
|
63
|
+
the `Why` row verbatim so the user can copy it.
|
|
64
|
+
|
|
65
|
+
## 3. List
|
|
66
|
+
|
|
67
|
+
```
|
|
68
|
+
skitterspec idea list
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Relay the ideas as a table in the body of the message, one row per idea:
|
|
72
|
+
title, date, and the handle that promotes it. That is `/spec idea:<id>` for a
|
|
73
|
+
file idea, and `/spec #N` (or the provider's own reference) for a tracker idea.
|
|
74
|
+
An empty list is an answer, so say it is empty.
|
|
75
|
+
|
|
76
|
+
## 4. Drop
|
|
77
|
+
|
|
78
|
+
```
|
|
79
|
+
skitterspec idea drop <ref> --reason "<reason>"
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
Pass the reason when one was given. **Do not ask for one** — dropping a
|
|
83
|
+
thought should cost no more than having it. On the tracker the idea is closed
|
|
84
|
+
as not planned. In the file the entry is removed and the reason goes in the
|
|
85
|
+
commit, where git keeps it.
|
|
86
|
+
|
|
87
|
+
## Promotion is `/spec`'s, not this skill's
|
|
88
|
+
|
|
89
|
+
`/spec idea:<id>` or `/spec #N` turns an idea into a spec. It seeds the grill
|
|
90
|
+
from the idea and retires the idea once the spec exists. This skill never
|
|
91
|
+
writes a spec.
|
|
92
|
+
|
|
93
|
+
## Report
|
|
94
|
+
|
|
95
|
+
End with the block defined in `.claude/rules/spec-reports.md`. That file carries
|
|
96
|
+
the shape; this section carries only what is specific here. In list mode the
|
|
97
|
+
table of ideas is the body of the message, and the block follows it.
|
|
98
|
+
|
|
99
|
+
**Verdicts**
|
|
100
|
+
|
|
101
|
+
- `✅` — an idea was filed or dropped, or the list was read (an empty list
|
|
102
|
+
included).
|
|
103
|
+
- `⏸` — the engine refused, so nothing was written. Name the reason in `Why`,
|
|
104
|
+
with the text when it was a capture.
|
|
105
|
+
- Handing off to `/spec` emits no block here: that skill ends with its own.
|
|
106
|
+
|
|
107
|
+
**Fields:** `Tracker` · `Built` · `Landed` · `Follow-ups` · `Next`
|
|
108
|
+
|
|
109
|
+
`Tracker` is the idea's issue, when the provider holds it. `Built` is what
|
|
110
|
+
happened: the idea's id and title, where it went, or the count listed.
|
|
111
|
+
`Landed` covers the file store only: the commit on the base branch and
|
|
112
|
+
`not pushed · <the push it printed> publishes it`. `Next` is the handle that
|
|
113
|
+
promotes the idea (`/spec idea:<id>`, `/spec #N`), or `none` after a drop.
|
|
114
|
+
|
|
115
|
+
**`Follow-ups` is always `none` here.** An idea is the follow-up.
|
|
@@ -27,7 +27,7 @@ clobber customised content. Finish with a summary of created vs already-present.
|
|
|
27
27
|
> **Leave alone**. Non-interactively it only adds what's missing; `--resync` /
|
|
28
28
|
> `--reset` (reset needs `--yes`) drive the stronger actions.
|
|
29
29
|
|
|
30
|
-
The system is **
|
|
30
|
+
The system is **eighteen skills**: `spec` (feature, chore or issue), `spec-bug` (bug),
|
|
31
31
|
`spec-hotfix` (a bug fixed on a released tag),
|
|
32
32
|
`spec-incident` (a live outage, recorded as it happens),
|
|
33
33
|
`no-spec` (work that genuinely has none — off the base branch all the same),
|
|
@@ -36,7 +36,8 @@ The system is **seventeen skills**: `spec` (feature, chore or issue), `spec-bug`
|
|
|
36
36
|
`spec-reviewed` (pick up a review you approved on that page),
|
|
37
37
|
`spec-epic-next` (name the epic member that can start now), `spec-to-main`,
|
|
38
38
|
`spec-complete`, `spec-cancel`, `spec-tada` (a ta-da list of what got done),
|
|
39
|
-
`spec-todo` (where you left off, and what is ahead),
|
|
39
|
+
`spec-todo` (where you left off, and what is ahead), `spec-idea` (an idea
|
|
40
|
+
parked without a spec),
|
|
40
41
|
and this `spec-init`. The lifecycle is `backlog → in-progress → complete / cancelled`,
|
|
41
42
|
with `.core` holding always-apply project rules.
|
|
42
43
|
|
|
@@ -146,10 +146,20 @@ Linear API key is set (see `apply.transport` in `linear.config.md`).
|
|
|
146
146
|
and **finish the operation anyway**. The spec is complete/cancelled/reviewed in
|
|
147
147
|
the repo regardless; the mirror is disposable and the next push repairs it.
|
|
148
148
|
Do not roll anything back, and do not stop to ask.
|
|
149
|
-
- **In `/spec-complete`'s PR mode
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
149
|
+
- **In `/spec-complete`'s PR mode the Done waits for run 2.** Run 1 readies a
|
|
150
|
+
PR, and a ready PR is not a merged one. Which run pushes depends on the
|
|
151
|
+
`land.specDocs` lane:
|
|
152
|
+
- **`trunk`** — skip it on run 1. Run 2 moves the spec on base, so it pushes
|
|
153
|
+
there in this step's usual place, before its own commit.
|
|
154
|
+
- **`branch`** — run 1 commits the move to ride the PR, so push **here**,
|
|
155
|
+
holding the state: `spec-sync apply <spec> --plan <file> --hold-state`.
|
|
156
|
+
Everything but the Done goes now, and the snapshot is written as if the
|
|
157
|
+
Done had gone too, so it rides the PR. Run 2 sends it once the host has
|
|
158
|
+
merged: `spec-sync apply <spec> --send-held`, which needs no plan and
|
|
159
|
+
leaves the snapshot untouched. Over MCP, apply by hand and end run 1 with
|
|
160
|
+
`spec-sync record <spec> --held`.
|
|
161
|
+
|
|
162
|
+
The tracker's Done lands when the work does.
|
|
153
163
|
- **Say what happened** in the skill's report: mirror updated, skipped as
|
|
154
164
|
unlinked, or failed with the reason.
|
|
155
165
|
- **There is no unassign step, and that is not an omission.** Where the repo owns
|
|
@@ -173,6 +183,14 @@ In `/spec-complete` and `/spec-cancel` this step is deliberately pinned
|
|
|
173
183
|
snapshot under `specs/.core/`. Push after the commit instead and both are left
|
|
174
184
|
uncommitted, which makes `spec-env integrate` refuse to land the branch.
|
|
175
185
|
|
|
186
|
+
**PR mode keeps both halves by splitting the push across the runs.** In the
|
|
187
|
+
`branch` lane the commit happens in run 1, and run 2 only has the base branch,
|
|
188
|
+
where nothing is left to commit a snapshot to. An unsplit push there left a
|
|
189
|
+
modified snapshot on base after every completion. `--hold-state` writes run 2's
|
|
190
|
+
snapshot in run 1, and `--send-held` then moves only the state. If it says
|
|
191
|
+
nothing was held (a run 1 from before this), it sends the whole plan and names
|
|
192
|
+
the snapshot it leaves modified. Relay that line.
|
|
193
|
+
|
|
176
194
|
The snapshot is reached **by name**, not by breadth. It is a declared
|
|
177
195
|
`spec.companionPaths` entry (`specs/.core/linear-base/{identifier}.base.json`),
|
|
178
196
|
so `spec-env stage` returns it among this spec's owned paths and the commit below
|
|
@@ -46,6 +46,9 @@ What the lines mean:
|
|
|
46
46
|
- `finished:` — the specs that day completed or cancelled, by name.
|
|
47
47
|
- `blocked:` — a review verdict waiting, or a gate armed by a phase that ended
|
|
48
48
|
and still owes an answer. Read only for specs in flight.
|
|
49
|
+
- `ideas:` — how many ideas are waiting for the `(here)` project. It is a count,
|
|
50
|
+
never the next action: `/spec-idea` lists them, and the line is absent when
|
|
51
|
+
there are none or the count could not be read.
|
|
49
52
|
- `today:` — commits and moves since midnight, when there are any.
|
|
50
53
|
|
|
51
54
|
## 2. Write the recap
|
|
@@ -45,6 +45,14 @@ require('../src/env/config.js').setProviderEnvDefaults(
|
|
|
45
45
|
require('../src/env/config.js').setProviderConfigFile(
|
|
46
46
|
require('../src/vendor/linear/config.js').CONFIG_FILE,
|
|
47
47
|
)
|
|
48
|
+
// Linear holds ideas: an issue carrying `intake.ideaLabel`, in no project.
|
|
49
|
+
// Registered so `skitterspec idea` hands Linear the command instead of writing
|
|
50
|
+
// specs/ideas.md (see common src/idea.js, selectStore).
|
|
51
|
+
require('../src/idea.js').setProviderIdeaStore({
|
|
52
|
+
supports: true,
|
|
53
|
+
run: (sub, argv, { cwd, out } = {}) =>
|
|
54
|
+
require('../src/vendor/linear/cli-sync.js').specSync(['idea', sub, ...argv], { cwd, out }),
|
|
55
|
+
})
|
|
48
56
|
const {
|
|
49
57
|
PROVIDER_COMMANDS,
|
|
50
58
|
providerHelpSection,
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skitterbyte/skitterspec-linear",
|
|
3
|
-
"version": "19.
|
|
3
|
+
"version": "19.13.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",
|