Handoff

Handoff

Create a handoff that lets another person or agent continue the work without replaying the whole conversation. Prefer a compact, evidence-backed Markdown artifact over a broad transcript dump.

Default Workflow

1. Identify the handoff intent:
   • continue: another agent should pick up the work
   • review: a person should inspect a decision, diff, or result
   • escalate: help is needed on a blocker or question
   • archive: preserve the current state for later
2. Capture only the context needed to continue:
   • current status and completed work
   • next steps or the specific question to answer
   • key files with narrow line ranges
   • relevant command outputs and verification results
   • risks, assumptions, constraints, and known non-goals
3. Generate the Markdown with scripts/create_handoff.py when a file or clipboard-ready artifact is useful.
4. Review the generated handoff before sharing:
   • The title should make the work recognizable in five seconds.
   • The summary should say what changed and why the handoff exists.
   • The next steps or open questions should be actionable.
   • The artifact should not leak secrets, customer data, or private credentials.

Output Contract

• Default output directory: _handoffs/
• Resolve the output directory relative to --base-dir; if omitted, use the current working directory.
• Default filename: YYYYMMDD-HHMMSS-<title-slug>.md
• Copy the generated Markdown to the system clipboard by default when a clipboard command is available.
• Include Git repo root and branch when available.
• Every handoff should contain at least:
  • generation time
  • base directory and Git metadata when available
  • intent
  • summary
  • status
  • next steps or open questions
  • relevant context files, command outputs, and notes when provided

Script

Script: scripts/create_handoff.py

Common flags:

• --title: one-line handoff title, required
• --summary: why this handoff exists and what the receiver needs to know, required
• --intent: continue, review, escalate, or archive; defaults to continue
• --status: repeat to record completed work or current state
• --next-step: repeat to list concrete continuation steps
• --open-question: repeat to list unresolved questions or blockers
• --decision: repeat to record decisions already made
• --risk: repeat to record risks, assumptions, or tradeoffs
• --note: repeat to record extra context
• --context PATH[:START[-END]]: repeat to attach code context
  • src/app.py
  • src/app.py:20
  • src/app.py:20-60
• --command "...": repeat to capture read-only command output
• --base-dir: base directory for resolving context paths and running commands; defaults to the current working directory
• --out-dir: output directory; defaults to _handoffs
• --slug: override the filename slug; defaults to a slug derived from the title
• --no-clipboard: skip copying generated Markdown to the system clipboard

Example:

python3 scripts/create_handoff.py \
  --title "Auth callback refactor ready for review" \
  --intent review \
  --summary "The callback handler now validates state before exchanging tokens. Please review the error-path behavior and naming before merge." \
  --status "Updated the callback route and shared OAuth helper." \
  --status "Added regression coverage for missing and mismatched state." \
  --next-step "Review the redirect behavior for expired sessions." \
  --open-question "Should invalid state redirect to login or show a dedicated error page?" \
  --context "src/routes/auth/callback.ts:1-160" \
  --context "tests/auth-callback.test.ts:20-110" \
  --command "pnpm test tests/auth-callback.test.ts --runInBand" \
  --risk "No manual browser pass has been run yet."

Context Rules

• Prefer file paths with explicit line ranges over whole files.
• Include command outputs only when they prove status, failures, or verification.
• If the handoff is tied to a diff, include the relevant snippets and a short change summary.
• Do not run mutating or destructive commands through --command; convert them to read-only checks or paste the relevant result manually.
• Do not include tokens, cookies, secrets, full .env files, production credentials, customer data, or private account details.

Inline Handoffs

When a persistent artifact is unnecessary, write the handoff directly in the final response with the same shape:

• title
• intent
• summary
• status
• next steps or open questions
• evidence and verification
• risks or assumptions

Keep inline handoffs short enough to act on immediately.