@@ -21,10 +21,11 @@ Why this matters:
## What to include
1. The goal: one or two sentences describing what needs to happen
-2. 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)
-3. Recent changes: brief description of what we just did that creates this need (so the agent understands the "before" state)
-4. Discovered constraints: non-obvious gotchas, API limitations, or decisions that aren't evident from the code
-5. References: links to issues, commits, docs, or prior handoffs that informed this work
+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
@@ -54,7 +55,7 @@ New tasks usually get status `later`.
### Note structure
```markdown
-> [Warm, direct message to user—make them smile when they find this later]
+[A warm, direct, conversational note to the user. Make them smile when they find this later! :3]
---
@@ -64,7 +65,7 @@ Hello, future me! o/
Start here:
-- `path/to/file.go:XX-YY` — [why this location matters]
+- `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.]
@@ -78,21 +79,22 @@ After creation, refer to the task with [title](lunatask://deep/link) syntax.
### References trailer
-When user references external resources (issues, commits, PRs, tickets), append a `References:` section:
+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:
```markdown
References:
-- https://github.com/user/repo/issues/123
-- project-name/commit/abc123
-- project-name/todo/456
+- 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.
+Only append; never overwrite unless explicitly asked.
Lunatask only supports full replacement, so reproduce the original note verbatim, then add:
@@ -6,7 +6,12 @@ When MCP tools are unavailable, use `lune` CLI.
```bash
lune task add "Title" -a AREA_KEY -n "$(cat <<'EOF'
-Note content
+Intro paragraph
+
+# Section
+
+Content
+
EOF
)"
```
@@ -18,21 +23,31 @@ EOF
-g --goal Goal key
</task_add_flags>
-Output includes the task ID needed to replace `PLACEHOLDER_ID` in the note.
+Output includes the task ID.
## Updating notes
```bash
lune task update ID -n "$(cat <<'EOF'
-Full replacement content
+Intro paragraph
+
+# Section
+
+Content
+
+---
+
+Appended content
+
EOF
)"
```
-Notes are replaced entirely—reproduce original content when appending.
+Notes are replaced entirely, so reproduce original content when appending.
-## Listing areas
+## Listing
```bash
lune area list
+lune goal list -a projects # goals in area 'projects'
```
@@ -7,14 +7,29 @@ metadata:
author: Amolith <amolith@secluded.site>
---
-Treat the provided plan as **high-level suggestions only**. Before acting:
-
-1. Read relevant source code, documentation, and library APIs
-2. Verify the plan is still accurate, necessary, and beneficial
-3. If deviations exist between the plan and current state:
- - Stop
- - Summarize the deviations
- - Wait for user input before proceeding
+## Purpose
+
+Handoff notes are **navigation aids**, not solutions. They point you toward relevant code and context, but the codebase may have changed since the handoff was written. Your job is to explore the current state and form your own understanding.
+
+## Before acting
+
+1. Read the actual files: entry points in the handoff tell you where to look, but always read the current source. Any code snippets in the handoff may be stale.
+2. Verify the plan still applies: check that the goal is still relevant and the suggested approach still makes sense given the current code.
+3. If present, follow the references: external links, commits, and docs in the handoff were included for a reason. Skim them for context.
+
+## If the code has diverged
+
+If you find significant differences between what the handoff describes and what the code actually looks like:
+
+- Stop
+- Summarize what changed
+- Wait for user input before proceeding
+
+Don't try to reconcile the handoff with reality on your own. The user may have context about why things changed.
+
+## Workflow
+
+When you begin working on the task, update its status according to the area's workflow. When finished, mark it `complete`.
---
@@ -18,6 +18,26 @@ lune task update ID -s STATUS
Valid statuses depend on the area's workflow (see `lune area list`).
+## Updating notes
+
+```bash
+lune task update ID -n "$(cat <<'EOF'
+Intro paragraph
+
+# Section
+
+Content
+
+---
+
+Appended content
+
+EOF
+)"
+```
+
+Notes are replaced entirely, so reproduce original content when appending.
+
## Marking complete
```bash