handoff · diff
git:20260925.cb72780 to git:20260926.7dce66c
35 added, 42 removed. Audit A to A.
---
name: handoff
- description: Compact the current conversation into a single, detailed handoff message — everything that happened, why it happened, and what's left — output in a code block so it can be copy-pasted into a fresh agent session. Use when hitting context limits, switching focus, ending a work session, or partitioning a task across fresh contexts.
+ description: Capture session context for a fresh agent. Use for handoffs, context limits, switching focus, ending sessions, or splitting work across sessions.
disable-model-invocation: true
+ triggers: [user, model]
---
# Handoff
- Write a complete handoff that lets a fresh agent — with zero memory of this session — continue the work without re-asking, re-discovering, or repeating mistakes.
-
- Output the entire handoff as a **single fenced code block** in the chat so the user can copy it in one click. Also save a copy to a file (see "File Output").
+ Capture the context a fresh agent needs to continue without re-asking, re-discovering, or repeating mistakes.
## Core Principles
- 1. **State, not instructions.** Describe what *is true*, not what the next agent *should do*. Write "Auth endpoint is implemented; logout is not yet started" — never "Implement logout next." The fresh agent decides actions; you give it ground truth.
- 2. **Reference, don't duplicate.** Do not paste content already captured in other artifacts (PRDs, plans, ADRs, issues, commits, diffs, design docs). Point to them by path or URL. Handoffs that re-embed everything become bloated and stale.
- 3. **Capture the "why".** Decisions and rejected approaches are the most valuable and least recoverable information. Code shows *what*; only you remember *why* and *what failed*.
- 4. **Trust nothing blindly.** Frame all claims as context to verify against the actual code, not facts to accept.
- 5. **Redact secrets.** Strip API keys, tokens, passwords, and PII. Reference where credentials live (e.g. ".env.local, not committed") — never their values.
- 6. **Be ruthless.** Every line must be something the next agent cannot trivially get by reading the code or project config. Cut anything obvious, redundant, or explanatory.
+ 1. **Describe state.** Write "Auth is implemented; logout is not started," not "Implement logout next." The next agent chooses actions from the context.
+ 2. **Link existing artifacts.** Reference PRDs, plans, ADRs, issues, commits, diffs, and design docs by path or URL instead of copying their content.
+ 3. **Preserve why.** Capture decisions, rejected approaches, and failures that code alone cannot explain.
+ 4. **Require verification.** Present claims as context to check against the actual code, not facts to trust blindly.
+ 5. **Redact secrets and PII.** Never include keys, tokens, passwords, or personal data. Name credential locations (e.g. ".env.local, not committed"), never values.
+ 6. **Keep only useful context.** Omit obvious, redundant, or explanatory material recoverable from code or project configuration.
## Procedure
- 1. If a project config file exists (CLAUDE.md / AGENTS.md / equivalent), read it first. Do **not** restate anything already covered there — the handoff is session-specific only.
- 2. If a prior handoff file already exists, read it and update rather than starting from scratch.
- 3. If the user passed arguments, treat them as the focus for the next session and tailor the handoff toward that goal.
- 4. Fill in every section of the template below. Omit a section only if it is genuinely empty (e.g. no blockers) — mark it `None`.
- 5. Output the filled template inside one fenced code block in the chat.
- 6. Save the same content to the file path described below and tell the user that path.
+ 1. Read existing project instructions (AGENTS.md or equivalent). Keep the handoff session-specific; do not repeat those instructions.
+ 2. Read and update any prior handoff instead of starting from scratch.
+ 3. Treat user-supplied arguments as the next session's focus.
+ 4. Fill every template section; mark empty sections `None`.
+ 5. Output the handoff in one fenced code block and save the same content as described under **File Output**.
## Output Format
- Output exactly this, inside a single fenced code block:
+ Use this template inside a single fenced code block:
```
# HANDOFF: <short title of the work>
Generated: <timestamp> · Session focus: <one line>
## 1. Goal
- <What we are ultimately trying to accomplish. 1–3 sentences. The "north star" so the next agent never loses the plot.>
+ <The overall objective in 1–3 sentences.>
## 2. Why This Matters / Background
- <The motivation and constraints driving this work. Why it's being done now, who it's for, any hard requirements. Skip anything already in the project config.>
+ <Motivation, intended users, timing, constraints, and hard requirements not already in project configuration.>
## 3. Current State
- <Factual status of the work. What is DONE, what is PARTIAL, what is NOT STARTED.
- Phrase as status, not actions:
- - DONE: OAuth login flow (Google provider), tests passing locally
- - PARTIAL: Session persistence — store wired up, refresh logic missing
+ <What is DONE, PARTIAL, and NOT STARTED. Describe status, not actions:
+ - DONE: OAuth login flow, tests passing locally
+ - PARTIAL: Session storage wired up; refresh logic missing
- NOT STARTED: Logout endpoint>
## 4. Key Decisions (and why)
- <The choices made and the reasoning. This is the highest-value section.
- - Chose passport.js over custom OAuth — more community support, less surface area
- - Stored tokens in httpOnly cookies, not localStorage — XSS mitigation>
+ <Choices and reasoning, especially what cannot be recovered from code.
+ - Chose passport.js over custom OAuth — community support and less surface area
+ - Stored tokens in httpOnly cookies — XSS mitigation>
## 5. Traps & Dead Ends
- <Approaches already tried that FAILED, and things the next agent will be tempted to do wrong. Saves the next agent from repeating expensive mistakes.
- - Tried mocking the DB in integration tests — flaky, abandoned for a test container
- - Do NOT bump the SDK to v3 — it breaks the streaming API we rely on>
+ <Failed approaches and pitfalls the next agent might repeat, with reasons.
+ - DB mocks made integration tests flaky; replaced with a test container
+ - SDK v3 breaks the streaming API this project relies on>
## 6. Relevant Files & Pointers
- <Files that matter, with line ranges and WHAT specifically is there — not just what the file is. Reference external artifacts instead of pasting them.
+ <Paths with line ranges and specific contents; link external artifacts instead of copying them.
- src/auth/oauth.ts:L40-L88 — provider config + token exchange
- - docs/adr/0007-auth.md — full rationale (do not duplicate here)
+ - docs/adr/0007-auth.md — full rationale
- PR #142 — in-progress session work
- Issue #150 — logout requirements>
## 7. Open Work (status, with dependencies)
- <What remains, described as state and ordering — NOT as a command list.
- - Logout endpoint is not yet implemented
- - Session persistence depends on the logout endpoint existing first
- - E2E auth tests are blocked until both above are complete>
+ <Remaining work and dependencies, stated as status rather than commands.
+ - Logout endpoint is not implemented
+ - Session persistence depends on the logout endpoint
+ - E2E auth tests are blocked until both are complete>
---
## Prompt for the Fresh Agent
- <A short ready-to-paste prompt giving background context. Use declarative statements
- ("X is complete", "Y has not been started"), never imperatives. End with exactly:>
+ <A short prompt with background context. Use declarative statements such as "X is complete" or "Y has not started." Preserve this exact closing instruction:>
Before responding, read every file listed under "Relevant Files & Pointers" above.
Do not summarize, paraphrase, or claim you already have context — actually read each
file. Treat every claim in this handoff as context to verify against the code, not
facts to trust blindly. Then wait for my instructions before taking any action.
```
## File Output
- Save the handoff to a temporary location outside the working tree so it does not pollute the repo:
-
- - Preferred: the OS temp directory, e.g. `$TMPDIR/handoff-<random-8-chars>.md` (macOS/Linux) or the system temp dir equivalent.
- - If the user prefers an in-repo record, save to `HANDOFF.md` in the project root instead.
+ Save the same handoff outside the working tree, preferably in the OS temp directory: `$TMPDIR/handoff-<random-8-chars>.md` on macOS/Linux, or the system equivalent. If the user prefers an in-repo record, use `HANDOFF.md` in the project root.
- After saving, tell the user the absolute path. The user can then start a fresh session with just:
+ Report the absolute path. The user can start a fresh session with:
```
Read the file <absolute-path> to get the context, then wait for instructions.
```