bug-ops/claude-plugins/agent-handoff

Agent Handoff Protocol

Subagents work in isolated context. This protocol enables communication via Markdown+frontmatter files.

File Path

.local/handoff/{TS}-{agent}.md where TS=$(date +%Y-%m-%dT%H-%M-%S) and {agent} is your suffix:

architect · developer · testing · performance · security · review · cicd · debug · critic · live-tester · researcher · arch-analyst · security-analyst

On Startup

1. TS=$(date +%Y-%m-%dT%H-%M-%S)
2. Read ${CLAUDE_SKILL_DIR}/references/{agent}.md for your Output schema. Exception: arch-analyst and security-analyst take their Output schema from their audit skill (arch-inspect / security-audit) — skip this read.
3. Parent handoff frontmatter arrives inline in your task description — that is routing metadata. Read a full body only when you need detailed context: cat .local/handoff/{id}.md
4. For grandparent+ chain read frontmatter only: awk 'BEGIN{n=0}/^---/{n++;if(n==2)exit}n==1&&!/^---/{print}' file.md

Before Finishing

1. mkdir -p .local/handoff && HANDOFF_ID="${TS}-{agent}"
2. Write .local/handoff/${HANDOFF_ID}.md:

~~~markdown

id: {HANDOFF_ID} parent: {parent-id | [id1, id2] | null} agent: {suffix} status: {completed | blocked | needs_discussion} summary: "One sentence: what was done + key artifact" next_agent: {suffix | null} next_task: "Short imperative task, or empty"

Context

Stack: {profiles and reference files read, per the stack skill — e.g. rust (toolchain, developer); omit for agents that do not load stack} {<=2 sentences: constraints or decisions the next agent cannot get from the frontmatter chain. Do NOT restate the task or parent summaries.}

Output

{Per references/{agent}.md schema.} ~~~

Frontmatter is flat scalars; the only allowed array is parent: [id1, id2] when parallel work converges on one agent.

Conditional sections: ## Blockers if status: blocked; ## Acceptance Criteria if next_task needs more than one line. On needs_discussion state the open question — the caller returns it to the user.

1. Return frontmatter + path to caller — parent routes without reading the file. The block goes where your caller reads results: SendMessage to the lead when you are a teammate, the SubagentHandback call when you have that tool, otherwise your final message:

~~~markdown

Handoff

File: .local/handoff/{HANDOFF_ID}.md Frontmatter:

{the frontmatter block above}

~~~

Compactness Rules

Every handoff body is re-read by downstream agents — each extra line costs tokens on every read:

• Never restate the task, parent summaries, or anything the frontmatter chain already carries.
• Never list what git diff shows: no function/test name listings, no code snippets. Counts + paths + one-line descriptions. Exception: debugger — the fix snippet IS the payload.
• Omit empty or inapplicable sections entirely. No decorative estimates or filler prose.
• Aim for <=40 lines of body; never pad.