@apralabs/apra-fleet 0.3.4 → 0.3.6
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 +8 -1
- package/dist/agents/_shared/GRAPH-SEMANTICS.md +47 -0
- package/dist/agents/ci-watcher.md +43 -0
- package/dist/agents/deployer.md +51 -28
- package/dist/agents/doer.md +160 -31
- package/dist/agents/harvester.md +81 -6
- package/dist/agents/integ-test-runner.md +147 -17
- package/dist/agents/plan-reviewer.md +76 -9
- package/dist/agents/planner.md +80 -15
- package/dist/agents/reviewer.md +90 -13
- package/dist/agents/schemas/ci-watcher-input.json +26 -0
- package/dist/agents/schemas/ci-watcher-output.json +18 -0
- package/dist/agents/schemas/deployer-input.json +19 -0
- package/dist/agents/schemas/deployer-output.json +17 -0
- package/dist/agents/schemas/doer-input.json +25 -0
- package/dist/agents/schemas/doer-output.json +22 -0
- package/dist/agents/schemas/harvester-input.json +31 -0
- package/dist/agents/schemas/harvester-output.json +18 -0
- package/dist/agents/schemas/integ-test-runner-input.json +20 -0
- package/dist/agents/schemas/integ-test-runner-output.json +27 -0
- package/dist/agents/schemas/plan-reviewer-input.json +15 -0
- package/dist/agents/schemas/plan-reviewer-output.json +30 -0
- package/dist/agents/schemas/reviewer-input.json +25 -0
- package/dist/agents/schemas/reviewer-output.json +34 -0
- package/dist/cli/config.d.ts +6 -0
- package/dist/cli/config.d.ts.map +1 -1
- package/dist/cli/config.js +11 -0
- package/dist/cli/config.js.map +1 -1
- package/dist/cli/install.d.ts +10 -0
- package/dist/cli/install.d.ts.map +1 -1
- package/dist/cli/install.js +74 -23
- package/dist/cli/install.js.map +1 -1
- package/dist/cli/secret.js +8 -2
- package/dist/cli/secret.js.map +1 -1
- package/dist/cli/uninstall.d.ts.map +1 -1
- package/dist/cli/uninstall.js +19 -0
- package/dist/cli/uninstall.js.map +1 -1
- package/dist/cli/watch.d.ts +8 -0
- package/dist/cli/watch.d.ts.map +1 -0
- package/dist/cli/watch.js +536 -0
- package/dist/cli/watch.js.map +1 -0
- package/dist/index.js +10 -4
- package/dist/index.js.map +1 -1
- package/dist/os/linux.d.ts +1 -0
- package/dist/os/linux.d.ts.map +1 -1
- package/dist/os/linux.js +4 -0
- package/dist/os/linux.js.map +1 -1
- package/dist/os/macos.d.ts +1 -0
- package/dist/os/macos.d.ts.map +1 -1
- package/dist/os/macos.js +5 -0
- package/dist/os/macos.js.map +1 -1
- package/dist/os/os-commands.d.ts +2 -0
- package/dist/os/os-commands.d.ts.map +1 -1
- package/dist/os/windows.d.ts +1 -0
- package/dist/os/windows.d.ts.map +1 -1
- package/dist/os/windows.js +7 -0
- package/dist/os/windows.js.map +1 -1
- package/dist/services/agent-provisioner.d.ts +39 -0
- package/dist/services/agent-provisioner.d.ts.map +1 -0
- package/dist/services/agent-provisioner.js +130 -0
- package/dist/services/agent-provisioner.js.map +1 -0
- package/dist/services/sftp.d.ts +15 -0
- package/dist/services/sftp.d.ts.map +1 -1
- package/dist/services/sftp.js +34 -0
- package/dist/services/sftp.js.map +1 -1
- package/dist/services/ssh.d.ts +13 -0
- package/dist/services/ssh.d.ts.map +1 -1
- package/dist/services/ssh.js +46 -0
- package/dist/services/ssh.js.map +1 -1
- package/dist/services/stall/log-path-resolver.d.ts +8 -0
- package/dist/services/stall/log-path-resolver.d.ts.map +1 -1
- package/dist/services/stall/log-path-resolver.js +12 -4
- package/dist/services/stall/log-path-resolver.js.map +1 -1
- package/dist/services/statusline.d.ts.map +1 -1
- package/dist/services/statusline.js +16 -4
- package/dist/services/statusline.js.map +1 -1
- package/dist/services/user-config.d.ts +14 -0
- package/dist/services/user-config.d.ts.map +1 -1
- package/dist/services/user-config.js +22 -0
- package/dist/services/user-config.js.map +1 -1
- package/dist/services/watch/fleet-log.d.ts +34 -0
- package/dist/services/watch/fleet-log.d.ts.map +1 -0
- package/dist/services/watch/fleet-log.js +168 -0
- package/dist/services/watch/fleet-log.js.map +1 -0
- package/dist/services/watch/project-resolver.d.ts +51 -0
- package/dist/services/watch/project-resolver.d.ts.map +1 -0
- package/dist/services/watch/project-resolver.js +104 -0
- package/dist/services/watch/project-resolver.js.map +1 -0
- package/dist/services/watch/transcript-formatter.d.ts +26 -0
- package/dist/services/watch/transcript-formatter.d.ts.map +1 -0
- package/dist/services/watch/transcript-formatter.js +210 -0
- package/dist/services/watch/transcript-formatter.js.map +1 -0
- package/dist/skills/auto-sprint-args/SKILL.md +88 -0
- package/dist/skills/pm/SKILL.md +101 -42
- package/dist/skills/pm/beads.md +27 -22
- package/dist/skills/pm/cost.md +6 -4
- package/dist/skills/pm/doer-reviewer-loop.md +62 -62
- package/dist/skills/pm/fleet-addendum.md +11 -5
- package/dist/skills/pm/simple-sprint.md +6 -5
- package/dist/skills/pm/sprint.md +53 -37
- package/dist/tools/check-status.d.ts.map +1 -1
- package/dist/tools/check-status.js +47 -29
- package/dist/tools/check-status.js.map +1 -1
- package/dist/tools/cloud-control.d.ts +2 -2
- package/dist/tools/compose-permissions.d.ts +6 -3
- package/dist/tools/compose-permissions.d.ts.map +1 -1
- package/dist/tools/compose-permissions.js +63 -5
- package/dist/tools/compose-permissions.js.map +1 -1
- package/dist/tools/execute-command.d.ts.map +1 -1
- package/dist/tools/execute-command.js +18 -2
- package/dist/tools/execute-command.js.map +1 -1
- package/dist/tools/execute-prompt.d.ts +1 -0
- package/dist/tools/execute-prompt.d.ts.map +1 -1
- package/dist/tools/execute-prompt.js +38 -1
- package/dist/tools/execute-prompt.js.map +1 -1
- package/dist/tools/list-members.d.ts +3 -0
- package/dist/tools/list-members.d.ts.map +1 -1
- package/dist/tools/list-members.js +30 -15
- package/dist/tools/list-members.js.map +1 -1
- package/dist/tools/register-member.d.ts +6 -0
- package/dist/tools/register-member.d.ts.map +1 -1
- package/dist/tools/register-member.js +35 -0
- package/dist/tools/register-member.js.map +1 -1
- package/dist/tools/update-member.d.ts +6 -0
- package/dist/tools/update-member.d.ts.map +1 -1
- package/dist/tools/update-member.js +40 -0
- package/dist/tools/update-member.js.map +1 -1
- package/dist/types.d.ts +2 -0
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/agent-helpers.d.ts +8 -0
- package/dist/utils/agent-helpers.d.ts.map +1 -1
- package/dist/utils/agent-helpers.js +21 -0
- package/dist/utils/agent-helpers.js.map +1 -1
- package/dist/utils/skill-matrix.d.ts +19 -0
- package/dist/utils/skill-matrix.d.ts.map +1 -0
- package/dist/utils/skill-matrix.js +47 -0
- package/dist/utils/skill-matrix.js.map +1 -0
- package/dist/workflows/auto-sprint.js +1207 -204
- package/package.json +3 -2
- package/skills/fleet/permissions.md +60 -5
- package/skills/fleet/profiles/tag-devops.json +4 -0
- package/skills/fleet/profiles/tag-gpu.json +4 -0
- package/skills/fleet/skill-matrix.md +15 -8
- package/version.json +1 -1
- package/dist/services/stall/log-path-resolver.test.d.ts +0 -2
- package/dist/services/stall/log-path-resolver.test.d.ts.map +0 -1
- package/dist/services/stall/log-path-resolver.test.js +0 -76
- package/dist/services/stall/log-path-resolver.test.js.map +0 -1
- package/dist/skills/pm/tpl-progress.json +0 -35
package/dist/skills/pm/SKILL.md
CHANGED
|
@@ -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
|
|
25
|
-
`bd ready` and
|
|
26
|
-
|
|
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
|
|
30
|
-
|
|
31
|
-
|
|
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
|
|
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`
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
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
|
|
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 `--
|
|
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
|
-
|
|
99
|
-
|
|
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
|
-
|
|
104
|
-
|
|
105
|
-
and runs `bd update --status=open` /
|
|
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;
|
|
113
|
-
|
|
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;
|
|
116
|
-
|
|
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
|
|
163
|
-
|
|
164
|
-
|
|
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
|
|
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
|
-
|
|
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
|
|
229
|
-
|
|
230
|
-
|
|
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 (
|
|
248
|
-
|
|
249
|
-
|
|
250
|
-
|
|
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
|
|
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,
|
|
342
|
-
|
|
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.
|
package/dist/skills/pm/beads.md
CHANGED
|
@@ -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
|
|
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
|
|
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
|
|
18
|
-
|
|
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
|
-
--
|
|
43
|
+
--metadata '{"model": "standard-tier"}' # -> task-id
|
|
43
44
|
bd create "T1.2: <title>" -p 2 --parent <sprint-id> --assignee <track> \
|
|
44
|
-
--acceptance="..." --
|
|
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
|
|
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
|
|
58
|
-
|
|
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
|
|
61
|
-
reviewer
|
|
62
|
-
`
|
|
63
|
-
|
|
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> --
|
|
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
|
|
91
|
-
orchestrator runs `bd update --status=open` so the doer picks it
|
|
92
|
-
finding outside the reviewed scope goes into `newTasks`; the
|
|
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
|
package/dist/skills/pm/cost.md
CHANGED
|
@@ -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
|
|
95
|
-
|
|
96
|
-
|
|
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
|
|
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;
|
|
5
|
-
|
|
6
|
-
`bd
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
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
|
-
|
|
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
|
|
62
|
-
|
|
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
|
-
|
|
67
|
-
and runs the beads updates.
|
|
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
|
|
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>`,
|
|
109
|
-
`git log <base>..<branch>`); those are the source of truth for what
|
|
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
|
-
--
|
|
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
|
|
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
|
|
163
|
+
L = 3+ files/non-trivial design) and read its assigned model tier from its metadata.
|
|
161
164
|
|
|
162
|
-
|
|
163
|
-
-
|
|
164
|
-
|
|
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
|
|
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
|
-
|
|
170
|
-
|
|
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
|
|
174
|
-
`computeSprintQuote` (see `cost.md`). The array shape must match
|
|
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
|
|
203
|
-
|
|
204
|
-
|
|
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.
|
|
210
|
+
Do NOT run any bd commands. Return your structured output ONLY -- do not write a file:
|
|
207
211
|
|
|
208
|
-
APPROVED
|
|
209
|
-
<
|
|
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>", "
|
|
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:
|
|
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
|
|
223
|
+
Both fields must be present and contain valid JSON arrays when verdict is CHANGES NEEDED.
|
|
222
224
|
|
|
223
|
-
|
|
224
|
-
|
|
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
|
|
229
|
+
### Orchestrator reads the reviewer's output
|
|
229
230
|
|
|
230
|
-
After the reviewer
|
|
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.
|
|
234
|
+
1. Read the `verdict` field (`APPROVED` or `CHANGES_NEEDED`).
|
|
234
235
|
2. On CHANGES NEEDED:
|
|
235
|
-
-
|
|
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
|
-
-
|
|
239
|
-
|
|
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
|
|
249
|
-
reconstructs context from beads (`bd ready`, `bd show <id>`)
|
|
250
|
-
|
|
251
|
-
|
|
252
|
-
- **Tight iteration: continue the same agent.** For a quick same-worktree, same-
|
|
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
|
|
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
|
-
|
|
|
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
|
|
285
|
-
prompt). Never resume across a
|
|
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
|
|
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 | -- |
|