rocm Agent Handoff — amd-smi
The single hand-off contract between amd-smi agents and across session boundaries. One shape for every hop, so no agent restates its own dispatch/return format.
Core principle: Reference artifacts by path. Never paste file contents, diffs, or plans into the handoff — point to them. Redact secrets.
Nesting Budget
Subagents may dispatch their own subagents, but the chain is capped by the
agent-max-nesting-depth setting (default 3, declared in
.github/copilot-instructions.md — the single source of truth).
Rules:
- Depth is counted from the first orchestrator (Planning / Development / Review).
- Every dispatch carries a
Nesting depth: N/3line (see the template). The first orchestrator runs at1/3. - When you dispatch, pass
N+1to the receiver. - If you are running at depth
N == MAX, you are a leaf: do the work yourself, do not dispatch any subagent. (Dispatching parallel subagents at the same level all share yourN+1— width is unlimited, only depth is capped.) - If a leaf genuinely cannot proceed without going deeper, return
STATUS: BLOCKEDexplaining why, rather than exceeding the budget.
When to Use
- Planning dispatches a task to the Development or Review agent
- Development returns results to Planning, or hands a branch to Review
- A session is getting long and work must continue in a fresh session
Don't use when: answering a trivial inline request Planning can handle itself.
Where the Doc Goes
Write to the OS temp dir, not the workspace:
HANDOFF="${TMPDIR:-/tmp}/amdsmi-handoff-$(date +%Y%m%d-%H%M%S).md"
Pass the path to the receiver. Workspace stays clean (no stray handoff files in git).
Handoff Template
# Handoff: <one-line goal>
**From:** <planning | development> **To:** <development | review>
**Date:** <YYYY-MM-DD>
**Nesting depth:** <N>/3 <!-- receiver's depth; leaf when N == 3, do not dispatch further -->
## Goal
<one or two sentences — what the receiver must accomplish>
## Scope
- In: <files/dirs the receiver may change>
- Out: <files/dirs that are OFF LIMITS>
## Constraints
- <e.g., do not regenerate the wrapper unless adding a C API function>
- <project rules: TDD first, verification-before-completion, no push w/o approval>
## Artifacts (by path — do NOT inline)
- Spec: ${TMPDIR:-/tmp}/amdsmi-agent-specs/<file>.md
- Plan: ${TMPDIR:-/tmp}/amdsmi-agent-plans/<file>.md (task N, lines X–Y)
- Worktree: <abs path>
- Related: <PR URL, issue, prior handoff path>
## Suggested Skills
- <skill the receiver should load — e.g., test-driven-development, systematic-debugging>
## Expected Return
- <what the sender needs back — STATUS, files changed, tests run, blockers>
Expected Return (receiver → sender)
Receivers report back in this shape (replaces per-agent return formats):
STATUS: DONE | BLOCKED | NEEDS_CONTEXT
FILES CHANGED:
- <path>:<lines> — <summary>
TESTS RUN:
- <command> → <result>
VERIFICATION:
- <what was run from verification-before-completion>
BLOCKERS (if any):
- <description + which skill/agent resolves it>
Common Mistakes
| Mistake | Fix |
|---|---|
| Pasting the plan/diff into the handoff | Reference it by path |
| Writing the handoff into the workspace | Write to ${TMPDIR:-/tmp} |
| Omitting the Out-of-scope list | Always state what NOT to touch |
| Including tokens/passwords in Artifacts | Redact; reference the secret's location instead |
| Restating a skill's steps | List it under Suggested Skills — the receiver loads it |
| Dispatching a subagent while at max depth | You're a leaf — do the work, or return BLOCKED |
Omitting the Nesting depth line |
Always carry it; the receiver needs its budget |