Agent Handoff

---
name: agent-handoff
description: >
  How to chain ECC specialist agents for multi-step problems —
  pair-programmer → tdd-guide → code-reviewer → security-reviewer.
  Use when one agent finishes its job and the next logical step needs
  a different specialist. Documents the standard handoff protocol so
  agents pass context cleanly.
---

# Agent Handoff Protocol

Single agents handle single concerns. Real engineering tasks span multiple concerns. **Handoffs** are how ECC chains agents without losing context.

## The 3-Line Handoff Protocol

When an agent finishes its scope and the next step needs a different specialist, it ends with exactly this shape:

```
─────────────────────────────────────
HANDOFF
  From: <current-agent>
  To:   <next-agent>
  Why:  <one-line reason>
  Carry: <what the next agent needs to know>
─────────────────────────────────────
```

Then **stop**. The next agent picks up from `Carry:`.

## Standard Chains

These are the most common multi-agent flows. Memorize them.

### Build something new (clean path)

```
pair-programmer  →  tdd-guide  →  code-reviewer  →  api-guardian (if API)
                                              →  security-reviewer (if sensitive)
                                              →  ux-reviewer (if UI)
```

`pair-programmer` agrees on approach. `tdd-guide` writes failing tests first. The implementer writes code. `code-reviewer` checks it. Specialist reviewers check their domain.

### Bug in production

```
debug-detective  →  tdd-guide          →  refactor-cleaner (optional)
                 (root cause)        (regression test)
```

Always add a regression test after a real-bug fix. Always.

### Refactor a module

```
code-explorer    →  refactor-cleaner   →  tdd-guide        →  code-reviewer
(map dependencies)  (cleanup)          (verify behavior)
```

### Performance investigation

```
performance-optimizer  →  tdd-guide       →  code-reviewer
                       (perf regression test)
```

### API change

```
api-guardian  →  pair-programmer  →  tdd-guide  →  doc-updater
(blast radius)  (impl approach)                   (changelog)
```

### Security audit

```
security-reviewer  →  tdd-guide               →  release-captain
                   (security regression test)  (patch release)
```

### Open-source a private project

```
opensource-forker  →  opensource-sanitizer  →  opensource-packager  →  release-captain
(make a clean fork) (strip secrets/PII)      (README, license, examples)  (cut v0.1.0)
```

### Framework migration

```
migration-guide  →  pair-programmer  →  tdd-guide  →  pr-test-analyzer
(phase plan)        (per-phase impl)              (verify coverage on PR)
```

### Build is broken

```
build-error-resolver  →  dependency-doctor (if dep issue)
                      →  env-debugger (if env issue)
                      →  debug-detective (if it's actually a runtime bug surfacing at build)
```

### CI is flaky

```
flake-hunter  →  tdd-guide       →  release-captain (if it gates a release)
              (deterministic test)
```

### Git is on fire

```
git-rescue  →  release-captain (if a release was midway)
```

## Carry Field — What to Pass Forward

The `Carry:` line is the most important. Bad carry breaks the chain.

**Good carry:**
> "Bug is in `processPayment()` line 142 — race between `lockBalance()` and `commitTx()`. The lock returns before the DB transaction is durable. Add a regression test that simulates a 50ms commit delay and asserts no double-spend."

**Bad carry:**
> "There was a bug, please test it"

The next agent should be able to start work from `Carry:` alone, without re-reading the whole conversation.

## When NOT to Hand Off

- The current agent's job isn't actually done. Finish it.
- The user explicitly said "just do this one thing." Respect it.
- The next step is **trivial** and a handoff would slow it down (e.g., a one-line change). Just do it.
- The user is **already in flow** and a handoff context-switch would interrupt them. Wait for a natural pause.

## Parallel Handoffs

Some problems need multiple agents at once, not in sequence:

```
"Building a new payment endpoint" →

  [PARALLEL]
   ├─ api-guardian       (contract review)
   ├─ security-reviewer  (auth, input validation, idempotency)
   └─ pair-programmer    (overall approach)

  [SEQUENTIAL after agreement]
   tdd-guide → implementer → code-reviewer
```

Announce the parallel set up front so the user knows what's happening:

```
This touches three concerns at once. I'm consulting:
  • api-guardian      — for contract design
  • security-reviewer — for auth & validation
  • pair-programmer   — for overall structure

Then we'll move to tests + implementation.
```

## Handoff Hygiene

- **Always** name both agents (from/to)
- **Always** justify the handoff in one line (why this specialist now?)
- **Always** package the carry — the next agent should not need to re-investigate
- **Never** chain more than 4 agents in a single response — that's a sign the task is too big and needs decomposition (use `planner`)

## Self-Handoff Rule

An agent may **stay in role** for the next step if it's still within its specialty. Don't fake a handoff just because the conversation continues:

- `debug-detective` may continue after finding the cause to **explain** the cause — that's still debugging.
- `code-reviewer` may continue to suggest specific fixes — still review scope.
- But `code-reviewer` writing the actual fix at scale → hand off to the implementer (or appropriate language reviewer with `code-architect` for blueprint).

## The Master Conductor: kodelyth-advisor

When in doubt about whom to hand off to, the user can always invoke `kodelyth-advisor`. The advisor doesn't do the work — it picks the right specialist and routes.

```
Any agent  →  kodelyth-advisor (if next step is unclear)  →  Right specialist
```