handoff

name	handoff
description	Generates an extremely detailed LLM handoff report of the current session's work and opens a new cmux tab with claude pre-loaded to continue. Use when switching contexts, ending a session, or handing off work to a fresh LLM.

Handoff

Use this skill when:

• You need to hand off current work to a new LLM session
• The user says "handoff", "hand off", "pass context", "new tab continue", "transfer session"
• Ending a long session and want to preserve full context for continuation

Skill Flow

• Example: "handoff this work to a new tab"
• Example: "create a handoff report and continue in new tab"
• Example: "/handoff"
• Notes:
  • The report must be self-contained — the receiving LLM has ZERO prior context
  • Verify git state and file state directly, never trust prior claims
  • Save report to .omc/ with timestamped filename
  • cmux is used (not tmux) for terminal multiplexing
  • Be exhaustively detailed — the goal is full context transfer, not brevity

1. Gather Session State

Collect ALL of the following by running real commands (do NOT rely on memory alone):

Git state:

git branch --show-current
git log --oneline -10
git status --short
git diff --stat

Scan for prior handoffs — check what already exists so you can cross-reference or flag stale claims:

ls -la .omc/HANDOFF-* .omc/SESSION-HANDOFF-* 2>/dev/null

Modified files: List every file touched this session with what changed and why.

User's original request: Quote the user's exact words that started the work. Include any mid-session direction changes verbatim.

Decisions made: User-confirmed choices with rationale and what alternatives were rejected.

What was explored and rejected: Research, approaches, or designs that were tried and deprioritized — include WHY they were dropped.

External references: Any URLs, design references, documentation, screenshots, or assets the user provided or that informed the work.

Pending work: Anything started but not finished.

Errors encountered: Unresolved issues, failing tests, known bugs with exact error messages.

Key context: Domain knowledge, gotchas, non-obvious constraints discovered during the session.

Critical code snippets: For key changes, include the actual code (not just file paths) so the receiving LLM understands the implementation without reading every file.

2. Write the Handoff Report

Location: .omc/HANDOFF-{YYYY-MM-DD}-{slug}-full-context.md

The slug should be a concise kebab-case description of the work (e.g., clerk-auth-blocker, redesign-services-page).

Report structure — follow this exactly:

# LLM Handoff — {Title}

**Created:** {YYYY-MM-DD HH:MM} {timezone}
**Workspace:** {absolute path to project root}
**Branch:** {current branch}
**HEAD:** {short hash} — {commit subject}
**Audience:** another LLM/engineer continuing this exact work cold.
**Purpose:** {1-2 sentences on what this handoff preserves}
**Secrets policy:** do not print or commit raw credentials.

---

## 0. Read this first — critical current-state warning

{Any contradictions between prior handoff reports and current reality.
Scan existing .omc/HANDOFF-* files and flag stale completion claims.
If everything is clean, say so explicitly.}

---

## 1. User's goal (in their own words)

