Markdown

Multi-Agent CLI Handoff Contract

Portable contract for Codex (design), Claude Code (review), and Cursor (implement).

Verified against AGENTS.md, Codex AGENTS.md docs, Codex non-interactive docs, Claude Code memory/CLI docs, and Cursor CLI docs on 2026-07-29.

Repo bootstrap

If AGENTS.md or CLAUDE.md already exist, edit them in place — do not overwrite.

# Shared instructions (create only if missing)
if [ ! -f AGENTS.md ]; then
cat > AGENTS.md <<'EOF'
# AGENTS.md

## Commands
- Test:
- Typecheck:
- Lint:

## Patch rules
- One behavior change per branch
- No new dependencies without justification
- Do not edit secrets
- Do not merge to main

## Multi-agent protocol
- Read and update docs/handoffs/<active>.md every run
- Different tools/runs for designer, reviewer, implementer
- Stop for auth, payments, production infra, data deletion
EOF
fi

# Claude bridge (official import pattern; create only if missing)
if [ ! -f CLAUDE.md ]; then
printf '%s\n' '@AGENTS.md' '' '## Claude Code' '- Review jobs do not implement unless status is implement/fixes' > CLAUDE.md
fi

# Handoff area
mkdir -p docs/handoffs

Then create docs/handoffs/_template.md from the template below.

Handoff template

Save as docs/handoffs/_template.md:

# Handoff: <short name>

- ID:
- Status: design
- Owner now: codex
- Next owner: claude
- Branch:
- Worktree:

## Goal

## Non-goals

## Design

## Review

## Implementation notes

## Verification
- Command:
- Last result:

## Decision log
- YYYY-MM-DD <agent>: <note>

Status machine

Happy path: design → design-review → implement → impl-review → done

Loops: design-review can return to design; impl-review can send fixes then back to impl-review.

Also allowed: blocked-human

Role prompts

Codex / designer

Read AGENTS.md and the active handoff file.
Fill Design only: files, boundaries, test plan, risks, open questions.
Do not implement application code.
Set status=design-review, next owner=claude.
Append Decision log.

Claude / reviewer

Read CLAUDE.md/AGENTS.md and the active handoff file.
Do not implement application code.
Write Review as Blocking vs Non-blocking with concrete file-level findings.
If blocking: status=design or fixes (depending on stage), next owner=previous worker.
If clean: advance status to implement or done per stage.
Append Decision log.

Cursor / implementer

Read AGENTS.md and the active handoff file.
Status must be implement or fixes.
Implement only approved design + blocking review resolutions.
Run Verification command; record result.
Set status=impl-review, next owner=claude.
Do not merge.

CLI snippets

Codex design (codex exec; default sandbox is read-only, so grant workspace write for handoff edits):

codex exec --sandbox workspace-write "Read AGENTS.md and the active handoff. Fill Design only, set status=design-review, next owner=claude. Do not implement application code."

Claude Code review:

claude -p --max-turns 30 --output-format text "Review the active handoff per AGENTS.md. Update Review + status only. Do not implement application code."

If Claude cannot write non-interactively under your permission mode, keep the review read-only and paste findings into the handoff manually.

Cursor implement (same worktree as the handoff):

cd ../repo-<id>
agent -p --trust --sandbox enabled --output-format text "Status must be implement or fixes. Implement or fix per the active handoff and AGENTS.md. Update handoff. Do not merge."

Prefer git worktree add (below) so Branch/Worktree fields match the implementer checkout. If you use agent -w, update those fields to the path Cursor actually created under ~/.cursor/worktrees/.

Worktree rule

One handoff ID → one branch → one worktree → one implementer run at a time.

git fetch origin main
git worktree add -b feat/<id> ../repo-<id> origin/main

Permission rule

Definition of done

Stop conditions

Instruction files (AGENTS.md, CLAUDE.md) are shared context, not an enforcement boundary. Pair them with sandbox/permission controls for anything irreversible.