Agent Handoff Patterns

A durable handoff tells the next agent what project it joined, what people need to clarify, what context was loaded, which dropped files were just received, what rules are hard constraints, what changed, and how to verify it.

What an agent handoff is

An agent handoff is the structured transfer of project context, human briefing, task state, decisions, constraints, and evidence between agents or teams. A good handoff is not a transcript dump. It is a compact operating record that lets another human or AI resume work without private chat history and without guessing which claims are safe.

What must be preserved

Preserve project identity, the root human briefing, loaded context, hard constraints, source-of-truth boundaries, current task state, changed files or routes, known blockers, and the targeted verification plan.

Minimum project bundle

Required first response

Before broad edits, the next AI should summarize the project, name the public or supported surface, report intake files and dispositions, confirm hard constraints, name expected touchpoints, name targeted checks, and say whether full release or package checks are out of scope. When the work is a full build, it should also name the private .md, .uai, and .human source docs that need cleanup. That first response is not ceremony; it is the cheapest place to catch authority drift, stale context, unsupported claims, or unsafe edit paths.

Human briefing

The UAIX Project Handoff pattern now includes a root readme.human beside AGENTS.md. Use it to tell people what the AI needs humans to know, what it will defend, and which assumptions are unsafe. Keep it subordinate to AGENTS.md, project constraints, system instructions, repository rules, and the current human request.

Active file handoff

Real handoffs also need an intake place for loose files: notes, PDFs, screenshots, exported conversations, draft pages, package ZIPs, and outputs from other AI systems. LlmWikis dogfoods the UAIX Agent File Handoff pattern with active intent buckets: agent-file-handoff/Content/ for candidate public or editorial material and agent-file-handoff/Improvement/ for audits, QA findings, SEO reports, bug notes, and site-fix work. AGENTS.md-triggered chat-start intake refreshes .uai/intake-index.uai with the local helper script. Any needs-agent-review file must be inspected, summarized, and dispositioned before unrelated broad work continues. Already-dispositioned files move to agent-file-handoff/Archive/, which routine AI intake ignores unless a human explicitly names an archived file or moves it back into an active bucket. Watchers, daemons, queue folders, manifests, cron loops, background services, and bucket-local README instructions are outside the base pattern.

powershell -NoProfile -ExecutionPolicy Bypass -File scripts/Invoke-UaiFileIntake.ps1

Dropped files are local project inputs, not public pages. Promote only after source review, UAIX boundary checks, SEO/content review, and targeted route or file checks. Package checks belong to release-scoped work; full builds should also reconcile private source docs such as AGENTS.md, readme.human, and .uai files without adding them to public discovery.

Package dogfood lesson

The AIWikis.org package pass showed that a handoff recommendation is not enough by itself. Starter bundles and WordPress handoff exports should be inspected for the actual agent-file-handoff/ folders, loaded .uai files, source manifests, and release evidence before a site claims it is dogfooding the pattern.

Handoff checklist

1. Identify the project. Start with purpose, audience, current public truth, and active surface.
2. Brief the human. Keep readme.human short, plain, and focused on what people need to make explicit before steering AI work.
3. Process dropped files. Check agent-file-handoff/Content/ and agent-file-handoff/Improvement/ as part of AGENTS.md loading, ignore agent-file-handoff/Archive/, read .uai/intake-index.uai, and disposition every needs-agent-review file before unrelated broad planning.
4. Load durable context. Use root instructions plus topic files for stack, constraints, operations, style, file handoff, and progress.
5. Name hard boundaries. Call out support claims, destructive operations, authority rules, and production limits.
6. State intended edits. Say which files, routes, or public pages will change before broad edits.
7. Verify. Run targeted lint, route, discovery, or runtime checks that fit the change; reserve package and smoke checks for release-scoped work, and clean private source docs during full builds.

Common failure modes

Human review

Human review should confirm that the handoff did not widen support claims, hide destructive changes, blur UAIX authority, or skip practical verification.