Create Handoff

Create Handoff

You are tasked with writing a handoff document to hand off your work to another agent in a new session. You will create a handoff document that is thorough, but also concise. The goal is to compact and summarize your context without losing any of the key details of what you're working on.

Process

1. Filepath & Metadata

Use the following information to understand how to create your document:

First, determine the session name from existing handoffs:

ls -td thoughts/shared/handoffs/*/ 2>/dev/null | head -1 | xargs basename

This returns the most recently modified handoff folder name (e.g., open-source-release). Use this as the handoff folder name.

If no handoffs exist, use general as the folder name.

Create your file under: thoughts/shared/handoffs/{session-name}/YYYY-MM-DD_HH-MM_description.yaml, where:

• {session-name} is from existing handoffs (e.g., open-source-release) or general if none exist
• YYYY-MM-DD is today's date
• HH-MM is the current time in 24-hour format (no seconds needed)
• description is a brief kebab-case description

Examples:

• thoughts/shared/handoffs/open-source-release/2026-01-08_16-30_memory-system-fix.yaml
• thoughts/shared/handoffs/general/2026-01-08_16-30_bug-investigation.yaml

2. Write YAML handoff (~400 tokens vs ~2000 for markdown)

CRITICAL: Use EXACTLY this YAML format. Do NOT deviate or use alternative field names.

The goal: and now: fields are shown in the statusline - they MUST be named exactly this.

---
session: {session-name from ledger}
date: YYYY-MM-DD
status: complete|partial|blocked
outcome: SUCCEEDED|PARTIAL_PLUS|PARTIAL_MINUS|FAILED
---

goal: {What this session accomplished - shown in statusline}
now: {What next session should do first - shown in statusline}
test: {Command to verify this work, e.g., pytest tests/test_foo.py}

done_this_session:
  - task: {First completed task}
    files: [{file1.py}, {file2.py}]
  - task: {Second completed task}
    files: [{file3.py}]

blockers: [{any blocking issues}]

questions: [{unresolved questions for next session}]

decisions:
  - {decision_name}: {rationale}

findings:
  - {key_finding}: {details}

worked: [{approaches that worked}]
failed: [{approaches that failed and why}]

next:
  - {First next step}
  - {Second next step}

files:
  created: [{new files}]
  modified: [{changed files}]

Field guide:

• goal: + now: - REQUIRED, shown in statusline
• done_this_session: - What was accomplished with file references
• decisions: - Important choices and rationale
• findings: - Key learnings
• worked: / failed: - What to repeat vs avoid
• next: - Action items for next session

DO NOT use alternative field names like `session_goal`, `objective`, `focus`, `current`, etc. The statusline parser looks for EXACTLY `goal:` and `now:` - nothing else works. ---

3. Mark Session Outcome (REQUIRED)

IMPORTANT: Before responding to the user, you MUST ask about the session outcome.

Use the AskUserQuestion tool with these exact options:

Question: "How did this session go?"
Options:
  - SUCCEEDED: Task completed successfully
  - PARTIAL_PLUS: Mostly done, minor issues remain
  - PARTIAL_MINUS: Some progress, major issues remain
  - FAILED: Task abandoned or blocked

After the user responds, index and mark the outcome:

# Mark the most recent handoff (works with PostgreSQL or SQLite)
# Use git root to find project, then opc/scripts/core/
PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "${CLAUDE_PROJECT_DIR:-.}")

# First, index the handoff into the database
cd "$PROJECT_ROOT/opc" && uv run python scripts/core/artifact_index.py --file thoughts/shared/handoffs/{session_name}/{filename}.yaml

# Then mark the outcome
cd "$PROJECT_ROOT/opc" && uv run python scripts/core/artifact_mark.py --latest --outcome <USER_CHOICE>

IMPORTANT: Replace {session_name} and {filename} with the actual values from step 1.

These commands auto-detect the database (PostgreSQL if configured, SQLite fallback).

Note: If indexing fails, the marking step will show "Database marking was not available" - this is acceptable for the first handoff but indicates the indexing step was skipped.

4. Confirm completion

After marking the outcome, respond to the user:

Handoff created! Outcome marked as [OUTCOME].

Resume in a new session with:
/resume_handoff path/to/handoff.yaml

--- ##. Additional Notes & Instructions

• more information, not less. This is a guideline that defines the minimum of what a handoff should be. Always feel free to include more information if necessary.
• be thorough and precise. include both top-level objectives, and lower-level details as necessary.
• avoid excessive code snippets. While a brief snippet to describe some key change is important, avoid large code blocks or diffs; do not include one unless it's necessary (e.g. pertains to an error you're debugging). Prefer using /path/to/file.ext:line references that an agent can follow later when it's ready, e.g. packages/dashboard/src/app/dashboard/page.tsx:12-24

Option: create_handoff

I (Initiation)

activate: [session_ending, context_full, major_milestone, explicit_request] skip: [task_just_started, no_work_completed]

Y (Observation Space)

U (Action Space)

primary: [Bash, Write, AskUserQuestion] forbidden: [Edit existing handoffs]

pi (Policy)

P0: Determine Session Name

eta |-> read_ledger OR read_handoff OR fallback_general

P1: Gather Metadata

# Session name from ledger/handoff
ls thoughts/ledgers/CONTINUITY_CLAUDE-*.md 2>/dev/null | head -1 | sed 's/.*CONTINUITY_CLAUDE-\(.*\)\.md/\1/'
ls -d thoughts/shared/handoffs/*/ 2>/dev/null | head -1 | xargs basename

# Git metadata via spec_metadata.sh
~/.claude/scripts/spec_metadata.sh

# Braintrust IDs (if available)
cat ~/.claude/state/braintrust_sessions/*.json | jq -s 'sort_by(.started) | last'

P2: Write Handoff

eta |-> write_to_current_md
path = thoughts/shared/handoffs/{session_name}/current.md

Template structure:

• YAML frontmatter: date, session_name, git_commit, branch, root_span_id, turn_span_id
• Ledger section: Goal, Now, This Session, Next, Decisions
• Context section: Tasks, Critical References, Recent changes, Learnings, Post-Mortem, Artifacts, Next Steps

P3: Index and Mark Session Outcome

eta |-> index_handoff -> ask_user_outcome -> mark_in_db

Commands:

# Index handoff first
cd "$PROJECT_ROOT/opc" && uv run python scripts/core/artifact_index.py --file thoughts/shared/handoffs/{session_name}/{filename}.yaml

# Then mark outcome
cd "$PROJECT_ROOT/opc" && uv run python scripts/core/artifact_mark.py --latest --outcome <USER_CHOICE>

P4: Confirm Completion

eta |-> respond_with_resume_command

beta (Termination)

beta(eta) = 1.0 if handoff_written AND outcome_marked

success: [handoff_file_exists, outcome_recorded, user_confirmed] failure: [write_error, no_session_name, user_cancelled]

Output Schema

file: thoughts/shared/handoffs/{session_name}/current.md
sections: [Ledger, Context, Tasks, Learnings, Post-Mortem, Artifacts, Next Steps]
outcome: [SUCCEEDED, PARTIAL_PLUS, PARTIAL_MINUS, FAILED]

Invariants

inv_1: always ask outcome before completion
inv_2: never include large code blocks (use file:line refs)
inv_3: Ledger section extracted by SessionStart hook
inv_4: Post-Mortem required for artifact indexing