@apralabs/apra-fleet 0.3.3 → 0.3.5

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.
Files changed (150) hide show
  1. package/README.md +8 -1
  2. package/dist/agents/_shared/GRAPH-SEMANTICS.md +47 -0
  3. package/dist/agents/ci-watcher.md +43 -0
  4. package/dist/agents/deployer.md +51 -28
  5. package/dist/agents/doer.md +160 -31
  6. package/dist/agents/harvester.md +81 -6
  7. package/dist/agents/integ-test-runner.md +147 -17
  8. package/dist/agents/plan-reviewer.md +76 -9
  9. package/dist/agents/planner.md +80 -15
  10. package/dist/agents/reviewer.md +90 -13
  11. package/dist/agents/schemas/ci-watcher-input.json +26 -0
  12. package/dist/agents/schemas/ci-watcher-output.json +18 -0
  13. package/dist/agents/schemas/deployer-input.json +19 -0
  14. package/dist/agents/schemas/deployer-output.json +17 -0
  15. package/dist/agents/schemas/doer-input.json +25 -0
  16. package/dist/agents/schemas/doer-output.json +22 -0
  17. package/dist/agents/schemas/harvester-input.json +31 -0
  18. package/dist/agents/schemas/harvester-output.json +18 -0
  19. package/dist/agents/schemas/integ-test-runner-input.json +20 -0
  20. package/dist/agents/schemas/integ-test-runner-output.json +27 -0
  21. package/dist/agents/schemas/plan-reviewer-input.json +15 -0
  22. package/dist/agents/schemas/plan-reviewer-output.json +30 -0
  23. package/dist/agents/schemas/reviewer-input.json +25 -0
  24. package/dist/agents/schemas/reviewer-output.json +34 -0
  25. package/dist/cli/config.d.ts +9 -3
  26. package/dist/cli/config.d.ts.map +1 -1
  27. package/dist/cli/config.js +21 -8
  28. package/dist/cli/config.js.map +1 -1
  29. package/dist/cli/install.d.ts +10 -0
  30. package/dist/cli/install.d.ts.map +1 -1
  31. package/dist/cli/install.js +74 -23
  32. package/dist/cli/install.js.map +1 -1
  33. package/dist/cli/uninstall.d.ts.map +1 -1
  34. package/dist/cli/uninstall.js +19 -0
  35. package/dist/cli/uninstall.js.map +1 -1
  36. package/dist/cli/watch.d.ts +8 -0
  37. package/dist/cli/watch.d.ts.map +1 -0
  38. package/dist/cli/watch.js +536 -0
  39. package/dist/cli/watch.js.map +1 -0
  40. package/dist/index.js +10 -4
  41. package/dist/index.js.map +1 -1
  42. package/dist/os/linux.d.ts +1 -0
  43. package/dist/os/linux.d.ts.map +1 -1
  44. package/dist/os/linux.js +4 -0
  45. package/dist/os/linux.js.map +1 -1
  46. package/dist/os/macos.d.ts +1 -0
  47. package/dist/os/macos.d.ts.map +1 -1
  48. package/dist/os/macos.js +5 -0
  49. package/dist/os/macos.js.map +1 -1
  50. package/dist/os/os-commands.d.ts +2 -0
  51. package/dist/os/os-commands.d.ts.map +1 -1
  52. package/dist/os/windows.d.ts +1 -0
  53. package/dist/os/windows.d.ts.map +1 -1
  54. package/dist/os/windows.js +7 -0
  55. package/dist/os/windows.js.map +1 -1
  56. package/dist/providers/claude.d.ts.map +1 -1
  57. package/dist/providers/claude.js +10 -6
  58. package/dist/providers/claude.js.map +1 -1
  59. package/dist/services/agent-provisioner.d.ts +39 -0
  60. package/dist/services/agent-provisioner.d.ts.map +1 -0
  61. package/dist/services/agent-provisioner.js +130 -0
  62. package/dist/services/agent-provisioner.js.map +1 -0
  63. package/dist/services/sftp.d.ts +15 -0
  64. package/dist/services/sftp.d.ts.map +1 -1
  65. package/dist/services/sftp.js +34 -0
  66. package/dist/services/sftp.js.map +1 -1
  67. package/dist/services/ssh.d.ts +13 -0
  68. package/dist/services/ssh.d.ts.map +1 -1
  69. package/dist/services/ssh.js +46 -0
  70. package/dist/services/ssh.js.map +1 -1
  71. package/dist/services/stall/log-path-resolver.d.ts +8 -0
  72. package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
  73. package/dist/services/stall/log-path-resolver.js +12 -4
  74. package/dist/services/stall/log-path-resolver.js.map +1 -1
  75. package/dist/services/statusline.d.ts.map +1 -1
  76. package/dist/services/statusline.js +16 -4
  77. package/dist/services/statusline.js.map +1 -1
  78. package/dist/services/user-config.d.ts +14 -0
  79. package/dist/services/user-config.d.ts.map +1 -1
  80. package/dist/services/user-config.js +22 -0
  81. package/dist/services/user-config.js.map +1 -1
  82. package/dist/services/watch/fleet-log.d.ts +34 -0
  83. package/dist/services/watch/fleet-log.d.ts.map +1 -0
  84. package/dist/services/watch/fleet-log.js +168 -0
  85. package/dist/services/watch/fleet-log.js.map +1 -0
  86. package/dist/services/watch/project-resolver.d.ts +51 -0
  87. package/dist/services/watch/project-resolver.d.ts.map +1 -0
  88. package/dist/services/watch/project-resolver.js +104 -0
  89. package/dist/services/watch/project-resolver.js.map +1 -0
  90. package/dist/services/watch/transcript-formatter.d.ts +26 -0
  91. package/dist/services/watch/transcript-formatter.d.ts.map +1 -0
  92. package/dist/services/watch/transcript-formatter.js +210 -0
  93. package/dist/services/watch/transcript-formatter.js.map +1 -0
  94. package/dist/skills/auto-sprint-args/SKILL.md +88 -0
  95. package/dist/skills/pm/SKILL.md +101 -42
  96. package/dist/skills/pm/beads.md +27 -22
  97. package/dist/skills/pm/cost.md +6 -4
  98. package/dist/skills/pm/doer-reviewer-loop.md +62 -62
  99. package/dist/skills/pm/fleet-addendum.md +11 -5
  100. package/dist/skills/pm/simple-sprint.md +6 -5
  101. package/dist/skills/pm/sprint.md +53 -37
  102. package/dist/tools/check-status.d.ts.map +1 -1
  103. package/dist/tools/check-status.js +47 -29
  104. package/dist/tools/check-status.js.map +1 -1
  105. package/dist/tools/cloud-control.d.ts +2 -2
  106. package/dist/tools/compose-permissions.d.ts +6 -3
  107. package/dist/tools/compose-permissions.d.ts.map +1 -1
  108. package/dist/tools/compose-permissions.js +63 -5
  109. package/dist/tools/compose-permissions.js.map +1 -1
  110. package/dist/tools/execute-command.d.ts.map +1 -1
  111. package/dist/tools/execute-command.js +18 -2
  112. package/dist/tools/execute-command.js.map +1 -1
  113. package/dist/tools/execute-prompt.d.ts +1 -0
  114. package/dist/tools/execute-prompt.d.ts.map +1 -1
  115. package/dist/tools/execute-prompt.js +38 -1
  116. package/dist/tools/execute-prompt.js.map +1 -1
  117. package/dist/tools/list-members.d.ts +3 -0
  118. package/dist/tools/list-members.d.ts.map +1 -1
  119. package/dist/tools/list-members.js +30 -15
  120. package/dist/tools/list-members.js.map +1 -1
  121. package/dist/tools/register-member.d.ts +15 -9
  122. package/dist/tools/register-member.d.ts.map +1 -1
  123. package/dist/tools/register-member.js +35 -0
  124. package/dist/tools/register-member.js.map +1 -1
  125. package/dist/tools/update-member.d.ts +15 -9
  126. package/dist/tools/update-member.d.ts.map +1 -1
  127. package/dist/tools/update-member.js +40 -0
  128. package/dist/tools/update-member.js.map +1 -1
  129. package/dist/types.d.ts +2 -0
  130. package/dist/types.d.ts.map +1 -1
  131. package/dist/utils/agent-helpers.d.ts +8 -0
  132. package/dist/utils/agent-helpers.d.ts.map +1 -1
  133. package/dist/utils/agent-helpers.js +21 -0
  134. package/dist/utils/agent-helpers.js.map +1 -1
  135. package/dist/utils/skill-matrix.d.ts +19 -0
  136. package/dist/utils/skill-matrix.d.ts.map +1 -0
  137. package/dist/utils/skill-matrix.js +47 -0
  138. package/dist/utils/skill-matrix.js.map +1 -0
  139. package/dist/workflows/auto-sprint.js +1213 -208
  140. package/package.json +3 -2
  141. package/skills/fleet/permissions.md +60 -5
  142. package/skills/fleet/profiles/tag-devops.json +4 -0
  143. package/skills/fleet/profiles/tag-gpu.json +4 -0
  144. package/skills/fleet/skill-matrix.md +15 -8
  145. package/version.json +1 -1
  146. package/dist/services/stall/log-path-resolver.test.d.ts +0 -2
  147. package/dist/services/stall/log-path-resolver.test.d.ts.map +0 -1
  148. package/dist/services/stall/log-path-resolver.test.js +0 -76
  149. package/dist/services/stall/log-path-resolver.test.js.map +0 -1
  150. package/dist/skills/pm/tpl-progress.json +0 -35
