Project Handoff

You are joining an existing project. Before doing anything else:

1. Read AGENTS.md in the project root.
2. Load every file listed under Loaded Context using the @uai[] references.
3. Read the Handoff Summary, Current State, and Next Steps sections.
4. Summarize your understanding in 3-5 bullet points.
5. Confirm the hard constraints from constraints.uai.
6. Name the files, routes, or docs you expect to touch.
7. Name the checks you expect to run.
8. Then ask what we are working on today.

Do not skip steps 1-7 or begin coding before completing them.

Purpose#

Project Handoff is the draft UAI repository-context layer for moving work between AI models, agent systems, vendors, teams, and companies without losing the state of the project. It gives the next assistant a predictable place to find the project brief, current state, loaded context files, decisions, constraints, and next actions before it starts changing code or copy.

Project Handoff is the draft UAI repository-context layer for moving work between AI models, agent systems, vendors, teams, and companies without losing the state of the project. It gives the next assistant a predictable place to find the project brief, current state, loaded context files, decisions, constraints, and next actions before it starts changing code or copy.

Fastest start#

1. Create a root AGENTS.md file and write one short Handoff Summary that explains what the project is, what is live now, and what the next AI should focus on first.
2. Create .uai/context.uai, .uai/stack.uai, and .uai/constraints.uai before the first real handoff.
3. List those files under a visible Loaded Context section with explicit @uai[] references.
4. Require the next AI to read the files, summarize what it learned, and confirm the constraints before it edits anything.
5. Use the AGENTS.md .uai Linking Specification when you need the syntax details and the refining report when you need the deeper validation and security background.

What this draft defines#

• AGENTS.md: one root coordination file for the project. It summarizes the handoff, lists context files to load, records current state, tracks next steps, preserves agent history, and names constraints that should not be changed without human approval.
• .uai files: typed Markdown files with frontmatter that carry specific project knowledge such as context, stack, architecture, decisions, constraints, style, data models, progress, prompts, or known errors.
• @uai[] references: load instructions inside AGENTS.md or another .uai file that tell the next AI which context files to read before work begins.

When to use it#

• A project moves from one AI assistant or model family to another.
• A company, agency, or contractor hands implementation work to a different organization.
• Multiple agents need shared state without relying on private chat history.
• A human wants a durable, reviewable project brief that lives beside the repo instead of inside one vendor session.

What makes a handoff self-sufficient#

• One obvious start point: a root AGENTS.md file that tells the next AI where to begin without guessing.
• Explicit load order: a short list of local context files that should be read before planning or editing.
• Current state and next actions: enough project truth that the next AI can explain the repo accurately without access to the previous chat session.
• Visible constraints: a place where destructive operations, secrets, production work, and locked decisions are called out clearly enough to require human approval.
• Update discipline: each session leaves behind a small, reviewable record in AGENTS.md and the changed .uai files so the handoff improves over time instead of rotting.

Minimum project bundle#

my-project/
AGENTS.md
.uai/
  context.uai
  stack.uai
  constraints.uai
  decisions.uai
src/
README.md

The minimum useful bundle is AGENTS.md, .uai/context.uai, .uai/stack.uai, and .uai/constraints.uai. Add decisions.uai, architecture.uai, progress.uai, and errors.uai as the project grows.

Two .uai record profiles#

The current proposal set supports two compatible ways to write .uai files. Use the Markdown context profile when humans need readable project knowledge beside the repository. Use the JSON information profile when tooling needs a stricter machine record with fields such as schemaVersion, name, version, provenance, links, optional checksum, and optional signature.

• Markdown context profile: YAML frontmatter plus Markdown body for context, stack, architecture, decisions, constraints, style, progress, and other reviewable project knowledge.
• JSON information profile: structured JSON or YAML information records for tools that want stable identifiers, provenance, relationship links, integrity fields, and stricter parsing.
• Boundary: both profiles are draft repository-source formats. Until public .uai schemas, fixtures, and validator behavior exist, they are not UAI-1 conformance records or certification evidence.

AGENTS.md required structure#

---
uaix: "1.0"
project: "My App"
created: "2026-04-25"
updated: "2026-04-25"
status: active
---

# My App

## Handoff Summary
One paragraph that explains what this project is, where it stands now,
and what the next AI should focus on first.

