1---
2name: deferring-work-through-lunatask
3description: Captures findings, suggestions, and deferred work items in Lunatask with rich context for future sessions. Use when user says "we'll tackle this later", when you suggest improvements the user wants to defer, or when identifying issues to address separately.
4compatibility: Requires Lunatask MCP tools or CLI access
5license: AGPL-3.0-or-later
6metadata:
7 author: Amolith <amolith@secluded.site>
8---
9
10## Purpose
11
12Handoff notes are **navigation aids**, not solutions. A future agent will read this note in a fresh context window and explore the _current_ state of the codebase. Your job is to point it in the right direction, not do its thinking for it.
13
14Why this matters:
15
16- Code changes between now and when the task is picked up
17- Pasted code blocks become stale and misleading
18- The receiving agent builds better understanding by exploring than by inheriting your conclusions
19- Shorter handoffs mean the receiving agent has more context budget for actual work
20
21## What to include
22
231. The goal: one or two sentences describing what needs to happen
242. Broader context: If this task is part of a larger plan, briefly state the overall goal and where this piece fits. The receiving agent may make better decisions knowing its work will be immediately built on and having a brief idea how.
253. Entry points: specific file paths and line ranges where the receiving agent should start reading (e.g., `pkg/auth/tokens.go:45-80`, not the contents of those lines)
264. Recent changes: brief description of what we just did that creates this need (so the agent understands the "before" state)
275. Discovered constraints: non-obvious gotchas, API limitations, or decisions that aren't evident from the code
286. References: links to issues, commits, docs, or prior handoffs that informed this work
29
30## What NOT to include
31
32- Code blocks longer than ~5 lines: if you're tempted to paste implementation, paste the file path instead
33- Complete solutions: the receiving agent should derive these from current code state
34- Exhaustive context: only what's necessary to orient, not everything you learned
35- Copied file contents: always reference by path, never by content
36
37If you find yourself writing something that would let someone complete the task by copy-pasting from the note, you've gone too far. Back up and replace content with references.
38
39## Formatting
40
41### Title
42
43Titles must be:
44
45- Useful and concise
46- Conversational
47- Include the project name
48
49Example: `Implement FunctionSignature(Args) in go-lunatask`
50
51### Status
52
53New tasks usually get status `later`.
54
55### Note structure
56
57```markdown
58[A warm, direct, conversational note to the user. Make them smile when they find this later! :3]
59
60---
61
62Hello, future me! o/
63
64[Goal: 1-2 phrase description of what needs doing]
65
66Start here:
67
68- `path/to/file.go:XX-YY` — [why this location is relevant]
69- `another/file.go:ZZ` — [what to look for here]
70
71[Context: describe what we just did that led to the need for a hand-off. What constraints or gotchas we discovered. Keep this to a short paragraph.]
72
73[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.]
74
75When starting this task, update status according to workflow. When finished, mark `complete`.
76```
77
78After creation, refer to the task with [title](lunatask://deep/link) syntax.
79
80### References trailer
81
82Actively gather URLs, file paths, and external resources from the conversation that informed the plan and which would be relevant to the receiving agent. Don't assume it will have access to _any_ of our discussion. Especially gather external resources the user explicitly mentioned (issues, commits, PRs, tickets). List them all in a `References:` section along with brief description of why they're relevant:
83
84```markdown
85References:
86
87- https://github.com/coder/acp-go-sdk/blob/main/agent.go (Agent interface we need to implement)
88- charmbracelet/crush/commit/8a3f2d1 (added AgentCoordinator pattern—reuse this, don't duplicate)
89- ./1302.diff (old PR attempt; has useful patterns but duplicates setup logic we should avoid)
90- https://github.com/coder/acp-go-sdk/tree/main/example/{agent,claude-code,gemini}/main.go (reference implementations with simple REPLs)
91```
92
93Prefer web links; fall back to `project-name/type/id` format.
94
95## Appending to existing notes
96
97Only append; never overwrite unless explicitly asked.
98
99Lunatask only supports full replacement, so reproduce the original note verbatim, then add:
100
101```markdown
102---
103
104[New content here]
105```
106
107Use well-formed markdown with proper whitespace between sections.
108
109---
110
111If `lunatask` or `lune` MCP tools are unavailable, see [cli.md](references/cli.md). If the CLI is also unavailable, see [installing-lune.md](references/installing-lune.md).