@@ -21,14 +21,18 @@ All sprint state is held in:
21
21
 
22
22
  - **beads (`bd`), the task DB -- the single source of truth and the message bus:**
23
23
  sprint root, tasks, dependencies, assignees, acceptance criteria, model-tier assignment,
24
- review findings, backlog, PR link. The planner writes tasks here; the doer reads
25
- `bd ready` and claims/closes them; the reviewer reads acceptance criteria with
26
- `bd show` and reopens tasks on rework. There is no PLAN.md and no progress.json --
24
+ review findings, backlog, PR link. The planner writes tasks here; the orchestrator
25
+ reads `bd ready` and hands the doer explicit bead ids, which the doer claims/closes
26
+ (the doer never discovers work via bare `bd ready` -- see `agents/doer.md` Step 1);
27
+ the reviewer reads acceptance criteria with
28
+ `bd show` and returns `reopenIds` for the orchestrator to reopen -- the reviewer never
29
+ mutates beads directly. There is no PLAN.md and no progress.json --
27
30
  beads holds all task state. See `beads.md`.
28
31
  - **git, on each track's branch:** the code, the branch history, and the narrative
29
- files `requirements.md`, `design.md`, and `feedback.md` (the reviewer's verdict
30
- channel). git carries intent and the committed work; beads carries the plan and
31
- progress.
32
+ files `requirements.md` and `design.md`. The `reviewer`'s verdict is returned as
33
+ structured output directly to the orchestrator (`verdict`/`notes`/`reopenIds`/
34
+ `newTasks`), not written to a `feedback.md` file. git carries intent and the
35
+ committed work; beads carries the plan and progress.
32
36
 
33
37
  On every dispatch completion and after any restart, re-derive position from beads and
34
38
  git -- they are the single source of truth.
@@ -39,7 +43,7 @@ A sprint runs as one or more **cycles**. Each cycle moves through three phases i
39
43
  order; a fourth phase runs once at sprint close.
40
44
 
41
45
  - **Plan** -- dispatch `planner` to write the task DAG into beads (titles,
42
- acceptance criteria, model-tier notes, priorities, dependencies), loop
46
+ acceptance criteria, model-tier metadata, priorities, dependencies), loop
43
47
  `plan-reviewer` to APPROVED. Skip the loop if planning is already complete (sprint root
44
48
  has features and every open feature's tasks carry acceptance criteria); just reset
45
49
  any task orphaned `in_progress` from a crashed dispatch back to open.
@@ -48,10 +52,11 @@ order; a fourth phase runs once at sprint close.
48
52
  over the worked tasks. Repeat until `bd ready` is empty, no open task remains at
49
53
  the goal priority, and the last review verdict is APPROVED.
50
54
  - **Test** -- only when both `deploy.md` and `integ-test-playbook.md` are present:
51
- `deployer` brings up / resets the environment and deploys, `integ-test-runner`
52
- executes tests feature by feature (closes passing features, files bugs for
53
- failures), then `deployer` tears down. Skip the whole phase if either file is
54
- absent.
55
+ `deployer` deploys per `deploy.md` (deploy + smoke test), then
56
+ `integ-test-runner` runs `integ-test-playbook.md` end to end -- the real
57
+ functional suite, then the smoke-test sprint in a sandbox it brings up and
58
+ tears down itself -- plus each feature's tests (closes passing features,
59
+ files bugs for failures). Skip the whole phase if either file is absent.
55
60
  - **Harvest** -- runs once after the cycle loop exits (goal met or cycle ceiling
56
61
  hit): poll CI via `ci-watcher`, run a final reviewer pass, then `harvester`
