@skitterbyte/skitterspec-linear 19.10.0 → 19.12.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 CHANGED
@@ -89,11 +89,14 @@ them. Your `specs/` content and live `.core` config are never touched.
89
89
  | `/spec-complete` | Verify, land, tear down |
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
+ | `/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 |
92
94
  | `/spec-init` | Bootstrap or repair the workflow in a project |
93
95
  | `/spec-connect` | Point your canonical `localhost` ports at one spec's stack |
94
96
  | `/spec-live` | Check one spec out in the primary checkout, so your running server reloads it |
95
97
  | `/spec-remote-review` | Permit (or forbid) reviewing from off your network |
96
98
  | `/allow-main` | Allow writes on the base branch for this session — yours to run, never Claude's |
99
+ | `/allow-project` | Let this session work on another skitterspec project — yours to run, never Claude's |
97
100
  | `/spec-skip` | Move on from a phase without a verdict, reason recorded — yours to run, never Claude's |
98
101
  | `/spec-epic` | What every member of an epic needs next, in which tab, and the epic page |
99
102
  | `/spec-push` | Repo → Linear, one-way |
@@ -20,9 +20,15 @@ every phase. **`skitterspec status`** lists what is in flight across worktrees.
20
20
  At the end of the day, **`/spec-tada`** is the ta-da list: what you did across
21
21
  every project, grouped by spec — what landed, what was explored, what is still
22
22
  in flight — ending in a three-line standup (`skitterspec tada` is the engine).
23
- It covers the projects that share this one's `project.category`;
23
+ It covers the projects that share this one's `project.category`, leads with
24
+ the day's wins, and names only this project's work as the thing to do next;
24
25
  **`skitterspec project`** shows and sets the name and category, and
25
- `/spec-init` asks for both.
26
+ `/spec-init` asks for both. In the morning, **`/spec-todo`** answers the other
27
+ question: where each project was left on your last working day, what is
28
+ waiting on you, and what to pick up first. Both read across projects, and
29
+ neither acts on one: a session works on the project it was started in, and a
30
+ hook refuses its writes and lifecycle commands anywhere else until you type
31
+ `/allow-project <name>`.
26
32
 
27
33
  **Handing the review back.** The page takes marks: tick `✓ accept` per file as
28
34
  you read, note anything against a line or a whole file, answer the questions a
@@ -0,0 +1,28 @@
1
+ ---
2
+ description: Let this session work on another skitterspec project — name it (or its path); `off` guards it again
3
+ argument-hint: "<project> [off]"
4
+ allowed-tools: Bash({{exec}} skitterspec spec-env project allow:*)
5
+ disable-model-invocation: true
6
+ ---
7
+ !`{{exec}} skitterspec spec-env project allow $ARGUMENTS`
8
+
9
+ Relay the engine output above verbatim. Add nothing and run nothing else.
10
+
11
+ **Only you can run this, and that is the whole guard.** The project-guard hook
12
+ refuses a write, a `git` change or a `skitterspec` lifecycle command aimed at a
13
+ skitterspec project other than the one this session was started in. Its refusal
14
+ names two exits: open a session in that project and do the work there, or have
15
+ you lift the guard. Claude can take the first and can never take the second — a
16
+ guard the model can lift is decoration, which is the line `/allow-main` draws.
17
+
18
+ **Name the project the refusal named.** `/allow-project ereqs` lifts it for that
19
+ folder name; a path (`/allow-project ../ereqs`) pins it to that exact repo.
20
+
21
+ **It lapses with the session.** The lift is recorded against this session, so
22
+ a new session is guarded again. Where the harness exposes no session id it
23
+ degrades to a repo-wide lift that lasts until `/allow-project <project> off`;
24
+ the engine says which kind you got.
25
+
26
+ **It is machine-local and gitignored.** The project-wide switch is
27
+ `guards.projectBoundary` in `specs/.core/env.config.json`, and turning that off
28
+ is a different, committed decision.
@@ -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|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` CLI is
8
+ <up|bootstrap|nospec|main|project|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
@@ -376,9 +376,17 @@ through to a documented conservative default; see the field notes below.
376
376
  // blocks when the commits are ALSO unmerged into the base branch — a branch
