# 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.

```bash
# 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`:

```markdown
# 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

```text
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

```text
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

```text
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):

```bash
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:

```bash
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):

```bash
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.

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

## Permission rule

- Design/review stages: least privilege that can edit the handoff file
- Implementation: scoped worktree only
- Never use broad permission bypass flags on production checkouts as the default

## Definition of done

- [ ] Handoff status is `done`
- [ ] Design and at least one review exist
- [ ] Verification command result recorded
- [ ] Blocking findings resolved or human-waived
- [ ] Human merges the PR

## Stop conditions

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

- Auth / sessions / permissions
- Payments / billing
- Secrets
- Production infrastructure
- Data deletion
- More than two unresolved design-review loops