handoff

---
name: handoff
description: "Generate an intelligent context handoff document for the next agent. Triggers on: handoff, hand off, pass to next agent, context handoff, next agent, session done, stage done, wrap up for next agent, /handoff"
---

# Handoff — Intelligent Context Handoff for Next Agent

Generate a handoff document that gives the next agent in a fresh conversation the minimum context needed to fully understand the project state and immediately continue work — using the fewest tokens possible.

**This is NOT a template.** Every handoff is different. The structure, length, sections, and language of the handoff doc must be adapted to what actually happened and what comes next. The only thing that's fixed is the investigation process below.

---

## When to Use

- A task or stage is complete and the next step will be done in a new conversation
- The operator says "handoff", "wrap up", "done with this stage", "pass to next agent"
- Context window is getting large and work should continue in a fresh session

---

## Visual Output Format

When executing this skill, render all output using the clack-style visual system below. This makes the handoff process scannable and satisfying to watch.

### Banner

At the very start of the skill, display the banner via bash:

```bash
echo -e "\033[36m╭──────────────────────────────────────────────────╮\033[0m"
echo -e "\033[36m│\033[0m                                                  \033[36m│\033[0m"
echo -e "\033[36m│\033[0m   \033[1;37m◆  H A N D O F F\033[0m                              \033[36m│\033[0m"
echo -e "\033[36m│\033[0m   \033[2mIntelligent Context Handoff for Next Agent\033[0m     \033[36m│\033[0m"
echo -e "\033[36m│\033[0m                                                  \033[36m│\033[0m"
echo -e "\033[36m╰──────────────────────────────────────────────────╯\033[0m"
echo ""
```

### Symbol Reference

| Symbol | Meaning | Usage |
|--------|---------|-------|
| `◇` | Completed step | Phase finished successfully |
| `◆` | Active step | Currently executing phase |
| `●` | Info item | Findings, details, file paths |
| `▲` | Warning | Issues, stale docs, risks |
| `┌│└` | Guide bar | Vertical thread wrapping the flow |
| `╭╮╰╯` | Arc-corner box | Summary boxes |
| `├╯` | Branch point | Box title with horizontal extension |

### Guide Bar Rules

The entire handoff flow is wrapped in a vertical guide bar. Every line of output is prefixed with `│` to create a continuous visual thread:

```
┌
│  ◆ Phase N: Title
│
│    ● finding or detail
│    ● finding or detail
│
│  ◇ Phase N complete
│
└  Done
```

- Start with `┌` on its own line
- End with `└  Done` (or `└  Handoff complete`)
- Every content line between them starts with `│` + 2 spaces
- Phase headers: `│  ◆ Phase N: Title` (active) → `│  ◇ Phase N: Title` (done)
- Findings/details: `│    ● description`
- Warnings: `│    ▲ description`
- Empty `│` line between phases for breathing room

### Phase Header Format

Each phase output follows this pattern:

**Starting a phase:**
```
│
│  ◆ Phase N: Title
│
```

**Reporting findings (inline as you work):**
```
│    ● Found 2 prior handoff docs
│    ● Located PROJECT.md, roadmap.md
│    ● Current task: phase-3 implementation
```

**Phase complete:**
```
│
│  ◇ Phase N: Title — done
│
```

### Summary Box (End of Phase 6)

After generating the copy-paste prompt, display a summary box:

```bash
echo -e "\033[36m│\033[0m"
echo -e "\033[36m├──────────────────────────────────────────────────╮\033[0m"
echo -e "\033[36m│\033[0m                                                  \033[36m│\033[0m"
echo -e "\033[36m│\033[0m  \033[1;32m◇\033[0m \033[1;37mHandoff Complete\033[0m                             \033[36m│\033[0m"
echo -e "\033[36m│\033[0m                                                  \033[36m│\033[0m"
echo -e "\033[36m│\033[0m  Handoff doc: <absolute path>                    \033[36m│\033[0m"
echo -e "\033[36m│\033[0m  STATUS.md:   <absolute path>                    \033[36m│\033[0m"
echo -e "\033[36m│\033[0m  Snapshot:    <commit hash>                       \033[36m│\033[0m"
echo -e "\033[36m│\033[0m                                                  \033[36m│\033[0m"
echo -e "\033[36m╰──────────────────────────────────────────────────╯\033[0m"
echo ""
```

