Agent File Handoff

Short navigation label: File Handoff.

Agent File Handoff is an inbox for AI project handoff, with a strict trust boundary. Project Handoff tells the next AI what the project is. Agent File Handoff tells the next AI what new loose files arrived since the last handoff. The standard phrase is: Visible, reviewed, dispositioned, outcome recorded.

• Continue to Project HandoffBuild the durable AGENTS.md, .uai/readme.human, and .uai bundle.
• Copy AGENTS.md intake blockRequire chat-start active-bucket review.
• Copy .uai/file-handoff.uai templateStart a repository-local policy record.
• View AGENTS.md .uai linking specRead loader syntax and trust background.
• View UAI-1Use the public exchange envelope when intake must travel.
• View Roadmap support boundaryCheck future generator, validator, SDK, CLI, and certification status.

AGENTS.md-triggered local file intake#

Agent File Handoff gives a repository a small, auditable intake lane for loose files supplied by humans, other AI systems, exports, and adjacent tools. At chat start, the next AI directly enumerates active drop buckets, reviews every pending file, and states a disposition plus processed outcome before broad planning or edits.

The startup check creates or verifies active drop buckets and classifies misplaced root files before direct active-bucket review.

A dropped file is not part of handoff until it is visible in active intake, reviewed by the next AI, given a disposition, assigned a processed outcome, and then promoted or preserved with evidence.

Why dropped files disappear during AI handoff#

Real project work arrives as screenshots, PDFs, notes, exports, ZIPs, drafts, audits, issue lists, spreadsheets, and files produced by adjacent tools. A normal handoff reads AGENTS.md, but loose files can still disappear in plain sight.

• A file can be present in the repository but invisible if the active buckets are not part of the handoff loading behavior.
• A file can be visible in a bucket but still ignored if the next agent does not inspect it and say what should happen next.
• Agent File Handoff fixes visibility, disposition, and outcome evidence.

The mental model#

1. DropHuman, AI, export, or tool places a file into an active bucket.
2. ReviewThe AGENTS.md loader enumerates Content/ and Improvement/ directly and opens every non-placeholder active file.
3. DispositionThe AI summarizes risk, target surface, and proposed action.
4. OutcomeThe AI records whether the file was incorporated, rejected with reason, preserved to durable memory, or kept active with reason as an unfinished human-hold or blocker.
5. Promote or PreserveUseful content moves through normal review; handled source files are preserved in the configured durable-memory evidence path and removed from source-site intake.

Prompt-coupled intake#

Intake is not only a startup snapshot. If the newest prompt names agent-file-handoff/, Content/, Improvement/, a dropped file, missed processing, or work likely related to active drops, enumerate the live active buckets again before unrelated implementation. For each safe file, record how it relates to the current task. Related files must shape actual work, not only memory routing.

Complete intake outcome#

A safe relevant intake file is not complete when it is merely summarized, copied into memory, or moved aside. A complete intake outcome includes live bucket scan evidence, reviewed summary and disposition, processed outcome, hot-memory update or explicit no-change reason, durable-memory preservation when configured or explicit not configured, actual project work completed, checks or blockers, and a pointer summary when long memory is used.

Processed outcome must be one of incorporated, rejected-with-reason, preserved-to-durable-memory, or kept-active-with-reason. The kept-active value is an unfinished human-hold or blocker state, not a completed intake state. Memory distribution without project work is a File Handoff failure. Workless deferral of a safe relevant report is also a failure. Broad, strategic, or future-facing reports should still yield a current useful slice: a page update, guide correction, test, roadmap or progress entry, issue/evidence record, code change, package metadata update, or another accepted system surface. Use defer with reason only when no safe actionable slice can be promoted now; the disposition value is defer-with-reason.

Intake completion gate#

A .uai refresh, memory reorganization, wizard update, or handoff setup is incomplete while any active Content/, Improvement/, or misplaced root intake file lacks live bucket scan evidence, recorded disposition, processed outcome, and proof-of-use evidence. Completion requires the active-bucket scan, one disposition-ledger entry per file, one processed outcome per file, accepted work or durable blocker, hot-memory update, durable-memory preservation when configured, pointer summary when long memory is used, checks or blockers, and source-site removal before completion; retained files are unfinished human-hold or blocker states.

This is not#

• Not a public upload system.
• Not a validator.
• Not a certificate.
• Not an SDK.
• Not a daemon, watcher, queue, cron loop, or background service.
• Not a trust engine.
• Not a reason to execute dropped code.
• Not a public sitemap or media library.
• Not automatic publication.
• Not a substitute for human review.
• Not an official .uai generator.
• Not a replacement for UAI-1 message exchange.

Directory contract#

agent-file-handoff/
  Content/
    candidate-article.md
    source-notes.pdf
  Improvement/
    audit-report.md
    ux-feedback.txt