{Quote the user's original request verbatim.
If they changed direction mid-session, include each pivot with the exact quote.
This is the most important section — the receiving LLM must understand
the user's intent, not just what was built.}

## 2. Repository snapshot (verified at handoff time)

{Full git status output, diff stats, branch info.
Include the actual terminal output, not a summary.}

## 3. What was accomplished this session

{Numbered list of concrete deliverables.
Each item: what was done + which files + why + key code snippets.
Include enough code that the receiving LLM understands the implementation
without needing to read the file first.}

## 4. What was explored and rejected

{Approaches, designs, or research that were tried and deprioritized.
Format: What was tried → Why it was dropped → What replaced it.
This prevents the next LLM from re-exploring dead ends.}

## 5. Architecture & design decisions

{Key decisions made during the session.
Format: Decision → Rationale → Alternatives considered → User's choice.
Include external references (URLs, design shots, docs) that informed decisions.}

## 6. Current state of the code

{For each major area touched:
- What works (verified how — include test/typecheck output)
- What's partially done (what remains)
- What's broken or untested
Include relevant code snippets for partially-done work.}

## 7. Known issues & blockers

{Unresolved bugs, failing tests, environment issues.
Include exact error messages, stack traces, and reproduction steps.}

## 8. External references & assets

{URLs, design references, screenshots, documentation, or assets
that the user provided or that informed the work.
Include extracted attributes from design references if applicable.}

## 9. Files modified (complete list)

| File | Change Type | Summary |
|------|-------------|---------|
| path/to/file | created/modified/deleted | what and why |

## 10. Prior handoff cross-references

{List any prior .omc/HANDOFF-* or SESSION-HANDOFF-* files
that are relevant to this work. Flag which claims in them
are still valid vs stale.}

## 11. Next steps — what to do immediately

{Ordered list of what the receiving LLM should do first.
Be extremely specific:
- "Run pnpm typecheck to verify X"
- "Read src/components/Foo.tsx lines 45-80 to understand the current state"
- "The user wants Y next — start by..."
NOT vague instructions like "check types" or "continue the work".}

## 12. Context the next LLM needs

{Non-obvious things that cost time to discover:
- Environment setup quirks
- API behaviors / undocumented constraints
- Gotchas that wasted time this session
- Files to read first before making any changes
- Project conventions the LLM should follow (link to CLAUDE.md, DESIGN.md, etc.)}

Quality bar: The receiving LLM should be able to continue work within 2 minutes of reading the report, without re-exploring the codebase or re-discovering rejected approaches.

3. Save the Report

Use the Write tool to create the file at .omc/HANDOFF-{date}-{slug}-full-context.md.

4. Open New cmux Tab and Launch Claude

# 1. Create new tab and CAPTURE the surface ref from output
#    Output format: "OK surface:142 pane:92 workspace:76"
SURFACE_OUTPUT=$(cmux new-surface --type terminal)
SURFACE_REF=$(echo "$SURFACE_OUTPUT" | grep -oE 'surface:[0-9]+')

# 2. Wait for shell to be ready
sleep 1

# 3. cd to project root and launch claude with skip-permissions
cmux send --surface "$SURFACE_REF" "cd '$(pwd)' && claude --dangerously-skip-permissions"
cmux send-key --surface "$SURFACE_REF" "Enter"

# 4. Wait for claude to fully start (hooks, OMC init, etc.)
sleep 5

# 5. Send the initial prompt pointing to the handoff report
cmux send --surface "$SURFACE_REF" "Read .omc/{HANDOFF_FILENAME} — this is a handoff report from my previous session. Confirm you understand the current state, summarize the key points, and ask what I want to work on next."
cmux send-key --surface "$SURFACE_REF" "Enter"

If cmux is not available (error on any command), fall back to telling the user:

• The report path
• To open a new terminal tab manually
• To run claude --dangerously-skip-permissions and paste: Read .omc/{HANDOFF_FILENAME}

5. Confirm to User

Tell the user:

• Where the handoff report was saved (full path)
• That the new cmux tab was opened (include surface ref)
• That claude was launched with the handoff context
• Any manual steps needed (e.g., "approve the file read in the new tab")

Lessons Learned (from existing handoffs in this project)

• Always verify git state with real commands — prior session memory can be wrong after branch switches
• Flag contradictions between prior reports and current file system state explicitly in section 0
• Include absolute file paths — relative paths break across worktrees
• Quote the user's exact words — paraphrasing loses intent
• Include what was tried and rejected — prevents the next LLM from repeating dead-end exploration
• Include actual code snippets for key changes, not just file paths
• Include external design references with extracted attributes (e.g., a prior design reference → specific visual attributes list)
• The receiving LLM should never trust completion claims without evidence
• Cross-reference prior handoffs — flag which claims are still valid
• .omc/ is the canonical location for handoff reports in this project