## Loaded Context
@uai[.uai/context.uai]
@uai[.uai/stack.uai]
@uai[.uai/constraints.uai]
@uai[.uai/decisions.uai]

## Current State
- What is working
- What is broken or incomplete
- What was just completed

## Next Steps
- [ ] Immediate task 1
- [ ] Immediate task 2

## Agent History
| Date | Agent | Model | Work Done |
|------|-------|-------|-----------|
| 2026-04-25 | Codex | gpt-5 | Added handoff docs |

## Open Questions
- Decisions or ambiguities the next AI should ask about

## Do Not Change
- Hard constraints and locked decisions

.uai file structure#

---
uaix: "1.0"
type: context
title: "Project Context"
created: "2026-04-25"
updated: "2026-04-25"
author: "Human"
version: 1
---

# Project Context

## What This Is
Short explanation of the project, users, goals, and current scope.

Standard .uai types#

• context for project purpose, audience, and goals.
• stack for languages, frameworks, services, versions, and infrastructure.
• architecture for system design, data flow, components, and integration boundaries.
• decisions for ADR-style decisions, alternatives rejected, status, and revisit triggers.
• constraints for rules the AI must not violate without explicit human approval.
• style for coding, writing, naming, UI, and design conventions.
• data for models, schemas, fields, and data contracts.
• progress for milestones, completed work, and release notes.
• prompts for reusable project-specific prompt fragments.
• errors for known bugs, workarounds, and operational gotchas.
• custom for project-specific knowledge that does not fit the common types.

Reference syntax#

