Edward Langley
84 lines
4.2 KiB
Markdown
84 lines
4.2 KiB
Markdown
---
|
|
name: wave
|
|
description: Dispatch parallel agents to work through open beads and shepherd each to a merged PR. Use when an orchestrator is running a wave, partitioning the backlog, or writing a brief for a work-unit agent.
|
|
---
|
|
|
|
# Running a wave
|
|
|
|
An orchestrator chunks the open backlog, fans agents out, reviews what comes
|
|
back, and merges. `AGENTS.md` has the history; this is the operating procedure.
|
|
|
|
## Every agent gets its own worktree. No exceptions.
|
|
|
|
Dispatch with `isolation: "worktree"`. Without it every agent edits the **same**
|
|
working tree: one `git status` shows four agents' half-finished files, any commit
|
|
sweeps up the others' work, and any `git checkout` destroys it. This has happened
|
|
here. If you discover it mid-wave, stop every agent, have each create a worktree
|
|
and copy across **only files it can prove it touched**, then `git checkout --`
|
|
those files in the primary tree.
|
|
|
|
In the worktree: `direnv allow`, or `bd` reports a version *mismatch* rather than
|
|
failing cleanly. `direnv status` prints `Found RC allowed 0`, and `0` means
|
|
allowed — it reads like the opposite.
|
|
|
|
## Partitioning
|
|
|
|
By **crate or directory**, never by ticket count. **Tickets that share a file go
|
|
to one agent**, to be done sequentially — four widget migrations all touching
|
|
`src/draw.rs` are a guaranteed conflict split four ways. Group first, then count.
|
|
|
|
Tell each agent what ground is *not* theirs, and to report rather than guess when
|
|
it must cross. Two agents adding a workspace member will still collide in
|
|
`Cargo.toml`/`Cargo.lock`; keep both sides.
|
|
|
|
## What every brief must carry
|
|
|
|
1. **The expected base commit, by name.** Worktrees do not reliably branch from
|
|
HEAD — one was created three merges behind and only noticed because it was
|
|
told to check.
|
|
2. **The baseline**, so "N passing" is checkable rather than asserted: Rust test
|
|
count, harness counts, node counts.
|
|
3. **Its ground, and the ground that is not.**
|
|
4. **Never write** `.beads/**`, `prolog-sessions/kb.pl`, `context/repo-map.md`.
|
|
Agents read them freely and report proposed text; the orchestrator applies it.
|
|
5. **The commit trailers and PR footer**, spelled out.
|
|
6. **Do not push to `main`, do not merge.** The orchestrator merges.
|
|
7. **What to report**: branch and head SHA, PR number, what changed per ticket,
|
|
*what could not be verified and why*, proposed repo-map/kb text, and **what it
|
|
learned that the ticket did not predict** — consistently the most valuable
|
|
part, and omitted unless asked for explicitly.
|
|
|
|
## Method to require, because this repo's defect is a test that passes
|
|
|
|
- Failing test first, then the fix.
|
|
- Every guard proved by **injecting the fault it names** and watching it fail
|
|
**by name**. An injection that does not compile reads as a clean run, so
|
|
require a positive signal the build ran.
|
|
- `cargo test --workspace` is **fail-fast**; `--no-fail-fast` for any claim about
|
|
blast radius.
|
|
- A textually clean merge can **delete tests** with no conflict marker, and
|
|
`cargo check` will not notice. After any merge that moves a test module, diff
|
|
test **names** — a count is masked by the other side's additions.
|
|
|
|
## Shepherding
|
|
|
|
- Wait on checks with `scripts/pr-watch <pr> --expect <sha>`. Never hand-roll a
|
|
poll; see the `pr-watch` skill for the three ways they report green while wrong.
|
|
- Review before merging. Copilot's quota may be exhausted and its request is a
|
|
**silent no-op**; an absent review and an unrequested one both read as
|
|
"pending". Dispatch an adversarial reviewer and give it the head SHA, the base,
|
|
and a test-merge, so it reviews the tree that will exist.
|
|
- A re-review is of the **delta**, at a named SHA. A review of a superseded
|
|
commit reads as a pass.
|
|
- Merge on GitHub, then `git fetch gh && git merge --ff-only gh/main`.
|
|
- Anything posted to GitHub goes out under the owner's account: open every
|
|
comment with a line saying a Codex agent wrote it.
|
|
|
|
## Between waves
|
|
|
|
Run the code-review skill on the merged range. The characteristic find here is
|
|
not a wrong line, it is **a test that passes while the thing it names is
|
|
broken** — a vacuous fold test, a one-category fixture, a helper that fabricates
|
|
what the code under test needs. Ask the reviewer to inject the fault and watch
|
|
the check fail.
|