improvise/.agents/skills/wave/SKILL.md

name, description

name	description
wave	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. This file is the brief checklist's one home, and agent-rules.md beside it holds the rules each agent follows.

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 .envrc must be allowed, or bd fails confusingly: agent-rules.md, "Discipline per ticket".

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

Point the agent at agent-rules.md and tell it to read it in full first. That file is the agent's standing rules: base and push mechanics, the gate list, the claim, the vacuity shapes, evidence, the files it must not write, GitHub conventions (including how authors and reviewers answer reviews on the PR thread), the hand-back and disk cleanup. Do not restate them in the brief. A restated rule drifts from its source, and the brief is the copy nobody corrects. The brief adds only what varies per wave:

1. The expected base commit, by name. Worktrees do not reliably branch from HEAD. One was created three merges behind and was only noticed because it was told to check. The agent checks against it: agent-rules.md rule 1.
2. A reference baseline, so "N passing" is checkable and a drop is visible: Rust test count, harness counts, node counts, and the machine. The same commit once measured improvise-io's binary at 1.4s on one machine and 3.7–5.2s on another, so a figure with no machine is a claim about the suite, which it is not. The agent still measures its own.
3. Its ground, and the ground that is not. Name any orchestrator-only file it is exceptionally allowed to edit.
4. Its BEADS_ACTOR and its tickets. The actor also names the agent's commits: it commits through scripts/agent-git, which authors each one as Claude (<BEADS_ACTOR>) (agent-rules.md, "Discipline per ticket"). So give each agent its own actor, and do not tell it to set user.name.
5. The attribution line, commit trailers and PR footer, spelled out. They name the agent (Claude's line opens _Posted by Claude (<model>)…_) and this session's URL, which is why the shared agent-rules.md cannot hold them.
6. An explicit ask for what the ticket did not predict. agent-rules.md lists it in the hand-back. Say it in the brief anyway: it is consistently the most valuable part of a hand-back, and agents omit it unless asked.

When a hand-back teaches a new rule, add it to agent-rules.md in the same wave, not to the next brief.

Method to require

agent-rules.md, "Discipline per ticket" and "Gates": failing test first, a rival injected and watched failing by name, --no-fail-fast, and test names diffed after any merge. Hold the hand-back to it. This repo's characteristic defect is a test that passes.

Shepherding

• Wait on checks with scripts/pr-watch <pr> --expect <sha>. Never hand-roll a poll; see the pr-watch skill for the four ways they report green while wrong.
• Review before merging. Dispatch an adversarial reviewer and give it the head SHA, the base, and a test-merge, so it reviews the tree that will exist. Point it at agent-rules.md, "GitHub", for what a reviewer reads and answers first. Copilot reviews here again (2026-09-24), mostly in inline comments, and Codex as quota allows. Read both with scripts/pr-reviews <n> and see each finding answered before merging. Do not wait on either: an absent review and an unrequested one both read as "pending".
• Only the user's explicit approval accepts an ADR, and lets its PR merge. The review gates still apply, and none of them is approval: AGENTS.md, "ADR pull requests". While an ADR PR is open, keep a background poll for new non-agent comments and reviews, and resume its steward on each one. The user answers inline, and an answer left unread for hours is a failure.
• Before merging, check baseRefName is main (gh pr view <n> --json baseRefName). A stacked PR whose base has already merged still targets the stale base branch, and merging it lands nothing in main. Retarget it with gh pr edit <n> --base main first. AGENTS.md, "Shipping a wave", has the 2026-09-24 incident.
• Land a batch of approved PRs as one integration PR. Evidence files are append-at-EOF, so merging one at a time conflicts every other open PR. Then diff every conflict resolution against both parents and the merge base, and run the gates on the merged tree: AGENTS.md, "Merging many PRs at once".
• A re-review is of the delta, at a named SHA. A review of a superseded commit reads as a pass.
• Merge on GitHub with a merge commit, never a squash or rebase merge (agent-rules, rule 8). Then git fetch gh && git merge --ff-only gh/main. Close the bead only once the merge has landed. That is when the work is done: AGENTS.md, "Repository policy over the Beads blocks".
• Anything posted to GitHub goes out under the owner's account: open every comment with a line naming the model and saying an agent wrote it. That wording is agent-neutral because this one file serves Claude and Codex (.claude/skills/wave is a symlink to .agents/skills/wave).

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.