57
62
  extracts durable knowledge into `docs/` and `CHANGELOG`, and raise the PR.
@@ -85,36 +90,40 @@ Eight subagent roles carry the work, split into two groups.
85
90
  `deployer`, `integ-test-runner`, `ci-watcher`, `harvester`.
86
91
 
87
92
  Roles coordinate through beads (the task state and message bus) and the committed
88
- code and narrative files (`requirements.md`, `design.md`, `feedback.md`) on the
93
+ code and narrative files (`requirements.md`, `design.md`) on the
89
94
  track's branch.
90
95
 
91
96
  ### Sprint-core roles
92
97
 
93
98
  - `planner` -- reads `requirements.md` (and `design.md` if present), writes the task
94
99
  DAG into beads: one task per item with title/description, `--acceptance="..."`, a
95
- model tier in `--notes`, a priority, and dependencies (`bd dep add`). Writes no
96
- PLAN.md.
100
+ model tier in `--metadata '{"model": "..."}'`, a priority, and dependencies
101
+ (`bd dep add`). Writes no PLAN.md.
97
102
  - `plan-reviewer` -- inspects the beads DAG (`bd graph`, `bd ready`, `bd show`),
98
- writes `feedback.md` (`APPROVED` / `CHANGES NEEDED`).
99
- - `doer` -- finds work via `bd ready`, reads the task's acceptance + model tier with
103
+ returns structured output ONLY (`verdict`: `APPROVED` / `CHANGES_NEEDED`, `notes`,
104
+ `taskAssignments`); never writes `feedback.md` or `PLAN.md`.
105
+ - `doer` -- works the explicit bead ids the orchestrator hands it (never bare
106
+ `bd ready` discovery), reads each task's acceptance + model tier with
100
107
  `bd show`, claims it (`bd update --claim`), implements one task at a time, commits
101
108
  after each, closes it (`bd close`), STOPS at every VERIFY checkpoint.
102
109
  - `reviewer` -- reads each worked task's acceptance criteria (`bd show`) + the diff,
103
- writes `feedback.md` (`APPROVED` / `CHANGES NEEDED`) with `reopenIds` and `newTasks`
104
- arrays on CHANGES NEEDED; never touches beads. The orchestrator reads those arrays
105
- and runs `bd update --status=open` / `bd create` itself.
110
+ returns structured output ONLY (`verdict`: `APPROVED` / `CHANGES_NEEDED`, `notes`,
111
+ `reopenIds`, `newTasks`); never writes `feedback.md` and never touches beads directly.
112
+ The orchestrator reads that structured output and runs `bd update --status=open` /
113
+ `bd create` itself.
106
114
 
107
115
  ### Lifecycle-support roles
108
116
 
109
117
  Dispatch these only when their condition holds:
110
118
 
111
119
  - `deployer` -- in the Test phase, once the Develop exit condition is met (no open
112
- tasks at the goal priority, last review APPROVED) and `deploy.md` is present; runs
113
- the deploy/reset/teardown runbook.
120
+ tasks at the goal priority, last review APPROVED) and `deploy.md` is present;
121
+ follows `deploy.md` to deploy the build and run its smoke test. It does not
122
+ run `integ-test-playbook.md`.
114
123
  - `integ-test-runner` -- in the Test phase, after a successful deploy, when
115
- `integ-test-playbook.md` is present; executes integration tests feature by
116
- feature against the deployed environment, closing passing features and filing
117
- bugs for failures.
124
+ `integ-test-playbook.md` is present; owns that playbook end to end (real
125
+ functional suite, then sandbox Setup/Reset, smoke scenario, feature tests,
126
+ Teardown always), closing passing features and filing bugs for failures.
118
127
  - `ci-watcher` -- in Harvest, to poll CI for the sprint HEAD SHA (green / red /
119
128
  not configured / pending). [Fleet mode] PM may run `gh` CLI directly instead of
120
129
  dispatching (R13).
@@ -159,11 +168,15 @@ needs in the prompt, since agents share the filesystem:
159
168
  Matching model power to task complexity is a headline capability of this skill, not
160
169
  an option. Models fall into three tiers, strongest to cheapest: **premium-tier**,
161
170
  **standard-tier**, **cheap-tier**. **The planner decides the tier each work task runs
162
- on** and records it in the task's beads notes (`--notes="model: <tier>"`). At
163
- dispatch time the orchestrator reads it back with `bd show <id>` and dispatches each
164
- doer on that tier.
171
+ on** and records it as beads metadata (`--metadata '{"model": "<tier>"}'`) -- this is the
172
+ single canonical location the tier lives in; it is never written to `--notes`. At
173
+ dispatch time the orchestrator reads it back with `bd show <id>` (the `model` metadata
174
+ key) and dispatches each doer on that tier. `plan-reviewer` (criterion 10 / Step 3) reads
175
+ the tier from this same metadata key, so a planner that sets it here can never fail
176
+ plan-reviewer's model-metadata check -- the two are aligned by construction.
165
177
 
166
- How the planner chooses the doer tier:
178
+ How the planner chooses the doer tier (mirrors the criteria owned by `agents/planner.md`
179
+ itself -- keep the two in sync if either changes):
167
180
 
168
181
  - **cheap-tier** -- mechanical work: rename, move, config tweak, simple wiring,
169
182
  boilerplate.
@@ -177,7 +190,7 @@ It picks from the models actually available in the current environment.
177
190
  Fixed rules:
178
191
 
179
192
  - The `doer` runs on the tier the planner assigned to the task it will execute,
180
- read from the task's beads notes (`bd show <id>`) at dispatch time.
193
+ read from the task's beads metadata (`bd show <id>`, `model` key) at dispatch time.
181
194
  - `planner` runs premium-tier; `plan-reviewer` runs standard-tier. The `reviewer` runs
