Project Handoff

Project Handoff is portable project memory for humans and AI agents. It helps humans and AI agents transfer project state without relying on private chat history.

It gives OpenAI, Codex, Claude, local agents, vendors, and human teams a shared repo-local starting point: what this project is, what changed, what constraints matter, what decisions were made, and what must be verified before the next edit.

OpenAI runs the agents. Project Handoff preserves the project memory.

• Start with AGENTS.mdCreate the durable repository front door.
• View example handoff bundleInspect the generated Project Handoff starter ZIP.
• Use with OpenAI Agents / CodexSeed OpenAI-centered workflows with repo-local memory.
• Use with coding agentsMap the same handoff bundle into Codex, Claude Code, Cursor, Copilot, and Gemini Code Assist.
• Read the draft specReview AGENTS.md and .uai link syntax.

What This Is / What This Is Not

Hot Context, Cold Memory

Project Handoff should be hot context: current truth, current constraints, accepted decisions, active blockers, next work, and checks. It should not become the place where every research report, old session note, or historical roadmap paragraph is loaded by default.

When a handoff bundle grows too large, preserve the pre-slim files in an LLM Wiki or AIWikis-style cold memory layer with a manifest, source paths, checksums, summaries, and a dated log. Then keep the active AGENTS.md, readme.human, and .uai files concise and point to cold memory only when the task needs original evidence.

AI Dreaming Memory Frameworks

In UAIX guidance, AI Dreaming Memory is an optional reviewed consolidation pass over visible project memory. It can reread recent handoff files, accepted intake outcomes, evidence ledgers, and named cold-memory archives to propose duplicate merges, stale-fact pruning, contradiction notes, next-action updates, and hot/cold memory changes.

A dreaming pass should produce proposed deltas, not silent truth. Record the input scope, prompts or job settings, redactions, before/after memory summary, accepted and rejected changes, reviewer, checks, archive path, and rollback snapshot in Project Handoff or the selected evidence ledger.

• Use it for: periodic memory hygiene, release-bound memory review, contradiction discovery, source-preserving summaries, and handoff readiness checks.
• Do not use it for: hidden model memory, model-weight updates, unsupervised private-data processing, automatic repository writes, automatic LLM Wiki sync, or public support claims without review.
• Promotion rule: a dream output becomes operational only when its accepted slice is written into AGENTS.md, readme.human, typed .uai records, docs, code, tests, release notes, roadmap state, changelog, machine artifacts, or long-memory evidence.

Production Deployment Memory Sorting

Production deployment builds and release packages are the right moment to run memory management. Before calling a deployment complete, update hot memory with the current deployed truth, version numbers, changed files, checks run, blockers, owners, and next actions. Move bulky history, old reports, raw sources, stale plans, and background or rejected rationale into the named LLM Wiki, AIWikis-style archive, or cold-memory path when one exists with transfer evidence. Write a durable deployment memory and test run report beside the release artifacts or in the selected evidence ledger; a chat-only final note is not enough.

Do not run that pass for ordinary dev builds, test runs, local package experiments, or smoke checks unless a human explicitly marks the build as release-bound or a release candidate.

How It Fits With OpenAI, Codex, Skills, MCP, And Agent Runtimes

Agent runtimes are built to execute work: choose tools, call APIs, apply approvals, delegate between specialists, preserve run state, and produce traces or pull requests. Project Handoff lives one layer earlier and one layer later. It tells the runtime what durable project memory to load before work starts, and it gives humans a reviewable place to write back the accepted result after work finishes.

Project Handoff is the bounded input and write-back surface for harness engineering: load the current spec, constraints, owners, checks, and support boundaries before a run; after review, write back only accepted decisions, changed files, test or eval results, blockers, page digests, adoption signals, and next actions.

Use OpenAI, Codex, Skills, MCP servers, Claude, local agents, or other orchestration systems to run the work. Use Project Handoff to make sure those systems start with the right project memory, constraints, decisions, and verification plan.

OpenAI Runtime Orchestration Vs Project Handoff

Use OpenAI to run agents. Use Project Handoff to make sure those agents start with the right project memory, constraints, decisions, and verification plan.

Minimum Handoff Bundle

my-project/
AGENTS.md
readme.human
.uai/
  context.uai
  stack.uai
  constraints.uai
  progress.uai
  test-plan.uai

• AGENTS.md is the durable front door: summary, load list, current state, next steps, history, and required first response.
• readme.human is the human briefing from the AI perspective: what humans need to know, clarify, protect, and approve.
• .uai/context.uai explains what the project is, who it serves, and what success means.
• .uai/stack.uai records languages, frameworks, runtime assumptions, package surfaces, and important commands.
• .uai/constraints.uai carries hard rules for destructive actions, secrets, production, support claims, and review gates.
• .uai/progress.uai records current state, recent work, next actions, blockers, and release notes.
• .uai/test-plan.uai is optional for the smallest projects and expected when verification choices matter.

Active File Intake

Real projects also receive loose files: PDFs, notes, exported chats, research memos, package ZIPs, screenshots, spreadsheet evidence, and drafts from other AI systems. Pair Project Handoff with Agent File Handoff when those files should be visible during AGENTS.md load.