377
377
  // already landed on base tears down (and its branch is deleted) without
378
378
  // --force, even with no remote.
379
+ //
380
+ // `projectBoundary` (default true): a session works on the project it was
381
+ // started in. The project-guard hook refuses a write, a git change or a
382
+ // skitterspec lifecycle command aimed at ANOTHER skitterspec project (a
383
+ // checkout with specs/.core/); reads and every other program pass. The user
384
+ // lifts it for one session with /allow-project <name>; false turns it off
385
+ // for this project. Its sibling `mainIsLandingZone` is the main guard's switch.
379
386
  "guards": {
380
387
  "refuseTeardownIfDirty": true,
381
- "refuseTeardownIfUnpushed": true
388
+ "refuseTeardownIfUnpushed": true,
389
+ "projectBoundary": true
382
390
  },
383
391
 
384
392
  // What teardown cleans up beyond this machine. Nothing publishes a spec
@@ -416,8 +424,26 @@ through to a documented conservative default; see the field notes below.
416
424
  // Under `land.strategy: "pr"` take fetches and rebases onto
417
425
  // `<land.remote>/<base>`, since local base moves only when you pull; a
418
426
  // failed fetch falls back to local base and says so.
427
+ //
428
+ // `afterSwitch` is `afterLand`'s grammar — a string, `{ "run", "when" }`, or
429
+ // `{ "setup": true }` — run in the PRIMARY checkout after `live take` checks
430
+ // the branch out, and again after `live release` switches back. Both decide
431
+ // `when` against the same files (what the branch changes from base), since
432
+ // release reverts what take brought in. Unlike `afterLand` the ENGINE runs
433
+ // these, because `/spec-live` and the page's live action have no caller turn
434
+ // to run anything after them: output is captured, the first failure stops the
435
+ // list with the tail of its output, and the switch is never undone.
436
+ // A separate list, not `afterLand`, because `afterLand` may hold a data
437
+ // migration, which must never run for a branch that has not landed:
438
+ //
439
+ // "afterSwitch": [{ "setup": true }]
440
+ //
441
+ // [] (or absent) = none, and take and release print what they always did. It
442
+ // does not replace the "restart your dev server" warning — an install is not
443
+ // a restart.
419
444
  "live": {
420
- "migrations": []
445
+ "migrations": [],
446
+ "afterSwitch": []
421
447
  },
422
448
 
423
449
  // Hotfix landing (`spec-env hotfix land` / `/spec-complete` on a Type: Hotfix