182
195
  standard-tier by default but escalates to premium-tier whenever any doer streak in the
183
196
  iteration ran premium-tier -- review must never be weaker than the work it judges.
@@ -221,13 +234,15 @@ R1. NEVER read code to diagnose, fix, or write it. You dispatch agents, read
221
234
  (`git worktree add/list/remove`, `git merge`, `git diff <base>...<branch>`),
222
235
  beads commands, and PR commands.
223
236
  R2. **Project sandboxing** -- every narrative artifact (requirements.md, design.md,
224
- feedback.md, status.md) lives inside the track's worktree and nowhere else, and
225
- task state lives in the project's single beads DB. Never write project files
237
+ and in fleet mode status.md) lives inside the track's worktree and nowhere else,
238
+ and task state lives in the project's single beads DB. Never write project files
226
239
  outside a track's worktree or in the skill folder.
227
240
  R3. On session start: re-derive position from beads and git -- they are the
228
- single source of truth. Update status.md whenever a dispatch completes or
229
- a member reports back, not just at phase boundaries. Beads and git are the
230
- source of truth -- never rely on memory across sessions.
241
+ single source of truth; there is no status file to consult in local mode
242
+ (see `sprint.md` Recovery). **[Fleet mode]** additionally keep status.md
243
+ current whenever a dispatch completes or a member reports back (mode and
244
+ pairing records -- see `fleet-addendum.md`). Never rely on memory across
245
+ sessions.
231
246
  R4. **[Fleet mode]** Before dispatch: verify member has required tools via
232
247
  `execute_command -> which <tool>` or `<tool> --version`.
233
248
  R5. **[Fleet mode]** If a member can finish in one session (1-3 steps), use
@@ -244,10 +259,15 @@ R8. **[Fleet mode]** When executing a sequence of fleet calls (send_files,
244
259
  R9. **[Fleet mode]** For unattended execution, use `update_member(unattended=
245
260
  'auto')` for safer auto-approval or `update_member(unattended='dangerous')`
246
261
  for full permission bypass. Always compose and deliver permissions via
247
- `compose_permissions` before dispatch (see `fleet-addendum.md`).
248
- R10. During a sprint, every doer/reviewer turn updates beads (claim/close/reopen)
249
- and commits its code and feedback.md to the branch -- these carry the living
250
- state of the sprint. Only the agent context file stays uncommitted.
262
+ `compose_permissions` before dispatch, selecting members by tags (tags: ['doer'] /
263
+ tags: ['reviewer']). Never select members by role name or naming convention --
264
+ use tag queries exclusively (see Member selection below).
265
+ See `fleet-addendum.md`.
266
+ R10. During a sprint, every doer turn updates beads (claim/close) and commits its
267
+ code to the branch; every reviewer turn returns structured output (`verdict`/
268
+ `notes`/`reopenIds`/`newTasks`) and the orchestrator applies the resulting
269
+ reopen -- these carry the living state of the sprint. Only the agent context
270
+ file stays uncommitted.
251
271
  R11. Definition of done includes security audit and documentation -- ensure
252
272
  both are covered when adding tools/features.
253
273
  R12. At sprint completion: raise a PR, verify CI is green -- do NOT merge.
@@ -260,6 +280,44 @@ Rules marked **[Fleet mode]** apply only when running with fleet members. In
260
280
  local subagent mode they are skipped or adapted (see `fleet-addendum.md` for
261
281
  the fleet-specific execution model).
262
282
 
283
+ ## Member selection (fleet mode)
284
+
285
+ Always select fleet members by tag query -- never by role name, display name, or
286
+ any naming convention. The `list_members` tool accepts a `tags` filter that
287
+ returns only members carrying all of the listed tags.
288
+
289
+ ### Basic tag queries
290
+
291
+ ```
292
+ list_members(tags: ['doer']) # all members tagged doer
293
+ list_members(tags: ['reviewer']) # all members tagged reviewer
294
+ ```
295
+
296
+ Pick the first available result (or the preferred one if multiple match), then
297
+ dispatch to it. Rerun the query when switching from doer to reviewer roles -- do
298
+ not cache results across tag switches.
299
+
300
+ ### Multi-tag queries for capability-based dispatch
301
+
302
+ When a task requires a specific capability (e.g. a particular VCS platform,
303
+ language, or environment), narrow the query with additional tags:
304
+
305
+ ```
306
+ list_members(tags: ['reviewer', 'bitbucket']) # reviewer with Bitbucket access
307
+ list_members(tags: ['doer', 'python']) # doer with Python capability
308
+ list_members(tags: ['doer', 'rust']) # doer with Rust capability
309
+ ```
310
+
311
+ Multi-tag queries return members that carry ALL listed tags. If no member
312
+ matches a narrow query, fall back to the single-tag query (`tags: ['doer']` /
313
+ `tags: ['reviewer']`) and note the missing capability in the dispatch prompt.
314
+
315
+ ### compose_permissions and permissions delivery
316
+
317
+ After selecting a member with `list_members`, compose and deliver permissions
318
+ via `compose_permissions` using the same tag set before every dispatch. See
319
+ `fleet-addendum.md` for the full permissions workflow.
320
+
263
321
  ## Secrets and credentials (fleet mode)
264
322
 
265
323
  When running via fleet, never pass raw secrets in `execute_prompt` prompts --
@@ -312,7 +370,8 @@ and git.
312
370
  - **start** -- run the doer-review loop for the next pending phase. See
313
371
  `doer-reviewer-loop.md`.
314
372
  - **status** -- report position from `bd` queries (`bd list --status=open`,
315
- `bd ready`, `bd list --tree`) plus `git log` and the on-branch `feedback.md`.
373
+ `bd ready`, `bd list --tree`) plus `git log` and the latest reviewer/plan-reviewer
374
+ structured verdicts.
316
375
  - **resume** / **recover** -- reconstruct in-flight state from beads + git and
317
376
  continue. See `sprint.md` Recovery.
318
377
  - **deploy** -- run the project's `deploy.md` runbook (execute / verify / rollback).
@@ -338,6 +397,6 @@ and git.
338
397
  PR linking.
339
398
  - `fleet-addendum.md` -- fleet-only execution: permissions, compose_permissions,
340
399
  stop_prompt, unattended modes, context-file delivery.
