@apralabs/apra-fleet 0.2.2 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -8
- package/dist/agents/ci-watcher.md +46 -0
- package/dist/agents/deployer.md +75 -0
- package/dist/agents/doer.md +70 -0
- package/dist/agents/harvester.md +79 -0
- package/dist/agents/integ-test-runner.md +96 -0
- package/dist/agents/plan-reviewer.md +64 -0
- package/dist/agents/planner.md +94 -0
- package/dist/agents/reviewer.md +82 -0
- package/dist/cli/agent-transform.d.ts +11 -0
- package/dist/cli/agent-transform.d.ts.map +1 -0
- package/dist/cli/agent-transform.js +63 -0
- package/dist/cli/agent-transform.js.map +1 -0
- package/dist/cli/config.d.ts +1 -0
- package/dist/cli/config.d.ts.map +1 -1
- package/dist/cli/config.js +15 -0
- package/dist/cli/config.js.map +1 -1
- package/dist/cli/install.d.ts +5 -0
- package/dist/cli/install.d.ts.map +1 -1
- package/dist/cli/install.js +200 -23
- package/dist/cli/install.js.map +1 -1
- package/dist/cli/uninstall.js +1 -1
- package/dist/providers/index.d.ts +1 -0
- package/dist/providers/index.d.ts.map +1 -1
- package/dist/providers/index.js +3 -0
- package/dist/providers/index.js.map +1 -1
- package/dist/providers/opencode.d.ts +40 -0
- package/dist/providers/opencode.d.ts.map +1 -0
- package/dist/providers/opencode.js +178 -0
- package/dist/providers/opencode.js.map +1 -0
- package/dist/services/cloud/task-wrapper.js +1 -1
- package/dist/services/cloud/task-wrapper.js.map +1 -1
- package/dist/skills/pm/SKILL.md +343 -0
- package/dist/skills/pm/beads.md +137 -0
- package/dist/skills/pm/cost.md +152 -0
- package/dist/skills/pm/doer-reviewer-loop.md +297 -0
- package/dist/skills/pm/fleet-addendum.md +115 -0
- package/dist/skills/pm/simple-sprint.md +64 -0
- package/dist/skills/pm/sprint.md +311 -0
- package/dist/skills/pm/tpl-progress.json +35 -0
- package/dist/skills/pm/worktrees.md +92 -0
- package/dist/tools/cloud-control.d.ts +2 -2
- package/dist/tools/credential-store-set.d.ts +2 -2
- package/dist/tools/credential-store-update.d.ts +2 -2
- package/dist/tools/execute-prompt.d.ts +3 -0
- package/dist/tools/execute-prompt.d.ts.map +1 -1
- package/dist/tools/execute-prompt.js +17 -3
- package/dist/tools/execute-prompt.js.map +1 -1
- package/dist/tools/register-member.d.ts +29 -6
- package/dist/tools/register-member.d.ts.map +1 -1
- package/dist/tools/register-member.js +43 -3
- package/dist/tools/register-member.js.map +1 -1
- package/dist/tools/update-member.d.ts +29 -6
- package/dist/tools/update-member.d.ts.map +1 -1
- package/dist/tools/update-member.js +43 -3
- package/dist/tools/update-member.js.map +1 -1
- package/dist/types.d.ts +6 -1
- package/dist/types.d.ts.map +1 -1
- package/dist/utils/opencode-model-validation.d.ts +15 -0
- package/dist/utils/opencode-model-validation.d.ts.map +1 -0
- package/dist/utils/opencode-model-validation.js +40 -0
- package/dist/utils/opencode-model-validation.js.map +1 -0
- package/dist/workflows/auto-sprint.js +1676 -0
- package/package.json +2 -2
- package/version.json +1 -1
- package/skills/pm/SKILL.md +0 -110
- package/skills/pm/backlog-item.md +0 -65
- package/skills/pm/beads.md +0 -192
- package/skills/pm/cleanup.md +0 -15
- package/skills/pm/context-file.md +0 -40
- package/skills/pm/doer-reviewer.md +0 -123
- package/skills/pm/init.md +0 -25
- package/skills/pm/multi-pair-sprint.md +0 -64
- package/skills/pm/plan-prompt.md +0 -94
- package/skills/pm/simple-sprint.md +0 -42
- package/skills/pm/single-pair-sprint.md +0 -178
- package/skills/pm/tpl-deploy.md +0 -24
- package/skills/pm/tpl-design.md +0 -29
- package/skills/pm/tpl-doer.md +0 -43
- package/skills/pm/tpl-plan.md +0 -72
- package/skills/pm/tpl-pm.md +0 -2
- package/skills/pm/tpl-progress.json +0 -28
- package/skills/pm/tpl-projects.md +0 -4
- package/skills/pm/tpl-requirements.md +0 -21
- package/skills/pm/tpl-reviewer-plan.md +0 -53
- package/skills/pm/tpl-reviewer.md +0 -72
- package/skills/pm/tpl-status.md +0 -29
|
@@ -0,0 +1,297 @@
|
|
|
1
|
+
# Doer-Reviewer Loop
|
|
2
|
+
|
|
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 /
|
|
11
|
+
plan-reviewer -- is in `sprint.md`.)
|
|
12
|
+
|
|
13
|
+
## Pre-flight checks
|
|
14
|
+
|
|
15
|
+
### Before any dispatch
|
|
16
|
+
|
|
17
|
+
Verify the agent's worktree is on the correct branch with a clean working tree:
|
|
18
|
+
|
|
19
|
+
1. `git -C <worktree> status --porcelain` -- must be empty.
|
|
20
|
+
2. `git -C <worktree> branch --show-current` -- must match the track's branch.
|
|
21
|
+
|
|
22
|
+
Do not dispatch into a worktree on the wrong branch or with uncommitted changes.
|
|
23
|
+
|
|
24
|
+
### Before review dispatch (SHA matching)
|
|
25
|
+
|
|
26
|
+
Verify the reviewer sees the same state the doer pushed:
|
|
27
|
+
|
|
28
|
+
1. `git -C <reviewer-worktree> rev-parse HEAD` -- record the SHA.
|
|
29
|
+
2. Compare with the doer's last pushed HEAD on the track branch.
|
|
30
|
+
3. If SHA does not match: `git -C <reviewer-worktree> fetch origin &&
|
|
31
|
+
git -C <reviewer-worktree> reset --hard origin/<branch>`, then re-verify.
|
|
32
|
+
|
|
33
|
+
Never dispatch a reviewer against stale code -- SHA mismatch means the review
|
|
34
|
+
covers the wrong diff.
|
|
35
|
+
|
|
36
|
+
## The loop (the Develop phase of one cycle)
|
|
37
|
+
|
|
38
|
+
```
|
|
39
|
+
Plan APPROVED, beads tasks created (each with acceptance criteria + model tier in
|
|
40
|
+
notes). goal priority = the sprint's exit threshold.
|
|
41
|
+
loop:
|
|
42
|
+
1. Find ready tasks: bd ready (tasks with no open blockers, in the sprint-root subtree).
|
|
43
|
+
If none AND bd list --status=open at the goal priority is empty AND the last
|
|
44
|
+
reviewer verdict was APPROVED -> Develop phase done; exit to Test (or Harvest
|
|
45
|
+
on the final cycle).
|
|
46
|
+
2. Group ready tasks into model streaks (consecutive tasks sharing a model tier,
|
|
47
|
+
in priority/dependency order). For each streak the doer, on dispatch:
|
|
48
|
+
- reads each task with `bd show <id>` (description, acceptance, model tier),
|
|
49
|
+
- claims it with `bd update <id> --claim`,
|
|
50
|
+
- implements the work and commits,
|
|
51
|
+
- closes it with `bd close <id>`.
|
|
52
|
+
The doer works its streak in order and STOPS at the VERIFY checkpoint.
|
|
53
|
+
3. On doer completion: assert the worktree is clean (`git status --porcelain`
|
|
54
|
+
empty); a dirty tree means the doer left uncommitted work -- send it back to
|
|
55
|
+
commit before any review. If a task is blocked, the doer leaves it open with a
|
|
56
|
+
blocker note -- handle the blocker (see Safeguards). The doer has already
|
|
57
|
+
closed the tasks it finished; the orchestrator does not touch beads here.
|
|
58
|
+
4. Dispatch ONE reviewer (inline) over all tasks worked this iteration. It reads
|
|
59
|
+
each task's acceptance criteria with `bd show <id>` and the diff. The reviewer
|
|
60
|
+
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
|
+
APPROVED -> tasks stay closed. `reopenIds` and `newTasks` absent or
|
|
64
|
+
empty -- no beads action needed.
|
|
65
|
+
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
|
+
-> back to step 1.
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
**Exit condition.** The Develop phase exits when `bd ready` returns nothing, no open
|
|
72
|
+
task at the goal priority remains, **and** the last reviewer verdict was APPROVED --
|
|
73
|
+
a single APPROVED is sufficient because beads tracks discrete tasks, not a
|
|
74
|
+
convergence streak. Any CHANGES NEEDED reopens tasks, so the loop continues until
|
|
75
|
+
they are cleared and a clean APPROVED lands on an empty ready queue. Never advance to
|
|
76
|
+
Test or Harvest with open tasks at the goal priority.
|
|
77
|
+
|
|
78
|
+
The orchestrator does nothing between a doer finishing and a reviewer starting except
|
|
79
|
+
read state from beads + git and dispatch. Never pause for the user mid-loop.
|
|
80
|
+
|
|
81
|
+
## Model per task
|
|
82
|
+
|
|
83
|
+
The planner assigned each task a model **tier** -- cheap-tier for mechanical tasks,
|
|
84
|
+
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>`
|
|
86
|
+
at dispatch time and dispatch the doer on that tier. An iteration may span tiers
|
|
87
|
+
across its ready tasks; run one doer dispatch per model streak (a run of consecutive
|
|
88
|
+
tasks sharing a tier), in priority/dependency order. An iteration with three tier
|
|
89
|
+
groups becomes up to three doer dispatches, each on its own tier. The dispatch whose
|
|
90
|
+
streak reaches the VERIFY task carries through it.
|
|
91
|
+
|
|
92
|
+
The reviewer runs standard-tier, escalated to premium-tier whenever any streak in the
|
|
93
|
+
iteration ran premium-tier -- review must never be weaker than the work it judges. Cheap
|
|
94
|
+
bounded state checks (`bd ready` queries, feedback commits, log appends) run
|
|
95
|
+
cheap-tier.
|
|
96
|
+
|
|
97
|
+
## Dispatch and wait inline
|
|
98
|
+
|
|
99
|
+
Dispatch each subagent and wait for its result in the same turn -- the dispatch
|
|
100
|
+
returns the agent's result to you inline. Run the loop sequentially this way: one
|
|
101
|
+
dispatch, its result, the next. NEVER end your turn while a dispatched agent still
|
|
102
|
+
owes you a result; in a headless run nothing re-invokes you, so ending the turn
|
|
103
|
+
parks the sprint. With multiple tracks, dispatch one per active track and poll them
|
|
104
|
+
to completion within the turn -- track A's reviewer can run while track B's doer
|
|
105
|
+
works -- but keep the turn alive until you have collected their results.
|
|
106
|
+
|
|
107
|
+
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
|
+
|
|
112
|
+
## Commit identity
|
|
113
|
+
|
|
114
|
+
So the branch history shows who did what, each role commits under its OWN git
|
|
115
|
+
identity rather than the ambient one. Pass it inline on every commit -- do not rely
|
|
116
|
+
on global config:
|
|
117
|
+
|
|
118
|
+
```
|
|
119
|
+
git -c user.name='pm-<role>' -c user.email='<role>@pm.local' commit -m "<msg>"
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Identities: `pm-planner`, `pm-plan-reviewer`, `pm-doer`,
|
|
123
|
+
`pm-reviewer`. The orchestrator's own git plumbing (requirements.md, design.md,
|
|
124
|
+
and the completion scaffolding drop) commits as `pm`. Each template below restates
|
|
125
|
+
its identity so the dispatched agent uses it.
|
|
126
|
+
|
|
127
|
+
## Per-role prompt templates
|
|
128
|
+
|
|
129
|
+
Everything the agent needs is in the prompt plus the committed files in its
|
|
130
|
+
worktree. Every prompt pins the worktree path. `<transport line>` is decided once
|
|
131
|
+
per repo (see `worktrees.md` Transport): remote present => "Push your commits." ;
|
|
132
|
+
local-only => "This is a local-only worktree -- commit every turn and skip pushing."
|
|
133
|
+
|
|
134
|
+
### planner
|
|
135
|
+
|
|
136
|
+
```
|
|
137
|
+
You are planning a track. Your worktree is <abs worktree path> on branch <branch>
|
|
138
|
+
(base <base>). cd there first; use absolute paths. Read requirements.md (and
|
|
139
|
+
design.md if present). Follow your planner instructions: explore, draft, front-load
|
|
140
|
+
foundations, self-critique, refine. Then write the plan into beads under sprint root
|
|
141
|
+
<sprint-id> -- do NOT write PLAN.md. For each task: bd create "<title>" -p <priority>
|
|
142
|
+
--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
|
|
144
|
+
for standard implementation, premium-tier for hard design (pick from the tiers available
|
|
145
|
+
in this environment). Wire dependencies with bd dep add <task> <blocker>. Verify
|
|
146
|
+
with bd ready that leaf tasks (not features/sprint roots) are unblocked. <transport line>.
|
|
147
|
+
The worktree and branch already exist -- do not create or switch branches.
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
### plan-reviewer
|
|
151
|
+
|
|
152
|
+
```
|
|
153
|
+
You are reviewing a plan. Your worktree is <abs worktree path> on branch <branch>.
|
|
154
|
+
cd there; use absolute paths. Read requirements.md and design.md (if present), then
|
|
155
|
+
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.
|
|
157
|
+
Follow your plan-reviewer instructions: check coverage, task size, acceptance
|
|
158
|
+
criteria, dependency direction, and model-tier assignment. Classify each task with a
|
|
159
|
+
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.
|
|
161
|
+
|
|
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
|
+
dependency direction problems
|
|
166
|
+
- taskAssignments section: one line per task in JSON array form:
|
|
167
|
+
[{"id":"<beads-id>","bucket":"S|M|L","model":"<tier: cheap|standard|premium>"},...]
|
|
168
|
+
|
|
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>.
|
|
171
|
+
```
|
|
172
|
+
|
|
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>" }]`.
|
|
176
|
+
|
|
177
|
+
### doer
|
|
178
|
+
|
|
179
|
+
```
|
|
180
|
+
You are executing tasks. Your worktree is <abs worktree path> on branch <branch>
|
|
181
|
+
(base <base>). cd there; use absolute paths. Work ONLY task(s) <task scope>, in
|
|
182
|
+
order. For each task: bd show <id> to read its description and acceptance criteria;
|
|
183
|
+
bd update <id> --claim to claim it; implement the work; run fast tests; commit as
|
|
184
|
+
identity pm-doer (git -c user.name='pm-doer' -c user.email='doer@pm.local' commit);
|
|
185
|
+
then bd close <id>. Never close a type=feature or type=bug issue -- only type=task.
|
|
186
|
+
If your scope reaches the VERIFY checkpoint, run it -- build, linter, and full test
|
|
187
|
+
suite -- then stop. Otherwise stop after the last task in <task scope>. If a task is
|
|
188
|
+
blocked, leave it open, add a blocker note (bd update <id> --notes="blocked: ..."),
|
|
189
|
+
and stop. <transport line>. Do not start anything beyond <task scope>. The worktree
|
|
190
|
+
and branch already exist -- do not create branches.
|
|
191
|
+
[If fixing review findings:] the reopened task(s) carry review notes (bd show <id>).
|
|
192
|
+
Address every finding, commit, bd close <id> again, then stop for re-review.
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
### reviewer
|
|
196
|
+
|
|
197
|
+
```
|
|
198
|
+
You are reviewing code. Your worktree is <abs worktree path> on branch <branch>
|
|
199
|
+
(base <base>). cd there; use absolute paths. Review ONLY the tasks worked this
|
|
200
|
+
iteration: <task ids>. Run bd show <id> on each to read its acceptance criteria, and
|
|
201
|
+
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.
|
|
205
|
+
|
|
206
|
+
Do NOT run any bd commands. Write your verdict to feedback.md in this exact format:
|
|
207
|
+
|
|
208
|
+
APPROVED
|
|
209
|
+
<or>
|
|
210
|
+
CHANGES NEEDED
|
|
211
|
+
|
|
212
|
+
<human-readable notes: one finding per task, referencing the task ID and what
|
|
213
|
+
acceptance criterion was not met>
|
|
214
|
+
|
|
215
|
+
reopenIds: ["<id1>", "<id2>"]
|
|
216
|
+
newTasks: [{"title": "fix: <finding>", "notes": "<detail>", "priority": 0}]
|
|
217
|
+
|
|
218
|
+
On APPROVED: omit reopenIds and newTasks (or write empty arrays).
|
|
219
|
+
On CHANGES NEEDED: reopenIds lists every task that failed its acceptance criteria;
|
|
220
|
+
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.
|
|
222
|
+
|
|
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>.
|
|
226
|
+
```
|
|
227
|
+
|
|
228
|
+
### Orchestrator reads feedback.md
|
|
229
|
+
|
|
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:
|
|
232
|
+
|
|
233
|
+
1. Parse the verdict from the first non-empty line (`APPROVED` or `CHANGES NEEDED`).
|
|
234
|
+
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>"`.
|
|
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>"`.
|
|
240
|
+
Empty array `[]` means no new tasks to create.
|
|
241
|
+
3. On APPROVED: no beads action needed.
|
|
242
|
+
|
|
243
|
+
## Continuity between dispatches
|
|
244
|
+
|
|
245
|
+
Each dispatch is a fresh subagent run; continuity comes from the files it reads.
|
|
246
|
+
Two ways to continue:
|
|
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
|
|
253
|
+
turn -- e.g. the doer addressing review findings it just produced context for --
|
|
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.
|
|
256
|
+
|
|
257
|
+
## Resume rules
|
|
258
|
+
|
|
259
|
+
Resume is data-driven from beads task state, not manually reasoned. A fresh dispatch
|
|
260
|
+
re-derives everything from `bd ready` / `bd show <id>` and `git log`; resume keeps an
|
|
261
|
+
agent's in-session context for a tight follow-up turn.
|
|
262
|
+
|
|
263
|
+
### Doer dispatches
|
|
264
|
+
|
|
265
|
+
| Condition | resume |
|
|
266
|
+
|-----------|--------|
|
|
267
|
+
| Next ready task is the same kind of work the agent just finished | `true` (continue session) |
|
|
268
|
+
| Next ready task is a context switch (different feature/area) | `false` (fresh) |
|
|
269
|
+
| After reviewer CHANGES NEEDED -> same doer fixes the reopened task it just built | `true` |
|
|
270
|
+
| Role switch (doer -> reviewer) | `false` |
|
|
271
|
+
|
|
272
|
+
### All dispatches
|
|
273
|
+
|
|
274
|
+
| Dispatch | resume |
|
|
275
|
+
|----------|--------|
|
|
276
|
+
| Initial plan generation | `false` |
|
|
277
|
+
| Plan revision (any feedback iteration) | `true` |
|
|
278
|
+
| Initial review dispatch | `false` |
|
|
279
|
+
| Re-review after CHANGES NEEDED + doer fixes | `true` |
|
|
280
|
+
| Role switch (doer -> reviewer, or reviewer -> doer) | `false` |
|
|
281
|
+
| After stop_prompt cancellation (fleet mode) | `false` -- session state unreliable after kill; start fresh |
|
|
282
|
+
| After session timed out mid-grant (fleet mode) | `true` -- fleet auto-recovers but member restarts without prior context |
|
|
283
|
+
|
|
284
|
+
A role switch always requires sending the new context (context file or inline
|
|
285
|
+
prompt). Never resume across a role switch.
|
|
286
|
+
|
|
287
|
+
## Safeguards
|
|
288
|
+
|
|
289
|
+
| Safeguard | Trigger | Orchestrator action | Limit |
|
|
290
|
+
|----------------------|----------------------------------|------------------------------------------------------------------|------------------|
|
|
291
|
+
| Dispatch retry | Agent errors or returns nothing | Re-dispatch the same role fresh; after 3 fails, pause + flag user | 3 per dispatch |
|
|
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
|
+
| Zero progress | Two fresh dispatches, no commits | Escalate to a stronger model; still stuck after the strongest => flag | 2 per model |
|
|
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 | -- |
|
|
295
|
+
|
|
296
|
+
Escalate to the user only after a safeguard limit trips, on a genuine requirements
|
|
297
|
+
ambiguity, or on a risky/irreversible action. Otherwise keep the loop running.
|
|
@@ -0,0 +1,115 @@
|
|
|
1
|
+
# Fleet Execution Addendum
|
|
2
|
+
|
|
3
|
+
This document covers features that apply ONLY when the pm skill runs in fleet
|
|
4
|
+
mode (dispatching to remote fleet members via execute_prompt). In local subagent
|
|
5
|
+
mode, everything here is skipped -- local subagents inherit the orchestrator's
|
|
6
|
+
permissions and context.
|
|
7
|
+
|
|
8
|
+
## Mode detection
|
|
9
|
+
|
|
10
|
+
At sprint start, detect the execution mode:
|
|
11
|
+
|
|
12
|
+
1. Probe for fleet MCP tools (fleet_status, list_members). If the tool is absent
|
|
13
|
+
or returns no members, fall to local mode.
|
|
14
|
+
2. An explicit --local or --fleet flag from the user overrides the probe.
|
|
15
|
+
3. Default: if fleet members are available AND the task tier has a matching
|
|
16
|
+
member, use fleet mode. Otherwise use local mode.
|
|
17
|
+
|
|
18
|
+
Record the mode in status.md at sprint init so recovery/resume uses the same
|
|
19
|
+
mode.
|
|
20
|
+
|
|
21
|
+
## Permissions
|
|
22
|
+
|
|
23
|
+
Compose and deliver permissions per the fleet skill permissions.md for each
|
|
24
|
+
member's role before dispatch. Recompose when switching roles (doer to reviewer
|
|
25
|
+
or vice versa). Each provider gets its native permission config --
|
|
26
|
+
compose_permissions handles the format automatically.
|
|
27
|
+
|
|
28
|
+
Call compose_permissions before EVERY dispatch regardless of unattended mode.
|
|
29
|
+
|
|
30
|
+
### Unattended modes
|
|
31
|
+
|
|
32
|
+
- `update_member(unattended='auto')` -- safer auto-approval scoped to
|
|
33
|
+
explicitly listed operations.
|
|
34
|
+
- `update_member(unattended='dangerous')` -- full permission bypass. Prefer
|
|
35
|
+
auto over dangerous.
|
|
36
|
+
- Do NOT pass dangerously_skip_permissions to execute_prompt -- it is deprecated
|
|
37
|
+
and ignored.
|
|
38
|
+
|
|
39
|
+
### Mid-sprint permission denial
|
|
40
|
+
|
|
41
|
+
If a member is blocked by a permission denial:
|
|
42
|
+
|
|
43
|
+
1. Call compose_permissions with `grant: [<denied permission>]` and
|
|
44
|
+
project_folder.
|
|
45
|
+
2. This grants the missing permission, delivers the updated config, and appends
|
|
46
|
+
to the ledger so future phases start with it included.
|
|
47
|
+
3. Resume the member with resume=true.
|
|
48
|
+
4. Never bypass by running the denied command yourself via execute_command.
|
|
49
|
+
|
|
50
|
+
Act on the grant promptly -- the inactivity timer fires on stdout silence. If
|
|
51
|
+
it fires while you are composing permissions, resume=true still succeeds via
|
|
52
|
+
stale-session auto-recovery, but the member restarts without its in-progress
|
|
53
|
+
context.
|
|
54
|
+
|
|
55
|
+
## stop_prompt
|
|
56
|
+
|
|
57
|
+
Use stop_prompt (a fleet MCP tool) when a member is working on the wrong thing,
|
|
58
|
+
stuck in a loop, or dispatched with incorrect instructions. Always follow
|
|
59
|
+
immediately with resume=false to start a clean session.
|
|
60
|
+
|
|
61
|
+
stop_prompt kills the member's LLM process. This is distinct from stopping a
|
|
62
|
+
background orchestration sub-task within the PM's own session.
|
|
63
|
+
|
|
64
|
+
## Doer-reviewer pairing (fleet mode)
|
|
65
|
+
|
|
66
|
+
1. Record pair in status.md. Multiple pairs per project is normal.
|
|
67
|
+
2. Override icons via update_member -- doer gets circle, reviewer gets square,
|
|
68
|
+
same color.
|
|
69
|
+
3. Compose and deliver permissions for each member's role.
|
|
70
|
+
4. Send the role-specific agent context file via send_files before dispatch.
|
|
71
|
+
|
|
72
|
+
## Agent context file delivery
|
|
73
|
+
|
|
74
|
+
Each fleet member needs a provider-specific agent context file in their
|
|
75
|
+
work_folder root. It is the member's persistent execution model and survives
|
|
76
|
+
across session resumes.
|
|
77
|
+
|
|
78
|
+
### Provider filename table
|
|
79
|
+
|
|
80
|
+
Use member_detail -> llmProvider to determine the target filename:
|
|
81
|
+
|
|
82
|
+
| Provider | Filename |
|
|
83
|
+
|----------|----------|
|
|
84
|
+
| Claude | CLAUDE.md |
|
|
85
|
+
| Antigravity (agy) | AGY.md |
|
|
86
|
+
| Gemini | GEMINI.md |
|
|
87
|
+
| Codex | AGENTS.md |
|
|
88
|
+
| Copilot | COPILOT.md |
|
|
89
|
+
| OpenCode | OPENCODE.md |
|
|
90
|
+
|
|
91
|
+
### Rules
|
|
92
|
+
|
|
93
|
+
- Pick the correct template based on role and filename based on provider.
|
|
94
|
+
- Fill in {{branch}} and {{base_branch}} with the sprint branch and base branch
|
|
95
|
+
before delivering.
|
|
96
|
+
- Send to member via send_files to the member's work_folder root before dispatch.
|
|
97
|
+
- Never commit to git -- add the filename to the member's .gitignore.
|
|
98
|
+
- On role switch: send the new context file before dispatch.
|
|
99
|
+
- Remove before merge: use the cleanup procedure in sprint.md Completion.
|
|
100
|
+
|
|
101
|
+
## Secrets and credentials
|
|
102
|
+
|
|
103
|
+
Never pass raw secrets in execute_prompt prompts -- reference the credential by
|
|
104
|
+
name only (e.g. "authenticate using credential github_pat"). The member then
|
|
105
|
+
uses {{secure.github_pat}} in its own execute_command calls. The
|
|
106
|
+
{{secure.NAME}} token is substituted at launch time -- reference it bare in
|
|
107
|
+
execute_command, not inside your own quotes (it is already single-quote-escaped
|
|
108
|
+
by the fleet).
|
|
109
|
+
|
|
110
|
+
## Fleet call batching (R8)
|
|
111
|
+
|
|
112
|
+
When executing a sequence of fleet calls -- any combination of send_files,
|
|
113
|
+
execute_command, execute_prompt, receive_files -- club them into a single
|
|
114
|
+
background Agent rather than issuing individual calls or multiple background
|
|
115
|
+
agents. This reduces orchestrator turn overhead.
|
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Simple Sprint
|
|
2
|
+
|
|
3
|
+
A lightweight flow for small, single-session tasks. Use this when the work is
|
|
4
|
+
small enough that the full plan/plan-review loop is unnecessary overhead. State
|
|
5
|
+
still lives in beads + git -- there is no PLAN.md or progress.json in any sprint.
|
|
6
|
+
|
|
7
|
+
## When to use
|
|
8
|
+
|
|
9
|
+
- 1-3 tasks, completable in a single session
|
|
10
|
+
- No complex phasing or cross-phase dependencies
|
|
11
|
+
- Low risk, well-understood scope
|
|
12
|
+
|
|
13
|
+
Use the full sprint lifecycle (sprint.md) for anything larger. If the work turns
|
|
14
|
+
out bigger than expected, promote to a full sprint.
|
|
15
|
+
|
|
16
|
+
## Flow
|
|
17
|
+
|
|
18
|
+
1. Write a concise requirements.md on the branch and commit.
|
|
19
|
+
2. Create a small beads sprint root + a task per item, each with `--acceptance="..."` and a
|
|
20
|
+
`--notes="model: <tier>"` tag.
|
|
21
|
+
3. Dispatch the doer (tier sized to the work). The doer claims each task
|
|
22
|
+
(`bd update <id> --claim`), implements, commits, pushes, and closes it
|
|
23
|
+
(`bd close <id>`).
|
|
24
|
+
4. Dispatch the reviewer (premium-tier, fresh session). It reads each task's acceptance
|
|
25
|
+
criteria (`bd show <id>`) + the diff and outputs a verdict: APPROVED or
|
|
26
|
+
CHANGES NEEDED.
|
|
27
|
+
5. On APPROVED: close the delivered source issues, clean sprint scaffolding from the
|
|
28
|
+
PR (see sprint.md Completion step 5 -- git rm sprint-created narrative files,
|
|
29
|
+
restore any the repo already shipped, then verify the net diff is product only),
|
|
30
|
+
commit as pm, raise the PR (or report the diff for local-only), remove the
|
|
31
|
+
worktree.
|
|
32
|
+
6. On CHANGES NEEDED: the orchestrator reads `reopenIds` and `newTasks` from
|
|
33
|
+
feedback.md; runs `bd update <id> --status=open` for each reopen ID and
|
|
34
|
+
`bd create` for each new task; then re-dispatches the doer from step 3.
|
|
35
|
+
7. Create low-priority beads tasks for any unresolved findings or deferred items.
|
|
36
|
+
8. STOP: do not merge. Surface the PR URL and CI status to the user and await
|
|
37
|
+
explicit instruction.
|
|
38
|
+
|
|
39
|
+
## Rules
|
|
40
|
+
|
|
41
|
+
- Still requires pre-flight checks (see doer-reviewer-loop.md Pre-flight checks).
|
|
42
|
+
- In fleet mode: still requires permissions and doer/reviewer pairing (see
|
|
43
|
+
fleet-addendum.md).
|
|
44
|
+
- Beads + git carry the state -- as in every sprint, no progress.json or PLAN.md.
|
|
45
|
+
- Branch naming: choose a name that makes the purpose clear --
|
|
46
|
+
feat/<description>, fix/<description>, chore/<description>.
|
|
47
|
+
|
|
48
|
+
## Recovery after orchestrator restart
|
|
49
|
+
|
|
50
|
+
Recovery relies on beads and git history.
|
|
51
|
+
|
|
52
|
+
1. `bd list --tree <sprint-id>` (and `bd ready`) -- what is open, in progress, closed.
|
|
53
|
+
2. Per worktree: `git log --oneline -5` -- any commits since last known state?
|
|
54
|
+
3. `git status` -- uncommitted changes?
|
|
55
|
+
|
|
56
|
+
Then act:
|
|
57
|
+
|
|
58
|
+
- **Task in_progress with no matching commits** -> reset it
|
|
59
|
+
(`bd update <id> --status=open`) and re-dispatch the doer.
|
|
60
|
+
- **Work committed, next step clear** -> dispatch reviewer or continue doer.
|
|
61
|
+
- **At review checkpoint** -> dispatch reviewer (fresh session).
|
|
62
|
+
- **Uncommitted changes of unknown origin** -> escalate to user: "commit and
|
|
63
|
+
resume, or discard?"
|
|
64
|
+
- **No progress** -> re-dispatch from scratch.
|