@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 +3 -0
- package/assets/claude-md-section.md +8 -2
- package/assets/commands/allow-project.md +28 -0
- package/assets/core/env.config.md +29 -3
- package/assets/core/linear.config.md +7 -0
- package/assets/hooks/project-guard.cjs +161 -0
- package/assets/rules/spec-planning.md +44 -1
- 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 -1
- package/assets/skills/spec-review/SKILL.md +22 -4
- package/assets/skills/spec-tada/SKILL.md +26 -4
- package/assets/skills/spec-todo/SKILL.md +104 -0
- package/bin/skitterspec-linear.js +8 -0
- package/package.json +1 -1
- package/src/cli.js +266 -21
- package/src/env/config.js +26 -3
- package/src/env/hooks.js +10 -0
- package/src/env/integrate.js +5 -34
- package/src/env/live.js +106 -4
- package/src/env/projectguard.js +389 -0
- package/src/env/triggered.js +50 -0
- package/src/idea.js +190 -0
- package/src/ideacmd.js +242 -0
- package/src/tada/digest.js +41 -2
- package/src/tada/format.js +4 -2
- package/src/tada/page.js +35 -7
- package/src/tada/repo.js +22 -2
- package/src/tada/serve.js +13 -7
- package/src/tada/todo.js +250 -0
- 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
|
@@ -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
|
|
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.
|