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. 3. 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:** ```yaml {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.