@@ -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.
@@ -0,0 +1,161 @@
1
+ #!/usr/bin/env node
2
+ 'use strict'
3
+
4
+ /**
5
+ * Project guard — the harness half.
6
+ *
7
+ * A session belongs to the project it was started in. The skills say so, and a
8
+ * skill is prose: a report that ends on another repo's `/spec-complete` reads
9
+ * as an instruction, and nothing in prose stops a session `cd`-ing over there
10
+ * and doing it. So the rule is also enforced one level down, where a write or a
11
+ * shell command is a tool call the harness has to ask about first.
12
+ *
13
+ * WHAT IT GUARDS: a write tool whose path lands in another skitterspec project,
14
+ * and a Bash command that runs `git` (to change something) or the engine there.
15
+ * Reads, and every other program, pass.
16
+ *
17
+ * THIS SCRIPT DECIDES NOTHING. It hands the call to `spec-env project check`
18
+ * and turns one exit status into an answer, for `main-guard.cjs`'s reason: a
19
+ * hook with its own opinions is a second implementation nothing can test.
20
+ *
21
+ * HOME IS THIS SCRIPT'S PROJECT, NOT THE SESSION'S DIRECTORY. `cwd` is wherever
22
+ * the session has `cd`-ed to — which is exactly the thing being judged — so the
23
+ * project this hook was installed into is the one the session belongs to.
24
+ *
25
+ * IT FAILS OPEN, EVERYWHERE: no engine, an unreadable payload, a crash, a
26
+ * timeout. Being wrong the permissive way costs one act the skills also warn
27
+ * against; being wrong the other way stops ordinary work with no reason given.
28
+ */
29
+
30
+ const fs = require('node:fs')
31
+ const path = require('node:path')
32
+ const { spawnSync } = require('node:child_process')
33
+
34
+ function allow() {
35
+ process.exit(0)
36
+ }
37
+
38
+ // The JSON route rather than exit-2, so the reason reaches Claude — who has to
39
+ // act on it by leaving the work to a session in that project.
40
+ function deny(reason) {
41
+ process.stdout.write(
42
+ JSON.stringify({
43
+ hookSpecificOutput: {
44
+ hookEventName: 'PreToolUse',
45
+ permissionDecision: 'deny',
46
+ permissionDecisionReason: reason,
47
+ },
48
+ }) + '\n',
49
+ )
50
+ process.exit(0)
51
+ }
52
+
53
+ function readPayload() {
54
+ try {
55
+ const parsed = JSON.parse(fs.readFileSync(0, 'utf8'))
56
+ return parsed && typeof parsed === 'object' ? parsed : null
57
+ } catch {
58
+ return null
59
+ }
60
+ }
61
+
62
+ // Identical to `main-guard.cjs`'s, deliberately — see the reasons there.
63
+ const ENGINES = ['skitterspec', 'skitterspec-linear', 'skitterspec-jira', 'skitterspec-github', 'skitterspec-azure-boards']
64
+
65
+ function findEngine(projectDir, platform = process.platform) {
66
+ if (process.env.SKITTERSPEC_BIN) return process.env.SKITTERSPEC_BIN
67
+ let at = projectDir
68
+ for (let i = 0; i < 6 && at; i++) {
69
+ for (const name of ENGINES) {
70
+ const candidate =
71
+ platform === 'win32'
72
+ ? path.join(at, 'node_modules', '@skitterbyte', name, 'bin', `${name}.js`)
73
+ : path.join(at, 'node_modules', '.bin', name)
74
+ if (fs.existsSync(candidate)) return candidate
75
+ }
76
+ const up = path.dirname(at)
77
+ if (up === at) break
78
+ at = up
79
+ }
80
+ return 'skitterspec'
81
+ }
82
+
83
+ function engineCommand(projectDir, platform = process.platform) {
84
+ const engine = findEngine(projectDir, platform)
85
+ return /\.[cm]?js$/i.test(engine) ? { file: process.execPath, args: [engine] } : { file: engine, args: [] }
86
+ }
87
+
88
+ const WRITE_TOOLS = new Set(['Edit', 'Write', 'NotebookEdit', 'MultiEdit'])
89
+
90
+ function writeTarget(input) {
91
+ if (!input || typeof input !== 'object') return null
92
+ for (const key of ['file_path', 'notebook_path']) {
93
+ if (typeof input[key] === 'string' && input[key]) return input[key]
94
+ }
95
+ return null
96
+ }
97
+
98
+ // A command that cannot be one the guard is about — no git, no engine — is let
99
+ // through without starting the engine at all. This hook fires on every Bash
100
+ // call, and most of them are neither.
101
+ function mayConcern(command) {
102
+ return /\bgit\b|skitterspec/.test(command)
103
+ }
104
+
105
+ // Inside the home checkout itself: certainly home, no engine needed. A
106
+ // worktree lives elsewhere, so a path outside this is still asked about.
107
+ function insideHome(home, target) {
108
+ const rel = path.relative(home, path.resolve(home, target))
109
+ return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel))
110
+ }
111
+
112
+ function isRefusal(stdout) {
113
+ return /^spec-env project: /m.test(stdout || '')
114
+ }
115
+
116
+ function homeDir() {
117
+ // `${CLAUDE_PROJECT_DIR}` is the project the harness started in; the script's
118
+ // own location is the same answer when it is not set.
119
+ return process.env.CLAUDE_PROJECT_DIR || path.resolve(__dirname, '..', '..')
120
+ }
121
+
122
+ function main() {
123
+ const payload = readPayload()
124
+ if (!payload) allow()
125
+
126
+ const home = homeDir()
127
+ const cwd = typeof payload.cwd === 'string' && payload.cwd ? payload.cwd : process.cwd()
128
+ const session = typeof payload.session_id === 'string' ? payload.session_id : ''
129
+ const argv = ['spec-env', 'project', 'check', '--dir', home, '--cwd', cwd]
130
+
131
+ if (WRITE_TOOLS.has(payload.tool_name)) {
132
+ const target = writeTarget(payload.tool_input)
133
+ if (!target || insideHome(home, path.resolve(cwd, target))) allow()
134
+ argv.push('--path', path.resolve(cwd, target))
135
+ } else if (payload.tool_name === 'Bash') {
136
+ const command = payload.tool_input && payload.tool_input.command
137
+ if (typeof command !== 'string' || !mayConcern(command)) allow()
138
+ argv.push('--command', command)
139
+ } else {
140
+ allow()
141
+ }
142
+ if (session) argv.push('--session', session)
143
+
144
+ const engine = engineCommand(home)
145
+ const result = spawnSync(engine.file, [...engine.args, ...argv], { cwd: home, encoding: 'utf8', timeout: 8000 })
146
+ if (result.error || result.status !== 1) allow()
147
+ // Exit 1 alone is a crash as often as a refusal; the printed line decides.
148
+ const said = (result.stdout || '').trim()
149
+ if (!isRefusal(said)) allow()
150
+ deny(said)
151
+ }
152
+
153
+ if (require.main === module) {
154
+ try {
155
+ main()
156
+ } catch {
157
+ allow()
158
+ }
159
+ }
160
+
161
+ module.exports = { findEngine, engineCommand, WRITE_TOOLS, writeTarget, mayConcern, insideHome, isRefusal }
@@ -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) |
@@ -21,6 +22,7 @@ and lifecycle stay consistent. Each sets a status on the spec header
21
22
  | `/spec-complete` | Verify all phases done + tests green; land + tear down | `Complete` | `specs/complete/` |
