@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.
Files changed (87) hide show
  1. package/README.md +29 -8
  2. package/dist/agents/ci-watcher.md +46 -0
  3. package/dist/agents/deployer.md +75 -0
  4. package/dist/agents/doer.md +70 -0
  5. package/dist/agents/harvester.md +79 -0
  6. package/dist/agents/integ-test-runner.md +96 -0
  7. package/dist/agents/plan-reviewer.md +64 -0
  8. package/dist/agents/planner.md +94 -0
  9. package/dist/agents/reviewer.md +82 -0
  10. package/dist/cli/agent-transform.d.ts +11 -0
  11. package/dist/cli/agent-transform.d.ts.map +1 -0
  12. package/dist/cli/agent-transform.js +63 -0
  13. package/dist/cli/agent-transform.js.map +1 -0
  14. package/dist/cli/config.d.ts +1 -0
  15. package/dist/cli/config.d.ts.map +1 -1
  16. package/dist/cli/config.js +15 -0
  17. package/dist/cli/config.js.map +1 -1
  18. package/dist/cli/install.d.ts +5 -0
  19. package/dist/cli/install.d.ts.map +1 -1
  20. package/dist/cli/install.js +200 -23
  21. package/dist/cli/install.js.map +1 -1
  22. package/dist/cli/uninstall.js +1 -1
  23. package/dist/providers/index.d.ts +1 -0
  24. package/dist/providers/index.d.ts.map +1 -1
  25. package/dist/providers/index.js +3 -0
  26. package/dist/providers/index.js.map +1 -1
  27. package/dist/providers/opencode.d.ts +40 -0
  28. package/dist/providers/opencode.d.ts.map +1 -0
  29. package/dist/providers/opencode.js +178 -0
  30. package/dist/providers/opencode.js.map +1 -0
  31. package/dist/services/cloud/task-wrapper.js +1 -1
  32. package/dist/services/cloud/task-wrapper.js.map +1 -1
  33. package/dist/skills/pm/SKILL.md +343 -0
  34. package/dist/skills/pm/beads.md +137 -0
  35. package/dist/skills/pm/cost.md +152 -0
  36. package/dist/skills/pm/doer-reviewer-loop.md +297 -0
  37. package/dist/skills/pm/fleet-addendum.md +115 -0
  38. package/dist/skills/pm/simple-sprint.md +64 -0
  39. package/dist/skills/pm/sprint.md +311 -0
  40. package/dist/skills/pm/tpl-progress.json +35 -0
  41. package/dist/skills/pm/worktrees.md +92 -0
  42. package/dist/tools/cloud-control.d.ts +2 -2
  43. package/dist/tools/credential-store-set.d.ts +2 -2
  44. package/dist/tools/credential-store-update.d.ts +2 -2
  45. package/dist/tools/execute-prompt.d.ts +3 -0
  46. package/dist/tools/execute-prompt.d.ts.map +1 -1
  47. package/dist/tools/execute-prompt.js +17 -3
  48. package/dist/tools/execute-prompt.js.map +1 -1
  49. package/dist/tools/register-member.d.ts +29 -6
  50. package/dist/tools/register-member.d.ts.map +1 -1
  51. package/dist/tools/register-member.js +43 -3
  52. package/dist/tools/register-member.js.map +1 -1
  53. package/dist/tools/update-member.d.ts +29 -6
  54. package/dist/tools/update-member.d.ts.map +1 -1
  55. package/dist/tools/update-member.js +43 -3
  56. package/dist/tools/update-member.js.map +1 -1
  57. package/dist/types.d.ts +6 -1
  58. package/dist/types.d.ts.map +1 -1
  59. package/dist/utils/opencode-model-validation.d.ts +15 -0
  60. package/dist/utils/opencode-model-validation.d.ts.map +1 -0
  61. package/dist/utils/opencode-model-validation.js +40 -0
  62. package/dist/utils/opencode-model-validation.js.map +1 -0
  63. package/dist/workflows/auto-sprint.js +1676 -0
  64. package/package.json +2 -2
  65. package/version.json +1 -1
  66. package/skills/pm/SKILL.md +0 -110
  67. package/skills/pm/backlog-item.md +0 -65
  68. package/skills/pm/beads.md +0 -192
  69. package/skills/pm/cleanup.md +0 -15
  70. package/skills/pm/context-file.md +0 -40
  71. package/skills/pm/doer-reviewer.md +0 -123
  72. package/skills/pm/init.md +0 -25
  73. package/skills/pm/multi-pair-sprint.md +0 -64
  74. package/skills/pm/plan-prompt.md +0 -94
  75. package/skills/pm/simple-sprint.md +0 -42
  76. package/skills/pm/single-pair-sprint.md +0 -178
  77. package/skills/pm/tpl-deploy.md +0 -24
  78. package/skills/pm/tpl-design.md +0 -29
  79. package/skills/pm/tpl-doer.md +0 -43
  80. package/skills/pm/tpl-plan.md +0 -72
  81. package/skills/pm/tpl-pm.md +0 -2
  82. package/skills/pm/tpl-progress.json +0 -28
  83. package/skills/pm/tpl-projects.md +0 -4
  84. package/skills/pm/tpl-requirements.md +0 -21
  85. package/skills/pm/tpl-reviewer-plan.md +0 -53
  86. package/skills/pm/tpl-reviewer.md +0 -72
  87. package/skills/pm/tpl-status.md +0 -29
