# Coding agent continuity workflow

Use this repository pattern when unfinished work may move between Codex,
Claude Code, Cursor, Gemini CLI, a person, or an unattended service agent.

## 1. Keep stable instructions separate

Put durable repository guidance in the instruction surface used by your agent
host:

- Codex: `AGENTS.md`
- Claude Code: `CLAUDE.md`
- Gemini CLI: `GEMINI.md`
- Cursor: `.cursor/rules/*.mdc`; Cursor CLI also reads root `AGENTS.md` and
  `CLAUDE.md`

Stable instructions should contain architecture boundaries, coding
conventions, safety rules, and the commands used to build, lint, and test the
repository. Do not rewrite them for every task.

## 2. Maintain changing task state

Create `HANDOFF.md` beside the work:

```md
# Checkout reliability fix

## Objective

Prevent duplicate checkout submission after a network retry.

## Repository state

- Repository: `company/storefront`
- Branch: `fix/checkout-idempotency`
- Commit: `4f2c8d1`
- Worktree: clean except `src/checkout/retry.ts`

## Current state

The retry path now reuses the initial idempotency key. The focused unit test
passes. The browser interruption test has not been run.

## Decisions

- Generate the key before the first request.
- Reuse it for transport retries.
- Do not retry a declined payment.

## Evidence

- `npm test -- retry.test.ts`: 12 passed.
- `src/checkout/retry.ts`: key creation moved outside the retry loop.
- Review thread: browser interruption behavior still needs verification.

## Constraints

- Do not log payment data or the idempotency key.
- Preserve the public checkout API.

## Next action

Run the browser interruption test, confirm one order is created, and publish
the result.

## Owner

Successor coding agent, reviewed by Payments.
```

## 3. Sender checkpoint

```bash
git status --short
git diff --stat
git rev-parse --short HEAD
npm test
```

Update `HANDOFF.md` with the actual results. Commit it when Git is the shared
visibility boundary. Publish it with its supporting files when the work must
cross a model, machine, repository, person, or access boundary:

```bash
handover publish . --title "Continue checkout reliability fix"
```

## 4. Successor verification

```bash
handover search "checkout reliability"
handover pull <slug-or-url> --out ./continued-work
cd ./continued-work

git status --short
git log -1 --oneline
```

Before editing:

1. Read the applicable nested instruction files.
2. Compare the declared branch and commit with the checkout.
3. Inspect changed files and open review comments.
4. Reproduce one meaningful test or failure.
5. Confirm that no newer handoff revision changes the next action.
6. Continue with the expected revision identifier when using MCP or HTTP.

## 5. Publish the continuation

The new revision should record:

- what changed;
- what was verified;
- what remains unresolved;
- which feedback was addressed;
- the next action and owner.

Do not replace the prior revision. The earlier state must remain available to
the reviewer and the next agent.

## Do not publish

- `.env` files, private keys, tokens, or reusable credentials;
- hidden chain-of-thought or full transcripts without a continuation purpose;
- generated dependency and build directories;
- unrelated personal or customer data;
- claims without the file, command result, or source needed to verify them.

## Continue

- Interactive public example: https://handover.sh/demo
- Agent-readable example: https://handover.sh/demo.json
- Install Handover: https://handover.sh/install
- MCP workflow: https://handover.sh/guides/mcp-workflow-for-multi-agent-collaboration