troupe-standup/wizard-work/quill/troupe-handoff-protocol.md

Troupe Handoff Protocol

Draft v1.0 — Quill, Draft lane

Purpose

Give each wizard a deterministic, evidence-based handoff when a session ends, is interrupted, or is routed to another operator. No orphaned state, no assumed context.

Trigger Conditions

Use this protocol when ANY of the following is true:

• Session ends with unfinished artifacts.
• A child subagent returns a summary that needs verification.
• Operator switches to a different wizard mid-task.
• Cron job output needs routing back to the troupe.

Steps

1. Freeze the artifact state

   • Record absolute paths of every file written.
   • Record every tool call that had a side effect (terminal, web_search, delegate_task, cronjob, push).
   • Do NOT delete or move files during handoff.

2. Write the Handoff Ledger Create handoff-<timestamp>.md in the session scratch dir with exactly these sections:

   • ## Context — operator, lane, model/provider, goal.
   • ## Completed — artifact paths + one-line description + test/evidence that verified it.
   • ## Unfinished — stub paths, what remains, acceptance criteria for completion.
   • ## Blockers — exact error text, missing credentials, rate limits, or tool failures.
   • ## Next Action — one command or tool call that advances the unfinished work.

3. Verify with a CHECK command Every handoff MUST include a single bare shell command whose exit code is 0 on success and nonzero on failure. Example:

   • test -f /path/to/artifact && wc -c < /path/to/artifact | awk '{print $1 > 500}'
   • python3 -c "import json; json.load(open('/path/to/artifact'))" (validates JSON parse) Do NOT append ; echo ..., ; true, or || true. The exit code is the verdict.

4. Route the ledger

   • Copy the ledger to /root/troupe-standup/wizard-work/<wizard-name>/.
   • Commit with message: <wizard-name>: handoff <short-goal>.
   • If a FORGE_TOKEN is present, push to origin main.
   • If push fails, leave the local commit and report the exact error in Blockers.

5. Resume Rule The receiving wizard reads ONLY the handoff ledger and the listed artifact paths. It does NOT read prior session transcripts unless the ledger says so.

Evidence Requirements

No claim in a handoff is accepted without one of:

• A tool call result with a verified exit code.
• A file path confirmed by test -f.
• A URL confirmed by curl -sI <url> | head -1.

Non-Goals

This protocol does not cover credential rotation, vendor negotiation, or model selection. Those are operator decisions recorded in Blockers.

---

End of protocol. Next action: write a test handoff ledger for an actual artifact and verify the CHECK command exit code.