@@ -0,0 +1,343 @@
1
+ ---
2
+ name: pm
3
+ description: Project Manager skill. One orchestrator session drives eight subagent roles -- planner, plan-reviewer, doer, reviewer, deployer, integ-test-runner, ci-watcher, harvester -- through cycles of Plan, Develop, Test, and Harvest across one or more parallel tracks in isolated git worktrees, running each task on a complexity-matched model tier and looping to a reviewer-APPROVED verdict and a PR. Sprint state lives in a beads task DB (the single source of truth) and git. Use to drive a single project's multi-step development end to end.
4
+ ---
5
+
6
+ # pm -- Project Manager
7
+
8
+ You are the orchestrator. From one session you drive a project's development by
9
+ dispatching subagents across sprint-core and lifecycle-support roles, running
10
+ **cycles** of four **phases** -- Plan, Develop, Test, Harvest -- until the work is
11
+ APPROVED and a PR is raised. You never write code yourself -- you dispatch, read
12
+ verdicts, manage git and the task DB, and drive the loop.
13
+
14
+ One orchestrator manages exactly **one project**. Within that project, work may be
15
+ split into independent **tracks** that run in parallel, each in its own git
16
+ worktree (see Tracks and parallelism).
17
+
18
+ ## State lives in two places
19
+
20
+ All sprint state is held in:
21
+
22
+ - **beads (`bd`), the task DB -- the single source of truth and the message bus:**
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 --
27
+ beads holds all task state. See `beads.md`.
28
+ - **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
+
33
+ On every dispatch completion and after any restart, re-derive position from beads and
34
+ git -- they are the single source of truth.
35
+
36
+ ## Cycles and phases
37
+
38
+ A sprint runs as one or more **cycles**. Each cycle moves through three phases in
39
+ order; a fourth phase runs once at sprint close.
40
+
41
+ - **Plan** -- dispatch `planner` to write the task DAG into beads (titles,
42
+ acceptance criteria, model-tier notes, priorities, dependencies), loop
43
+ `plan-reviewer` to APPROVED. Skip the loop if planning is already complete (sprint root
44
+ has features and every open feature's tasks carry acceptance criteria); just reset
45
+ any task orphaned `in_progress` from a crashed dispatch back to open.
46
+ - **Develop** -- run the doer-review loop. Read `bd ready`, dispatch `doer` per ready
47
+ model streak (each doer claims and closes its tasks in beads), then one `reviewer`
48
+ over the worked tasks. Repeat until `bd ready` is empty, no open task remains at
49
+ the goal priority, and the last review verdict is APPROVED.
50
+ - **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
+ - **Harvest** -- runs once after the cycle loop exits (goal met or cycle ceiling
56
+ hit): poll CI via `ci-watcher`, run a final reviewer pass, then `harvester`
57
+ extracts durable knowledge into `docs/` and `CHANGELOG`, and raise the PR.
58
+
59
+ At the end of each cycle, check the **goal**: the sprint is done when no open
60
+ beads issue in the sprint-root subtree sits at or above the goal priority (default
61
+ P1/P2). If the goal is met, exit the cycle loop and run Harvest. Otherwise start
62
+ the next cycle, capped by a cycle ceiling (default 5). Abort early if a cycle
63
+ resolves none of the previous cycle's open issues -- two cycles with no progress
64
+ is a signal to stop and flag the user, not loop forever.
65
+
66
+ ### Develop exit condition
67
+
68
+ The Develop phase exits when `bd ready` returns nothing, `bd list --status=open` at
69
+ the goal priority is empty, **and** the last `reviewer` verdict was APPROVED. A
70
+ single APPROVED is sufficient -- beads tracks discrete tasks, so once every task is
71
+ closed and the final review passes there is nothing left to converge on. Any CHANGES
72
+ NEEDED reopens the failing tasks (they return to `bd ready`), so the loop simply
73
+ continues until they are cleared and a clean APPROVED lands on an empty queue. This
74
+ gate guards the transition from Develop into Test (or, on the final cycle, into
75
+ Harvest): never deploy or harvest with open tasks at the goal priority.
76
+
77
+ ## Role taxonomy
78
+
79
+ Eight subagent roles carry the work, split into two groups.
80
+
81
+ **Sprint-core** roles run every cycle, one of: `planner`, `plan-reviewer`,
82
+ `doer`, `reviewer`.
83
+
84
+ **Lifecycle-support** roles run only when their phase or condition fires, one of:
85
+ `deployer`, `integ-test-runner`, `ci-watcher`, `harvester`.
86
+
87
+ 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
89
+ track's branch.
90
+
91
+ ### Sprint-core roles
92
+
93
+ - `planner` -- reads `requirements.md` (and `design.md` if present), writes the task
94
+ 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.
97
+ - `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
100
+ `bd show`, claims it (`bd update --claim`), implements one task at a time, commits
101
+ after each, closes it (`bd close`), STOPS at every VERIFY checkpoint.
102
+ - `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.
106
+
107
+ ### Lifecycle-support roles
108
+
109
+ Dispatch these only when their condition holds:
110
+
111
+ - `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.
114
+ - `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.
118
+ - `ci-watcher` -- in Harvest, to poll CI for the sprint HEAD SHA (green / red /
119
+ not configured / pending). [Fleet mode] PM may run `gh` CLI directly instead of
120
+ dispatching (R13).
121
+ - `harvester` -- in Harvest, at sprint close, to extract durable knowledge into
122
+ `docs/` and update `CHANGELOG`.
123
+
124
+ ## Tracks and parallelism
125
+
126
+ A **track** is one independent unit of work: one branch, one worktree, and its own
127
+ full pipeline (`planner` -> `plan-reviewer` -> `doer` -> `reviewer`). A project may
128
+ run a single track, or several tracks at once.
129
+
130
+ - **A single track** is the common case: one branch, the pipeline runs end to end.
131
+ - **Multiple tracks** run when the work splits into independent, low-coupling units.
132
+ Each track gets its own worktree and branch and its own full pipeline, and the
133
+ tracks run **concurrently** -- nothing forces one track's planner to wait on
134
+ another track's doer. The orchestrator fans out, drives each track's loop
135
+ independently, and integrates at the end.
136
+
137
+ Within one track the pipeline is sequential (the doer stops before the reviewer
138
+ runs). Across tracks everything is parallel. Worktrees give each track its own
139
+ files, so concurrent tracks never collide. See `worktrees.md` for topology and
140
+ `sprint.md` for the parallel integration flow.
141
+
142
+ ## Dispatch
143
+
144
+ Each dispatch is one inline subagent call. It carries everything the agent
145
+ needs in the prompt, since agents share the filesystem:
146
+
147
+ - **Role** -- one of the roles listed in the taxonomy above.
148
+ - **Prompt** -- pins the track's worktree (absolute path + branch) and states the
149
+ task. Per-role templates are in `doer-reviewer-loop.md`.
150
+ - **Inline** -- dispatch a subagent and receive its result in the same turn, then
151
+ act on it; run the loop sequentially this way. For parallel tracks, dispatch
152
+ several at once and poll them to completion within the turn. Keep the turn alive
153
+ until the results are in -- do not end it expecting to be re-invoked.
154
+ - **Model** -- the exact model the planner assigned to this task (see Model
155
+ assignment); the orchestrator passes it through verbatim.
156
+
157
+ ## Model assignment
158
+
159
+ Matching model power to task complexity is a headline capability of this skill, not
160
+ an option. Models fall into three tiers, strongest to cheapest: **premium-tier**,
161
+ **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.
165
+
166
+ How the planner chooses the doer tier:
167
+
168
+ - **cheap-tier** -- mechanical work: rename, move, config tweak, simple wiring,
169
+ boilerplate.
170
+ - **standard-tier** -- standard implementation: a new function, an API endpoint, a
171
+ test suite, a focused refactor.
172
+ - **premium-tier** -- hard work: architecture, multi-file design, high-ambiguity or
173
+ cross-cutting reasoning.
174
+
175
+ It picks from the models actually available in the current environment.
176
+
177
+ Fixed rules:
178
+
179
+ - 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.
181
+ - `planner` runs premium-tier; `plan-reviewer` runs standard-tier. The `reviewer` runs
182
+ standard-tier by default but escalates to premium-tier whenever any doer streak in the
183
+ iteration ran premium-tier -- review must never be weaker than the work it judges.
184
+ Planning and review are the quality gates and must not be under-powered.
185
+ - Cheap, bounded state-check dispatches (read-only `bd`/`git` queries such as
186
+ `bd ready` / `bd show`, log appends, feedback commits) run cheap-tier.
187
+ - A user override always wins.
188
+
189
+ ## Sprint selection
190
+
191
+ Before starting, choose the shape that fits:
192
+
193
+ | Condition | Sprint type | Reference |
194
+ |-----------|-------------|-----------|
195
+ | 1-3 tasks, one sitting, low risk, no phasing | Lightweight | `simple-sprint.md` |
196
+ | Work splits into independent, low-coupling units | Parallel tracks | `sprint.md` Parallel tracks |
197
+ | Default | Single track, full lifecycle | `sprint.md` |
198
+
199
+ If tracks are tightly coupled or share significant upfront dependencies, use
200
+ single track -- splitting tightly coupled work creates more coordination overhead
201
+ than it saves.
202
+
203
+ ## Command reference
204
+
205
+ | Command | Action | Details |
206
+ |---------|--------|---------|
207
+ | `/pm plan <requirement>` | Write requirements, dispatch planner, loop plan-reviewer to APPROVED | `sprint.md` |
208
+ | `/pm start` | Run the doer-review loop for the next pending phase | `doer-reviewer-loop.md` |
209
+ | `/pm status` | Report position from beads + git | -- |
210
+ | `/pm resume` / `/pm recover` | Reconstruct state from beads + git and continue | `sprint.md` Recovery |
211
+ | `/pm deploy` | Run the project's deploy.md runbook | `sprint.md` Test |
212
+ | `/pm backlog` / `/pm tasks` | Manage deferred items and view the task tree via beads | `beads.md` |
213
+ | `/pm cleanup` | Close sprint root, drop scaffolding, raise PR, remove worktrees | `sprint.md` Completion |
214
+ | `/pm init <project>` | Set up project folder, beads sprint root, worktree | `sprint.md` Setup |
215
+ | `/pm pair <doer> <reviewer>` | Assign doer-reviewer pair (fleet mode) | `fleet-addendum.md` |
216
+
217
+ ## Core rules
218
+
219
+ R1. NEVER read code to diagnose, fix, or write it. You dispatch agents, read
220
+ verdicts, and drive the loop. The only code you touch is git plumbing
221
+ (`git worktree add/list/remove`, `git merge`, `git diff <base>...<branch>`),
222
+ beads commands, and PR commands.
223
+ 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
226
+ outside a track's worktree or in the skill folder.
227
+ 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.
231
+ R4. **[Fleet mode]** Before dispatch: verify member has required tools via
232
+ `execute_command -> which <tool>` or `<tool> --version`.
233
+ R5. **[Fleet mode]** If a member can finish in one session (1-3 steps), use
234
+ ad-hoc `execute_prompt`. Otherwise use the task harness.
235
+ R6. NEVER let agents sit idle -- after planning, immediately start execution.
236
+ At VERIFY checkpoints, immediately dispatch reviews.
237
+ R7. During execution: keep going until stuck or done -- do not wait for the
238
+ user. At checkpoints, filter questions: resolve what you can, only escalate
239
+ genuine ambiguities. During planning: escalate tough calls (ambiguous
240
+ requirements, risky trade-offs, architectural decisions).
241
+ R8. **[Fleet mode]** When executing a sequence of fleet calls (send_files,
242
+ execute_command, execute_prompt, receive_files), club them into a single
243
+ background Agent rather than issuing individual calls.
244
+ R9. **[Fleet mode]** For unattended execution, use `update_member(unattended=
245
+ 'auto')` for safer auto-approval or `update_member(unattended='dangerous')`
246
+ 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.
251
+ R11. Definition of done includes security audit and documentation -- ensure
252
+ both are covered when adding tools/features.
253
+ R12. At sprint completion: raise a PR, verify CI is green -- do NOT merge.
254
+ Merge is the user's decision.
255
+ R13. **[Fleet mode]** PM runs `gh` CLI commands directly via Bash -- never
256
+ delegate to fleet members. PM owns PR lifecycle and CI file commits.
257
+ R14. Always read referenced sub-documents before executing PM commands.
258
+
259
+ Rules marked **[Fleet mode]** apply only when running with fleet members. In
260
+ local subagent mode they are skipped or adapted (see `fleet-addendum.md` for
261
+ the fleet-specific execution model).
262
+
263
+ ## Secrets and credentials (fleet mode)
264
+
265
+ When running via fleet, never pass raw secrets in `execute_prompt` prompts --
266
+ reference the credential by name only (e.g. "authenticate using credential
267
+ github_pat"). The member then uses `{{secure.github_pat}}` in its own
268
+ `execute_command` calls. See `fleet-addendum.md` for the full reference.
269
+
270
+ ## Provider awareness (fleet mode)
271
+
272
+ When dispatching to fleet members, the orchestrator must account for
273
+ provider-specific behaviors. The most important is the agent context file
274
+ filename -- each provider expects a different name:
275
+
276
+ | Provider | Context file |
277
+ |----------|-------------|
278
+ | Claude | CLAUDE.md |
279
+ | Antigravity (agy) | AGY.md |
280
+ | Gemini | GEMINI.md |
281
+ | Codex | AGENTS.md |
282
+ | Copilot | COPILOT.md |
283
+ | OpenCode | OPENCODE.md |
284
+
285
+ In local subagent mode, context is passed inline via the dispatch prompt --
286
+ the filename table does not apply.
287
+
288
+ ## Lifecycle
289
+
290
+ A sprint runs as cycles of phases. Within a cycle, do not skip or stall between
291
+ phases.
292
+
293
+ ```
294
+ per cycle: Plan (planner writes beads tasks -> plan-reviewer loop) -> Develop
295
+ (doer-review loop: bd ready -> claim -> close, to a clean APPROVED)
296
+ -> Test (deploy + integ tests, if applicable)
297
+ -> goal check -> next cycle | exit
298
+ at close: Harvest (CI watch -> final review -> docs/CHANGELOG -> PR)
299
+ ```
300
+
301
+ For small, low-risk work (1-3 tasks, no phasing) use the lightweight path instead
302
+ of the full harness. See `sprint.md` Sprint selection.
303
+
304
+ ## Commands
305
+
306
+ The orchestrator performs these operations. Each reads and writes state through beads
307
+ and git.
308
+
309
+ - **plan** `<requirement>` -- write `requirements.md` (+ `design.md` when warranted),
310
+ dispatch `planner` to create tasks in beads under the sprint root (acceptance criteria, model
311
+ tier, priorities, dependencies), loop `plan-reviewer` to APPROVED. See `sprint.md`.
312
+ - **start** -- run the doer-review loop for the next pending phase. See
313
+ `doer-reviewer-loop.md`.
314
+ - **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`.
316
+ - **resume** / **recover** -- reconstruct in-flight state from beads + git and
317
+ continue. See `sprint.md` Recovery.
318
+ - **deploy** -- run the project's `deploy.md` runbook (execute / verify / rollback).
319
+ See `sprint.md` Test.
320
+ - **backlog** / **tasks** -- manage deferred items and view the task tree via beads.
321
+ See `beads.md`.
322
+ - **cleanup** -- close the beads sprint root and the delivered source issues, drop the
323
+ sprint scaffolding files (so the PR's net diff is product only), raise the PR, and
324
+ remove the track worktrees. See `sprint.md` Completion.
325
+
326
+ ## Sub-documents
327
+
328
+ - `sprint.md` -- full lifecycle: the cycle loop, requirements, design, Plan,
329
+ Develop, Test, Harvest, goal and exit gates, sprint selection, parallel-track
330
+ integration, and recovery.
331
+ - `simple-sprint.md` -- lightweight 1-3 task flow (beads + git only, like every
332
+ sprint).
333
+ - `doer-reviewer-loop.md` -- the dispatch loop: per-role prompt templates,
334
+ inline dispatch, continuity between dispatches, and safeguards.
335
+ - `worktrees.md` -- worktree topology, parallel-track layout, lifecycle, transport.
336
+ - `beads.md` -- the task-DB backbone and single source of truth: sprint-root/task
337
+ lifecycle, acceptance criteria, model tiers, findings-as-tasks, backlog, recovery,
338
+ PR linking.
339
+ - `fleet-addendum.md` -- fleet-only execution: permissions, compose_permissions,
340
+ 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.
@@ -0,0 +1,137 @@
1
+ # Beads -- the single source of truth
2
+
3
+ beads (`bd`) is pm's task store and message bus. It holds what is in flight, what
4
+ is blocked, what was deferred, what each task must satisfy, and what each review
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
8
+ history, and the requirements/design narrative; **beads holds all task state.**
9
+
10
+ ## One project, one DB
11
+
12
+ An orchestrator manages one project, so there is one beads DB for that project and
13
+ one **sprint root** per sprint. The DB is a local `.beads/` at the **base checkout** (the
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` /
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.
19
+ The DB persists on disk across sessions, so it survives without being committed.
20
+ Committing it is optional and only shares issue history across machines; if you do,
21
+ commit it on the base or integration branch -- keeping it off the track feature
22
+ branches so parallel tracks share one DB. Tasks reference their track via assignee
23
+ or label.
24
+
25
+ ## Lifecycle hooks (not optional)
26
+
27
+ `bd` is called at these points. The planner, doer, and reviewer run their own `bd`
28
+ commands; the orchestrator runs setup, completion, and recovery queries.
29
+
30
+ **Sprint setup** (orchestrator) -- create the sprint root, reusing an existing one if present:
31
+ ```
32
+ bd search "sprint: <name>" --status all # reuse the id if found
33
+ bd create "sprint: <name>" -p 1 # else create -> <sprint-id>
34
+ ```
35
+
36
+ **Plan phase** (planner) -- one task per plan item, each carrying its acceptance
37
+ criteria, assigned model tier, priority, and track; dependencies wired. The planner
38
+ writes these directly into beads -- there is no PLAN.md:
39
+ ```
40
+ bd create "T1.1: <title>" -p 1 --parent <sprint-id> --assignee <track> \
41
+ --acceptance="<what must be true for this task to be done>" \
42
+ --notes="model: standard-tier" # -> task-id
43
+ bd create "T1.2: <title>" -p 2 --parent <sprint-id> --assignee <track> \
44
+ --acceptance="..." --notes="model: cheap-tier"
45
+ bd dep add <T1.2-id> <T1.1-id> # T1.2 blocked until T1.1 done
46
+ ```
47
+ The acceptance criteria are the reviewer's contract; the model tier in notes is the
48
+ doer's dispatch tier. Both live on the task -- nothing is written to a plan file.
49
+
50
+ **Doer dispatch** (doer) -- read the task, claim it, implement, close it:
51
+ ```
52
+ bd show <task-id> # read description + acceptance + model tier
53
+ bd update <task-id> --claim # claim (open -> in_progress, assigns self)
54
+ bd close <task-id> # when the work is complete
55
+ bd ready # confirm what is unblocked next
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`.
59
+
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:
64
+ ```
65
+ # for each id in reopenIds:
66
+ bd update <task-id> --status=open --notes="review: <finding from notes section>"
67
+
68
+ # for each entry in newTasks:
69
+ bd create "<title>" -p <priority> --parent <sprint-id> --assignee <track> --acceptance="<notes>"
70
+ ```
71
+ Reopened tasks return to `bd ready` as work for the next iteration. On APPROVED
72
+ neither command is needed -- tasks stay closed.
73
+
74
+ **At completion** -- close the sprint root, close the delivered source issues, persist the
75
+ state, link the PR:
76
+ ```
77
+ bd close <sprint-id> <source-issue-id> [<source-issue-id> ...]
78
+ bd export -o <track-worktree>/.beads/issues.jsonl # refresh the tracked file from the db
79
+ bd note <sprint-id> "PR: <url>"
80
+ ```
81
+ The source issues are the ready backlog items the sprint's requirement was drawn
82
+ from. Closing the sprint root alone leaves them open, so the backlog never reflects the
83
+ delivered work -- close them here too. With a db backend (dolt) `bd close` does NOT
84
+ update `issues.jsonl`; `bd export -o <file>` rewrites it (a bare `bd export` prints to
85
+ stdout). Commit the refreshed `.beads/issues.jsonl` on the branch so the closures are
86
+ durable and visible in the PR.
87
+
88
+ ## Findings are never lost
89
+
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.
93
+ MEDIUM/LOW findings and any scope deferred mid-sprint become low-priority backlog
94
+ tasks. Every finding either gets fixed (`bd close`) or is explicitly carried as
95
+ backlog -- it is never dropped silently.
96
+
97
+ ## Backlog
98
+
99
+ Deferred work lives as low-priority tasks under the sprint root, with enough detail to act
100
+ on later without re-investigation:
101
+ ```
102
+ bd create "<headline>" -p 3 --parent <sprint-id> --description "Impact / Source / Detail / Cost of not doing it"
103
+ ```
104
+ Manage it:
105
+ ```
106
+ bd list --status open --pretty # review
107
+ bd update <id> -p 1 # promote
108
+ bd close <id> --reason "<why>" # retire as stale/superseded
109
+ bd dep add <id> <blocker-id> # gate behind another item
110
+ ```
111
+
112
+ ## Status and recovery via beads
113
+
114
+ State re-derives entirely from beads + git -- no PLAN.md, no progress.json. To see
115
+ position at any time:
116
+ ```
117
+ bd list --status=open # work still to do
118
+ bd list --status=in_progress # tasks claimed by an interrupted dispatch
119
+ bd ready # everything unblocked right now, across tracks
120
+ bd list --tree <sprint-id> # full sprint tree: tasks, status, assignee
121
+ bd show <task-id> # full context: description, acceptance, model tier, notes
122
+ ```
123
+ beads reflects claim/close actions, not on-disk completion -- always confirm against
124
+ `git log <base>..<branch>` and `git status` before acting. A task marked
125
+ `in_progress` with no matching commits is an orphaned claim from a crashed dispatch;
126
+ reset it with `bd update <id> --status=open`. See `sprint.md` Recovery.
127
+
128
+ ## Rules
129
+
130
+ - **Check before create** (sprint root and task) -- `bd search ... --status all`; reuse if
131
+ found, never duplicate.
132
+ - **Check before claim** -- dispatch only if the task is `open`.
133
+ - `bd close` is idempotent and safe to re-run.
134
+ - **Never re-run `bd init`** on a repo that already has `.beads/` -- it pulls from remote, recreates the Dolt database, and overwrites local issue state. If the database is missing, prefer `bd export` + restore over `bd init`.
135
+ - Premature close -> `bd reopen <id>`.
136
+ - Never use `bd edit` -- it opens an interactive editor and blocks. Use
137
+ `bd update --status/--assignee/--notes` inline.
@@ -0,0 +1,152 @@
1
+ # Cost Quoting and Calibration
2
+
3
+ pm produces sprint cost quotes and post-sprint analyses using the same pure
4
+ JavaScript functions as the auto-sprint workflow. No arithmetic is done in prose --
5
+ all numbers come from deterministic JS. Node.js (v18+) is required; the orchestrator
6
+ checks for it at setup and warns the user if it is absent (cost features are skipped,
7
+ everything else runs normally).
8
+
9
+ ## Source of the functions
10
+
11
+ `install.mjs` extracts the pure functions from `auto-sprint.js` at install time
12
+ and writes them as a self-contained CommonJS module to `cost.js` in the same
13
+ directory as this file (`<configDir>/skills/pm/cost.js`). It is refreshed
14
+ automatically on every install run -- no `--force` needed. On Claude Code, the
15
+ full `auto-sprint.js` is additionally copied to `~/.claude/workflows/auto-sprint.js`
16
+ so the `/auto-sprint` workflow works natively.
17
+
18
+ The orchestrator loads the functions with a plain `require()` using `__SKILL_DIR__`
19
+ (the absolute path to the skill directory, available in the orchestrator context):
20
+
21
+ ```bash
22
+ node -e "
23
+ const { computeSprintQuote } = require('__SKILL_DIR__/cost.js');
24
+ const fs = require('fs');
25
+ const calib = JSON.parse(fs.readFileSync('sprint-logs/calibration.json', 'utf8'));
26
+ const ta = JSON.parse(process.env.TASK_ASSIGNMENTS);
27
+ process.stdout.write(JSON.stringify(computeSprintQuote(ta, calib)));
28
+ "
29
+ ```
30
+
31
+ Replace `__SKILL_DIR__` with the absolute path for your provider:
32
+
33
+ | Provider | `__SKILL_DIR__` |
34
+ |----------|----------------|
35
+ | Claude | `~/.claude/skills/pm` |
36
+ | Gemini | `~/.gemini/skills/pm` |
37
+ | AGY | `~/.gemini/antigravity-cli/skills/pm` |
38
+ | OpenCode | `~/.config/opencode/skills/pm` |
39
+
40
+ Pass inputs via `process.env` (for JSON blobs) or inline literals. Capture stdout
41
+ and parse as JSON.
42
+
43
+ ## Calibration file
44
+
45
+ `sprint-logs/calibration.json` is the single source of truth for pricing, bucket
46
+ sizes, cycle assumptions, and historical averages. It is shared between auto-sprint
47
+ and pm -- they update the same file so historical data accumulates regardless of
48
+ which harness ran the sprint.
49
+
50
+ Keys in `model_prices_per_1m_output_tokens` and `role_models` are **tier names**
51
+ (`cheap`, `standard`, `premium`), not provider-specific model IDs. The mapping from
52
+ tier name to actual model ID lives exclusively in `TIER_TO_MODEL` inside
53
+ `auto-sprint.js` -- the single place to update when models change. This makes
54
+ `calibration.json` provider-agnostic and reusable across Claude, AGY, OpenCode, etc.
55
+
56
+ - **On first run** (file absent): the setup step bootstraps it from `DEFAULT_CALIBRATION`
57
+ inside `cost.js` (same object the workflow uses). Write it with:
58
+ ```bash
59
+ node -e "
60
+ const { DEFAULT_CALIBRATION } = require('__SKILL_DIR__/cost.js');
61
+ const fs = require('fs');
62
+ fs.mkdirSync('sprint-logs', { recursive: true });
63
+ fs.writeFileSync('sprint-logs/calibration.json', JSON.stringify(DEFAULT_CALIBRATION, null, 2));
64
+ "
65
+ ```
66
+ Replace `__SKILL_DIR__` with the absolute path to the pm skill directory.
67
+ - **On subsequent runs**: read it, deep-merge with `DEFAULT_CALIBRATION` (so new
68
+ fields added to the source always have a default), and use the result.
69
+
70
+ ## Setup check (once per sprint)
71
+
72
+ ```bash
73
+ node --version 2>/dev/null || echo MISSING
74
+ ```
75
+
76
+ If `MISSING`: warn the user that cost quoting is unavailable, skip all cost steps,
77
+ continue the sprint normally. If Node.js is present, proceed with calibration load /
78
+ bootstrap as above.
79
+
80
+ ## Phase 3 -- quote after plan APPROVED
81
+
82
+ After the plan-reviewer returns APPROVED with `taskAssignments` (id + bucket + model
83
+ per task -- see `doer-reviewer-loop.md` plan-reviewer template), the orchestrator:
84
+
85
+ 1. Writes `taskAssignments` to a temp env var or file.
86
+ 2. Runs `computeSprintQuote(taskAssignments, calibration)` via the node snippet above.
87
+ 3. Logs the quote (opt/expected/pessimistic scenarios, calibration source).
88
+ 4. Writes per-task cost estimates back to beads notes:
89
+ ```bash
90
+ bd update <id> --notes="cost-estimate: bucket=<B> model=<M> doer_tokens=<N> reviewer_tokens=<N> output_usd=<N>"
91
+ ```
92
+ Dispatch a single cheap-tier agent to run all `bd update` commands in one pass.
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:
97
+ ```json
98
+ [{ "id": "BD-10", "bucket": "M", "model": "standard" }, ...]
99
+ ```
100
+
101
+ ## Harvest -- analysis and calibration update
102
+
103
+ At sprint close, after the harvester runs:
104
+
105
+ 1. **Compute analysis**: run `computeSprintAnalysis(quote, logEntries, calibration,
106
+ actualCycles)`. `logEntries` is the sprint log JSONL (see Sprint log below) read
107
+ and parsed from `sprint-logs/<branch>-<startedAt>.jsonl`. If the log file does not
108
+ exist (pm ran without logging), pass `[]` for logEntries -- the analysis degrades
109
+ gracefully to estimates-only.
110
+ 2. **Build summary**: run `buildSprintSummary(analysis, quote, calibration, opts)`
111
+ where `opts = { branch, goal, goalMet, cycleCount, tasksCompleted, tasksOpen,
112
+ startedAt }`. Write the returned `summaryText` to
113
+ `sprint-logs/<branch>-<startedAt>.analysis.md` and commit it.
114
+ 3. **Update calibration**: run `computeUpdatedCalibration(calibration, analysis,
115
+ startedAt, taskAssignments, logEntries)` and write the result back to
116
+ `sprint-logs/calibration.json`. Commit it. This blends the actual token counts
117
+ into the historical averages so future quotes improve.
118
+
119
+ ## Sprint log
120
+
121
+ pm appends one JSONL record per dispatch to `sprint-logs/<branch>-<startedAt>.jsonl`
122
+ so `computeSprintAnalysis` can compare estimates to actuals. Each record:
123
+
124
+ ```json
125
+ { "ts": "<ISO timestamp>", "cycle": 1, "phase": "Develop", "label": "doer-c1-i1",
126
+ "model": "<tier: cheap|standard|premium>", "context": "tasks BD-10, BD-11",
127
+ "outTokens": 1234, "costUsd": 0.0185 }
128
+ ```
129
+
130
+ The orchestrator appends after each dispatch using a cheap-tier agent (same
131
+ `appendNewEntries` pattern as auto-sprint). The `label` format `<role>-c<N>-i<M>`
132
+ is required -- `computeSprintAnalysis` strips the suffix to recover the role name.
133
+
134
+ If the Claude Code harness does not expose per-subagent token counts, record
135
+ `outTokens: 0` and `costUsd: 0` -- the analysis will show actuals as zero but the
136
+ estimate side still works and calibration is not corrupted.
137
+
138
+ ## Node.js invocation pattern for all functions
139
+
140
+ All five functions follow the same extract-and-call pattern. Reference:
141
+
142
+ | Function | When | Inputs | Output |
143
+ |---|---|---|---|
144
+ | `computeSprintQuote` | After plan APPROVED | `taskAssignments`, `calibration` | quote object with scenarios |
145
+ | `computeSprintAnalysis` | Harvest | `quote`, `logEntries`, `calibration`, `actualCycles` | analysisText + byRole |
146
+ | `buildSprintSummary` | Harvest | `analysis`, `quote`, `calibration`, `opts` | summaryText markdown |
147
+ | `computeUpdatedCalibration` | Harvest | `calibration`, `analysis`, `startedAt`, `taskAssignments`, `logEntries` | updated calibration object |
148
+ | `DEFAULT_CALIBRATION` | Setup bootstrap | -- | JSON to write to calibration.json |
149
+
150
+ Never hardcode prices, bucket sizes, or cycle assumptions -- always read them from
151
+ `calibration.json` (or `DEFAULT_CALIBRATION` on first bootstrap). The file is the
152
+ single source of truth shared across all sprint harnesses.