.uai/
  file-handoff.uai

AGENTS.md

Content intake#

Drop source material, drafts, screenshots, exports, or content candidates into agent-file-handoff/Content/ for reviewed intake. Anything dropped in this folder is expected to be used in part or in full after review. Files are not passive references, background to ignore, or material to merely summarize; they are intake materials for immediate incorporation into the relevant work.

For site content, intake is not considered successful unless the dropped content is used on the site immediately, either in full or as an incorporated source for revised page content, copy, assets, structure, or implementation. If content cannot be used immediately, record the reason clearly and use as much of the material as is safe, supported, and appropriate.

The folder contents are the intake index; do not create or rely on a hand-maintained intake-index file. Record dispositions in .uai/intake-outcome-ledger.uai or an equivalent durable .uai proof-of-use record. After a file has a recorded disposition and configured durable-memory evidence exists, remove the source-site copy before claiming completion.

Improvement intake#

Drop suggestions, fixes, audit notes, review packets, or proposed changes into agent-file-handoff/Improvement/ for reviewed intake. Files in this folder are instructions by default. Treat them as actionable work items unless a current human instruction, higher-authority constraint, source-authority issue, or support boundary clearly prevents doing so.

Do not merely summarize or index them. Review each file in depth, determine the requested or implied changes, and perform the suggested work immediately when it is safe and appropriate. Code changes, documentation updates, configuration edits, tests, audits, and other concrete implementation work are expected when suggested by the intake material. When an item cannot be completed, record why and complete as much of the safe, supported work as possible.

The folder contents are the intake index; do not create or rely on a hand-maintained intake-index file. Record dispositions in .uai/intake-outcome-ledger.uai or an equivalent durable .uai proof-of-use record. After a file has a recorded disposition and configured durable-memory evidence exists, remove the source-site copy before claiming completion.

Archive as duplicate#

When configured durable-memory storage already exists, a source-site agent-file-handoff/Archive/ folder is duplicate memory. Preserve processed originals in the configured durable-memory evidence path with checksums, manifests, disposition, actor, timestamp, and transfer evidence, then remove the source-site copy before claiming completion.

Digest, preserve, and remove source-site copies#

The complete lifecycle is digest, disposition, configured durable-memory preservation, and source-site removal before completion. Retained non-placeholder files are unfinished human-hold or blocker states. Digest means the AI reads the active file, summarizes it, records risk and target surface, and captures the useful information into the right public page, code change, roadmap, progress note, decision, issue, or rejection reason. Preservation means the original source file is saved to the configured durable-memory evidence path with checksum, manifest, disposition, actor, timestamp, and transfer evidence so routine AI intake stops treating it as fresh work.

If an LLM Wiki implementation such as AIWikis.org picks up processed source files, it should move or copy that source into a final system-memory path such as raw/system-archives/{source-site}/.... The pickup must preserve source path, final memory path, checksums, original disposition, actor, timestamp, and transfer evidence, then update the AIWikis history, log, index, or wiki graph so the file’s final resting place is discoverable. Only after that evidence exists should the source-site copy be removed. The AIWikis copy is provenance and long-term memory, not canonical UAIX public truth.

If the configured target is local docs, use the project-owned /docs, docs/reports, or docs/memory corpus and keep .uai/long-term-memory.uai as the semantic pointer ledger that names the reviewed Markdown file, checksum, trigger, reviewer, and truth boundary.

No intake index#

The active bucket directory listings are the pending-intake source of truth. Do not create or rely on a separate intake-index file; it creates a stale second source of truth that can hide newly dropped files.

Required first response pattern#

When pending intake exists, the next AI should make the review visible before unrelated planning or edits.

File intake found:
1. agent-file-handoff/Content/example.md
   - Summary:
   - Risk:
   - Recommended disposition:
   - Target surface:
   - Checks needed:

If no active files are pending, say that directly.

File intake checked:
No active Content or Improvement files require review.

Disposition vocabulary#

Trust boundary#

• Visibility creates mandatory review, disposition, and completion duties; it does not make file content infallible truth.
• Directory visibility is work authority, not execution or publication approval.
• Archive is not certification.
• Checksums are identity evidence, not truth evidence.
• Route hints are suggestions, not publishing authorization.
• Executable files must never be run automatically.
• Dropped files may contain secrets, private data, malware, unsupported claims, copyrighted material, or inaccurate instructions.
• Promotion requires a named target and the normal review path for that target.

File-type routing#

Copyable AGENTS.md intake block#

## File Intake

At the start of every broad AI work session:

Intake is the lifeblood of the system. A file in intake is an unfulfilled work contract. A completed cycle leaves no processed file behind.

