@gobing-ai/spur 0.3.81 → 0.3.83
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/.claude-plugin/marketplace.json +1 -1
- package/config/config.example.yaml +19 -17
- package/config/config.global.yaml +6 -3
- package/config/templates/docs/99_PROJECT_CONSTITUTION.md +75 -13
- package/config/transition-shims.json +0 -7
- package/package.json +1 -1
- package/plugins/sp/README.md +19 -13
- package/plugins/sp/agents/expert-spur.md +3 -3
- package/plugins/sp/lib/idea-handoff.generated.mjs +84 -56
- package/plugins/sp/plugin.json +1 -1
- package/plugins/sp/scripts/inline-run-setup.ts +69 -1
- package/plugins/sp/scripts/quality-gate.mjs +52 -1
- package/plugins/sp/scripts/quality-gate.ts +70 -0
- package/plugins/sp/scripts/surface-drift-inventory.ts +0 -2
- package/plugins/sp/scripts/task-size-precheck.ts +44 -16
- package/plugins/sp/scripts/verify-answer-lint.ts +17 -1
- package/plugins/sp/skills/code-review/references/review-lenses.md +3 -0
- package/plugins/sp/skills/spur-cli/SKILL.md +4 -8
- package/plugins/sp/skills/spur-cli/references/agent.md +30 -97
- package/plugins/sp/skills/spur-cli/references/message.md +1 -1
- package/plugins/sp/skills/spur-cli/references/projects.md +7 -27
- package/plugins/sp/skills/spur-cli/references/self.md +2 -2
- package/plugins/sp/skills/spur-cli/references/serve.md +4 -4
- package/plugins/sp/skills/spur-cli/references/tasks.md +1 -1
- package/plugins/sp/skills/spur-composer/SKILL.md +3 -3
- package/plugins/sp/skills/spur-dev/references/ac-style-guide.md +10 -0
- package/plugins/sp/skills/spur-dev/references/execution-batch.md +1 -1
- package/plugins/sp/skills/spur-dev/references/execution-workflow.md +4 -6
- package/plugins/sp/skills/spur-dev/references/glossary.md +1 -1
- package/plugins/sp/skills/spur-dev/references/inline-pipeline-driver.md +11 -1
- package/plugins/sp/skills/spur-doctor/SKILL.md +2 -2
- package/schemas/spur-config.schema.json +61 -85
- package/spur.js +3621 -4861
- package/web/_astro/BoardApp.D-WlxiN2.js +1 -0
- package/web/_astro/{BoardApp.B1U26g3I.js → BoardApp.D8bM9pKL.js} +73 -73
- package/web/_astro/{TaskDetail.DwPqpq7v.js → TaskDetail.BPRqgVUE.js} +1 -1
- package/web/_astro/{arc.CweZEjN2.js → arc.BPrPES3z.js} +1 -1
- package/web/_astro/{architectureDiagram-3BPJPVTR.D89pbDuv.js → architectureDiagram-3BPJPVTR.qX_7q02P.js} +1 -1
- package/web/_astro/{blockDiagram-GPEHLZMM.BOuTeEpX.js → blockDiagram-GPEHLZMM.CUZfj5V7.js} +1 -1
- package/web/_astro/{c4Diagram-AAUBKEIU.CASbkWZF.js → c4Diagram-AAUBKEIU.CTaOr8hH.js} +1 -1
- package/web/_astro/channel.DGZaFHZx.js +1 -0
- package/web/_astro/{chunk-2J33WTMH.BKQYtOvY.js → chunk-2J33WTMH.Dt-9wf3h.js} +1 -1
- package/web/_astro/{chunk-4BX2VUAB.9sHLdMtG.js → chunk-4BX2VUAB.CTC2sdoN.js} +1 -1
- package/web/_astro/{chunk-55IACEB6.wOLXWlPs.js → chunk-55IACEB6.DQcxt2_g.js} +1 -1
- package/web/_astro/{chunk-727SXJPM.DovFbwg3.js → chunk-727SXJPM.DXFPSn-a.js} +1 -1
- package/web/_astro/{chunk-AQP2D5EJ.B1Weod1X.js → chunk-AQP2D5EJ.BCx3U4bT.js} +1 -1
- package/web/_astro/{chunk-FMBD7UC4.TEMS04st.js → chunk-FMBD7UC4.DL2tJkdO.js} +1 -1
- package/web/_astro/{chunk-ND2GUHAM.Cp8VT1wQ.js → chunk-ND2GUHAM.DZyflMro.js} +1 -1
- package/web/_astro/{chunk-QZHKN3VN.BzATdEcP.js → chunk-QZHKN3VN.CUI2mT09.js} +1 -1
- package/web/_astro/{classDiagram-4FO5ZUOK.C9BOCfAO.js → classDiagram-4FO5ZUOK.g4rX4Fr1.js} +1 -1
- package/web/_astro/{classDiagram-v2-Q7XG4LA2.C9BOCfAO.js → classDiagram-v2-Q7XG4LA2.g4rX4Fr1.js} +1 -1
- package/web/_astro/{cose-bilkent-S5V4N54A.DUnr4UAw.js → cose-bilkent-S5V4N54A.CzWJLqp0.js} +1 -1
- package/web/_astro/{cynefin-OW5HDTMX.rYq5uM3D.js → cynefin-OW5HDTMX.WgsvQeCR.js} +1 -1
- package/web/_astro/{dagre-BM42HDAG.CWeNKe3I.js → dagre-BM42HDAG.Dzv6ngql.js} +1 -1
- package/web/_astro/{diagram-2AECGRRQ.DCkfls10.js → diagram-2AECGRRQ.CpJ4a9rU.js} +1 -1
- package/web/_astro/{diagram-5GNKFQAL.D5U4JCka.js → diagram-5GNKFQAL.CzPlF_dq.js} +1 -1
- package/web/_astro/{diagram-KO2AKTUF.BZJgqaqG.js → diagram-KO2AKTUF.TAkZNTcQ.js} +1 -1
- package/web/_astro/{diagram-LMA3HP47.DoMeHvPR.js → diagram-LMA3HP47.uCjoKSag.js} +1 -1
- package/web/_astro/{diagram-OG6HWLK6.B50qwwWX.js → diagram-OG6HWLK6.eMplIjoK.js} +1 -1
- package/web/_astro/{erDiagram-TEJ5UH35.DdGPG6LK.js → erDiagram-TEJ5UH35.Bf7zoXGz.js} +1 -1
- package/web/_astro/{flowDiagram-I6XJVG4X.QP2MJ12u.js → flowDiagram-I6XJVG4X.B_bHj3gN.js} +1 -1
- package/web/_astro/{ganttDiagram-6RSMTGT7.BI6LgKSy.js → ganttDiagram-6RSMTGT7.BasrHRMj.js} +1 -1
- package/web/_astro/{gitGraphDiagram-PVQCEYII.npPZiC2G.js → gitGraphDiagram-PVQCEYII.C6iphq1x.js} +1 -1
- package/web/_astro/{infoDiagram-5YYISTIA.DCJCBVbp.js → infoDiagram-5YYISTIA.HXmDMhW4.js} +1 -1
- package/web/_astro/{ishikawaDiagram-YF4QCWOH.BMLV-3I1.js → ishikawaDiagram-YF4QCWOH.BSmW8NiU.js} +1 -1
- package/web/_astro/{journeyDiagram-JHISSGLW.LE58crde.js → journeyDiagram-JHISSGLW.DEQow5fo.js} +1 -1
- package/web/_astro/{kanban-definition-UN3LZRKU.BPbz8rH9.js → kanban-definition-UN3LZRKU.IVm9cTdc.js} +1 -1
- package/web/_astro/{linear.DhZaBtYh.js → linear.CrsM73_9.js} +1 -1
- package/web/_astro/{mermaid.core.BD5-jXum.js → mermaid.core.CfBeDJls.js} +4 -4
- package/web/_astro/{mindmap-definition-RKZ34NQL.MTJyrQ65.js → mindmap-definition-RKZ34NQL.C3j60Y-0.js} +1 -1
- package/web/_astro/{pieDiagram-4H26LBE5.BrDhDvIS.js → pieDiagram-4H26LBE5.B-aCMeEA.js} +1 -1
- package/web/_astro/{quadrantDiagram-W4KKPZXB.71d73_5N.js → quadrantDiagram-W4KKPZXB.Cib965yq.js} +1 -1
- package/web/_astro/{requirementDiagram-4Y6WPE33.Bga6UF-z.js → requirementDiagram-4Y6WPE33.D61cS4O-.js} +1 -1
- package/web/_astro/{sankeyDiagram-5OEKKPKP.BnHs4K82.js → sankeyDiagram-5OEKKPKP.GKF2qVPy.js} +1 -1
- package/web/_astro/{sequenceDiagram-3UESZ5HK.DsfY2gnj.js → sequenceDiagram-3UESZ5HK.DZnq8F2h.js} +1 -1
- package/web/_astro/{stateDiagram-AJRCARHV.DvsTSc9a.js → stateDiagram-AJRCARHV.DXUFmdgM.js} +1 -1
- package/web/_astro/{stateDiagram-v2-BHNVJYJU.DxzzmHUR.js → stateDiagram-v2-BHNVJYJU.BtHmhLEz.js} +1 -1
- package/web/_astro/{timeline-definition-PNZ67QCA.4ZuQmOTt.js → timeline-definition-PNZ67QCA.Cy-WW2ln.js} +1 -1
- package/web/_astro/{vennDiagram-CIIHVFJN.Ck5Q86SG.js → vennDiagram-CIIHVFJN.SLp5b9KI.js} +1 -1
- package/web/_astro/{wardleyDiagram-YWT4CUSO.BK7k2hXr.js → wardleyDiagram-YWT4CUSO.Bww45mWV.js} +1 -1
- package/web/_astro/{xychartDiagram-2RQKCTM6.DfCrgauK.js → xychartDiagram-2RQKCTM6.DR4swI6a.js} +1 -1
- package/web/apple-touch-icon.png +0 -0
- package/web/favicon.ico +0 -0
- package/web/favicon.svg +17 -4
- package/web/icon-192.png +0 -0
- package/web/icon-512.png +0 -0
- package/web/index.html +2 -2
- package/web/site.webmanifest +31 -0
- package/web/spur_logo.svg +1 -0
- package/plugins/README.md +0 -656
- package/plugins/sp/skills/spur-cli/references/team.md +0 -165
- package/web/_astro/BoardApp.Csgyg-lS.js +0 -1
- package/web/_astro/channel.Cx6sXxhq.js +0 -1
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spur-cli-agent
|
|
3
|
-
description: "spur-cli noun reference: operate `spur agent` as the coding-agent execution surface - run prompts, wait on pinned occupants,
|
|
3
|
+
description: "spur-cli noun reference: operate `spur agent` as the coding-agent execution surface - run prompts, wait on pinned occupants, list agent specs, start/stop supervised processes, and check readiness."
|
|
4
4
|
see_also:
|
|
5
5
|
- spur-cli
|
|
6
6
|
---
|
|
@@ -9,7 +9,7 @@ see_also:
|
|
|
9
9
|
|
|
10
10
|
`spur agent` is the CLI for **running and inspecting coding agents**. It wraps the agents the
|
|
11
11
|
operator already has installed (Claude Code, Codex, omp, OpenCode, Antigravity, etc.) behind a
|
|
12
|
-
uniform run, wait,
|
|
12
|
+
uniform run, wait, and supervision surface, so the rest of the harness can dispatch work without
|
|
13
13
|
hard-coding a specific agent.
|
|
14
14
|
|
|
15
15
|
This is a **companion reference**, not an orchestrator. It documents *what each verb is and how to
|
|
@@ -22,18 +22,14 @@ that before using `run` for fan-out dispatch.
|
|
|
22
22
|
| Verb | Purpose | Key flags |
|
|
23
23
|
| ---- | ------- | --------- |
|
|
24
24
|
| `run <prompt>` | Execute a prompt or slash command via a coding agent | `--agent <name>` `--spec <id>` `--model <name>` `--mode <mode>` `--continue` `--cwd <path>` `--drain` `--json` |
|
|
25
|
-
| `loop` | Persistent self-draining inbox loop for a team member (supervisor-managed) | `--spec <id>` `--agent <id>` `--poll <ms>` |
|
|
26
25
|
| `wait [<specId>]` | Identity-pinned wait for an occupant run to reach a lifecycle state (G4 wave 2; `--role` selector per 0685) | `--role <name>` `--run <runId>` `--until <state>...` `--timeout <ms>` `--json` |
|
|
27
|
-
| `list` | List detected coding agents, or
|
|
26
|
+
| `list` | List detected coding agents, or agent specs with `--specs` (live run status merged from `spur serve`) | `--specs` `--server <url>` `--json` |
|
|
28
27
|
| `doctor [agent]` | Check agent readiness | `--json` `--probe-health` `--force-refresh` |
|
|
29
|
-
| `
|
|
30
|
-
| `
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
`list`, `doctor`, `run`, `wait`, and `create` accept `--json` plus `--json-envelope`. `loop`, `edit`,
|
|
36
|
-
and `delete` are human/process-control surfaces. **Exit codes:** `0` success, `1` failure, and `2`
|
|
28
|
+
| `start <spec-id>` | Start a supervised agent process (requires `spur serve`) | `--server <url>` `--json` |
|
|
29
|
+
| `stop <spec-id>` | Stop a supervised agent process (requires `spur serve`) | `--server <url>` `--json` |
|
|
30
|
+
|
|
31
|
+
`list`, `doctor`, `run`, `wait`, `start`, and `stop` accept `--json` plus `--json-envelope`. The hidden
|
|
32
|
+
`loop` is a supervisor-internal process surface. **Exit codes:** `0` success, `1` failure, and `2`
|
|
37
33
|
invalid usage; `run` can also propagate the invoked agent's non-zero result.
|
|
38
34
|
|
|
39
35
|
## `run` - execute a prompt via a coding agent
|
|
@@ -56,7 +52,7 @@ through a coding agent as an external process, producing a persisted run record
|
|
|
56
52
|
| `--mode <mode>` | Agent output mode: `text` or `json`. |
|
|
57
53
|
| `--continue` | Resume the previous agent session instead of starting fresh. |
|
|
58
54
|
| `--cwd <path>` | Working directory for agent execution (default: current directory). |
|
|
59
|
-
| `--spec <id>` |
|
|
55
|
+
| `--spec <id>` | Agent spec id (occupant addressing, 0542 R1). Pairs with `--drain`; with `--spec` alone the run is addressed to the occupant without touching the inbox. A legacy `--agent <spec-id>` is still accepted as fallback addressing (task 0849 retired the `agent-flag-spec-id` deprecation warning). |
|
|
60
56
|
| `--drain` | Prepend pending inbox messages addressed to `--spec <id>` before the prompt. |
|
|
61
57
|
| `--json` | Output machine-readable JSON where supported. |
|
|
62
58
|
| `--json-envelope` | Wrap JSON using the facade's standard output contract. |
|
|
@@ -85,30 +81,15 @@ can fail when the external agent writes its own storage outside the sandbox's al
|
|
|
85
81
|
`AgentStorage` SQLite DB). This is not a reason to abandon `spur agent run` - triggers 1-4 still
|
|
86
82
|
justify it - but ensure the run executes in a context that can write the target agent's storage.
|
|
87
83
|
|
|
88
|
-
## `loop` -
|
|
89
|
-
|
|
90
|
-
```bash
|
|
91
|
-
spur agent loop --agent worker-1 --poll 2000
|
|
92
|
-
```
|
|
93
|
-
|
|
94
|
-
`loop` is the **persistent self-draining wrapper** used by the team supervisor. It waits for a
|
|
95
|
-
wake on the `system_events` ledger — a human request (`message.sent`), a strategy change
|
|
96
|
-
(`strategy.changed`), a capacity change (`fleet.capacity.changed`), or a completion receipt
|
|
97
|
-
(`agent.invoke.exit`) — then drains the inbox into an `agent run` invocation. An idle wake
|
|
98
|
-
records the hold reason instead of dispatching; with no wake event at all it still drains every
|
|
99
|
-
`--poll` ms (backstop). It
|
|
100
|
-
between drains. It is not typically invoked directly by the operator - `spur agent start` launches it
|
|
101
|
-
under supervision.
|
|
102
|
-
|
|
103
|
-
### Flags
|
|
104
|
-
|
|
105
|
-
| Flag | Purpose |
|
|
106
|
-
|------|---------|
|
|
107
|
-
| `--spec <id>` | **Required.** Team agent spec id / message recipient (0542 R1; legacy `--agent <spec-id>` still read with a one-time warning). |
|
|
108
|
-
| `--poll <ms>` | Wakeup backstop timeout in milliseconds — drains at least this often (default: `2000`). |
|
|
84
|
+
## `loop` - supervisor-internal self-draining wrapper (hidden)
|
|
109
85
|
|
|
110
|
-
|
|
111
|
-
|
|
86
|
+
`spur agent loop --spec <id> [--poll <ms>]` is spawned by the `spur serve` supervisor for each
|
|
87
|
+
materialized agent spec; it is hidden from `--help` and not an operator verb (use `spur agent start`).
|
|
88
|
+
It waits for a wake on the `system_events` ledger — a human request (`message.sent`), a strategy
|
|
89
|
+
change (`strategy.changed`), a capacity change (`fleet.capacity.changed`), or a completion receipt
|
|
90
|
+
(`agent.invoke.exit`) — then drains the inbox into an `agent run` invocation. An idle wake records
|
|
91
|
+
the hold reason instead of dispatching; with no wake event it still drains every `--poll` ms
|
|
92
|
+
(default `2000`). It runs until `SIGINT` / `SIGTERM`.
|
|
112
93
|
|
|
113
94
|
## `wait` - identity-pinned occupant wait (G4 wave 2)
|
|
114
95
|
|
|
@@ -149,17 +130,17 @@ exits 2 naming the accepted vocabulary. Resolution collapses onto the same ident
|
|
|
149
130
|
| `timeout` | 1 | Caller `--timeout` elapsed (or aborted via SIGINT). |
|
|
150
131
|
| `usage` | 2 | Invalid flags, or `--until blocked` as the sole target (no first-class signal in wave 2). |
|
|
151
132
|
|
|
152
|
-
## `list` - detected agents and
|
|
133
|
+
## `list` - detected agents and agent specs
|
|
153
134
|
|
|
154
135
|
```bash
|
|
155
136
|
spur agent list # detected coding agents on this machine
|
|
156
|
-
spur agent list --specs #
|
|
137
|
+
spur agent list --specs # agent specs under .spur/agents/
|
|
157
138
|
spur agent list --json # machine-readable
|
|
158
139
|
```
|
|
159
140
|
|
|
160
141
|
Without `--specs`, lists coding agents detected on the host (by binary on `PATH`). With `--specs`,
|
|
161
|
-
lists
|
|
162
|
-
supervisor
|
|
142
|
+
lists agent specs (`.spur/agents/*.yaml`) **with live run status merged from the server's
|
|
143
|
+
supervisor**: each row carries a trailing status column
|
|
163
144
|
(`running` / `stopped` / `errored` / `unknown`) and `pid=<n>` where a process exists. When `spur serve`
|
|
164
145
|
is unreachable, the listing falls back to all `stopped` with a stderr warning. `--server <url>`
|
|
165
146
|
(default `http://localhost:3000/api`) targets the supervisor API.
|
|
@@ -184,89 +165,41 @@ Checks whether each agent is installed and ready to run. Text mode renders a cap
|
|
|
184
165
|
(`cheap|standard|capable-*`), MODEL the pinned config model (`—` when undeclared), and ROLES lists
|
|
185
166
|
candidate pipeline roles with `*` on the elected one. Exit `1` if any checked agent is not ready.
|
|
186
167
|
|
|
187
|
-
## `
|
|
188
|
-
|
|
189
|
-
```bash
|
|
190
|
-
spur agent create worker-1 --type claude --tags team:alpha --model sonnet
|
|
191
|
-
spur agent create reviewer --type codex --autonomy review --auto-start
|
|
192
|
-
```
|
|
193
|
-
|
|
194
|
-
Writes a team agent spec to `.spur/agents/<id>.yaml`. The spec captures the agent's identity
|
|
195
|
-
(type, model, autonomy, system prompt, tags) so the fleet declaration (`.spur/fleet.json`, converted
|
|
196
|
-
by `spur projects migrate`) can materialize a roster and `spur
|
|
197
|
-
agent loop` can self-drain its inbox.
|
|
198
|
-
|
|
199
|
-
### Flags
|
|
200
|
-
|
|
201
|
-
| Flag | Purpose |
|
|
202
|
-
| ------ | --------- |
|
|
203
|
-
| `--type <agent-type>` | Agent spec type (e.g. `claude`, `codex`, `omp`). |
|
|
204
|
-
| `--tags <a,b>` | Comma-separated team identity tags (e.g. `team:alpha,role:worker`). |
|
|
205
|
-
| `--model <name>` | Agent model argument. |
|
|
206
|
-
| `--autonomy <level>` | Autonomy level (e.g. `full`, `review`). |
|
|
207
|
-
| `--system-prompt <text>` | Team identity system prompt. |
|
|
208
|
-
| `--name <name>` | Agent display name. |
|
|
209
|
-
| `--workspace <path>` | Workspace path for this agent. |
|
|
210
|
-
| `--purpose <text>` | Team identity purpose. |
|
|
211
|
-
| `--auto-start` | Auto-start flag (started by the supervisor when serve materializes the fleet; without it, start manually with `spur agent start`). |
|
|
212
|
-
| `--no-identity-preamble` | Disable the identity preamble prepended to prompts. |
|
|
213
|
-
| `--json` | Output machine-readable JSON. |
|
|
214
|
-
|
|
215
|
-
## `edit` - open a spec in `$EDITOR`
|
|
216
|
-
|
|
217
|
-
```bash
|
|
218
|
-
spur agent edit worker-1
|
|
219
|
-
```
|
|
220
|
-
|
|
221
|
-
Opens `.spur/agents/<id>.yaml` in `$EDITOR`. If `$EDITOR` is unset, prints the spec path instead.
|
|
222
|
-
|
|
223
|
-
## `delete` - remove a spec
|
|
224
|
-
|
|
225
|
-
```bash
|
|
226
|
-
spur agent delete worker-1 --force
|
|
227
|
-
```
|
|
228
|
-
|
|
229
|
-
`--force` is required (guards against accidental deletion). Removes `.spur/agents/<id>.yaml`.
|
|
230
|
-
|
|
231
|
-
## `start` - start a supervised process (0848)
|
|
168
|
+
## `start` - start a supervised process
|
|
232
169
|
|
|
233
170
|
```bash
|
|
234
171
|
spur agent start worker-1
|
|
235
172
|
spur agent start worker-1 --json
|
|
236
173
|
```
|
|
237
174
|
|
|
238
|
-
|
|
239
|
-
(`POST /api/
|
|
175
|
+
Posts to the `spur serve` supervisor API
|
|
176
|
+
(`POST /api/agents/:id/start`) and prints `started <id> (pid=<n>, status=<s>)`. Requires a
|
|
240
177
|
reachable `spur serve`; `--server <url>` (default `http://localhost:3000/api`) targets it. Exit `1`
|
|
241
178
|
when the server is unreachable or the start fails.
|
|
242
179
|
|
|
243
|
-
## `stop` - stop a supervised process
|
|
180
|
+
## `stop` - stop a supervised process
|
|
244
181
|
|
|
245
182
|
```bash
|
|
246
183
|
spur agent stop worker-1
|
|
247
184
|
spur agent stop worker-1 --json
|
|
248
185
|
```
|
|
249
186
|
|
|
250
|
-
|
|
251
|
-
(`POST /api/
|
|
252
|
-
`start`.
|
|
253
|
-
`team down --purge`.
|
|
187
|
+
Posts to the supervisor API
|
|
188
|
+
(`POST /api/agents/:id/stop`) and prints `stopped <id>`. Same server requirement and flags as
|
|
189
|
+
`start`.
|
|
254
190
|
|
|
255
191
|
## What this skill is NOT
|
|
256
192
|
|
|
257
193
|
- **Not the dispatch decision.** *When* to use `spur agent run` vs a native subagent is the
|
|
258
194
|
**[dispatch-surface rule](../../parallel-execution/references/dispatch-surface.md)**, not this
|
|
259
195
|
reference. This reference documents the verbs; that rule decides which surface carries a dispatch.
|
|
260
|
-
- **Not the
|
|
261
|
-
start` / `stop` manage supervised processes and `agent list --specs` reports live state
|
|
262
|
-
moved these homes off the deprecated `spur team` noun).
|
|
196
|
+
- **Not the fleet orchestrator.** The `spur serve` supervisor drives the lifecycle: `spur agent
|
|
197
|
+
start` / `stop` manage supervised processes and `agent list --specs` reports live state.
|
|
263
198
|
|
|
264
199
|
## See also
|
|
265
200
|
|
|
266
201
|
- **[dispatch-surface.md](../../parallel-execution/references/dispatch-surface.md)** - native
|
|
267
202
|
subagent vs `spur agent run` decision rule. `--model` and `--agent` are its escalation levers.
|
|
268
|
-
- **`spur team` (see [team.md](team.md))** - deprecated team noun (0848); its verbs moved to this
|
|
269
|
-
noun (`start`/`stop`/`list --specs`) and to `spur task update --assignee`.
|
|
270
203
|
- **`spur message` (see [message.md](message.md))** - the inbox `--drain` reads from.
|
|
271
204
|
- **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.
|
|
272
205
|
|
|
@@ -134,7 +134,7 @@ lines.
|
|
|
134
134
|
|
|
135
135
|
- **`spur agent` (see [agent.md](agent.md))** - `run --drain` and `loop` consume the inbox.
|
|
136
136
|
- **`spur task` (see [tasks.md](tasks.md))** - `task update --assignee` wires an agent spec to a
|
|
137
|
-
task
|
|
137
|
+
task.
|
|
138
138
|
- **`sp:spur-cli`** SKILL.md - the facade that routes to this reference.
|
|
139
139
|
|
|
140
140
|
> **Shared option declarations (0618):** options shared across command modules resolve from
|
|
@@ -22,7 +22,6 @@ shapes live in `apps/cli/src/commands/projects.ts`.
|
|
|
22
22
|
| `list` | List entries with live running status | `--json` `--fleet` |
|
|
23
23
|
| `start <target>` | Start or reuse a detached project server | `--port <n>` `--json` |
|
|
24
24
|
| `stop <target>` | Best-effort stop the listener and clear its recorded port | `--json` |
|
|
25
|
-
| `migrate [path]` | Preview (default) or apply the legacy `agent.team` → `fleet.json` conversion (0847) | `--dry-run` `--apply` `--json` |
|
|
26
25
|
|
|
27
26
|
Every verb also advertises `--json-envelope`; use the facade's machine-output contract. Success is
|
|
28
27
|
exit `0`; validation, registry, spawn, health, or lookup failure is exit `1`.
|
|
@@ -37,14 +36,15 @@ exit `0`; validation, registry, spawn, health, or lookup failure is exit `1`.
|
|
|
37
36
|
defaults the display name to its basename. It upserts; it does not start a server. The current
|
|
38
37
|
source does not enforce a `.spur/` marker or directory type.
|
|
39
38
|
- `list` probes recorded ports and heals stale entries to `port: 0` before reporting `running`.
|
|
40
|
-
- `list --fleet` (0835) additionally resolves each project's fleet
|
|
41
|
-
|
|
39
|
+
- `list --fleet` (0835/0858) additionally resolves each project's `agent.fleet` section from that
|
|
40
|
+
project's `.spur/config.yaml` under the existing verb (no new noun). Per project it prints one line
|
|
42
41
|
per member: instance id (the spec id / mailbox identity), `role`, resolved `executor`,
|
|
43
42
|
`fsWrite` capability state, and derived `write` flag. A project with no declaration reports
|
|
44
|
-
`no declaration (.
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
`
|
|
43
|
+
`no declaration (agent.fleet)`; a declared but switched-off fleet reports
|
|
44
|
+
`disabled (agent.fleet.enabled: false)` and still lists its roster; an all-disabled roster reports
|
|
45
|
+
`no enabled members`; a project whose config fails to load (a retired source, an invalid section)
|
|
46
|
+
reports the loader's message without failing the listing. Under `--json` each project gains `fleet`
|
|
47
|
+
(the resolved fleet, `null` on resolution failure) and, on failure, `fleetError`.
|
|
48
48
|
- `list --fleet` (0836) also reports the project's orchestrator binding: one
|
|
49
49
|
`orchestrator:` line per project with state `bound-online <id> (holder <spec-id>)`,
|
|
50
50
|
`bound-offline <id> (no live claim)`, `missing (no-orchestrator-declared)`, or
|
|
@@ -60,26 +60,6 @@ exit `0`; validation, registry, spawn, health, or lookup failure is exit `1`.
|
|
|
60
60
|
persisted row, or `unavailable (<error>)` on a db failure. Under `--json` each
|
|
61
61
|
project gains `strategy` (`{ strategy, strategyVersion }`, `null` when
|
|
62
62
|
unpersisted) and, on failure, `strategyError`.
|
|
63
|
-
- `migrate [path]` (0847) converts the single legacy `agent.team.<id>` roster whose
|
|
64
|
-
`work_dir` resolves to the project into `<project>/.spur/fleet.json`, preserving
|
|
65
|
-
every spec id verbatim (explicit member ids freeze the `<role>-<n>` derivation).
|
|
66
|
-
Dry-run is the default: it emits the 0846 plan (steps + conflicts + warnings) and
|
|
67
|
-
writes nothing — an existing project db is opened read-only without migrations;
|
|
68
|
-
an absent db or table contributes no addressed identities.
|
|
69
|
-
`--apply` validates first, deep-equals an existing declaration (`unchanged`, no
|
|
70
|
-
rewrite), backs up a differing prior file to `.bak`, then atomically writes the
|
|
71
|
-
declaration (`converted`). It is purely additive — specs, `config.yaml`, and the
|
|
72
|
-
database are never touched — and it refuses to write while any conflict exists
|
|
73
|
-
(`addressed-id-without-spec`, `two-teams-one-project`, …). A registry name that
|
|
74
|
-
differs from the legacy team ID is `project-name-mismatch`: align that name
|
|
75
|
-
explicitly before conversion so fleet resolution preserves the spec-id prefix.
|
|
76
|
-
Exit codes: `0` for a
|
|
77
|
-
clean preview or `converted`/`unchanged`/`nothing-to-convert`; `2` when blocked
|
|
78
|
-
(the JSON payload still carries the full plan/result); `1` on error. Under
|
|
79
|
-
`--json` the payload is the raw `MigrationPlan` (preview) or `ConversionResult`
|
|
80
|
-
(apply). `rollback` is a service-level API (no CLI verb): restore the `.bak` a
|
|
81
|
-
previous apply created, remove a file that apply created when no `.bak` exists,
|
|
82
|
-
or report `nothing-to-roll-back`.
|
|
83
63
|
|
|
84
64
|
## Server lifecycle
|
|
85
65
|
|
|
@@ -77,7 +77,7 @@ spur self serve --json # dry probe: print { port, url, pid, runni
|
|
|
77
77
|
```
|
|
78
78
|
|
|
79
79
|
Starts the Hono/Cloudflare-Worker server that serves the web Task Kanban and exposes the team
|
|
80
|
-
supervisor API (`/api/
|
|
80
|
+
supervisor API (`/api/processes/*` + `/api/agents/*`). It is the local fallback when no remote server is configured.
|
|
81
81
|
Flags: `--port <n>`, `--host <addr>`, `--no-open`, `--cwd <path>`, `--json` (a dry probe — reports
|
|
82
82
|
the resolved port/url without starting the server). Full flag semantics: **[serve.md](serve.md)**.
|
|
83
83
|
|
|
@@ -95,7 +95,7 @@ directory. Only flag is `--json`.
|
|
|
95
95
|
|
|
96
96
|
## What this skill is NOT
|
|
97
97
|
|
|
98
|
-
- **Not the
|
|
98
|
+
- **Not the agent supervisor.** `self serve` hosts the supervisor API; `spur agent start` / `stop` /
|
|
99
99
|
`agent list --specs` are the verbs that drive and inspect it (0848). See
|
|
100
100
|
**[agent.md](agent.md)**.
|
|
101
101
|
- **Not a production server.** This is the local fallback. Production deployment uses the Cloudflare
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: spur-cli-serve
|
|
3
|
-
description: "spur-cli noun reference: operate `spur serve` as the local web-server fallback - start the Hono/Cloudflare-Worker server that backs the web Task Kanban and the
|
|
3
|
+
description: "spur-cli noun reference: operate `spur serve` as the local web-server fallback - start the Hono/Cloudflare-Worker server that backs the web Task Kanban and the supervisor API. Single verb, five flags."
|
|
4
4
|
see_also:
|
|
5
5
|
- spur-cli
|
|
6
6
|
---
|
|
@@ -8,7 +8,7 @@ see_also:
|
|
|
8
8
|
# spur serve - local web server
|
|
9
9
|
|
|
10
10
|
`spur serve` starts the **Spur web server** - a local Hono / Cloudflare-Worker server that serves
|
|
11
|
-
the web Task Kanban and exposes the
|
|
11
|
+
the web Task Kanban and exposes the supervisor API (`/api/processes/*` + `/api/agents/*`). It is the local fallback
|
|
12
12
|
when no remote server is configured.
|
|
13
13
|
|
|
14
14
|
## Verb map
|
|
@@ -29,7 +29,7 @@ spur serve --json # dry probe: print { port, url, pid, running
|
|
|
29
29
|
```
|
|
30
30
|
|
|
31
31
|
Starts the server with the Hono app backed by the local SQLite database. The web Task Kanban and
|
|
32
|
-
the
|
|
32
|
+
the supervisor API become available at `http://<host>:<port>`.
|
|
33
33
|
|
|
34
34
|
### Flags
|
|
35
35
|
|
|
@@ -46,7 +46,7 @@ the team supervisor API become available at `http://<host>:<port>`.
|
|
|
46
46
|
|
|
47
47
|
## What this skill is NOT
|
|
48
48
|
|
|
49
|
-
- **Not the
|
|
49
|
+
- **Not the agent supervisor.** `spur serve` hosts the supervisor API; `spur agent start` / `stop` /
|
|
50
50
|
`agent list --specs` are the verbs that drive and inspect it (0848). See
|
|
51
51
|
**[agent.md](agent.md)**.
|
|
52
52
|
- **Not a production server.** This is the local fallback. Production deployment uses the Cloudflare
|
|
@@ -40,7 +40,7 @@ re-reading or re-tokenizing the task.
|
|
|
40
40
|
| ---- | ------- | --------- |
|
|
41
41
|
| `create <title>` | Allocate a new task (race-safe WBS) | `--feature <id>` `--parent <wbs>` `--template <variant>` `--dedupe-within <s>` `--allow-duplicate-name` `--folder` `--json` |
|
|
42
42
|
| `show <wbs>` | Print one task's frontmatter + body | `--folder` `--json` |
|
|
43
|
-
| `update <wbs> [status]` | Lifecycle transition, section replace, **or** frontmatter set | `--section <name> --from-file <path>` `--assignee <spec-id>` (
|
|
43
|
+
| `update <wbs> [status]` | Lifecycle transition, section replace, **or** frontmatter set | `--section <name> --from-file <path>` `--assignee <spec-id>` (exclusive with `--section`) `--feature <id>` `--priority <p>` `--no-lifecycle` `--force-done` `--reason <text>` `--verdict-dir <path>` `--folder` `--json` |
|
|
44
44
|
| `deps <wbs> <op> [values...]` | Mutate `dependencies[]` frontmatter array (ops: `set`, `add`, `remove`, `clear`) | `--folder` `--json` |
|
|
45
45
|
| `sections <wbs> <op> [name]` | Initialize, add, or list canonical task sections (ops: `init`, `add`, `list`) | `--folder` `--json` |
|
|
46
46
|
| `list` | List tasks, filtered | `--status <s>` `--phase <p>` `--parent <wbs>` `--feature <id>` `--folder` `--json` |
|
|
@@ -36,8 +36,8 @@ its own output and never runs a recurring loop — evaluation is the doctor's jo
|
|
|
36
36
|
or flag catalog: [../spur-cli/SKILL.md](../spur-cli/SKILL.md).
|
|
37
37
|
- **Recurring loops and coordination go to `sp:super-planner`** or a workflow — not here. This skill
|
|
38
38
|
runs one bounded composition or tuning pass per invocation.
|
|
39
|
-
- **Forbidden
|
|
40
|
-
`spur agent
|
|
39
|
+
- **Forbidden surface: `spur agent loop`** (supervisor-internal). Agent specs are read through
|
|
40
|
+
`spur agent list --specs`; they are declared in the fleet config, not authored by a CLI verb.
|
|
41
41
|
- **Writes land only through `spur` verbs** and the ladder's gated file steps (§ below). The shared
|
|
42
42
|
step additionally needs recorded operator consent plus `build:bundle` parity.
|
|
43
43
|
|
|
@@ -49,7 +49,7 @@ its own output and never runs a recurring loop — evaluation is the doctor's jo
|
|
|
49
49
|
| feature | Apply accepted rows through `spur feature update --section --from-file`; keep acceptance criteria in Gherkin | [../spur-cli/references/features.md](../spur-cli/references/features.md) |
|
|
50
50
|
| rule | The trace-driven tuning loop (§ Rule tuning loop) | [../spur-cli/references/rules.md](../spur-cli/references/rules.md) · [fine-tuning](../spur-cli/references/rules/fine-tuning.md) |
|
|
51
51
|
| workflow | Catalog selection, the composition ladder, and the ADR-115 budgets (§ below) | [../spur-cli/references/workflows.md](../spur-cli/references/workflows.md) · [operations](../spur-cli/references/workflows/operations.md) |
|
|
52
|
-
| agent spec |
|
|
52
|
+
| agent spec | Read through `spur agent list --specs`; specs are materialized from the fleet declaration at serve start | [../spur-cli/references/agent.md](../spur-cli/references/agent.md) |
|
|
53
53
|
|
|
54
54
|
Do not drive the planning→execution lifecycle from here — that is `sp:spur-dev`.
|
|
55
55
|
|
|
@@ -127,6 +127,16 @@ unmatchable):
|
|
|
127
127
|
| AC-0817-HERM-SKIP | MET | test | `tests/loader.test.ts:962` | ← declared
|
|
128
128
|
```
|
|
129
129
|
|
|
130
|
+
### A bullet's bold head is its id
|
|
131
|
+
|
|
132
|
+
`verify-answer-lint` declares the bold span of a single-line criterion bullet
|
|
133
|
+
(`- **AC2 — The roster runtime is gone (R3).** Given …, when …, then …`) and its head before the
|
|
134
|
+
first ` — ` or `:` — so answer rows may key `AC2` or `AC2 — The roster runtime is gone (R3).`. Keep
|
|
135
|
+
at least one answer row keyed to the verbatim feature scenario title the task graduates, and keep
|
|
136
|
+
requirement ids in the corpus form they are checked against (`- **R1** — …`): `L3.requirements-format`
|
|
137
|
+
matches `R\d+` followed by a space, so a colon after the bold span silently drops the whole section
|
|
138
|
+
to a warning.
|
|
139
|
+
|
|
130
140
|
### The id is exactly the scenario title — no Gherkin body appended
|
|
131
141
|
|
|
132
142
|
An AC row id must be **exactly** the scenario title (plus any of the four forms above), with the
|
|
@@ -885,7 +885,7 @@ command doc so it does not read as a bug.
|
|
|
885
885
|
## Still out of scope
|
|
886
886
|
|
|
887
887
|
- **Interactive within-step Q&A** — a headless subprocess `agent.run` agent asking the operator a
|
|
888
|
-
real question. This waits for the workspace module + inbox module +
|
|
888
|
+
real question. This waits for the workspace module + inbox module + the agent fleet.
|
|
889
889
|
`sp:super-planner` surfaces blockers/HITL only at the **batch boundary** (between task runs), not
|
|
890
890
|
from inside a pipeline step.
|
|
891
891
|
|
|
@@ -327,12 +327,10 @@ task.** A `cheap`/`standard`-tier model handed a task that big does not fail fas
|
|
|
327
327
|
entire `implementTimeoutMs` and exits 3 with a partial tree (run `ca130182` — 7 reqs / 9 plan
|
|
328
328
|
items / 12+ files → 30 minutes, 6 of 12 files, no tests, no docs, no `## Solution`).
|
|
329
329
|
|
|
330
|
-
The precheck size gate
|
|
331
|
-
|
|
332
|
-
|
|
333
|
-
|
|
334
|
-
`--agent <capable>` / `--vars '{"implementAgent":"<capable>"}'`, or split — never by raising
|
|
335
|
-
`maxImplementReqs`: the caps accept a big task, they do not make a flash model able to finish one.
|
|
330
|
+
The precheck size gate is count-only: it writes FAIL above 10 requirements or 16 Plan items and
|
|
331
|
+
never consults the executor's capability tier. Clear a FAIL deliberately — split the task, or raise
|
|
332
|
+
the cap with `--vars '{"maxImplementReqs":<n>}'` — but the caps only accept a big task, they do not
|
|
333
|
+
make a flash model able to finish one.
|
|
336
334
|
|
|
337
335
|
The empty-implement guard (`requireDiff` on the task-pipeline `implement` step, R3) fails the
|
|
338
336
|
run fast when an implement exits 0 with zero non-corpus changes — a no-op never drifts into
|
|
@@ -55,7 +55,7 @@ Avoid: *result* (too generic — a verdict has a fixed three-value contract), *r
|
|
|
55
55
|
for narrative output like the dogfood report or batch report).
|
|
56
56
|
|
|
57
57
|
**noun/verb** — the two-part CLI grammar: a noun names the domain object (`task`, `feature`,
|
|
58
|
-
`rule`, `workflow`, `agent`, `message
|
|
58
|
+
`rule`, `workflow`, `agent`, `message`), a verb names the operation on it (`create`,
|
|
59
59
|
`update`, `check`, `run`, `list`). The `sp:spur-cli` facade organizes its references one file
|
|
60
60
|
per noun.
|
|
61
61
|
Avoid: *command* alone (ambiguous with a `/sp:dev-*` slash command, which is a different
|
|
@@ -206,7 +206,12 @@ Action semantics come from the YAML and the workflow action contract:
|
|
|
206
206
|
state mutates the task, the host validates the same refusal conditions inline — the declared
|
|
207
207
|
artifact exists at the resolved path and is canonical-valid for the run's wbs (for
|
|
208
208
|
`verify-verdict`: verdict `PASS`), `proofBinding: current` is honored against a freshly captured
|
|
209
|
-
proof digest
|
|
209
|
+
proof digest — capture it with `bun "$SETUP_SCRIPT" --fingerprint --task-file <task path>
|
|
210
|
+
[--feature-file <feature path>]`, the same entry point used at Run setup, which prints the engine
|
|
211
|
+
`sha256:<hex>` digest. Run it from the worktree root (cwd feeds the git-tree half of the digest)
|
|
212
|
+
and pass the same `--feature-file` the run folded in — omitting it, or running from elsewhere,
|
|
213
|
+
yields a different digest and the mismatch surfaces later as a refused `run.artifact`
|
|
214
|
+
registration — and the run-scoped review-completion marker exists — then appends one provenance
|
|
210
215
|
line to `.spur/run/<run-id>.log` naming the equivalence (artifact kind, path, verdict, digest) and
|
|
211
216
|
proceeds to `spur task record`. A failed validation stops at the state and follows the failure
|
|
212
217
|
contract; the step is never silently skipped. Artifact-provenance consumers read that run-log
|
|
@@ -267,6 +272,11 @@ boundary, and a delegate left to re-derive them re-derives them against its own
|
|
|
267
272
|
Nothing else: no task/session transcripts, no machine-specific session paths. The WBS/path already
|
|
268
273
|
carried by the slash command remains the task handoff.
|
|
269
274
|
|
|
275
|
+
**Delegate hygiene.** A dispatched stage cleans up after itself: temporary artifacts stay inside the
|
|
276
|
+
execution tree, and an ad-hoc git worktree created for a comparison is removed before the stage
|
|
277
|
+
reports. The G65 batch's implement dispatches left an 867 MB worktree plus a trail of `/tmp` scratch
|
|
278
|
+
files that outlived the run (2026-09-15).
|
|
279
|
+
|
|
270
280
|
**Verify-stage artifact contract.** A verify handoff names
|
|
271
281
|
[`code-verification/references/verdict-schema.md`](../../code-verification/references/verdict-schema.md)
|
|
272
282
|
as the canonical answer schema and carries this compact form verbatim:
|
|
@@ -42,7 +42,7 @@ record saves the returned table under `docs/reports/`; the doctor creates no art
|
|
|
42
42
|
of scope and are never re-interpreted here; history-anatomy is the only history interpreter.
|
|
43
43
|
- **Recurring reflection loops and coordination go to `sp:super-planner`** or a workflow — one
|
|
44
44
|
bounded evaluation pass per invocation.
|
|
45
|
-
- **Forbidden
|
|
45
|
+
- **Forbidden surface: `spur agent loop`** (supervisor-internal). Agent specs are read only through
|
|
46
46
|
`spur agent list --specs --json`.
|
|
47
47
|
|
|
48
48
|
## Evidence per noun
|
|
@@ -53,7 +53,7 @@ record saves the returned table under `docs/reports/`; the doctor creates no art
|
|
|
53
53
|
| feature | `spur feature check <id> --json` |
|
|
54
54
|
| rule | `spur rule trace --json`, `spur rule validate` |
|
|
55
55
|
| workflow | `spur workflow validate --json` (findings by `level`), `node "$(superskill script path sp workflow-step-profile.mjs)" <workflow> --json` |
|
|
56
|
-
| agent spec | `spur agent list --specs --json
|
|
56
|
+
| agent spec | `spur agent list --specs --json` |
|
|
57
57
|
| history | A `sp:history-anatomy` report ([../history-anatomy/SKILL.md](../history-anatomy/SKILL.md)), never raw history records |
|
|
58
58
|
|
|
59
59
|
Every row of a proposal cites the evidence it rests on. No anchor, no proposal.
|