Briefing subagents so they finish the job.

Guides

Subagents fail in predictable ways: the brief was vague, two of them edited the same file, or the orchestrator reported their "done" without checking it. Each has a simple rule against it. This guide is drawn from the orchestration protocol in CommonRig's free sample, which is MIT licensed and free to download.

Who owns what

  • The orchestrator owns scope, decisions, integration and the final claim. Delegating work does not delegate accountability.
  • An implementer delivers one bounded change inside its assigned files. Its "done" means ready for verification.
  • A reviewer gets read-only access and the original evidence, not the implementer's explanation of why the change is right.

Decide whether delegation pays

Delegate mechanical changes across many files, a bounded inventory, a test investigation or a draft with a clear outline. Keep a small single-file change, an unclear spec or a bug you already understand in the main session. Briefing, retries, review and integration all count: saving ten minutes of typing is a loss if review takes twenty because the brief left naming undecided. For deterministic transformations, a script is often simpler to verify than an agent.

A brief the implementer can finish

A brief should stand alone after a restart. Replace every placeholder before you send it.

Outcome: observable result and reason the owner needs it.
Working directory: exact absolute path.
Read first: relevant instruction files and interface contract.
Write only: exact file paths, including tests and handoff.
Read-only dependencies: exact paths or bounded source extracts.
Behaviour: inputs, outputs, failure cases and compatibility constraints.
Acceptance: commands and observations that prove the result.
Limits: runtime, cost, dependencies, network and external-action permissions.
Git: no git writes, including add, commit, checkout, restore, reset,
     stash, clean, merge, rebase and worktree changes.
Collaboration: other writers are active; never revert their changes.
Handoff: changed files, checks with results, unresolved issues, next step.
Stop condition: scope collision, missing contract or two failed attempts.

Do not write "fix whatever you find" when you mean three named files. If acceptance needs a new test file, put it in the write list.

Parallel writers

Two agents writing in one working tree need disjoint files, and every brief forbids all git writes. A stage, checkout, stash or reset by one agent can silently destroy another's work. Better still, give each writer its own git worktree. The orchestrator commits each returned lane with a scoped pathspec once it has reviewed the diff.

Verify before you report

Read the diff, rerun the checks that matter and look at anything a user will see. After two failed attempts at the same lot, change the approach rather than resending the brief. A second model's finding is not dismissed on instinct: disprove it with a test or a quoted design, or get a third opinion.

Check your own files

Paste your CLAUDE.md or AGENTS.md into the free footprint scorer, or get the free sample and run rig doctor --lite locally. The hosted doctor check is A$0.50 a run and scores the whole setup, hooks included. The kit (A$10 once) has the rule source, generator, hooks and protocols these guides describe.

More guides