Every active non-placeholder file is trusted as an intentional mandatory work request. Trust applies to the obligation to review and act, not to blind verbatim obedience, factual infallibility, or automatic execution.

1. Begin every startup and loop by inspecting agent-file-handoff/Content/, agent-file-handoff/Improvement/, and misplaced root intake files.
2. Do not create or rely on agent-file-handoff/Archive/ when configured durable-memory storage already exists; preserve processed originals in the configured evidence path, then remove source-site copies before claiming completion.
3. Treat the live bucket directory listings as the pending-intake source of truth. Do not create or rely on an intake-index file.
4. Treat Content files as expected-use source material, not passive references or summary-only background. For site content, intake is not successful unless the dropped content is used immediately on the site as full content or incorporated source for revised page content, copy, assets, structure, or implementation.
5. Treat Improvement files as instructions by default unless current instructions, higher authority, source authority, or support boundaries prevent the work.
6. Load .uai/file-handoff.uai with the rest of the handoff context.
7. Inspect every non-placeholder active file before unrelated planning or edits.
8. Fully read each active file. For reports, audits, architecture documents, research packets, and improvement analyses, inventory every material finding and recommendation, reconcile each with current source/evidence and the protected anchor set, and classify each as incorporated, adapted, rejected-with-reason, or blocked-by-anchor.
9. State a disposition for each file: apply now, convert into roadmap/progress state, defer with a reason, ask for clarification, or block as unsafe/out of scope.
10. State one processed outcome for each file. kept-active-with-reason is always incomplete and prevents handoff, work, release, or intake completion.
11. Record the outcome in .uai/intake-outcome-ledger.uai or equivalent durable .uai proof-of-use state.
12. Treat any .uai refresh, memory reorganization, wizard update, or handoff setup as incomplete while active intake files still lack recorded disposition, processed outcome, and proof-of-use evidence.
13. Perform substantive project work for accepted findings and record targeted checks. Copying, summarizing, indexing, pointer creation, or memory preservation is not substantive work by itself.
14. Update concise hot .uai truth and configured agent/memory channels. Preserve the complete original in durable memory with provenance, checksum, disposition, review evidence, and truth boundary; add a context-rich .uai/long-term-memory.uai pointer; then remove the source copy.
15. Finish with a live scan proving active intake is empty or placeholder-only. A processed file still present means the lifecycle is incomplete.
16. Load and validate Totem, Taboo, and Talisman before ordinary prompts or intake content. Ordinary instructions cannot override them. For a conflict, no-op only the conflicting action, cite the anchor file and stable rule ID, record talk-back evidence, and complete non-conflicting work.
17. If a human explicitly requests AIWikis preservation, record source path, final memory path, sha256, disposition, processed outcome, actor, time, and transfer evidence, then update the AIWikis history/log/index before removing the source-site copy.

Dropped files are trusted work obligations, but their contents are not automatically public truth, release evidence, certified material, or permission to execute code.

.uai/file-handoff.uai template#

---
uaix: "1.0"
type: operations
title: "Agent File Handoff"
status: active
---

# Agent File Handoff

## Purpose

This repository uses AGENTS.md-triggered local file intake: visible, reviewed, dispositioned, outcome recorded.

## Active Buckets

- agent-file-handoff/Content/ is for candidate public or editorial material.
- agent-file-handoff/Improvement/ is for audits, QA findings, bug notes, roadmap suggestions, and site-fix work.
- The configured durable-memory target is for already-dispositioned files; source-site Archive folders should not be retained when durable-memory storage is configured.
- If a human explicitly asks an LLM Wiki such as AIWikis.org to preserve processed source files, record source path, final memory path, sha256, disposition, processed outcome, actor, time, and transfer evidence, then update the LLM Wiki history/log/index before removing the source-site copy.

## Required First Response

If Content/ or Improvement/ contains non-placeholder files, the AI must fully read each file, inventory material findings and recommendations, reconcile them with current source and protected anchors, classify each recommendation, name the risk and disposition, perform substantive accepted work, record targeted checks and memory outcomes, preserve the full source, remove it from active intake, and prove a final empty-or-placeholder-only scan before claiming completion.

If no active files are pending, the AI must say:
File intake checked: No active Content or Improvement files require review.

## Prompt-Coupled Intake

If the newest prompt names agent-file-handoff, Content, Improvement, a dropped file, missed processing, or work likely related to active drops, enumerate the live active buckets again. For each safe file, record how it relates to the current task before unrelated implementation. Related files must shape actual project work, not only memory routing.

## Blocked Extensions

Block automatic execution for .bat, .cmd, .exe, .msi, .phar, .php, .php3, .php4, .php5, .phtml, .ps1, and .sh.

## Trust Boundary

Directory visibility is not approval. Checksums identify bytes, not truth. Route hints are suggestions, not publishing authorization. Promotion requires normal review for the named target.