Handoff notes are navigation aids, not solutions. A future agent will read this note in a fresh context window and explore the current state of whatever it's investigating. Your job is to point it in the right direction, not do its thinking for it.

Why this matters:

• Code, CLI behavior, and tool interfaces may change between now and when the task is picked up
• Pasted outputs, code blocks, and behavioral descriptions may become stale
• The receiving agent builds better understanding by exploring than by inheriting your conclusions
• Shorter handoffs mean the receiving agent has more context budget for actual work

Tone

The handoff body (below the ---) is a note from you to another agent, not to the user. It should be:

• Direct and practical: do include a brief warm greeting, but focus more on the body. The receiving agent needs clarity more than friendliness.
• Imperative where appropriate: "Start here", "Check whether X still applies", "Run this command to reproduce"
• Confident but not presumptuous: state what you learned, but acknowledge the receiving agent will verify against current state
• Terse, not curt: brevity is good, but don't leave out context that would help the receiving agent understand what it should be doing, why it's doing that, or what was done to get here

The warm, personal note to the user goes in the blockquote above the separator. Everything below is working notes between agents.

What to include

1. The goal: one or two sentences describing what needs to happen—whether that's implementing something, investigating behavior, or fixing a problem
2. Broader context: if this task is part of a larger plan, briefly state the overall goal and where this piece fits
3. Entry points: where the receiving agent should start exploring:
   • For code work: specific file paths and line ranges (e.g., pkg/auth/tokens.go:45-80)
   • For CLI investigation: the commands to run and what to look for
   • For MCP/API work: which tools or endpoints to examine and how to interact with them
   • For behavior investigation: how to reproduce
4. Recent changes: brief description of what we just did that creates this need
5. Discovered constraints: non-obvious gotchas, limitations, or decisions that aren't evident from exploration alone
6. References: links to issues, commits, docs, or prior handoffs that informed this work

Generally don't assume the receiving agent will have access to any of our discussion; it's your job to look over our conversation, determine what info is relevant to the handoff, and make sure it gets folded into the appropriate section. If the handoff doesn't include the context the receiving agent needs, it's your fault.

What NOT to include

• Code blocks longer than ~5 lines: paste the file path instead
• Complete solutions: the receiving agent should derive these from current state
• Exhaustive context: only what's necessary to orient, not everything you learned
• Copied outputs or file contents: reference how to obtain them, not the content itself
• Implementation specifications: "X maps to Y" or "call A then B" belongs in code. Frame as "we discovered X and Y need to correspond" and let the receiving agent verify.

If you find yourself writing something that would let someone complete the task by copy-pasting from the note, you've gone too far.

Note structure

The handoff body (after your note and its --- separator) should follow this structure:

[Goal: clearly describe what needs doing]

Start here:

- `path/to/file.go:XX-YY` — [why this location is relevant]
- `lune habit track KEY` — [what behavior to observe]
- `mcp tool_name` — [what to examine about this tool]

[Context: why do we need a handoff? What did we just do that led to this need? What constraints or gotchas did we discover?]

[Optional approach hints: high-level suggestions only—"consider X", not "implement X by doing Y". If the approach is obvious from the goal + entry points, omit this.]

When starting this task, update status according to area workflow. When finished, mark `completed`.

References trailer

Actively gather relevant URLs, file paths, and external resources from the conversation. List them in a References: section with brief descriptions of why they're relevant:

References:

- https://github.com/coder/acp-go-sdk/blob/main/agent.go (Agent interface to implement)
- /home/amolith/repos/personal/charm/crush/acp/1302.diff (old PR; useful patterns but avoid its duplication of setup logic)
- /home/amolith/repos/misc/acp-go-sdk (Agent Client Protocol SDK for Go, what we're relying on for ACP server functionality)
- charmbracelet/crush/commit/8a3f2d1 (added AgentCoordinator pattern—reuse, don't duplicate)
- `lune task add --help` (current flag behavior to preserve)

Prefer absolute paths to local clones; fall back to web links, organisation/project/type/id format, or commands to run.