rust-agent-handoff

name	rust-agent-handoff
description	Handoff protocol for Rust multi-agent development system. Use when working as rust-architect, rust-developer, rust-testing-engineer, rust-performance-engineer, rust-security-maintenance, rust-code-reviewer, rust-cicd-devops, or rust-debugger. ALWAYS read on agent startup.

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 provided in task description:

cat <provided-path>

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

Before Finishing — ALWAYS:

1. Write Handoff File

mkdir -p .local/handoff
TS=$(date +%Y-%m-%dT%H-%M-%S)
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  # or null if fresh start
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:

1. Read your agent-specific schema from reference/<agent>.md
2. If handoff path provided — read it
3. 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

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

1. Always write handoff file before finishing, even if blocked
2. Always return handoff path in your response to parent
3. Include acceptance criteria for recommended next agent
4. references file paths created/modified
5. Keep summaries concise — details in specific fields
6. Read provided handoff first thing on startup
7. Don't assume next agent — parent decides orchestration