Rust Agent Handoff Protocol Skill

Rust Agent Handoff Protocol

Subagents work in isolated context — they cannot see each other's conversations. This protocol enables structured communication through flat YAML files.

Directory Structure

.local/
└── handoff/
    ├── 2025-01-09T14-30-45-architect.yaml
    ├── 2025-01-09T15-00-00-developer.yaml
    └── ...

File Naming Convention

{YYYY-MM-DDTHH-MM-SS}-{agent}.yaml

| Agent | Filename suffix | |-------|-----------------| | rust-architect | -architect.yaml | | rust-developer | -developer.yaml | | rust-testing-engineer | -testing.yaml | | rust-performance-engineer | -performance.yaml | | rust-security-maintenance | -security.yaml | | rust-code-reviewer | -review.yaml | | rust-cicd-devops | -cicd.yaml | | rust-debugger | -debug.yaml |

Communication Model

Parent Agent (or User)
    │
    ├── Task(rust-architect): "Design system"
    │       ↓
    │   rust-architect executes
    │       - reads handoff if path provided
    │       - does work
    │       - writes handoff file
    │       - RETURNS result with handoff path
    │       ↓
    ├── receives result, reads handoff path
    │
    ├── Task(rust-developer): "Implement. Handoff: <path>"
    │       ↓
    │   rust-developer executes
    │       ...

Key point: Subagents cannot call each other directly. They return results to parent, who orchestrates the next call.

On Startup

If handoff file path(s) provided in task description:

Single handoff:

cat <provided-path>

Multiple handoffs (when merging contexts):

cat <path1>
cat <path2>
# ...

Reading parent context (recommended):

After reading the provided handoff, read its parent reports to understand the full context chain:

# Extract parent ID(s) from the handoff file
# If parent is a single value:
PARENT_ID=$(grep '^parent:' <provided-path> | awk '{print $2}' | tr -d '"')
if [ "$PARENT_ID" != "null" ]; then
  cat ".local/handoff/${PARENT_ID}.yaml"
fi

# If parent is an array, you may need to read multiple files
# Repeat recursively to understand the full chain

This helps you understand decisions made by previous agents in the workflow chain.

If no handoff provided: Start fresh — this is a new task.

Before Finishing — ALWAYS:

1. Write Handoff File

Use the $TS variable obtained at startup:

mkdir -p .local/handoff
cat > ".local/handoff/${TS}-<agent>.yaml" << 'EOF'
# Your YAML report here
EOF

2. Return Handoff Path to Caller

End your response with clear handoff information:

## Handoff

**Status:** completed
**Handoff file:** `.local/handoff/2025-01-09T14-30-45-architect.yaml`
**Recommended next:** rust-developer
**Task for next agent:** Implement Email and User types per architecture spec

The parent agent will use this to orchestrate the next step.

Base Schema (All Agents)

id: 2025-01-09T14-30-45-architect
parent: 2025-01-09T14-00-00-developer  # Single source, or null if fresh start
# parent: [2025-01-09T14-00-00-developer, 2025-01-09T13-30-00-architect]  # Multiple sources (array)
agent: architect  # architect | developer | testing | performance | security | review | cicd | debug
timestamp: "2025-01-09T14:30:45"
status: completed  # completed | blocked | needs_discussion

context:
  task: "Original task description"
  phase: "01"  # optional phase number

output:
  # Agent-specific output (see schemas below)

next:  # Recommendation for parent agent
  agent: rust-developer  # suggested next agent, or null if done
  task: "Task description for next agent"
  priority: high  # high | medium | low
  acceptance_criteria:
    - "Criterion 1"
    - "Criterion 2"

Agent-Specific Output Schemas

Each agent has a specific output schema. Read the references file for your agent:

| Agent | references File | |-------|----------------| | rust-architect | references/architect.md | | rust-developer | references/developer.md | | rust-testing-engineer | references/testing.md | | rust-performance-engineer | references/performance.md | | rust-security-maintenance | references/security.md | | rust-code-reviewer | references/review.md | | rust-cicd-devops | references/cicd.md | | rust-debugger | references/debug.md |

On Startup — ALWAYS:

Get timestamp immediately (use this for handoff filename later):
```
TS=$(date +%Y-%m-%dT%H-%M-%S)
echo "Timestamp: $TS"
```
Read your agent-specific schema from reference/<agent>.md
If handoff path provided:
- Read the provided handoff file(s)
- Read parent handoff(s) to understand full context chain (extract parent field and read those files recursively)
- This gives you complete understanding of prior decisions and work
Then proceed with task

