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.

Hot context and cold memory

A handoff fails when it tries to carry the whole institution in the startup packet. Keep the hot layer small: current facts, constraints, decisions that still affect behavior, active blockers, next work, and checks. Move older progress history, long research, old package lessons, and pre-slim snapshots into an LLM Wiki or cold archive with hashes, source summaries, and a dated log. Future agents should load cold memory only when they need original wording or deep rationale.

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.

Coding-agent compatibility

Codex, Cursor, Claude Code, Gemini, Copilot, local agents, vendors, and human maintainers can share one handoff bundle when tool-specific files stay thin and point back to the same source: AGENTS.md, readme.human, and typed .uai records. Those files provide context and boundaries; they do not override system instructions, the current human request, repository rules, or safety requirements.

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.

Complete intake outcome: for every safe relevant file, the agent must name the reviewed disposition, complete at least one site or system work item, update hot memory or explain why not, preserve long-memory or archive evidence when configured, run targeted checks, and report blockers before archiving the source. Memory distribution without site or system work is a failed handoff. Do not count copying a report into memory as the project work.

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.

Required first moves for coding agents

1. Load the front door. Read the canonical AGENTS.md and only then follow pointers to concise current state files.
2. Refresh intake. Inspect active handoff buckets and disposition every new file before broad unrelated edits.
3. Name boundaries. Repeat support-claim, security, privacy, publication, and destructive-operation limits before changing public content or code.
4. Stage source-backed edits. Convert loose reports into reviewable page copy, handoff state, roadmap entries, or archived evidence.
5. Verify locally. Run targeted checks tied to the files and routes changed, and say when full release/package checks were out of scope.

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, disposition every needs-agent-review file, complete real site or system work for every safe relevant file, and record hot-memory plus long-memory/archive outcomes before unrelated broad planning.
4. Load durable context. Use root instructions plus topic files for stack, constraints, operations, style, file handoff, and progress.
5. Check the context budget. If startup files are carrying old research or full progress history, archive the old detail and keep only the current conclusion plus pointer.
6. Name hard boundaries. Call out support claims, destructive operations, authority rules, and production limits.
7. State intended edits. Say which files, routes, or public pages will change before broad edits.
8. 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.