Handoff

Commands

/handoff — Main Command

Step 1: Read ai-handoff.yaml (your role), handoff-state.json (state), and the active cycle file docs/handoffs/[phase]_[type]_cycle.md.

Step 2: Check state and act:

• No state file or empty: "No active cycle. Lead should run /handoff start [phase]."
• Approved / done: If plan → "Plan approved! Implement, then /handoff start [phase] impl." If impl → "Implementation approved! Start next phase."
• Escalated: "Escalated to human arbiter. Waiting for decision in the cycle file."
• Needs-human: "Paused for human input. Human should edit the cycle file's Human Input Needed section, set STATE: in-progress, and set READY_FOR: to the appropriate role."
• Aborted: "Cycle was aborted. See cycle file for reason."
• Not your turn: "Waiting for [other agent]. Tell them to run /handoff."
• Your turn: See below.

As Lead (your turn)

1. Read the reviewer's latest feedback from the cycle file
2. Address the feedback: update the plan or implementation files
3. Add a new ## Round [N+1] section to the cycle file with ### Lead (your response) and ### Reviewer (_awaiting response_)
4. Update CYCLE_STATUS: READY_FOR: reviewer, increment ROUND
5. Run: python -m ai_handoff state set --turn reviewer --status ready --command "Read .claude/skills/handoff/SKILL.md and handoff-state.json, then act on your turn" --phase [phase] --round [N+1] --updated-by [your-agent-name]

As Reviewer (your turn)

1. Read the lead's submission and the referenced plan/implementation files
2. Choose ONE action:
   • APPROVE — Set STATE: approved. Run: python -m ai_handoff state set --status done --result approved --updated-by [your-agent-name]
   • REQUEST_CHANGES — Write specific feedback. If round 5: set STATE: escalated, run: python -m ai_handoff state set --status escalated --updated-by [your-agent-name]. Otherwise: set READY_FOR: lead, run: python -m ai_handoff state set --turn lead --status ready --command "Read .claude/skills/handoff/SKILL.md and handoff-state.json, then act on your turn" --phase [phase] --round [round] --updated-by [your-agent-name]
   • ESCALATE — Set STATE: escalated. Run: python -m ai_handoff state set --status escalated --updated-by [your-agent-name]
   • NEED_HUMAN — Add ### Human Input Needed section with your question. Set STATE: needs-human, READY_FOR: human. Run: python -m ai_handoff state set --status escalated --updated-by [your-agent-name]

Step 3 — CRITICAL: You MUST end every /handoff response with this exact box:

┌──────────────────────────────────────────────────┐
│ NEXT: Tell [agent name] to run:  /handoff        │
└──────────────────────────────────────────────────┘

Replace [agent name] with the next agent's name. For completed/escalated/needs-human states, replace with the appropriate next action.

/handoff start [phase] — Start a New Phase

Lead only. Append impl to start an implementation review instead of a plan review.

1. Read ai-handoff.yaml to confirm you are the lead
2. Create or verify the phase plan at docs/phases/[phase].md (Summary, Scope, Technical Approach, Files, Success Criteria)
3. Create docs/handoffs/[phase]_[plan|impl]_cycle.md with:
   • Metadata block (phase, type, date, lead name, reviewer name)
   • Reference to plan file (or implementation files if impl)
   • ## Round 1 with ### Lead (Action: SUBMIT_FOR_REVIEW, summary) and ### Reviewer (_awaiting response_)
   • CYCLE_STATUS block: READY_FOR: reviewer, ROUND: 1, STATE: in-progress
4. Run: python -m ai_handoff state set --turn reviewer --status ready --command "Read .claude/skills/handoff/SKILL.md and handoff-state.json, then act on your turn" --phase [phase] --type [plan|impl] --round 1 --updated-by [your-agent-name]
5. End with the NEXT COMMAND box.

/handoff status — Orientation & Reset

For both agents. Re-reads everything and gives a full orientation.

1. Read ai-handoff.yaml → show role assignment
2. Read handoff-state.json → show current state
3. Read active cycle file → show round, last action
4. Output: Phase: [phase] | Type: [plan/impl] | Round: [N] | Turn: [agent] | Status: [state]
5. End with the NEXT COMMAND box showing the appropriate next action.