Replace `<absolute path>` and `<commit hash>` with actual values. Pad lines with spaces so the right `│` aligns at column 52.

---

## The Process

### Phase 1: Trace the Chain (Look Backward)

**Before doing anything else**, display the banner (see Visual Output Format above) and start the guide bar with `┌`. Then begin Phase 1 with `│  ◆ Phase 1: Trace the Chain`.

Investigate:

1. **Find prior handoff docs** — search the project directory for files with "handoff" in the name, or files that look like they served as context transfers between agents. Read them to understand the chain of work.
2. **Find project structure docs** — look for task breakdowns, roadmaps, phase plans, SOPs, CLAUDE.md, PROJECT.md, or any planning documents that define the overall mission and stages.
3. **Find the current task definition** — locate the specific task doc, issue, or plan that was being worked on this session.

If prior handoff docs exist, the new handoff should be written as a continuation — the next agent should be able to read ONLY the new handoff doc (not the old ones) and still have everything it needs.

### Phase 2: Audit This Session (Look at the Present)

Gather concrete facts about what happened:

1. **Git diff / git log** — what files were created, modified, or deleted since the session started (or since the last commit before this session's work). Use `git diff --stat` and `git log --oneline` to get a clear picture.
2. **Key decisions made** — review the conversation for decisions, constraints discovered, trade-offs chosen, things that broke and how they were fixed, architectural choices.
3. **Current state** — does the code build? Are there failing tests? Uncommitted changes? Pending migrations? Anything half-finished?
4. **What was explicitly NOT done** — things that were discussed but deliberately deferred, out-of-scope items, known shortcuts taken.

### Phase 3: Scan Forward (Look at What's Next)

Cross-reference future work:

1. **Identify the next task(s)** — from task breakdowns, roadmaps, or conversation context, determine what the next agent should work on.
2. **Check for ripple effects** — did anything done this session change assumptions, invalidate plans, create new dependencies, or affect future tasks? This is critical — if we changed a database schema, renamed a type, or discovered a constraint, future task docs may now be partially wrong.
3. **Flag stale docs** — if any planning documents are now out of date because of this session's work, explicitly call this out.

### Phase 4: Build the Minimum Reading List

Figure out the smallest set of files the next agent needs to read:

1. **Docs** — only the task definitions, SOPs, or reference docs actually needed for the next step. NOT everything that was read this session.
2. **Code** — only the entry points, types, and modules the next agent will need to touch or understand. Provide absolute paths.
3. **Order them** — put the most important files first. The next agent should be able to stop reading early if context is tight.

### Phase 5: Write the Handoff Doc

Now write the handoff document. Adapt the structure to what's actually needed — don't force sections that have nothing useful to say, and add sections that the specific situation demands.

**General principles:**
- Write for an agent that knows NOTHING about this project — assume zero prior context
- Be precise: file paths must be absolute, type names must be exact, command examples must be copy-pasteable
- Include verification commands the next agent should run before starting (e.g., `git status`, `rg "some_symbol"`, build/lint checks)
- Include constraints and "do NOT touch" rules if applicable
- If the task has sub-steps, specify the exact order
- Use the same language the operator has been using in this session (Chinese, English, or mixed)

**Where to save the file:**
- If there's an existing pattern of handoff docs or task docs in the project, follow that pattern (same directory, similar naming)
- If not, save it in the project root or a planning/docs directory that makes sense
- Name it descriptively — include the stage/task name and "handoff" (e.g., `04-18A-完成-handoff给18B.md`, `handoff-phase2-complete.md`)

### Phase 5.5: Update STATUS.md

Maintain a running progress log at the **project root** as `STATUS.md`. This is the single file a fresh agent reads to orient itself — even without any handoff prompt.

**If `STATUS.md` does not exist**, create it with the three-layer template:

```markdown
# [Project Name] — Status

## ▲ Current

_(No entries yet. This will be filled by the first handoff.)_

## ■ Milestones

_(empty)_

## ▼ Archive

_(empty)_
```

**Before appending a new entry, check if compression is needed:**

1. Count total lines in `STATUS.md`
2. If **> 100 lines** OR `■ Milestones` has **> 15 entries**:
   - Move all entries from `▲ Current` except the most recent → `■ Milestones` as one-line summaries (format: `- [YYYY-MM-DD] 一句话描述 | ✅/⚠️/🔴`)
   - If `■ Milestones` exceeds 15 entries, move the oldest entries to `▼ Archive` (or delete if `▼ Archive` already has >10 entries — git history preserves the detail)
3. Then append the new entry to `▲ Current`

**New entry format** (append to `▲ Current` section):

```markdown
---

## [YYYY-MM-DD] | [one-line session summary]

**Done this session:**
- [concrete completed item]
- [concrete completed item]

**Current state:**
[Where exactly things stand — what's working, what's half-done, any broken or unstable state]

**Next steps:**
1. [Most immediate action — specific enough to act on]
2. [Following action]
3. [Further if known]

**Decisions / notes:**
- [Non-obvious choices made, constraints discovered, things not to forget]
```

Keep each entry self-contained. Someone reading only the `▲ Current` section should be able to orient immediately.

### Phase 5.7: Snapshot Commit

After writing the handoff doc and updating STATUS.md, create a snapshot commit so the repo state matches the handoff exactly. This gives the next agent a clean starting point and a restore point if anything goes wrong.

```bash
git add -A && git commit -m "snapshot: before [next task/phase name]"
```

If there are files that should NOT be committed (e.g., `.mcp.json` with API keys, `.env` files), add them to `.gitignore` first. When in doubt, ask the operator before committing.

### Phase 6: Generate the Prompt

After writing the handoff file and updating STATUS.md, output a short prompt block that the operator can copy-paste into a new conversation. This prompt should:

- Point the new agent to the handoff file path (absolute)
- State the core task in 1-2 sentences
- Include any critical constraints in 1-2 sentences
- Tell the agent to read the handoff file first, then follow its instructions
- Be as short as possible — the handoff doc has the details, the prompt is just the entry point

Format it as a fenced code block so the operator can copy it easily.

After the prompt block, display the **Summary Box** (see Visual Output Format above) with the actual handoff doc path, STATUS.md path, and snapshot commit hash. End the entire flow with `└  Done`.

---

## Fresh Session Orientation

When a new chat opens and the operator asks something like **"帮我看一下这个project进行到什么程度了"** or **"where are we? what's next?"** — without any handoff prompt — do the following:

1. Look for `STATUS.md` in the **project root** (current working directory)
2. Read **only** the `▲ Current` section (the most recent 1-2 entries) and the top 5 lines of `■ Milestones`. Do NOT read the full file — use line-limited reads or `head`.
3. Run `git log --oneline -5` to check for any commits since the last STATUS.md entry
4. Present a clear, direct orientation:
   - What was done last session
   - Current state of the project
   - Recommended next steps in priority order
   - Any outstanding blockers or decisions
5. **Passive compression check**: if `STATUS.md` exceeds 100 lines, note this to the operator and offer to compress it. Do NOT auto-compress during orientation — it's a read-first moment.

Do NOT wait for the operator to find the file or point you to it. Finding and reading `STATUS.md` is the default first move when asked about project status.

---

## Anti-Patterns

- **Don't write a conversation transcript** — the next agent doesn't need to know what we discussed, only what was decided and what exists now.
- **Don't include context the next agent can derive from the code** — if something is obvious from reading a file, don't duplicate it in the handoff. Just point to the file.
- **Don't pad with boilerplate sections** — if there are no constraints, don't add an empty "Constraints" section. If there's no schema change, don't add a "Database" section.
- **Don't over-include the reading list** — every extra file costs tokens. Be ruthless about what's truly needed vs. nice-to-have.
- **Don't assume the next agent will read prior handoff docs** — each handoff should be self-contained. If info from a prior handoff is still relevant, carry it forward.