Workflow Examples

New Project Flow (Parent Orchestrates)

Parent Agent
    │
    ├─► Task(rust-architect): "Design user system"
    │   └─► returns: handoff A
    │
    ├─► Task(rust-developer): "Implement. Handoff: A"
    │   └─► returns: handoff B
    │
    ├─► Task(rust-testing-engineer): "Add tests. Handoff: B"
    │   └─► returns: handoff C
    │
    ├─► Task(rust-code-reviewer): "Review. Handoff: C"
    │   └─► returns: handoff D (approved)
    │
    └─► Task(rust-cicd-devops): "Setup CI. Handoff: D"
        └─► returns: handoff E (done)

Bug Fix Flow

Parent Agent
    │
    ├─► Task(rust-debugger): "Investigate crash"
    │   └─► returns: handoff with root cause
    │
    ├─► Task(rust-developer): "Fix bug. Handoff: ..."
    │   └─► returns: handoff with fix
    │
    ├─► Task(rust-testing-engineer): "Add regression test. Handoff: ..."
    │   └─► returns: handoff with tests
    │
    └─► Task(rust-code-reviewer): "Review fix. Handoff: ..."
        └─► returns: approved

Review Iteration

Parent Agent
    │
    ├─► Task(rust-code-reviewer): "Review PR"
    │   └─► returns: changes_requested, issues list
    │
    ├─► Task(rust-developer): "Fix review issues. Handoff: ..."
    │   └─► returns: fixes applied
    │
    └─► Task(rust-code-reviewer): "Re-review. Handoff: ..."
        └─► returns: approved

Parallel Work Merge

Parent Agent
    │
    ├─► Task(rust-architect): "Design API"
    │   └─► returns: handoff A
    │
    ├─► [Parallel] Task(rust-developer): "Implement API. Handoff: A"
    │   │         Task(rust-testing-engineer): "Design test strategy. Handoff: A"
    │   │
    │   └─► returns: handoff B (implementation)
    │       returns: handoff C (test strategy)
    │
    └─► Task(rust-testing-engineer): "Implement tests. Handoff: [B, C]"
        └─► parent: [handoff-B-id, handoff-C-id]

Response Format (Return to Parent)

When finishing, structure your response so parent can easily extract handoff info:

## Summary

[Brief description of what was done]

## Work Completed

- [Item 1]
- [Item 2]

## Handoff

| Field | Value |
|-------|-------|
| Status | `completed` / `blocked` / `needs_discussion` |
| Handoff file | `.local/handoff/2025-01-09T14-30-45-developer.yaml` |
| Recommended next | `rust-testing-engineer` (or `none` if done) |
| Task for next | Add unit tests for Email and User types |

Parent agent parses this to decide next step.

Status Values

| Status | Meaning | Next Action | |--------|---------|-------------| | completed | Work done successfully | Proceed to next agent | | blocked | Cannot proceed | Return to caller with blocker | | needs_discussion | Decisions needed | Return to user for input |

Best Practices

Always write handoff file before finishing, even if blocked
Always return handoff path in your response to parent
Include acceptance criteria for recommended next agent
references file paths created/modified
Keep summaries concise — details in specific fields
Read provided handoff(s) first thing on startup
Read parent chain to understand full context (see example below)
Don't assume next agent — parent decides orchestration
Multiple parents — Use array when merging contexts from parallel work or multiple sources
When reading multiple handoffs — Synthesize information, note conflicts in your output

Reading Parent Chain Example

# Read the provided handoff
CURRENT_HANDOFF=".local/handoff/2025-01-09T15-00-00-developer.yaml"
cat "$CURRENT_HANDOFF"

# Extract and read parent (simple approach)
PARENT_ID=$(grep '^parent:' "$CURRENT_HANDOFF" | awk '{print $2}' | tr -d '" ')
if [ "$PARENT_ID" != "null" ] && [ -n "$PARENT_ID" ]; then
  echo "Reading parent context..."
  cat ".local/handoff/${PARENT_ID}.yaml"

  # Can continue recursively if needed
  GRANDPARENT_ID=$(grep '^parent:' ".local/handoff/${PARENT_ID}.yaml" | awk '{print $2}' | tr -d '" ')
  if [ "$GRANDPARENT_ID" != "null" ] && [ -n "$GRANDPARENT_ID" ]; then
    cat ".local/handoff/${GRANDPARENT_ID}.yaml"
  fi
fi

This helps you understand the full decision chain and context from previous agents.

Agent Skills: Rust Agent Handoff Protocol

Install this agent skill to your local

Skill Files