1---
2name: creating-tasks-through-lunatask
3description: Creates tasks in Lunatask for todos, reminders, deferred work, and handoffs. Use when the user wants to capture something for later, whether for themselves or for a future agent session.
4compatibility: Requires Lunatask MCP or CLI tools
5user-invocable: true
6license: LicenseRef-MutuaL-1.2
7metadata:
8 author: Amolith <amolith@secluded.site>
9---
10
11**Tasks**: Reminders, todos, bug reports, feature ideas. Self-contained; the note captures what and why for the user.
12
13**Handoffs**: Work a future agent will pick up in a fresh context window. Requires careful framing so the receiving agent knows where to start and what we learned. See [handoff.md](references/handoff.md) before creating these.
14
15If unclear which type, ask the user "is this a task or a handoff?"
16
17## Tone
18
19Always include a warm, friendly, personal, and conversational note from you to the user. Address them by name if you know it. Otherwise, just start with a friendly greeting omitting their name. Task notes are exclusively a friendly note from you to the user, while handoffs _also_ include a thorough prompt for another agent to pick up. See [handoff.md#tone](references/handoff.md#tone) for more detail.
20
21## Formatting
22
23### Title
24
25Titles must be clear:
26
27- Useful and concise
28- Conversational
29- Include the project name only if goal doesn't exactly match the project name.
30 - A task for the go-lunatask client library in area `projects` and goal `lunatask` would require `go-lunatask` in the title.
31 - A task for crush in area `projects` and goal `crush` should _not_ include `crush` in the title.
32
33Examples:
34
35- `Accept 'completed' as status alias in lune`
36- `Implement ACP event sink in Crush`
37- `Investigate why lune habit track silently fails`
38
39### Area and goal
40
41Area is required. Goal is **optional** — only set one if the user specifies it or the task clearly belongs to an existing goal. Don't guess. The goal cannot be unset through the CLI after creation, so it's better to omit than to get it wrong.
42
43### Status
44
45New tasks usually get status `later`. When beginning work on a task, update according to workflow, then completed when done (or use `done` subcommand shortcut).
46
47### Note structure
48
49**Tasks:**
50
51```markdown
52> [Friendly greeting], [context if helpful]
53>
54> [What needs doing and why]
55>
56> [Optional: relevant links, files, or commands if they'd help]
57```
58
59**Handoffs:**
60
61```markdown
62> [Friendly greeting], [context if helpful]
63>
64> [What needs doing and why]
65
66---
67
68[See references/handoff.md for how to write this section]
69```
70
71### References
72
73Include relevant links when they'd help—issues, commits, docs, files. For handoffs, gather these proactively from previous messages; for tasks, include what's useful.
74
75## Appending to existing notes
76
77Only append; never overwrite unless explicitly asked.
78
79Lunatask only supports full replacement, so reproduce the original note verbatim, then add:
80
81```markdown
82---
83
84[New content here]
85```
86
87## Surfacing tech debt
88
89While working, you may notice code smells, outdated patterns, missing tests, or other improvement opportunities related _or unrelated_ to the current task. We might also intentionally introduce tech debt, aware of the trade-offs. Don't let these observations or introductions disappear with the session; ask the user whether you should mention them.
90
91If the user confirms and it's/they're
92
93- **relevant to the handoff**: mention briefly in context section so the receiving agent is aware
94- **worth tracking separately**: suggest capturing as standalone task(s) so the user can pick up or hand off to another agent later. Even as standalone tasks, make sure to include enough context that another agent could pick it up.
95
96---
97
98If `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).