341
- - `cost.md` -- cost quoting and calibration: Node.js check, extracting pure
342
- functions from auto-sprint.js, quote after plan APPROVED, sprint log format,
343
- harvest analysis and calibration update.
400
+ - `cost.md` -- cost quoting and calibration: Node.js check, the extracted
401
+ `cost.js` module installed alongside the skill, quote after plan APPROVED,
402
+ sprint log format, harvest analysis and calibration update.
@@ -3,8 +3,8 @@
3
3
  beads (`bd`) is pm's task store and message bus. It holds what is in flight, what
4
4
  is blocked, what was deferred, what each task must satisfy, and what each review
5
5
  found. There is no PLAN.md and no progress.json: the planner writes tasks into
6
- beads, the doer reads `bd ready` and claims/closes tasks, and the reviewer reads
7
- each task's acceptance criteria with `bd show`. git holds only the code, the branch
6
+ beads, the orchestrator reads `bd ready` and hands the doer explicit bead ids to
7
+ claim/close, and the reviewer reads each task's acceptance criteria with `bd show`. git holds only the code, the branch
8
8
  history, and the requirements/design narrative; **beads holds all task state.**
9
9
 
10
10
  ## One project, one DB
@@ -12,10 +12,11 @@ history, and the requirements/design narrative; **beads holds all task state.**
12
12
  An orchestrator manages one project, so there is one beads DB for that project and
