@skitterbyte/skitterspec-linear 19.15.0 → 19.16.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 +2 -0
- package/assets/claude-md-section.md +12 -0
- package/assets/core/env.config.md +9 -1
- package/assets/hooks/main-guard.cjs +73 -6
- package/assets/hooks/project-guard.cjs +80 -6
- package/assets/hooks/review-gate.cjs +73 -6
- package/assets/rules/commit-trailers.md +2 -2
- package/assets/rules/spec-planning.md +12 -1
- package/assets/skills/spec/SKILL.md +20 -3
- package/assets/skills/spec-bug/SKILL.md +8 -2
- package/assets/skills/spec-complete/SKILL.md +23 -1
- package/assets/skills/spec-hotfix/SKILL.md +8 -2
- package/assets/skills/spec-init/SKILL.md +4 -2
- package/assets/skills/spec-next/SKILL.md +18 -0
- package/assets/skills/spec-park/SKILL.md +92 -0
- package/assets/skills/spec-resume/SKILL.md +153 -0
- package/assets/skills/spec-status/SKILL.md +1 -1
- package/assets/skills/spec-sync/SKILL.md +12 -12
- package/assets/skills/spec-todo/SKILL.md +5 -2
- package/package.json +1 -1
- package/src/cli.js +169 -6
- package/src/env/bootstrap.js +3 -1
- package/src/env/checks.js +49 -0
- package/src/env/config.js +11 -0
- package/src/env/hooks.js +53 -4
- package/src/env/provision.js +10 -2
- package/src/env/resume.js +234 -0
- package/src/init.js +287 -49
- package/src/tada/todo.js +19 -4
- package/src/vendor/linear/cli-sync.js +3 -3
- package/src/vendor/provider-kit/src/specs.js +46 -1
- package/src/vendor/sync-core/src/summary.js +10 -1
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec-park
|
|
3
|
+
description: Park a spec in flight on something outside the repo — a deploy, another project's release, a soak period — by recording a `Blocked on:` line on the spec or one of its phases, committed on its branch. The worktree stays. `/spec-resume` is how you come back. Use when the user says "/spec-park", "park this until…", "we're waiting on the deploy", "this is blocked on <thing>", or a phase cannot go on until something happens elsewhere.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /spec-park — record why a spec is waiting
|
|
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
|
+
A spec that stops for a reason outside the repo looks, from the outside, just
|
|
14
|
+
like one somebody abandoned. This skill writes the reason down where every
|
|
15
|
+
other skill reads it: `/spec-resume` shows it first, `/spec-next` stops before
|
|
16
|
+
building past it, and `/spec-todo` and the ticket both say *parked* rather than
|
|
17
|
+
*stalled*.
|
|
18
|
+
|
|
19
|
+
The argument is `"<reason>" [--until YYYY-MM-DD] [--phase N] [<spec>]`.
|
|
20
|
+
|
|
21
|
+
## 1. Find the spec
|
|
22
|
+
|
|
23
|
+
Ask the engine, with the spec named or, bare, the one you are standing in:
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
skitterspec spec-env resume [<spec>] --json
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
**Only an in-progress spec is parked.** On `ok: false`, relay `refused` and stop
|
|
30
|
+
with `⏸`. A backlog spec has not started, so there is nothing to wait in the
|
|
31
|
+
middle of. A spec with no worktree here is still parked, on its branch, after
|
|
32
|
+
`/spec-resume` has put it back on this machine. Say that in `Next` rather
|
|
33
|
+
than writing into a tree that is not there.
|
|
34
|
+
|
|
35
|
+
**A reason is required.** A bare `/spec-park` asks for one and writes nothing.
|
|
36
|
+
"Blocked" with no reason is the silence this exists to replace. The reason is
|
|
37
|
+
what the person coming back acts on.
|
|
38
|
+
|
|
39
|
+
## 2. Write the line
|
|
40
|
+
|
|
41
|
+
```
|
|
42
|
+
> **Blocked on:** <reason> (until <YYYY-MM-DD>)
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The `(until …)` is optional, and is the only part anything reads as data: past
|
|
46
|
+
that date `/spec-todo` says the wait has run out. Write a date only when one
|
|
47
|
+
was given. Never infer one from "a week".
|
|
48
|
+
|
|
49
|
+
- **No `--phase`:** the line goes in `00-overview.md`'s header block, after
|
|
50
|
+
the last `> **…:**` line. It holds every phase.
|
|
51
|
+
- **`--phase N`:** it goes in `0N-<slug>.md`'s header, under the
|
|
52
|
+
`> Spec: …` line. It holds that phase only. Earlier phases still build.
|
|
53
|
+
|
|
54
|
+
**A line already there is replaced, not doubled.** Say in `Notes` what it
|
|
55
|
+
said before. That is history worth keeping, so it also gets a dated Changelog
|
|
56
|
+
line: `- <date> — Parked: <reason>` (or `Re-parked: …, was <old>`).
|
|
57
|
+
|
|
58
|
+
## 3. Commit it on the spec's branch
|
|
59
|
+
|
|
60
|
+
Inside the spec's worktree. Use `skitterspec spec-env stage <spec>` for the
|
|
61
|
+
`owned` paths, and commit pathspec-bounded on both halves as
|
|
62
|
+
`docs(spec): park <spec> — <reason, short>`, with the `Refs:` trailer
|
|
63
|
+
(`spec-sync ref`) when there is a ticket.
|
|
64
|
+
|
|
65
|
+
**Only the spec's own documents.** Uncommitted work belonging to the phase in
|
|
66
|
+
progress is left exactly as it is, and reported in `Untouched`. Parking is not
|
|
67
|
+
a reason to commit half a phase.
|
|
68
|
+
|
|
69
|
+
**The worktree stays.** A wait is usually days, and `/spec-resume` rebuilds a
|
|
70
|
+
worktree only when one is actually missing.
|
|
71
|
+
|
|
72
|
+
**The ticket hears about it on the next push.** Where a provider is installed,
|
|
73
|
+
run `/spec-push` now: the summary block carries the blocker. It is never
|
|
74
|
+
fatal, and the board's Status is never set from here, because the tracker owns
|
|
75
|
+
status.
|
|
76
|
+
|
|
77
|
+
## Report
|
|
78
|
+
|
|
79
|
+
End with the block defined in `.claude/rules/spec-reports.md`.
|
|
80
|
+
|
|
81
|
+
**Verdicts**
|
|
82
|
+
|
|
83
|
+
- `✅`: the line is written and committed.
|
|
84
|
+
- `⏸`: refused (not in progress, no reason, no worktree here). Nothing
|
|
85
|
+
changed.
|
|
86
|
+
|
|
87
|
+
**Fields:** `Tracker` · `Spec` · `Built` · `Notes` · `Untouched` ·
|
|
88
|
+
`Follow-ups` · `Next`
|
|
89
|
+
|
|
90
|
+
`Built` quotes the line as written and where it went (spec, or phase N). `Next`
|
|
91
|
+
is `/spec-resume <spec> <what happened>` for whoever comes back, written the way
|
|
92
|
+
they would type it.
|
|
@@ -0,0 +1,153 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: spec-resume
|
|
3
|
+
description: Go back into a spec that is already in flight, by its name or its ticket (#N), without starting anything. Rebuilds its worktree when this machine has none, moves the session there, shows what it is blocked on, then acts on the message given with it — feedback on shipped work, "the deploy is out", a question. Use when the user says "/spec-resume", "back to <spec>", "pick up #N again", or reports on a spec that is already in progress.
|
|
4
|
+
---
|
|
5
|
+
|
|
6
|
+
# /spec-resume — back into a spec in flight
|
|
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
|
+
Some specs wait on things outside the repo: a deploy, another project's
|
|
14
|
+
release, a phase that has to run in prod for a week. This skill is how you come
|
|
15
|
+
back to one. **It is not a start.** It moves no bucket, assigns nobody, touches
|
|
16
|
+
no tracker status and builds nothing itself. `/spec-start` puts a spec in
|
|
17
|
+
flight, and `/spec-next` builds a phase. This skill puts you back where the
|
|
18
|
+
spec is, then does what the message asks.
|
|
19
|
+
|
|
20
|
+
The argument is `<name|#N> [message]`. The first word is the spec, and
|
|
21
|
+
everything after it, a leading `-` or `—` dropped, is the message.
|
|
22
|
+
|
|
23
|
+
## 1. Ask the engine
|
|
24
|
+
|
|
25
|
+
```
|
|
26
|
+
skitterspec spec-env resume <name|#N> --json
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
It reads every copy of the spec it can see: this checkout, each worktree, and
|
|
30
|
+
each spec branch, local then remote-tracking, never fetched. That matters
|
|
31
|
+
because the base branch reads `backlog` for the whole life of a spec, and under
|
|
32
|
+
`land.specDocs: "branch"` an in-flight spec may exist only on its branch.
|
|
33
|
+
|
|
34
|
+
- **`ok: false`.** Relay the `refused` text and stop with `⏸`. It covers a
|
|
35
|
+
name or ticket that matches nothing (it never guesses the nearest), a spec in
|
|
36
|
+
`backlog` (`Next` is `/spec-start <name>`), one already complete or
|
|
37
|
+
cancelled, and one with no branch anywhere to resume from.
|
|
38
|
+
- **`ok: true`.** Carry on. `blockers`, `progress` and `identifier` are read
|
|
39
|
+
in step 3.
|
|
40
|
+
|
|
41
|
+
## 2. Get into its worktree
|
|
42
|
+
|
|
43
|
+
**Only when the project has per-spec isolation** (`specs/.core/env.config.json`).
|
|
44
|
+
Without it there is no worktree, so you are already where the spec is. Skip to
|
|
45
|
+
step 3.
|
|
46
|
+
|
|
47
|
+
**Bring the review server up first, from the primary checkout**, exactly as
|
|
48
|
+
`/spec-start` §2b does: `skitterspec spec-env review serve --host 0.0.0.0`.
|
|
49
|
+
Say nothing when it is already up. If it can't start, say so in one line and
|
|
50
|
+
carry on.
|
|
51
|
+
|
|
52
|
+
**When `commands` is non-empty, this machine has no worktree for the spec.**
|
|
53
|
+
That is the expected path, not an edge case: a spec parked on another machine,
|
|
54
|
+
or pruned while it waited. Run the `commands` as printed, then the `then`
|
|
55
|
+
commands, with the `cd` in front, as `/spec-start` step 3 does:
|
|
56
|
+
|
|
57
|
+
```
|
|
58
|
+
cd "<worktree.path>" && skitterspec spec-env bootstrap <spec>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
The commands attach the spec's own branch, local or tracked from the remote.
|
|
62
|
+
**Never add a `-b` of your own.** A fresh fork would hand back an empty tree with
|
|
63
|
+
the work out of reach, and the engine refused that case already.
|
|
64
|
+
|
|
65
|
+
**When `commands` is empty, the worktree is there.** `cd` into `worktree.path`
|
|
66
|
+
unless the session is already standing in it.
|
|
67
|
+
|
|
68
|
+
**Then confirm the move landed.** `skitterspec spec-env resolve` with no
|
|
69
|
+
argument must name this spec, the same positive signal `/spec-start` asks for.
|
|
70
|
+
If it names anything else, stop with `❌`, print the path, and write nothing.
|
|
71
|
+
|
|
72
|
+
## 3. Show where it stands
|
|
73
|
+
|
|
74
|
+
Before acting on the message, read the spec's `00-overview.md` and the phase
|
|
75
|
+
file for `progress.current` (else the first unfinished one). Then put any
|
|
76
|
+
`blockers` in front of the reader, one per line, with the `until` date where it
|
|
77
|
+
has one. A blocker is the most important thing a resumed spec can say: it is
|
|
78
|
+
why the spec stopped.
|
|
79
|
+
|
|
80
|
+
## 4. Act on the message
|
|
81
|
+
|
|
82
|
+
**No message: report and stop.** `Next` is `/spec-next` (or the blocker, if
|
|
83
|
+
one stands in its way).
|
|
84
|
+
|
|
85
|
+
**With a message, read it against the spec and decide what it is asking.**
|
|
86
|
+
This is judgment, not a template. A message is usually one of these, and can
|
|
87
|
+
be several:
|
|
88
|
+
|
|
89
|
+
- **A blocker's condition is met.** For example: "LSC is released", "it has
|
|
90
|
+
been live a week". Where the message plainly says so, remove that
|
|
91
|
+
`> **Blocked on:**` line and add a dated Changelog line naming what cleared
|
|
92
|
+
it. Where you cannot tell whether it is met, **ask once**: "this was blocked
|
|
93
|
+
on `<text>`, is that done?". Never clear a blocker in silence.
|
|
94
|
+
- **A question about the spec.** For example: "now LSC is out, what do we need
|
|
95
|
+
to test?". Answer it from the spec's own phases, tasks and Decisions, and
|
|
96
|
+
quote the tasks rather than paraphrasing them. Write nothing.
|
|
97
|
+
- **Feedback on the work this spec shipped.** For example: "the toast says why,
|
|
98
|
+
but the record stays on screen and delete does nothing". Turn it into tasks:
|
|
99
|
+
add them to the current `🔄` phase, or, when every phase is `✅`, to a new
|
|
100
|
+
phase file plus an index row (`/spec-next` §4's rule for new work). Add a
|
|
101
|
+
dated Changelog line quoting the report.
|
|
102
|
+
- **Work outside this spec.** For example: a different feature, or a defect in
|
|
103
|
+
code the spec never touched. Propose the right door with a one-line reason,
|
|
104
|
+
confirm first, as `.claude/rules/spec-planning.md`'s kind routing does. A
|
|
105
|
+
defect goes to `/spec-bug`; new behaviour goes to `/spec`. On a no, carry
|
|
106
|
+
on with whatever part of the message was this spec's.
|
|
107
|
+
|
|
108
|
+
**Commit what you wrote to the spec before building anything.** Use
|
|
109
|
+
`skitterspec spec-env stage <spec>` and its `owned` paths, pathspec-bounded on
|
|
110
|
+
both the `add` and the `commit`, as `docs(spec): resume <spec> — <what changed>`
|
|
111
|
+
with the `Refs:` trailer when there is a ticket. `/spec-next` §2 refuses to
|
|
112
|
+
build on an uncommitted tree, and these edits are the spec's own documents, not
|
|
113
|
+
a phase's work.
|
|
114
|
+
|
|
115
|
+
**Then build, if the message asked for work.** Hand off to a bare
|
|
116
|
+
**`/spec-next`**: it resolves this spec from the worktree you are standing in,
|
|
117
|
+
honours the review gate, builds the first unfinished phase (which now holds the
|
|
118
|
+
new tasks), and ends on its own review page. That is the only way this skill
|
|
119
|
+
writes code. A gate that `/spec-next` refuses on is relayed as it says. It is
|
|
120
|
+
never stepped past.
|
|
121
|
+
|
|
122
|
+
**Where the message cleared a blocker and asked for nothing more**, do not
|
|
123
|
+
build on that alone. Offer it instead: "build phase N now?", recommending yes,
|
|
124
|
+
the same question `/spec-start` step 6 asks. A blocker clearing is a reason the
|
|
125
|
+
work can go on, not an instruction to do it now.
|
|
126
|
+
|
|
127
|
+
## 5. Report
|
|
128
|
+
|
|
129
|
+
**When step 4 handed off to `/spec-next`, emit no block here.** That skill
|
|
130
|
+
ends with its own block, and two blocks for one run is the noise the contract
|
|
131
|
+
exists to remove.
|
|
132
|
+
|
|
133
|
+
Otherwise, end with the block defined in `.claude/rules/spec-reports.md`.
|
|
134
|
+
|
|
135
|
+
**Verdicts**
|
|
136
|
+
|
|
137
|
+
- `✅`: the session is standing in the spec's worktree and the message, if
|
|
138
|
+
any, was answered.
|
|
139
|
+
- `⚠️`: resumed, with something worth knowing. For example, a blocker still
|
|
140
|
+
stands, or bootstrap failed a step that does not stop the reading.
|
|
141
|
+
- `❌`: provisioning or the move failed part-way. Name what was left and
|
|
142
|
+
where.
|
|
143
|
+
- `⏸`: the engine refused. Nothing was provisioned and nothing moved.
|
|
144
|
+
|
|
145
|
+
**Fields:** `Tracker` · `Spec` · `Built` · `Notes` · `Worktree` ·
|
|
146
|
+
`Follow-ups` · `Next`
|
|
147
|
+
|
|
148
|
+
`Spec` is the bucket and progress (`2 of 4 done, phase 3 in progress`).
|
|
149
|
+
`Worktree` is the path, and says **entered** or **provisioned**. `Built` lists
|
|
150
|
+
what the message added to the spec (tasks, a cleared blocker), and is absent
|
|
151
|
+
when nothing was written. `Notes` carries any blocker still standing, quoted.
|
|
152
|
+
`Next` is `/spec-next` when the spec is ready to build, or the blocker when one
|
|
153
|
+
stands in the way.
|
|
@@ -80,7 +80,7 @@ stale. That is not push drift and `/spec-push` cannot fix it: it will fail with
|
|
|
80
80
|
Point the user at the CLI and stop:
|
|
81
81
|
|
|
82
82
|
```
|
|
83
|
-
|
|
83
|
+
{{exec}} skitterspec-linear spec-sync retarget
|
|
84
84
|
```
|
|
85
85
|
|
|
86
86
|
Read-only until `--yes`. Do not attempt the rewrite by hand — the identifiers
|
|
@@ -20,13 +20,13 @@ tell the user how to enable Linear sync and stop.
|
|
|
20
20
|
|
|
21
21
|
## The invocation — always state it
|
|
22
22
|
|
|
23
|
-
`spec-sync` is a subcommand of
|
|
24
|
-
is never on `PATH
|
|
23
|
+
`spec-sync` is a subcommand of the provider binary, not a program of its own,
|
|
24
|
+
so it is never on `PATH` by itself. Typing `spec-sync` gives `command not found`, which reads as
|
|
25
25
|
a broken install rather than a wrong invocation. Always run it — and always show
|
|
26
26
|
the user you ran it — in full:
|
|
27
27
|
|
|
28
28
|
```
|
|
29
|
-
|
|
29
|
+
{{exec}} skitterspec-linear spec-sync <subcommand> [args]
|
|
30
30
|
```
|
|
31
31
|
|
|
32
32
|
In a project that installs the Linear superset the binary is
|
|
@@ -75,9 +75,9 @@ Say which skill you're handing to and stop; don't reimplement either.
|
|
|
75
75
|
## 3. The read-only subcommands
|
|
76
76
|
|
|
77
77
|
```
|
|
78
|
-
|
|
79
|
-
|
|
80
|
-
|
|
78
|
+
{{exec}} skitterspec-linear spec-sync linked [--json]
|
|
79
|
+
{{exec}} skitterspec-linear spec-sync states [--via api|mcp] [--json]
|
|
80
|
+
{{exec}} skitterspec-linear spec-sync projects [--via api|mcp] [--json]
|
|
81
81
|
```
|
|
82
82
|
|
|
83
83
|
- **`linked`** is offline: which specs carry a `linear_identifier`, their bucket,
|
|
@@ -98,7 +98,7 @@ pnpm exec skitterspec-linear spec-sync projects [--via api|mcp] [--json]
|
|
|
98
98
|
## 4. `verify` — check what the tracker actually stored
|
|
99
99
|
|
|
100
100
|
```
|
|
101
|
-
|
|
101
|
+
{{exec}} skitterspec-linear spec-sync verify <spec> --stored <file>
|
|
102
102
|
```
|
|
103
103
|
|
|
104
104
|
`--stored` is **what Linear currently holds**, read back over MCP:
|
|
@@ -118,7 +118,7 @@ by pushing again.
|
|
|
118
118
|
## 5. `stamp` — the manual escape hatch
|
|
119
119
|
|
|
120
120
|
```
|
|
121
|
-
|
|
121
|
+
{{exec}} skitterspec-linear spec-sync stamp <spec> --issue KEY-1 [--url URL] [--sub <ref>=KEY-2 …]
|
|
122
122
|
```
|
|
123
123
|
|
|
124
124
|
Writes the ids into the spec's frontmatter without touching Linear. For adopting
|
|
@@ -129,7 +129,7 @@ mint a duplicate, so read the values back to the user before writing.
|
|
|
129
129
|
## 6. `apply --all <bucket>` — bulk, and the one with real blast radius
|
|
130
130
|
|
|
131
131
|
```
|
|
132
|
-
|
|
132
|
+
{{exec}} skitterspec-linear spec-sync apply --all <bucket> [--via api|mcp] [--json]
|
|
133
133
|
```
|
|
134
134
|
|
|
135
135
|
**Confirm before running, and state creates and updates separately.** They are
|
|
@@ -157,8 +157,8 @@ its object exists, so an interrupted run continues rather than duplicating.
|
|
|
157
157
|
## 7. `ref` and `released` — tickets in commits
|
|
158
158
|
|
|
159
159
|
```
|
|
160
|
-
|
|
161
|
-
|
|
160
|
+
{{exec}} skitterspec-linear spec-sync ref [--json]
|
|
161
|
+
{{exec}} skitterspec-linear spec-sync released [<range>] [--json]
|
|
162
162
|
```
|
|
163
163
|
|
|
164
164
|
`ref` prints the ticket for the branch you are on, so a commit can carry
|
|
@@ -189,7 +189,7 @@ the report saying which commits it set aside.
|
|
|
189
189
|
## 8. `retarget` — after a Linear team is renamed
|
|
190
190
|
|
|
191
191
|
```
|
|
192
|
-
|
|
192
|
+
{{exec}} skitterspec-linear spec-sync retarget [--yes]
|
|
193
193
|
```
|
|
194
194
|
|
|
195
195
|
Renaming a Linear team rewrites the key in every issue identifier, and
|
|
@@ -44,8 +44,11 @@ What the lines mean:
|
|
|
44
44
|
stopped.
|
|
45
45
|
- `in flight:` — where the spec stands now, and its next action.
|
|
46
46
|
- `finished:` — the specs that day completed or cancelled, by name.
|
|
47
|
-
- `blocked:` — a review verdict waiting,
|
|
48
|
-
and still owes an answer
|
|
47
|
+
- `blocked:` — a review verdict waiting, a gate armed by a phase that ended
|
|
48
|
+
and still owes an answer, or a spec **parked** on something outside the repo
|
|
49
|
+
(its `Blocked on:` line, naming `/spec-resume`). A parked spec whose
|
|
50
|
+
`until` date has arrived says *ready to resume*. Read only for specs in
|
|
51
|
+
flight.
|
|
49
52
|
- `ideas:` — how many ideas are waiting for the `(here)` project. It is a count,
|
|
50
53
|
never the next action: `/spec-idea` lists them, and the line is absent when
|
|
51
54
|
there are none or the count could not be read.
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skitterbyte/skitterspec-linear",
|
|
3
|
-
"version": "19.
|
|
3
|
+
"version": "19.16.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",
|
package/src/cli.js
CHANGED
|
@@ -5,7 +5,7 @@ const path = require('path')
|
|
|
5
5
|
const os = require('os')
|
|
6
6
|
const { pathToFileURL } = require('url')
|
|
7
7
|
const { execFileSync } = require('child_process')
|
|
8
|
-
const { init, resync, reset, checkSync, isExistingSetup } = require('./init.js')
|
|
8
|
+
const { init, resync, reset, checkSync, isExistingSetup, localSeedFiles } = require('./init.js')
|
|
9
9
|
const {
|
|
10
10
|
detectReleaseTooling,
|
|
11
11
|
removeReleaseTooling,
|
|
@@ -43,8 +43,10 @@ const SPEC_ENV_VERBS = Object.freeze([
|
|
|
43
43
|
'live',
|
|
44
44
|
'review',
|
|
45
45
|
'stage',
|
|
46
|
+
'checks',
|
|
46
47
|
'status',
|
|
47
48
|
'resolve',
|
|
49
|
+
'resume',
|
|
48
50
|
'base',
|
|
49
51
|
'nospec',
|
|
50
52
|
'main',
|
|
@@ -198,6 +200,7 @@ const {
|
|
|
198
200
|
const { planPrune, liveSlugsForSpecs, reconcileRegistry } = require('./env/prune.js')
|
|
199
201
|
const { planIntegrate, planIntegrateCheckout, planIntegratePr, planIntegrateDocs } = require('./env/integrate.js')
|
|
200
202
|
const { specBranchDocs, preferBranches } = require('./env/specbranches.js')
|
|
203
|
+
const { findTarget, planResume, resumeLines, blockingNext } = require('./env/resume.js')
|
|
201
204
|
const { parseRemote, prFor, prPlanCommand, prAbandonCommand, preferRemoteBase } = require('./env/host.js')
|
|
202
205
|
const { collectDisposition } = require('./env/disposition.js')
|
|
203
206
|
const { planHandoff } = require('./env/handoff.js')
|
|
@@ -336,8 +339,13 @@ Usage:
|
|
|
336
339
|
--run-reviewers runs review.reviewers)
|
|
337
340
|
stage [spec] split the uncommitted tree into this spec's
|
|
338
341
|
documents and everything else
|
|
342
|
+
checks [spec] run complete.checks in the spec's worktree
|
|
343
|
+
(advisory — always exits 0)
|
|
339
344
|
status list provisioned specs + port blocks
|
|
340
345
|
resolve <spec> print resolved slug/type/branch/paths
|
|
346
|
+
resume [spec|#N] an in-flight spec: its blockers, and the plan
|
|
347
|
+
to rebuild its worktree from its branch
|
|
348
|
+
(prints commands; creates nothing)
|
|
341
349
|
base fetch, list baseBranchPattern matches
|
|
342
350
|
newest-first, mark the base, and name
|
|
343
351
|
specs forked from an older match
|
|
@@ -409,8 +417,12 @@ Options (init / update):
|
|
|
409
417
|
--dir <path> Target project dir (default: positional arg or cwd)
|
|
410
418
|
--gating (init) Adopt release gating: each spec records whether
|
|
411
419
|
it ships behind a feature flag
|
|
420
|
+
--local (init) Keep the install on this machine: managed
|
|
421
|
+
files excluded from git, hooks in
|
|
422
|
+
settings.local.json, the block in CLAUDE.local.md.
|
|
423
|
+
For one developer on a shared repo — never a team
|
|
412
424
|
--no-claude-md Skip creating/patching CLAUDE.md
|
|
413
|
-
--yes, -y
|
|
425
|
+
--yes, -y Accept defaults; skip the interactive setup prompts
|
|
414
426
|
--isolation / --no-isolation Enable/skip per-spec isolation (a git
|
|
415
427
|
worktree per spec; writes env.config.json)
|
|
416
428
|
--name <name> / --category <c> (init --isolation) Write project.name /
|
|
@@ -444,6 +456,7 @@ function parse(argv) {
|
|
|
444
456
|
if (a === '--force') opts.force = true
|
|
445
457
|
else if (a === '--no-claude-md') opts.claudeMd = false
|
|
446
458
|
else if (a === '--yes' || a === '-y') opts.yes = true
|
|
459
|
+
else if (a === '--local') opts.local = true
|
|
447
460
|
else if (a === '--isolation') opts.isolation = true
|
|
448
461
|
else if (a === '--no-isolation') opts.isolation = false
|
|
449
462
|
else if (a === '--gating') opts.gating = true
|
|
@@ -920,7 +933,20 @@ function repoBlockers(repo, specs) {
|
|
|
920
933
|
} catch {
|
|
921
934
|
return []
|
|
922
935
|
}
|
|
923
|
-
|
|
936
|
+
// Each spec's own copy — its worktree where it has one, since base reads
|
|
937
|
+
// `backlog` for the life of a spec and holds none of its Blocked on: edits.
|
|
938
|
+
// A spec that cannot be resolved or read is not parked, it is unknown.
|
|
939
|
+
const parked = {}
|
|
940
|
+
for (const spec of specs) {
|
|
941
|
+
try {
|
|
942
|
+
const copy = readSpecCopy(resolveSpecWithWorktree(repo, config, spec).path)
|
|
943
|
+
const b = copy && blockingNext(copy)
|
|
944
|
+
if (b) parked[spec] = b
|
|
945
|
+
} catch {
|
|
946
|
+
// cannot tell — say nothing
|
|
947
|
+
}
|
|
948
|
+
}
|
|
949
|
+
return readBlockers(reviewsDirFor(repo, config), specs, config.review && config.review.required, parked)
|
|
924
950
|
}
|
|
925
951
|
|
|
926
952
|
/**
|
|
@@ -2290,7 +2316,7 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
|
|
|
2290
2316
|
// `setup` exactly as a spec does, since a `setup` that reads a seeded `.env`
|
|
2291
2317
|
// fails without it; what it never has is a stack, so no slot is consulted.
|
|
2292
2318
|
if (spec.specless && !spec.unwritten) {
|
|
2293
|
-
steps = worktreeSteps(spec, null, config, { docs, wantsDocker: false })
|
|
2319
|
+
steps = worktreeSteps(spec, null, config, { docs, wantsDocker: false, localSeeds: localSeedFiles(dir) })
|
|
2294
2320
|
} else {
|
|
2295
2321
|
const compose = composeFilePresent(dir, config)
|
|
2296
2322
|
const { wantsDocker } = resolveStack(spec, config, { docs, composeFilePresent: compose })
|
|
@@ -2310,6 +2336,7 @@ function specEnvBootstrap(dir, config, specArg, flags = {}) {
|
|
|
2310
2336
|
docs,
|
|
2311
2337
|
wantsDocker,
|
|
2312
2338
|
composeFilePresent: compose,
|
|
2339
|
+
localSeeds: localSeedFiles(dir),
|
|
2313
2340
|
})
|
|
2314
2341
|
}
|
|
2315
2342
|
|
|
@@ -4485,6 +4512,121 @@ function specEnvResolve(dir, config, specArg, flags = {}) {
|
|
|
4485
4512
|
)
|
|
4486
4513
|
}
|
|
4487
4514
|
|
|
4515
|
+
/**
|
|
4516
|
+
* `skitterspec spec-env resume <name|#N> [--json]` (feat-spec-resume)
|
|
4517
|
+
*
|
|
4518
|
+
* Which in-flight spec the argument means, what it is blocked on, and — where
|
|
4519
|
+
* this machine has no worktree for it — the commands that rebuild one from its
|
|
4520
|
+
* branch. Plans and prints; creates nothing, moves nothing, asks no tracker.
|
|
4521
|
+
* A refusal exits 1.
|
|
4522
|
+
*
|
|
4523
|
+
* Every copy of the spec this clone can see is read — the checkout it runs
|
|
4524
|
+
* from, each live worktree, and each spec branch (local, then remote-tracking,
|
|
4525
|
+
* never fetched) — because under `land.specDocs: "branch"` an in-flight spec
|
|
4526
|
+
* may exist nowhere else than its branch, and on the base branch its bucket
|
|
4527
|
+
* reads `backlog` whatever it really is. `env/resume.js` picks which copy
|
|
4528
|
+
* speaks.
|
|
4529
|
+
*/
|
|
4530
|
+
function specEnvResume(dir, config, arg, flags = {}) {
|
|
4531
|
+
const git = gitReader(dir)
|
|
4532
|
+
const prefix = prefixOf(config)
|
|
4533
|
+
const ownTree = (folder) => resolveSpecless(folder, dir, config, { spec: true }).worktreePath
|
|
4534
|
+
const copies = []
|
|
4535
|
+
const roots = [dir, ...[...liveWorktreePaths(git)].filter((p) => !sameDir(p, dir))]
|
|
4536
|
+
for (const root of roots) {
|
|
4537
|
+
const project = sameDir(root, dir) ? dir : projectIn(root, prefix)
|
|
4538
|
+
for (const bucket of BUCKETS) {
|
|
4539
|
+
let folders
|
|
4540
|
+
try {
|
|
4541
|
+
folders = fs.readdirSync(path.join(project, 'specs', bucket), { withFileTypes: true })
|
|
4542
|
+
} catch {
|
|
4543
|
+
continue
|
|
4544
|
+
}
|
|
4545
|
+
for (const entry of folders) {
|
|
4546
|
+
if (!entry.isDirectory()) continue
|
|
4547
|
+
const folder = entry.name
|
|
4548
|
+
// Another spec's worktree carries every base spec too; only a spec's
|
|
4549
|
+
// OWN tree speaks for it, and the checkout this ran from speaks last.
|
|
4550
|
+
const own = sameDir(ownTree(folder), root)
|
|
4551
|
+
if (!own && !sameDir(root, dir)) continue
|
|
4552
|
+
const copy = readSpecCopy(path.join(project, 'specs', bucket, folder))
|
|
4553
|
+
if (copy) copies.push({ folder, bucket, origin: own ? 'worktree' : 'here', ...copy })
|
|
4554
|
+
}
|
|
4555
|
+
}
|
|
4556
|
+
}
|
|
4557
|
+
let base = null
|
|
4558
|
+
try {
|
|
4559
|
+
base = resolveBaseBranch(config, git)
|
|
4560
|
+
} catch {
|
|
4561
|
+
// An unresolvable base hides branch-only specs; the disk copies still answer.
|
|
4562
|
+
}
|
|
4563
|
+
for (const b of specBranchDocs(git, config, base)) {
|
|
4564
|
+
copies.push({ folder: b.folder, bucket: b.bucket, origin: 'branch', local: b.local, ref: b.ref, overview: b.overview, phases: b.phases })
|
|
4565
|
+
}
|
|
4566
|
+
|
|
4567
|
+
// Bare means what every bare spec-env verb means: the worktree you are
|
|
4568
|
+
// standing in, else the sole provisioned spec. Neither answering leaves the
|
|
4569
|
+
// argument empty, and findTarget refuses that rather than guessing.
|
|
4570
|
+
if (!arg) {
|
|
4571
|
+
try {
|
|
4572
|
+
arg = resolveSpecWithWorktree(dir, config).folder
|
|
4573
|
+
} catch {
|
|
4574
|
+
arg = ''
|
|
4575
|
+
}
|
|
4576
|
+
}
|
|
4577
|
+
const identifierField = config.branch && config.branch.identifierField
|
|
4578
|
+
const found = findTarget(arg, copies, identifierField)
|
|
4579
|
+
if (found.refused) {
|
|
4580
|
+
process.exitCode = 1
|
|
4581
|
+
const r = { ok: false, refused: found.refused, refusedOnly: true }
|
|
4582
|
+
process.stdout.write(flags.json ? JSON.stringify({ ok: false, refused: found.refused }, null, 2) + '\n' : resumeLines(r).join('\n') + '\n')
|
|
4583
|
+
return
|
|
4584
|
+
}
|
|
4585
|
+
const target = found.target
|
|
4586
|
+
const remote = baseRemote(config)
|
|
4587
|
+
let branch
|
|
4588
|
+
if (target.origin === 'branch') {
|
|
4589
|
+
branch = target.ref.replace(/^refs\/heads\//, '').replace(new RegExp(`^refs/remotes/${remote}/`), '')
|
|
4590
|
+
} else {
|
|
4591
|
+
try {
|
|
4592
|
+
branch = resolveSpecWithWorktree(dir, config, target.folder).branch
|
|
4593
|
+
} catch {
|
|
4594
|
+
branch = resolveSpecless(target.folder, dir, config, { spec: true }).branch
|
|
4595
|
+
}
|
|
4596
|
+
}
|
|
4597
|
+
const worktreePath = ownTree(target.folder)
|
|
4598
|
+
const r = planResume(target, {
|
|
4599
|
+
branch,
|
|
4600
|
+
worktreePath,
|
|
4601
|
+
worktreeExists: fs.existsSync(worktreePath),
|
|
4602
|
+
localBranch: git(['show-ref', '--verify', '--quiet', `refs/heads/${branch}`]) !== null,
|
|
4603
|
+
remoteBranch: git(['show-ref', '--verify', '--quiet', `refs/remotes/${remote}/${branch}`]) !== null,
|
|
4604
|
+
remote,
|
|
4605
|
+
identifierField,
|
|
4606
|
+
})
|
|
4607
|
+
if (!r.ok) process.exitCode = 1
|
|
4608
|
+
process.stdout.write(flags.json ? JSON.stringify(r, null, 2) + '\n' : resumeLines(r).join('\n') + '\n')
|
|
4609
|
+
}
|
|
4610
|
+
|
|
4611
|
+
// A spec folder's overview and phase files, or null when it has no overview.
|
|
4612
|
+
function readSpecCopy(specDir) {
|
|
4613
|
+
let overview
|
|
4614
|
+
try {
|
|
4615
|
+
overview = fs.readFileSync(path.join(specDir, '00-overview.md'), 'utf8')
|
|
4616
|
+
} catch {
|
|
4617
|
+
return null
|
|
4618
|
+
}
|
|
4619
|
+
const phases = []
|
|
4620
|
+
for (const f of fs.readdirSync(specDir).filter((n) => /^(?!00-)\d{2}-.*\.md$/.test(n)).sort()) {
|
|
4621
|
+
try {
|
|
4622
|
+
phases.push({ n: Number(f.slice(0, 2)), text: fs.readFileSync(path.join(specDir, f), 'utf8') })
|
|
4623
|
+
} catch {
|
|
4624
|
+
// An unreadable phase file is left out, never counted as done or blocked.
|
|
4625
|
+
}
|
|
4626
|
+
}
|
|
4627
|
+
return { overview, phases }
|
|
4628
|
+
}
|
|
4629
|
+
|
|
4488
4630
|
/**
|
|
4489
4631
|
* `skitterspec spec-env base [--json] [--use-fallback | --unpin]`
|
|
4490
4632
|
*
|
|
@@ -4713,6 +4855,20 @@ function provisionedBranches(dir, config) {
|
|
|
4713
4855
|
* Re-anchoring would silently answer about the wrong checkout, so the tree read
|
|
4714
4856
|
* is printed rather than assumed.
|
|
4715
4857
|
*/
|
|
4858
|
+
// `spec-env checks [spec]` — run the project's `complete.checks` in the spec's
|
|
4859
|
+
// worktree, for `/spec-complete` to relay before it lands. Always exits 0: the
|
|
4860
|
+
// checks inform the completion and never stop it (`env/checks.js`).
|
|
4861
|
+
function specEnvChecks(dir, config, specArg, flags = {}) {
|
|
4862
|
+
const spec = resolveSpecWithWorktree(dir, config, specArg)
|
|
4863
|
+
const { runChecks, formatChecks } = require('./env/checks.js')
|
|
4864
|
+
const results = runChecks(config.complete.checks, { cwd: spec.projectPath || spec.worktreePath })
|
|
4865
|
+
if (flags.json) {
|
|
4866
|
+
process.stdout.write(JSON.stringify({ spec: spec.folder, checks: results }, null, 2) + '\n')
|
|
4867
|
+
return
|
|
4868
|
+
}
|
|
4869
|
+
process.stdout.write(formatChecks(spec.folder, results) + '\n')
|
|
4870
|
+
}
|
|
4871
|
+
|
|
4716
4872
|
function specEnvStage(dir, config, specArg, flags = {}, invokedFrom = dir) {
|
|
4717
4873
|
const spec = resolveSpecWithWorktree(dir, config, specArg)
|
|
4718
4874
|
|
|
@@ -8166,12 +8322,18 @@ async function specEnvDispatch(sub, dir, config, positional, flags, present, inv
|
|
|
8166
8322
|
case 'resolve':
|
|
8167
8323
|
specEnvResolve(dir, config, positional[0], flags)
|
|
8168
8324
|
break
|
|
8325
|
+
case 'resume':
|
|
8326
|
+
specEnvResume(dir, config, positional[0], flags)
|
|
8327
|
+
break
|
|
8169
8328
|
case 'base':
|
|
8170
8329
|
specEnvBase(dir, config, flags)
|
|
8171
8330
|
break
|
|
8172
8331
|
case 'stage':
|
|
8173
8332
|
specEnvStage(dir, config, positional[0], flags, invokedFrom)
|
|
8174
8333
|
break
|
|
8334
|
+
case 'checks':
|
|
8335
|
+
specEnvChecks(dir, config, positional[0], flags)
|
|
8336
|
+
break
|
|
8175
8337
|
case 'review':
|
|
8176
8338
|
// `serve` is the one review sub-action rather than a verb of its own: it
|
|
8177
8339
|
// answers the same question ("show me this diff") from the same engine,
|
|
@@ -8336,7 +8498,7 @@ async function run(argv) {
|
|
|
8336
8498
|
break
|
|
8337
8499
|
}
|
|
8338
8500
|
if (action === 'resync') {
|
|
8339
|
-
resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff })
|
|
8501
|
+
resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff, local: opts.local })
|
|
8340
8502
|
break
|
|
8341
8503
|
}
|
|
8342
8504
|
// action === 'create-missing' → fall through to a normal (skip-existing) init.
|
|
@@ -8363,6 +8525,7 @@ async function run(argv) {
|
|
|
8363
8525
|
workspaceMode,
|
|
8364
8526
|
gating,
|
|
8365
8527
|
project: opts.project,
|
|
8528
|
+
local: opts.local,
|
|
8366
8529
|
})
|
|
8367
8530
|
break
|
|
8368
8531
|
}
|
|
@@ -8374,7 +8537,7 @@ async function run(argv) {
|
|
|
8374
8537
|
checkSync(dir, { claudeMd: opts.claudeMd })
|
|
8375
8538
|
break
|
|
8376
8539
|
}
|
|
8377
|
-
resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff })
|
|
8540
|
+
resync(dir, { claudeMd: opts.claudeMd, force: opts.force, diff: opts.diff, local: opts.local })
|
|
8378
8541
|
await cleanupReleaseTooling(dir, opts)
|
|
8379
8542
|
break
|
|
8380
8543
|
default:
|
package/src/env/bootstrap.js
CHANGED
|
@@ -72,7 +72,9 @@ function runSeed(step, { cwd, mainRoot, fs, platform = process.platform }) {
|
|
|
72
72
|
}
|
|
73
73
|
fs.mkdirSync(path.dirname(dst), { recursive: true })
|
|
74
74
|
if (step.mode === 'copy') {
|
|
75
|
-
|
|
75
|
+
// A seed may be a directory (a local install seeds whole skill folders).
|
|
76
|
+
if (fs.statSync(src).isDirectory()) fs.cpSync(src, dst, { recursive: true })
|
|
77
|
+
else fs.copyFileSync(src, dst)
|
|
76
78
|
return { outcome: 'seeded', line: `seeded ${step.file} → ${src}` }
|
|
77
79
|
}
|
|
78
80
|
// WINDOWS WITHOUT DEVELOPER MODE CANNOT CREATE A SYMLINK (EPERM), and a
|