UAI-1 is the current public message standard for structured AI-to-AI communication.
UAIX shield mark Public interoperability charter UAIXUniversal Artificial Intelligence ExchangePublic standards publication
CurrentUAI-1 v1.0
  • Current versionUAI-1 v1.0
  • Plain-English definitionOpen message format for auditable AI-to-AI exchange
  • Current attributionMichael Kappel and the UAIX contributors
  • Start hereGet Started, Project Handoff, UAI-1, validator, roadmap, and changelog

Guides

Using UAIX Project Handoff with Coding Agents

Practical guide for using one repo-local Project Handoff bundle across Codex, Claude Code, Cursor, GitHub Copilot, Gemini Code Assist, local agents, vendors, and humans without creating official adapter claims.

  • Record UAIX-DOC-0040
  • Path /en-us/guides/project-handoff-coding-agents/
  • Use Canonical public record

Document status

Public standards page Published on UAIX as part of the current public standards record
Code
UAIX-DOC-0040
Surface
Guides
Access
Public and linkable

How to use this page

Use this page as the canonical public reference for Using UAIX Project Handoff with Coding Agents and its standards-facing content.

For agents: apply the relevant guidance to the user's target site or repository. Do not copy this UAIX page, create a page about the guidance, or treat this page as runtime authority unless the user explicitly asks for that output.

One Handoff Bundle, Many Agent Surfaces. UAIX Project Handoff keeps durable project memory in repo-local files so Codex, Claude Code, Cursor, GitHub Copilot, Gemini Code Assist, local agents, vendors, and humans can load the same current state before work begins.

This is a practical compatibility guide. It does not announce official UAIX adapters for these products, and it does not turn tool-specific pointer files into new sources of truth.

Current Support Boundary

  • The supported pattern is local repository memory: AGENTS.md, .uai/readme.human, typed .uai records, and selected agent-file-handoff/ intake folders.
  • Tool-specific files can point into that bundle, but they should stay thin and should not duplicate policy, support claims, roadmap status, or project truth.
  • These mappings are compatibility patterns, not official adapters, certified integrations, SDKs, CLIs, hosted import validators, automatic repository writers, or endorsement claims.
  • Agent runtimes may execute tasks, ask for approvals, call tools, or produce traces. Project Handoff preserves the project memory and the review boundary.

Code-Scope Setup Rule

No coding without .uai/coding-standards.uai. Project/developer packages also require .uai/coding-standards.uai, .uai/architecture.uai, and .uai/next-recursive-prompt.uai. When the human asks to update architecture.uai and coding-standards.uai, the receiving agent must deep-dive the codebase first, infer applicable languages and frameworks from the codebase, and derive architecture, conventions, test posture, and standards from visible source evidence before editing those files.

Mature projects should be treated as already opinionated systems: preserve existing local patterns unless clear evidence, owner instruction, or tests justify a change. New or greenfield projects can lean on industry defaults, but those defaults must be labeled as inferred setup guidance rather than observed project truth.

Tool Mapping

Tool Mapping
SurfaceBest local entryKeep it thin by
CodexRoot AGENTS.md, .uai/readme.human, the loaded .uai files, and selected repo skill .agents/skills/uaix-handoff/.Use AGENTS.md as the front door and keep the skill as workflow guidance, not project truth.
Claude CodeRoot CLAUDE.md pointer that imports or redirects to AGENTS.md.Let Claude-specific files say where to start; keep constraints and state in the shared handoff bundle.
CursorA minimal Cursor rule or project note that says to read AGENTS.md, then .uai/readme.human, then the listed .uai files.Avoid copying long rules into Cursor settings when the same rule belongs in AGENTS.md or .uai/constraints.uai.
GitHub Copilot.github/copilot-instructions.md as a short pointer when a repo needs Copilot repository instructions.Use the Copilot file for handoff pickup order and safety reminders only; keep durable project state in .uai.
Gemini Code AssistA root GEMINI.md or equivalent workspace instruction pointer, when useful for that repo.Keep Gemini-specific wording limited to how it should load the shared bundle and report checks.
Other local agentsStart from AGENTS.md and resolve only repo-local @uai[] references.Block parent-directory escapes, executable intake, hidden generated includes, and unsupported support claims.