22
23
  | `/spec-cancel` | Record progress, stamp a reason on the header; tear down | `Cancelled` | `specs/cancelled/` |
23
24
  | `/spec-tada` | A ta-da list — recap what you did in Claude Code over a window, across every project, by project then spec, ending in a standup. Read-only | (unchanged) | (unchanged) |
25
+ | `/spec-todo` | The morning half — where each project was left on the last working day, what is waiting on you, what to pick up first. Read-only | (unchanged) | (unchanged) |
24
26
  | `/spec-init` | Bootstrap/repair this workflow in a project (idempotent) | — | — |
25
27
 
26
28
  **Skills vs commands.** The table above lists **skills** — Claude reads them and
@@ -73,6 +75,17 @@ branch. Beneath it, `skitterspec spec-env nospec <name>` records the branch —
73
75
  and that record is what makes a name with nothing under `specs/**` resolvable by
74
76
  `review`, `integrate`, `down` and a bare `resolve`.
75
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
+
76
89
  **`/spec-tada` reads, and moves nothing.** It is in the table because it
77
90
  reports in the unit the table is about — a spec — but it changes no status,
78
91
  writes no file and commits nothing. `skitterspec tada` reads Claude Code's own
@@ -84,6 +97,17 @@ by a branch that happens to contain it — a spec branch cut this afternoon
84
97
  contains all of this morning. It is model-invocable, because "what did I do
85
98
  today?" should reach it.
86
99
 
100
+ **It leads with the wins, and it acts on nothing outside home.** The digest
101
+ marks a completed bug, hotfix or incident as `★ saved bacon` and any other
102
+ completed spec or a cut release as `★ win`, so the evening answer to *did I get
103
+ anything done?* opens with the evidence. It also marks the project the run
104
+ started from as `(here)`, and the report's closing `Next` — the line a reader
105
+ copies — names only that project's work: other projects' next steps are
106
+ suggestions in their own sections. **`/spec-todo`** is the morning half
107
+ (`skitterspec todo`): the last day with any activity, up to 14 days back, each
108
+ open spec where it was left, the verdicts waiting and gates armed, and today
109
+ so far — home first, and listed even when nothing happened there.
110
+
87
111
  **A report covers one category.** `project.category` in `env.config.json`