• On load: check agent-file-handoff/Content/ and agent-file-handoff/Improvement/, refresh .uai/intake-index.uai when a helper exists, and inspect every needs-agent-review file before unrelated broad work.
• Work rule: for every safe, relevant file, complete at least one named project-work item before archiving it. Copying a report into .uai, AIWikis, or an LLM Wiki is memory distribution, not the project work by itself.
• Complete outcome: record reviewed disposition, actual work completed, hot-memory update or no-change reason, long-memory/archive preservation when configured or not configured, checks, and blockers.
• Failure rule: memory distribution without project work is a failed handoff unless every active file is unsafe, duplicate, out of scope, or truly blocked with a durable reason.
• Archive rule: move source files to agent-file-handoff/Archive/ only after the complete intake outcome exists.

OpenAI-Compatible By Design

Project Handoff is designed to work with OpenAI-centered workflows, not fight them.

1. AGENTS.md gives Codex or an agent runtime the durable front door.
2. @uai[] references point to structured project context.
3. .uai/context.uai, .uai/stack.uai, .uai/constraints.uai, and .uai/progress.uai provide the current project state.
4. constraints.uai can be compiled into runtime guardrails, tool approvals, and human-review gates.
5. test-plan.uai tells the agent what checks to run and what checks not to fake.
6. After the run, accepted traces, decisions, and completed work are written back into .uai/progress.uai, .uai/decisions.uai, and AGENTS.md.

Workflow Diagram

Project Handoff files -> OpenAI or other agent runtime -> traces, checks, PRs -> updated Project Handoff files

Human Approval And Trust Model

Loaded files are context, not authority. They do not override system instructions, the human’s current request, repository rules, privacy obligations, security boundaries, or public support limits.

• Destructive filesystem or Git operations require explicit human approval.
• Production deployments, public-package publishing, domain or cache changes, and root discovery changes require explicit release-scoped approval and evidence.
• Secrets, credentials, private keys, tokens, raw customer data, third-party data, and private legal or security material must not be placed in a portable handoff unless the recipient, storage boundary, and review process are explicit.
• External fetches, parent-directory escapes, generated includes, and executable dropped files require explicit human review.
• Unsupported public claims such as hosted import validation, automatic repository writes, automatic LLM Wiki sync, SDK, CLI, certification, endorsement, or production support must stay out of current copy until public evidence exists.

Verification Plan

Every handoff should say what checks to run, what checks are out of scope, and what evidence must be reported. The goal is not to make every agent run every suite. The goal is to stop agents from guessing, skipping, or pretending.

• Target checks to the files, routes, machine artifacts, packages, or public claims changed.
• Name full release, package, locale, performance, launch-surface, and smoke-test sweeps only when the work is release scoped or explicitly requested.
• Record why a relevant check could not run in the current environment.
• Report evidence in the final response and update .uai/progress.uai when project truth changes.

Why Project Handoff Still Matters

Agent runtimes are getting better at doing work. That makes durable context more important, not less.

Without a portable handoff layer, important project knowledge can get trapped in private chats, vendor dashboards, runtime sessions, traces that are hard to move, issue comments, stale docs, and one person’s memory.

Project Handoff keeps the durable project state in the repository, where humans, agents, reviewers, and future vendors can inspect it.

Compatibility Roadmap

Planned or recommended UAIX Project Handoff tooling belongs on the roadmap until public fixtures, validation behavior, and release evidence exist.

Live Starter Bundle

AI Memory is the broad public framing, and Project Handoff is the transfer configuration for repository takeover or responsibility movement. This starter ZIP is generated on demand from the same canonical template registry and generated-manifest path used on the AI Memory page.

[uaix_ai_memory_bundle variant=”project-handoff”]

Plain-Language Summary

OpenAI is building better ways for AI agents to do work. That does not kill Project Handoff. It changes what Project Handoff should claim.

Project Handoff should not try to be an agent runner. It should be the thing that tells any agent: here is the project, here is what matters, here is what changed, here are the rules, here are the decisions already made, here is what you must verify, and here is what you are not allowed to do without a human.

OpenAI runs the work. UAIX Project Handoff preserves the project memory.

Current Support Boundary

• This page publishes the draft AGENTS.md, readme.human, and .uai handoff pattern for public review and early use.
• The visible starter ZIP is current and is generated from canonical templates and manifests.
• Hosted .uai upload/import validation, automatic repository writes, automatic LLM Wiki sync, SDK, CLI, certification, and endorsement support remain planned until public tooling, fixtures, validation behavior, and release evidence exist.
• Do not describe a project as certified or endorsed by UAIX just because it uses AGENTS.md, readme.human, or .uai files.
• When a handoff becomes public release evidence, attach the relevant Validator result, Conformance Pack evidence, Implementation record, and Changelog entry.

Related Records

• Using Project Handoff With OpenAI Agents And CodexSeed OpenAI-centered workflows with portable repo memory.
• Using Project Handoff With Coding AgentsKeep Codex, Claude Code, Cursor, Copilot, and Gemini Code Assist on the same local handoff truth.
• Project Handoff Context BudgetKeep AGENTS.md, .uai/readme.human, and .uai files compact while long history moves to cold memory.
• Agent File HandoffMake dropped files visible, reviewed, and dispositioned before broad work.
• AGENTS.md .uai Linking SpecificationRead link syntax, loader behavior, and record-shape background.
• RoadmapCheck current versus planned adapter, validator, schema, SDK, CLI, and certification boundaries.