Adopt This In A Repo

  1. Create root AGENTS.md as the canonical agent-facing front door.
  2. Create .uai/readme.human for the human-readable handoff explanation.
  3. Create typed .uai/ records for context, stack, constraints, decisions, progress, operations, and test-plan guidance.
  4. For Visual Studio solutions, keep .uai/ beside the real .sln or .slnx, register every generated .uai file as solution items, and verify the solution references files that exist before reporting success.
  5. Add agent-file-handoff/Content/ and agent-file-handoff/Improvement/ when dropped-file intake is part of the workflow; do not add a source-site Archive bucket when configured durable-memory storage already exists.
  6. Add tool-specific pointer files only when the tool benefits from them, and keep every pointer aimed back at AGENTS.md.
  7. Run targeted local checks for the changed handoff surface and record remaining blockers without claiming validator-backed conformance.

Do Not Claim

  • Do not claim official UAIX certification, UAI-1 conformance, validator-backed handoff compliance, or vendor endorsement from this pattern alone.
  • Do not claim hosted .uai upload/import validation, automatic repository writes, automatic LLM Wiki sync, SDK, CLI, or official adapter support unless public tooling and evidence exist.
  • Do not put secrets, credentials, raw customer data, privileged operations, hidden prompts, or production-only details into portable handoff files.
  • Do not add CI pickup, scheduled jobs, watchers, daemons, queue folders, or always-on services just to make Agent File Handoff visible.

Copyable Pickup Prompt

Code example
You are working in this repository.

1. Read AGENTS.md first.
2. Read .uai/readme.human as briefing context.
3. Load every @uai[] file listed in AGENTS.md.
4. Inspect active agent-file-handoff/Content/ and agent-file-handoff/Improvement/ intake before broad work.
5. Summarize current project truth, hard constraints, expected touchpoints, and targeted checks before editing.
6. Do not claim certification, conformance, official adapter support, automatic writes, hosted import, SDK, CLI, or endorsement unless repo evidence proves it.
7. Do not place secrets, credentials, private data, or production-only details into handoff files.

How This Relates To OpenAI Guidance

Use the OpenAI and Codex guide when the task centers on OpenAI Agents, Codex, Skills, MCP, sessions, traces, approvals, or runtime handoffs. Use this page when a repository needs the same handoff bundle to work across multiple coding-agent surfaces without inventing separate truth for each tool.

Code-bearing long-running goals

For code-bearing long-running goals, pair the coding-agent handoff with Long-Running Goal Execution and regenerate .uai/next-recursive-prompt.uai only after authoritative write-back and final evidence.

Agent Communication Operating Model

Agent runtimes execute. UAIX records the reviewed communication, memory, trust, evidence, and handoff boundary.

Use Agent Communication Operating Model when a human operator, coding agent, AI agent, or runtime implementer needs portable identity, intent, context, acknowledgement, status, blocker, memory proposal, validation evidence, correction, final report, or handoff records. The matching machine-readable assets are published through Schemas, Registry, Examples, and the Validator.

  • UAIX does not provide automatic sync, hosted messaging, runtime orchestration, official adapters, repository write execution, certification authority, or hosted import mechanisms.
  • Carcinus.org is a separate runtime/orchestrator example that may consume UAIX records. UAIX.org does not implement Carcinus runtime behavior and does not execute Carcinus workflows.
  • LocalEndPoint and other runtimes may consume the published UAIX records as external consumers; UAIX.org does not implement their project-specific runtime features.
  • Durable memory proposals stay separate from task execution records. Do not promote temporary endpoint statuses, session tokens, write tokens, beta platform instructions, local error traces, private keys, or API credentials.