SKILL.md

name: deferring-work-through-lunatask description: 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. compatibility: Requires Lunatask MCP tools or CLI access license: AGPL-3.0-or-later metadata: author: Amolith amolith@secluded.site

Purpose

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 the codebase. Your job is to point it in the right direction, not do its thinking for it.

Why this matters:

  • Code changes between now and when the task is picked up
  • Pasted code blocks become stale and misleading
  • 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

What to include

  1. The goal: one or two sentences describing what needs to happen
  2. 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.
  3. 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)
  4. Recent changes: brief description of what we just did that creates this need (so the agent understands the "before" state)
  5. Discovered constraints: non-obvious gotchas, API limitations, or decisions that aren't evident from the code
  6. References: links to issues, commits, docs, or prior handoffs that informed this work

What NOT to include

  • Code blocks longer than ~5 lines: if you're tempted to paste implementation, paste the file path instead
  • Complete solutions: the receiving agent should derive these from current code state
  • Exhaustive context: only what's necessary to orient, not everything you learned
  • Copied file contents: always reference by path, never by content

If 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.

Formatting

Title

Titles must be:

  • Useful and concise
  • Conversational
  • Include the project name

Example: Implement FunctionSignature(Args) in go-lunatask

Status

New tasks usually get status later.

Note structure

[A warm, direct, conversational note to the user. Make them smile when they find this later! :3]

---

Hello, future me! o/

[Goal: 1-2 phrase description of what needs doing]

Start here:

- `path/to/file.go:XX-YY` — [why this location is relevant]
- `another/file.go:ZZ` — [what to look for here]

[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.]

[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 workflow. When finished, mark `complete`.

After creation, refer to the task with title syntax.

References trailer

Actively 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:

References:

- https://github.com/coder/acp-go-sdk/blob/main/agent.go (Agent interface we need to implement)
- charmbracelet/crush/commit/8a3f2d1 (added AgentCoordinator pattern—reuse this, don't duplicate)
- ./1302.diff (old PR attempt; has useful patterns but duplicates setup logic we should avoid)
- https://github.com/coder/acp-go-sdk/tree/main/example/{agent,claude-code,gemini}/main.go (reference implementations with simple REPLs)

Prefer web links; fall back to project-name/type/id format.

Appending to existing notes

Only append; never overwrite unless explicitly asked.

Lunatask only supports full replacement, so reproduce the original note verbatim, then add:

---

[New content here]

Use well-formed markdown with proper whitespace between sections.

If lunatask or lune MCP tools are unavailable, see cli.md. If the CLI is also unavailable, see installing-lune.md.