Agent handoff

Agent Handoff

Create a compact, evidence-based continuation packet. Make the handoff useful to an agent that can access the artifacts but cannot see the current conversation.

Preserve the contract

• Treat repository state, files, command output, and external records as evidence. Do not treat memory as evidence.
• Separate verified facts from inferences and unknowns.
• Record the smallest exact next action that can restart progress.
• Preserve user intent, scope, constraints, and outstanding commitments.
• Never copy secrets, credentials, session tokens, private keys, or unnecessary personal data into a handoff.
• Do not label work complete without verification evidence.
• Use None — <reason> or Unknown — <how to resolve> instead of leaving a required field blank.

Choose an operation

1. Create or update: Capture work so another agent or session can continue it.
2. Validate: Audit an existing handoff for missing, vague, unsafe, or unsupported claims.
3. Resume: Reconstruct the task from a handoff and compare it with live state before acting.

Create or update a handoff

1. Reconstruct live state

Inspect the artifacts directly. Collect only information relevant to continuation:

• Original goal and measurable success criteria
• Authorized scope and explicit constraints
• Workspace, repository, branch, revision, and relevant external identifiers
• Modified, staged, untracked, committed, or published artifacts
• Work completed and work still outstanding
• Decisions, rationale, rejected approaches, and reversal conditions
• Verification commands and their exact summarized results
• Blockers, risks, failed attempts, and unresolved unknowns
• The first action the next agent should take

For a Git workspace, inspect at least the current branch, revision, working-tree status, and relevant diff. Do not run commands that mutate state merely to prepare a handoff.

2. Create the document

Prefer HANDOFF.md in the active project root unless the user or repository specifies another location. Seed the required structure with:

python scripts/create_handoff.py \
  --output HANDOFF.md \
  --goal "Ship the requested change with passing checks" \
  --next-action "Inspect the failing authentication test"

Resolve script paths relative to this skill directory, not the user's current directory. The generator records Git context when available and refuses to overwrite a file unless --force is supplied.

3. Replace every placeholder

Write for a cold reader:

• Use paths, URLs, issue numbers, branch names, and commands instead of phrases such as "the file" or "the test."
• Summarize results; do not paste large logs or diffs. Point to durable artifacts when detail matters.
• Mark each file or artifact with its state and why it matters.
• Record failed attempts only when they prevent repeated work or reveal a constraint.
• Make the first next action atomic and executable. Put later actions in dependency order.
• Include a retrieval method for external state without embedding credentials.

Read references/handoff-format.md when a field is unclear, when adapting the format, or when reviewing status and evidence semantics.

4. Validate before transfer

Run:

python scripts/validate_handoff.py HANDOFF.md --strict

Fix every error. Fix warnings or explain why the exception is accurate in the handoff. Re-run validation after edits.

5. Transfer explicitly

Tell the recipient where the handoff is and state its status. Do not claim that another agent has received or resumed it unless that transfer was verified.

Validate an existing handoff

Run the validator first, then inspect semantic accuracy against live state:

python scripts/validate_handoff.py path/to/HANDOFF.md --strict

Check that:

• The recorded branch, revision, file states, and external identifiers still exist.
• Verification results name a command or durable artifact and distinguish pass, fail, and not run.
• A complete handoff has checked success criteria and successful evidence.
• Unknowns include a concrete resolution method.
• The next action remains valid after any state drift.
• No secret or sensitive data is present.

Report discrepancies; do not silently rewrite the source of truth unless the user asked for an update.

Resume from a handoff

1. Read the entire handoff and any directly referenced artifact required for the first action.
2. Verify the workspace, branch, revision, working-tree state, and relevant external state.
3. Compare live state with the snapshot. Classify differences as expected progress, harmless drift, or a conflict.
4. Stop and surface a conflict when continuing could overwrite work, exceed authorization, or act on stale external state.
5. Otherwise execute the first valid next action and continue toward the recorded success criteria.
6. Update the handoff after material progress if another transfer is likely. Preserve prior decisions that still constrain the work.

Do not repeat completed work merely because the original conversation is unavailable. Do not assume the handoff grants authority for publishing, deletion, deployment, messaging, purchases, or other consequential actions.

Status vocabulary

Use exactly one status:

• in-progress: Work can continue and an actionable next step exists.
• blocked: Progress requires named user input, permission, dependency, or external state.
• ready-for-review: Implementation is done and evidence is recorded; review or approval remains.
• complete: Every success criterion is met and supported by verification evidence.

Prefer ready-for-review over complete when a human decision remains.