88
112
  decides which projects share a report — only those with the category of the
89
113
  repo it runs from, and an uncategorised project is in nobody's but its own
@@ -131,6 +155,21 @@ the guard, and only a person can type it. That asymmetry is the same line
131
155
  `/spec-reviewed` draws, and `spec-planning.md` already records that prose alone
132
156
  did not hold it once.
133
157
 
158
+ **`/allow-project` is its twin, for the other direction.** The main guard
159
+ stops work landing where it should not happen; `.claude/hooks/project-guard.cjs`
160
+ stops a session doing work that is **not its project's**. A session belongs to
161
+ the project it was started in, and a report read across projects once ended on
162
+ another repo's `/spec-complete` — which the session ran, `cd`-ing over there to
163
+ do it. So a write, a `git` change or a `skitterspec` lifecycle command aimed at
164
+ another skitterspec project (a checkout with `specs/.core/`) is refused, while
165
+ reads (`git log`, `skitterspec tada`) and every other program pass. Home is the
166
+ project the hook is installed in, never the session's cwd, because after a `cd`
167
+ the cwd is the thing being judged. `skitterspec spec-env project
168
+ <check|allow|status>` is the engine, `guards.projectBoundary` turns it off, and
169
+ it fails open on every cannot-tell. `/allow-project <name>` lifts it for one
170
+ session, and it is user-only for `/allow-main`'s reason: Claude must not be
171
+ able to lift a guard aimed at Claude.
172
+
134
173
  **`/spec-skip` is the fifth command**, and it is user-only for `/allow-main`'s
135
174
  reason rather than the mild one: it lifts the review gate, which is a guard
136
175
  aimed at Claude. It pre-executes `skitterspec spec-env review skip "<reason>"`
@@ -214,7 +253,7 @@ your canonical `localhost` ports so you can test it at the normal URL
214
253
  move, header edits, the code) happens on the spec's branch in the worktree; `main`
215
254
  changes only when it merges. Teardown is folded into `/spec-complete` ·
216
255
  `/spec-cancel`. Beneath the skills, `skitterspec spec-env
217
- <up|bootstrap|nospec|main|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` is the CLI
256
+ <up|bootstrap|nospec|main|project|down|prune|dev|connect|integrate|disposition|handoff|hotfix|live|review|stage|status|resolve|base>` is the CLI
218
257
  engine. `up` plans the fork;
219
258
  **`bootstrap` then runs the worktree's own steps itself** — seeding the gitignored files, the env file, `setup`, the stack — so
220
259
  the command a skill runs names no file, and a secrets hook that refuses any
@@ -249,6 +288,10 @@ thumb: **live overlay is the light default for *testing* a code-only spec** —
249
288
  is not how work gets started, and no lifecycle skill invokes it; it *refuses*
250
289
  stateful ones (`Stack: worktree + docker`, or a branch touching migrations) — keep
251
290
  `/spec-connect` + a Docker stack for those, and for genuinely parallel testing.
291
+ `live.afterSwitch` is the switch's counterpart of `afterLand` — the same
292
+ `{ run, when }` entries, run in the primary checkout after take and again after
293
+ release, so a changed lockfile or schema is caught up both ways. The engine runs
294
+ them itself, since `/spec-live` has no turn to run anything after it.
252
295
  Beneath it, `skitterspec spec-env live <take|release|abort|status>` is the engine.
253
296
 
254
297
  **Authoring a spec is work, so it happens off the base branch too (`/spec`).**
@@ -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 this push belongs to run 2.** Run 1 readies
100
- a PR, and a ready PR is not a merged one — so skip it on run 1, even where
101
- the `branch` lane committed the move to ride the PR, and run it on run 2 once
102
- the host has merged. The tracker's Done lands when the work does.
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 this push belongs to run 2.** Run 1 readies
181
- a PR, and a ready PR is not a merged one — so skip it on run 1, even where
182
- the `branch` lane committed the move to ride the PR, and run it on run 2 once
183
- the host has merged. The tracker's Done lands when the work does.
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, the
491
- §5 report — then **§7 teardown runs as normal**:
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.