13
13
  one **sprint root** per sprint. The DB is a local `.beads/` at the **base checkout** (the
14
14
  orchestrator's repo root) -- not inside any track worktree. The orchestrator runs
15
- every `bd` command from there. Doers run `bd ready` / `bd update --claim` /
15
+ every `bd` command from there. Doers run `bd show` / `bd update --claim` /
16
16
  `bd close` against that same DB; reviewers run `bd show` only -- they never write to
17
- beads. On CHANGES NEEDED the reviewer writes `reopenIds` and `newTasks` to
18
- `feedback.md`; the orchestrator reads that and runs the beads updates.
17
+ beads. On CHANGES NEEDED the reviewer returns `reopenIds` and `newTasks` as structured
18
+ output (it never writes feedback.md); the orchestrator reads that output and runs the
19
+ beads updates.
19
20
  The DB persists on disk across sessions, so it survives without being committed.
20
21
  Committing it is optional and only shares issue history across machines; if you do,
21
22
  commit it on the base or integration branch -- keeping it off the track feature
@@ -39,34 +40,37 @@ writes these directly into beads -- there is no PLAN.md:
39
40
  ```
40
41
  bd create "T1.1: <title>" -p 1 --parent <sprint-id> --assignee <track> \
41
42
  --acceptance="<what must be true for this task to be done>" \
42
- --notes="model: standard-tier" # -> task-id
43
+ --metadata '{"model": "standard-tier"}' # -> task-id
43
44
  bd create "T1.2: <title>" -p 2 --parent <sprint-id> --assignee <track> \
44
- --acceptance="..." --notes="model: cheap-tier"
45
+ --acceptance="..." --metadata '{"model": "cheap-tier"}'
45
46
  bd dep add <T1.2-id> <T1.1-id> # T1.2 blocked until T1.1 done
46
47
  ```
47
- The acceptance criteria are the reviewer's contract; the model tier in notes is the
48
+ The acceptance criteria are the reviewer's contract; the model tier in metadata is the
48
49
  doer's dispatch tier. Both live on the task -- nothing is written to a plan file.
49
50
 
50
51
  **Doer dispatch** (doer) -- read the task, claim it, implement, close it:
51
52
  ```
52
- bd show <task-id> # read description + acceptance + model tier
53
+ bd show <task-id> # read description + acceptance + model tier metadata
53
54
  bd update <task-id> --claim # claim (open -> in_progress, assigns self)
54
55
  bd close <task-id> # when the work is complete
55
- bd ready # confirm what is unblocked next
56
56
  ```
57
- The doer finds work with `bd ready` (tasks with no open blockers) and picks the
58
- highest-priority ready task. Never steal a task already `in_progress`.
57
+ The ORCHESTRATOR finds ready work (`bd ready` -- tasks with no open blockers, scoped to
58
+ the sprint root) and hands the doer an explicit list of bead ids in the dispatch prompt.
59
+ The doer works exactly that list and never runs bare `bd ready` to discover work itself
60
+ (it would see other sprints' concurrent tasks with no way to tell which are its own --
61
+ see `agents/doer.md` Step 1). Never steal a task already `in_progress`.
59
62
 
60
- **Reviewer returns CHANGES NEEDED** (orchestrator, after reading feedback.md) -- the
61
- reviewer writes its verdict, human notes, and two machine-readable lines to
62
- `feedback.md` (see `doer-reviewer-loop.md` reviewer template). The orchestrator
63
- parses those lines and runs:
63
+ **Reviewer returns CHANGES NEEDED** (orchestrator, after reading the reviewer's
64
+ structured output) -- the reviewer returns its verdict, human notes, and the
65
+ machine-readable `reopenIds` / `newTasks` arrays as structured output (see
66
+ `doer-reviewer-loop.md` reviewer template); it never writes feedback.md. The
67
+ orchestrator reads those fields and runs:
64
68
  ```
65
69
  # for each id in reopenIds:
66
70
  bd update <task-id> --status=open --notes="review: <finding from notes section>"
67
71
 
68
- # for each entry in newTasks:
69
- bd create "<title>" -p <priority> --parent <sprint-id> --assignee <track> --acceptance="<notes>"
72
+ # for each entry in newTasks ({title, description, priority}):
73
+ bd create "<title>" -p <priority> --parent <sprint-id> --assignee <track> --description="<description>"
70
74
  ```
71
75
  Reopened tasks return to `bd ready` as work for the next iteration. On APPROVED
72
76
  neither command is needed -- tasks stay closed.
@@ -87,9 +91,10 @@ durable and visible in the PR.
87
91
 
88
92
  ## Findings are never lost
89
93
 
90
- A review finding against the reviewed task goes into `reopenIds` in feedback.md; the
91
- orchestrator runs `bd update --status=open` so the doer picks it up next loop. A
92
- finding outside the reviewed scope goes into `newTasks`; the orchestrator creates it.
94
+ A review finding against the reviewed task goes into `reopenIds` in the reviewer's
95
+ structured output; the orchestrator runs `bd update --status=open` so the doer picks it
96
+ up next loop. A finding outside the reviewed scope goes into `newTasks`; the
97
+ orchestrator creates it.
93
98
  MEDIUM/LOW findings and any scope deferred mid-sprint become low-priority backlog
94
99
  tasks. Every finding either gets fixed (`bd close`) or is explicitly carried as
95
100
  backlog -- it is never dropped silently.
@@ -118,7 +123,7 @@ bd list --status=open # work still to do
118
123
  bd list --status=in_progress # tasks claimed by an interrupted dispatch
119
124
  bd ready # everything unblocked right now, across tracks
120
125
  bd list --tree <sprint-id> # full sprint tree: tasks, status, assignee
121
- bd show <task-id> # full context: description, acceptance, model tier, notes
126
+ bd show <task-id> # full context: description, acceptance, model tier metadata, notes
122
127
  ```
123
128
  beads reflects claim/close actions, not on-disk completion -- always confirm against
124
129
  `git log <base>..<branch>` and `git status` before acting. A task marked
@@ -91,9 +91,11 @@ per task -- see `doer-reviewer-loop.md` plan-reviewer template), the orchestrato
91
91
  ```
92
92
  Dispatch a single cheap-tier agent to run all `bd update` commands in one pass.
93
93
 
94
- The `taskAssignments` array shape (matches auto-sprint's `PLAN_REVIEW_SCHEMA`).
95
- The `model` field is the **tier name** (`cheap`/`standard`/`premium`) the planner
96
- recorded in the task's beads notes -- never a provider-specific model ID:
94
+ The `taskAssignments` array shape (matches the plan-reviewer role schema,
95
+ `agents/schemas/plan-reviewer-output.json`).
96
+ The `model` field is the **tier name** (`cheap`/`standard`/`premium`) read from the
97
+ task's assigned model tier in its beads metadata (`--metadata '{"model": "<tier>"}'`)
98
+ -- never a provider-specific model ID:
97
99
  ```json
98
100
  [{ "id": "BD-10", "bucket": "M", "model": "standard" }, ...]
99
101
  ```
@@ -131,7 +133,7 @@ The orchestrator appends after each dispatch using a cheap-tier agent (same
131
133
  `appendNewEntries` pattern as auto-sprint). The `label` format `<role>-c<N>-i<M>`
132
134
  is required -- `computeSprintAnalysis` strips the suffix to recover the role name.
133
135
 
134
- If the Claude Code harness does not expose per-subagent token counts, record
136
+ If the harness/CLI does not expose per-subagent token counts, record
135
137
  `outTokens: 0` and `costUsd: 0` -- the analysis will show actuals as zero but the
136
138
  estimate side still works and calibration is not corrupted.
137
139
 
@@ -1,13 +1,15 @@
1
1
  # Doer-Reviewer Loop
2
2
 
3
3
  The execute-phase loop for one track. Every dispatch is an inline subagent call (its
4
- result returns in the same turn). Beads is the task store; `feedback.md` is the
5
- reviewer's output channel. The doer finds work with `bd ready`, claims it with
6
- `bd update --claim`, and closes it with `bd close`. The reviewer reads acceptance
7
- criteria with `bd show` and writes its verdict to `feedback.md` -- it never touches
8
- beads. On CHANGES NEEDED the orchestrator reads `feedback.md` and runs the beads
9
- updates itself. There is no PLAN.md and no progress.json -- code is committed to the
10
- branch; all task state lives in beads. (The plan loop that precedes this -- planner /
4
+ result returns in the same turn). Beads is the task store; the reviewer's verdict is
5
+ returned as structured output directly to the orchestrator. The orchestrator finds
6
+ ready work with `bd ready` and hands the doer explicit bead ids; the doer claims each
7
+ with `bd update --claim` and closes it with `bd close`. The
8
+ reviewer reads acceptance criteria with `bd show` and returns its verdict
9
+ (`verdict`/`notes`/`reopenIds`/`newTasks`) as structured output -- it never touches
10
+ beads. On CHANGES NEEDED the orchestrator reads that structured output and runs the
11
+ beads updates itself. There is no PLAN.md and no progress.json -- code is committed to
12
+ the branch; all task state lives in beads. (The plan loop that precedes this -- planner /
11
13
  plan-reviewer -- is in `sprint.md`.)
12
14
 
13
15
  ## Pre-flight checks
@@ -37,7 +39,7 @@ covers the wrong diff.
37
39
 
38
40
  ```
39
41
  Plan APPROVED, beads tasks created (each with acceptance criteria + model tier in
40
- notes). goal priority = the sprint's exit threshold.
42
+ metadata). goal priority = the sprint's exit threshold.
41
43
  loop:
42
44
  1. Find ready tasks: bd ready (tasks with no open blockers, in the sprint-root subtree).
43
45
  If none AND bd list --status=open at the goal priority is empty AND the last
@@ -58,13 +60,14 @@ notes). goal priority = the sprint's exit threshold.
58
60
  4. Dispatch ONE reviewer (inline) over all tasks worked this iteration. It reads
59
61
  each task's acceptance criteria with `bd show <id>` and the diff. The reviewer
60
62
  runs standard-tier, escalated to premium-tier if any streak this iteration ran
61
- premium-tier. It writes its verdict to feedback.md (see reviewer template) and
62
- commits. Read feedback.md:
63
+ premium-tier. It returns its verdict as structured output only (see reviewer
64
+ template) -- it never writes a file. Read the returned verdict:
63
65
  APPROVED -> tasks stay closed. `reopenIds` and `newTasks` absent or
64
66
  empty -- no beads action needed.
65
67
  CHANGES NEEDED -> the orchestrator parses `reopenIds` and `newTasks` from
66
- feedback.md (see "Orchestrator reads feedback.md" below)
67
- and runs the beads updates. Dispatch the doer to fix.
68
+ the reviewer's structured output (see "Orchestrator reads
69
+ the reviewer's output" below) and runs the beads updates.
70
+ Dispatch the doer to fix.
68
71
  -> back to step 1.
69
72
  ```
70
73
 
@@ -82,7 +85,7 @@ read state from beads + git and dispatch. Never pause for the user mid-loop.
82
85
 
83
86
  The planner assigned each task a model **tier** -- cheap-tier for mechanical tasks,
84
87
  standard-tier for standard implementation, premium-tier for hard design -- and wrote it
85
- into the task's beads notes (`--notes="model: <tier>"`). Read it with `bd show <id>`
88
+ into the task's beads metadata (`--metadata '{"model": "<tier>"}'`). Read it with `bd show <id>`
86
89
  at dispatch time and dispatch the doer on that tier. An iteration may span tiers
87
90
  across its ready tasks; run one doer dispatch per model streak (a run of consecutive
88
91
  tasks sharing a tier), in priority/dependency order. An iteration with three tier
@@ -105,9 +108,9 @@ to completion within the turn -- track A's reviewer can run while track B's doer
105
108
  works -- but keep the turn alive until you have collected their results.
106
109
 
107
110
  After each agent returns, the orchestrator's FIRST action is to read state from beads
108
- and git (`bd ready`, `bd list --status=open`, `bd show <id>`, `feedback.md`,
109
- `git log <base>..<branch>`); those are the source of truth for what was dispatched
110
- and where it landed.
111
+ and git (`bd ready`, `bd list --status=open`, `bd show <id>`, the reviewer's returned
112
+ structured output, `git log <base>..<branch>`); those are the source of truth for what
113
+ was dispatched and where it landed.
111
114
 
112
115
  ## Commit identity
113
116
 
@@ -140,7 +143,7 @@ design.md if present). Follow your planner instructions: explore, draft, front-l
140
143
  foundations, self-critique, refine. Then write the plan into beads under sprint root
141
144
  <sprint-id> -- do NOT write PLAN.md. For each task: bd create "<title>" -p <priority>
142
145
  --parent <sprint-id> --assignee <track> --acceptance="<what must be true to be done>"
143
- --notes="model: <tier>", where <tier> is cheap-tier for mechanical work, standard-tier
146
+ --metadata '{"model": "<tier>"}', where <tier> is cheap-tier for mechanical work, standard-tier
144
147
  for standard implementation, premium-tier for hard design (pick from the tiers available
145
148
  in this environment). Wire dependencies with bd dep add <task> <blocker>. Verify
146
149
  with bd ready that leaf tasks (not features/sprint roots) are unblocked. <transport line>.
@@ -153,26 +156,27 @@ The worktree and branch already exist -- do not create or switch branches.
153
156
  You are reviewing a plan. Your worktree is <abs worktree path> on branch <branch>.
154
157
  cd there; use absolute paths. Read requirements.md and design.md (if present), then
155
158
  inspect the beads DAG under sprint root <sprint-id>: bd graph --compact <sprint-id>, bd ready,
156
- and bd show <id> on each task to read its acceptance criteria and model-tier note.
159
+ and bd show <id> on each task to read its acceptance criteria and model-tier metadata.
157
160
  Follow your plan-reviewer instructions: check coverage, task size, acceptance
158
161
  criteria, dependency direction, and model-tier assignment. Classify each task with a
159
162
  complexity bucket (S = 1 file/narrow scope, M = 2-3 files/moderate logic,
160
- L = 3+ files/non-trivial design) and read its assigned model tier from its notes.
163
+ L = 3+ files/non-trivial design) and read its assigned model tier from its metadata.
161
164
 