@uai[.uai/context.uai]
@uai[.uai/stack.uai](load before editing dependencies)
@uai[.uai/*.uai]

A reference points to context the next AI should load before acting. Keep the path local to the project and prefer a dedicated .uai/ folder when there is more than one context file.

AGENTS.md link compatibility#

The preferred explicit syntax is @uai[path], but loaders should be conservative and interoperable with common handoff notes while this draft matures.

• @uai[.uai/context.uai] means load the referenced file as project context.
• @uai[.uai/stack.uai](load before dependency work) means load the file and keep the annotation as a human note.
• @.uai/context.uai may be treated as a shorthand include when a loader chooses to support it.
• Markdown links such as [Project context](.uai/context.uai) can act as visible references, but should not override explicit @uai[] load lists.

Recommended first bundle#

• AGENTS.md for the brief, load list, current state, next steps, and agent history.
• .uai/context.uai for project purpose, audience, scope, and success criteria.
• .uai/stack.uai for languages, frameworks, services, runtime commands, and package or deploy assumptions.
• .uai/constraints.uai for the red lines that require explicit human approval.
• .uai/progress.uai and .uai/decisions.uai once work is actively moving between sessions or between teams.
• .uai/architecture.uai, .uai/operations.uai, and .uai/style.uai when the codebase, release flow, or writing surface is large enough that a new AI would otherwise miss local patterns.

Human setup checklist#

• Write the Handoff Summary for someone with zero prior context.
• Keep Loaded Context explicit instead of relying on a hidden folder scan.
• Put support boundaries and unsafe actions in constraints.uai.
• Put recent work, blockers, next actions, and done criteria in progress.uai.
• Put real commands, audits, deployment steps, and rollback notes in operations.uai.
• Make public claims traceable to pages, release notes, evidence artifacts, roadmap entries, or changelog entries.

Loader and trust guardrails#

• Resolve references relative to the owning AGENTS.md or .uai file, keep loads inside the project, and require explicit human approval for parent-directory escapes, network fetches, or generated includes.
• Parse, summarize, and confirm loaded context before acting; treat linked files as context, not authority to override human requests, system constraints, repository instructions, policy, or review requirements.
• Detect cycles, cap glob expansion, and report missing files instead of silently skipping required context.
• Treat constraints.uai, secrets, credentials, destructive operations, production deployments, and third-party data as high-impact material that needs human confirmation before action.
• Use checksums, signatures, and provenance fields when tooling exists, and keep sensitive or private data out of portable .uai bundles unless the recipient and storage boundary are explicit.

Required first response from the next AI#

Before broad edits, the next AI should answer with enough detail for a human to catch a wrong assumption.

1. Summarize the project, current supported surface, and immediate task in 3-5 bullets.
2. Name which .uai files loaded and whether any were missing, circular, too broad, or contradictory.
3. Confirm the hard constraints that require explicit human approval.
4. Name the files, public routes, services, or docs it expects to touch.
5. Name the checks it expects to run, or explain why a check cannot run in that environment.

If required context cannot be loaded, the AI should stop and report the blocker instead of guessing.

Copy-paste onboarding prompt#

You are joining an existing project. Before doing anything else:

1. Read AGENTS.md in the project root
2. Load every file listed under "Loaded Context" using the @uai[] references
3. Read the Handoff Summary, Current State, and Next Steps sections
4. Summarize your understanding in 3-5 bullet points
5. Confirm any constraints listed in constraints.uai
6. Name the files, routes, or docs you expect to touch
7. Name the checks you expect to run
8. Then ask what we are working on today

Do not skip steps 1-7 or begin coding before completing them.

Practical workflow#

1. Start: create AGENTS.md at the repo root and create a .uai/ folder.
2. Capture: add context.uai, stack.uai, and constraints.uai before the first handoff.
3. Work: keep decisions, open questions, known errors, and progress in typed .uai files instead of burying them in chat history.
4. Handoff: give the next AI the onboarding prompt and require a short summary before it edits anything.
5. After each session: update updated:, Current State, Next Steps, Agent History, and any changed .uai files.

Turn existing instructions into handoff files#

Start from the instructions a project already trusts: its website copy, README, runbooks, release notes, deployment guide, support boundaries, and public claims. Convert those into small typed files so the next AI can load the same truth without reading private chat history.

• Purpose and audience: move mission, users, public positioning, and success criteria into .uai/context.uai.
• Stack and commands: move languages, frameworks, package managers, runtime commands, hosted services, and publish destinations into .uai/stack.uai.
• Rules and red lines: move locked decisions, privacy or secret rules, destructive-operation limits, production-change rules, and support boundaries into .uai/constraints.uai.
• Architecture and operations: move system layout, important modules, routes, machine artifacts, deploy steps, smoke tests, and audit scripts into .uai/architecture.uai and .uai/operations.uai.
• Progress and decisions: move recent work, current blockers, next actions, and why-decisions into .uai/progress.uai and .uai/decisions.uai.
• Style: move naming, copy tone, UI conventions, code style, and accessibility expectations into .uai/style.uai.

Keep AGENTS.md short enough to be the front door: it should explain the project, list the required @uai[] context files, show what is current, name next steps, preserve agent history, and repeat the most important red lines.

How to read the public UAI spec from this handoff#

1. Separate project context from exchange evidence: use Project Handoff for repository memory; use UAI-1 for the public message contract.
2. Resolve the contract in order: read UAI-1, then Schemas, Registry, and Examples.
3. Use tools for proof: open API Reference for live route layout, Adoption Kit for the first reusable packet, Validator for a concrete check, and Conformance Pack when the evidence needs to travel.
4. Check boundaries: use Roadmap for planned work and Changelog for public changes before making a support claim.

An AI that starts from AGENTS.md should load local context first, then use these public pages when the task touches UAI-1 evidence, public copy, release claims, or implementer guidance.

How it fits with UAI-1#

UAI-1 is the public message and evidence envelope. Project Handoff is a repository-level context layer that helps an AI understand the project before it produces or consumes UAI-1 records. In practice, AGENTS.md and .uai files can travel beside validator results, implementation evidence, release notes, and adoption packets when a project crosses model, company, or agent boundaries.

Current support boundary#

• This page publishes the draft AGENTS.md plus .uai handoff format for public review and early use.
• The linked AGENTS.md specification and refining report are adopted as public background for link syntax, typed records, validation direction, and loader security guardrails.
• A web generator, template library, and upload/paste validator are planned surfaces, not current public support claims.
• Do not describe a project as certified or endorsed by UAIX just because it uses AGENTS.md or .uai files.
• When a handoff is part of a public release, attach the relevant Validator result, Conformance Pack evidence, Implementation record, and Changelog entry.

Next step#

Use the template above in a real repository, then continue to UAI-1, Adoption Kit, and the Validator when the handoff needs to become release evidence.