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, 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.
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 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 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.