162
- Overwrite feedback.md with:
163
- - First line: APPROVED or CHANGES NEEDED
164
- - Notes section: specific findings with issue IDs and exact bd commands to fix any
165
+ Return your structured output ONLY -- do not write a file:
166
+ - `verdict`: APPROVED or CHANGES_NEEDED (exact strings; the machine value is the
167
+ underscore form from agents/schemas/plan-reviewer-output.json)
168
+ - `notes`: specific findings with issue IDs and exact bd commands to fix any
165
169
  dependency direction problems
166
- - taskAssignments section: one line per task in JSON array form:
170
+ - `taskAssignments`: one entry per task in JSON array form:
167
171
  [{"id":"<beads-id>","bucket":"S|M|L","model":"<tier: cheap|standard|premium>"},...]
168
172
 
169
- Commit feedback.md as identity pm-plan-reviewer (git -c user.name='pm-plan-reviewer'
170
- -c user.email='plan-reviewer@pm.local' commit). <transport line>.
173
+ You never write feedback.md or mutate beads -- the orchestrator reads your structured
174
+ output. <transport line>.
171
175
  ```
172
176
 
173
- The orchestrator reads `taskAssignments` from `feedback.md` after APPROVED to run
174
- `computeSprintQuote` (see `cost.md`). The array shape must match exactly:
175
- `[{ "id": "<beads task id>", "bucket": "S|M|L", "model": "<tier: cheap|standard|premium>" }]`.
177
+ The orchestrator reads `taskAssignments` from the plan-reviewer's structured output
178
+ after APPROVED to run `computeSprintQuote` (see `cost.md`). The array shape must match
179
+ exactly: `[{ "id": "<beads task id>", "bucket": "S|M|L", "model": "<tier: cheap|standard|premium>" }]`.
176
180
 
177
181
  ### doer
178
182
 
@@ -199,44 +203,40 @@ You are reviewing code. Your worktree is <abs worktree path> on branch <branch>
199
203
  (base <base>). cd there; use absolute paths. Review ONLY the tasks worked this
200
204
  iteration: <task ids>. Run bd show <id> on each to read its acceptance criteria, and
201
205
  git diff <base>...<branch> to see the changes. Read requirements.md and design.md (if
202
- present). Run the build, linter, and full test suite. Read the prior feedback.md
203
- history (git log -- feedback.md) so you account for how earlier findings were
204
- addressed. Judge each task against its acceptance criteria.
206
+ present). Run the build, linter, and full test suite. Read the prior review history
207
+ (git log <base>..<branch>) so you account for how earlier findings were addressed.
208
+ Judge each task against its acceptance criteria.
205
209
 
206
- Do NOT run any bd commands. Write your verdict to feedback.md in this exact format:
210
+ Do NOT run any bd commands. Return your structured output ONLY -- do not write a file:
207
211
 
208
- APPROVED
209
- <or>
210
- CHANGES NEEDED
211
-
212
- <human-readable notes: one finding per task, referencing the task ID and what
212
+ verdict: "APPROVED" or "CHANGES_NEEDED"
213
+ notes: <human-readable notes: one finding per task, referencing the task ID and what
213
214
  acceptance criterion was not met>
214
-
215
215
  reopenIds: ["<id1>", "<id2>"]
216
- newTasks: [{"title": "fix: <finding>", "notes": "<detail>", "priority": 0}]
216
+ newTasks: [{"title": "fix: <finding>", "description": "<detail>", "priority": "P2"}]
217
+ (newTasks entries use {title, description, priority-as-string} -- the exact shape in
218
+ agents/schemas/reviewer-output.json)
217
219
 
218
- On APPROVED: omit reopenIds and newTasks (or write empty arrays).
220
+ On APPROVED: reopenIds and newTasks are both empty arrays.
219
221
  On CHANGES NEEDED: reopenIds lists every task that failed its acceptance criteria;
220
222
  newTasks lists out-of-scope findings that need a new tracked task (may be []).
221
- Both lines must be present and contain valid JSON arrays when verdict is CHANGES NEEDED.
223
+ Both fields must be present and contain valid JSON arrays when verdict is CHANGES NEEDED.
222
224
 
223
- Overwrite feedback.md with this content and commit as identity pm-reviewer
224
- (git -c user.name='pm-reviewer' -c user.email='reviewer@pm.local' commit).
225
- <transport line>.
225
+ You never write feedback.md or mutate beads -- the orchestrator reads your structured
226
+ output and applies the reopen/create transitions. <transport line>.
226
227
  ```
