subagent-delegation-playbook
verified2743e6b5-93c5-4d83-9c07-b3c36c4d6ac8
Decide when to delegate to a subagent, write a scoped self-contained brief, and hand off cleanly. Use when a task is independent enough to run in parallel or in isolation.
Metadata
Skill file
# Subagent Delegation Playbook
Use when considering handing work to a subagent or another agent. Delegation is
only worth it when the task is independent, bounded, verifiable, and free of
shared-state collisions — and only when the brief is self-contained.
## 1. The "should I delegate?" decision table
| Question | Delegate if... | Do it yourself if... |
|---|---|---|
| **Independent?** | No dependency on other in-flight work | Touches the same files/state as something else you're doing |
| **Bounded?** | Clear scope with a definite end | Open-ended "improve the codebase" |
| **Verifiable?** | A machine-checkable definition of done exists | "Done" is a judgment call you can't hand off |
| **No shared state?** | Works in its own files/branch | Edits files you are also editing |
Any "do it yourself" answer → don't delegate; the coordination cost exceeds the
savings.
## 2. The self-contained brief template
A subagent cannot read your mind or your full context. The brief must contain
everything it needs:
```markdown
# Brief: <task>
Objective: One sentence — what to accomplish, and why.
Context: Background the subagent needs. Reference files/branches/commits by
exact path. Assume it knows NOTHING about your session.
Scope: Exactly which files/dirs to touch, and — critically — what NOT to
touch.
Definition of done: The exact verify command that must pass. Machine-checkable.
Forbidden: Explicit negatives (do not reformat unrelated files, do not add
dependencies, do not touch src/db/).
Artifacts: The exact path(s) where the result must be written (file, branch,
report).
```
Example (the "good" brief):
```markdown
Objective: Add a `hash_password`/`verify_password` util with tests.
Context: Repo at /root/app, Python 3.11, uses pytest + ruff. Existing utils in
src/utils/. Follow the style in src/utils/slugify.py.
Scope: Create src/utils/password.py and tests/test_password.py ONLY.
Definition of done: `pytest tests/test_password.py -q` passes; `ruff check` clean.
Forbidden: Do not touch any other file. Do not add dependencies. Use `hashlib` +
`secrets` (stdlib only), no bcrypt/argon2.
Artifacts: Commit on branch feature/password-hash in /root/app.
```
## 3. Handoff hygiene — give it the verify command and artifact location
The two most common failure modes are (a) the subagent not knowing what "done"
means and (b) you not knowing where to find the result. Eliminate both:
- **Exact verify command** — paste the literal command, with the literal expected
output. Not "make sure tests pass" but `pytest tests/test_password.py -q`.
- **Exact artifact path** — "write to `/root/app/src/utils/password.py` and
branch `feature/password-hash`", not "put it in the utils folder somewhere".
- **A single owner per file** — never delegate to two agents who might both edit
the same file.
## 4. After the handoff
1. Record what you delegated, to whom, and the artifact path (in your scratchpad).
2. When the result comes back, **verify it** (see verify-subagent-reports).
3. Integrate only what passes verification.
## Guardrails
- Do **not** delegate without a machine-checkable acceptance criterion. A vague
brief guarantees a vague result.
- Do **not** let two agents edit the same file — that is conflict by construction.
- Do **not** write vague "make it better" briefs — scope it tightly.
- Do **not** assume the subagent shares your context; the brief must be fully
self-contained.
- Do verify the result before integrating it (trust but verify).
## Pitfalls
- **No verifiable acceptance criterion** — "improve the auth code" produces a
result you cannot confirm is correct.
- **Two agents, one file** — overlapping edits produce conflicts and lost work.
- **Vague scope** — "do what needs doing" lets the subagent drift into unrelated
changes (or refactor your whole repo).
- **Implicit context** — assuming the subagent knows your repo layout, style, or
the bug you are chasing; it does not.
- **Missing artifact path** — the subagent "finished" but you cannot find the
result, or it overwrote something important.
## Verify / Checklist
- [ ] The delegation decision table was applied (independent, bounded, verifiable, no shared state).
- [ ] The brief has: objective, context, scope, definition of done, forbidden, artifacts.
- [ ] "Definition of done" is a literal, machine-checkable command.
- [ ] "Artifacts" names exact file paths / branch names.
- [ ] No two agents own the same file.
- [ ] The result was verified (not taken on faith) before integration.Attached files
No attached files.