227
228
 
228
- ### Orchestrator reads feedback.md
229
+ ### Orchestrator reads the reviewer's output
229
230
 
230
- After the reviewer commits, the orchestrator reads feedback.md and runs all beads
231
- updates itself -- the reviewer is a pure reader of beads:
231
+ After the reviewer returns, the orchestrator reads its structured output and runs all
232
+ beads updates itself -- the reviewer is a pure reader of beads:
232
233
 
233
- 1. Parse the verdict from the first non-empty line (`APPROVED` or `CHANGES NEEDED`).
234
+ 1. Read the `verdict` field (`APPROVED` or `CHANGES_NEEDED`).
234
235
  2. On CHANGES NEEDED:
235
- - Find the last line starting with `reopenIds:`, parse the JSON array value.
236
- For each id: `bd update <id> --status=open --notes="<relevant finding from notes section>"`.
236
+ - Read `reopenIds`. For each id: `bd update <id> --status=open --notes="<relevant finding from notes>"`.
237
237
  Reopened tasks return to `bd ready` next iteration.
238
- - Find the last line starting with `newTasks:`, parse the JSON array value.
239
- For each entry: `bd create "<title>" -p <priority> --parent <sprint-id> --assignee <track> --acceptance="<notes>"`.
238
+ - Read `newTasks`. For each entry:
239
+ `bd create "<title>" -p <priority> --parent <sprint-id> --assignee <track> --description="<description>"`.
240
240
  Empty array `[]` means no new tasks to create.
241
241
  3. On APPROVED: no beads action needed.
242
242
 
@@ -245,14 +245,14 @@ updates itself -- the reviewer is a pure reader of beads:
245
245
  Each dispatch is a fresh subagent run; continuity comes from the files it reads.
246
246
  Two ways to continue:
247
247
 
248
- - **Default: fresh dispatch.** Dispatch a new agent of the right role; it
249
- reconstructs context from beads (`bd ready`, `bd show <id>`), `feedback.md`, and
250
- `git log`. This is robust and the right choice across phase boundaries and role
251
- switches -- the agents begin with a context-recovery `git log` and `bd` query.
252
- - **Tight iteration: continue the same agent.** For a quick same-worktree, same-role
248
+ - **Default: fresh dispatch.** Dispatch a new agent with the right tags (tags: ['doer'] / tags: ['reviewer']); it
249
+ reconstructs context from beads (`bd ready`, `bd show <id>`) and `git log`. This is
250
+ robust and the right choice across phase boundaries and tag switches -- the agents
251
+ begin with a context-recovery `git log` and `bd` query.
252
+ - **Tight iteration: continue the same agent.** For a quick same-worktree, same-tag
253
253
  turn -- e.g. the doer addressing review findings it just produced context for --
254
254
  continue the SAME agent instance, which keeps its context. Use this within one
255
- worktree and one role; switch roles with a fresh dispatch.
255
+ worktree and one tag; switch tags with a fresh dispatch.
256
256
 
257
257
  ## Resume rules
258
258
 
@@ -277,18 +277,18 @@ agent's in-session context for a tight follow-up turn.
277
277
  | Plan revision (any feedback iteration) | `true` |
278
278
  | Initial review dispatch | `false` |
279
279
  | Re-review after CHANGES NEEDED + doer fixes | `true` |
280
- | Role switch (doer -> reviewer, or reviewer -> doer) | `false` |
280
+ | Tag switch (tags: ['doer'] -> tags: ['reviewer'], or vice versa) | `false` |
281
281
  | After stop_prompt cancellation (fleet mode) | `false` -- session state unreliable after kill; start fresh |
282
282
  | After session timed out mid-grant (fleet mode) | `true` -- fleet auto-recovers but member restarts without prior context |
283
283
 
284
- A role switch always requires sending the new context (context file or inline
285
- prompt). Never resume across a role switch.
284
+ A tag switch always requires sending the new context (context file or inline
285
+ prompt). Never resume across a tag switch.
286
286
 
287
287
  ## Safeguards
288
288
 
289
289
  | Safeguard | Trigger | Orchestrator action | Limit |
290
290
  |----------------------|----------------------------------|------------------------------------------------------------------|------------------|
291
- | Dispatch retry | Agent errors or returns nothing | Re-dispatch the same role fresh; after 3 fails, pause + flag user | 3 per dispatch |
291
+ | Dispatch retry | Agent errors or returns nothing | Re-dispatch the same tag fresh; after 3 fails, pause + flag user | 3 per dispatch |
292
292
  | Doer-reviewer cycle | Reviewer lists task in `reopenIds`; orchestrator reopens it | Doer fixes, re-review; if 3 cycles leave it open, pause + flag | 3 cycles/task |
293
293
  | Zero progress | Two fresh dispatches, no commits | Escalate to a stronger model; still stuck after the strongest => flag | 2 per model |
294
294
  | Blocked task | Doer left a task open with a `blocked:` note | Read the blocker note (bd show <id>); resolve if mechanical, else flag user | -- |