Detailed changes
@@ -23,7 +23,7 @@ The `skills/authoring-skills/` directory has the necessary info for, well, autho
Two categories of skills exist:
- **Generic capability skills** (`resolving-secrets`, `formatting-commits`): Use specific tools to accomplish general tasks. Tool name omitted from skill name.
-- **Service workflow skills** (`deferring-work-through-lunatask`): Workflows for specific proprietary services. Service name included via `-through-{service}` suffix.
+- **Service workflow skills** (`creating-tasks-through-lunatask`): Workflows for specific proprietary services. Service name included via `-through-{service}` suffix.
## Design Principles
@@ -30,9 +30,9 @@ agent capabilities through a standardised format.
- [resolving-secrets](skills/resolving-secrets/SKILL.md): Wraps shell
commands to resolve secret references in environment variables. Use
when invoking `synu`, `crush`, `gh`, `hut`, etc.
-- [deferring-work-through-lunatask](skills/deferring-work-through-lunatask/SKILL.md):
- Captures findings, suggestions, and deferred work items in Lunatask
- with rich context for future sessions.
+- [creating-tasks-through-lunatask](skills/creating-tasks-through-lunatask/SKILL.md):
+ Creates tasks in Lunatask for todos, reminders, deferred work, and
+ handoffs.
- [resuming-work-through-lunatask](skills/resuming-work-through-lunatask/SKILL.md):
Resumes previously deferred work from Lunatask. Use when user pastes a
task note, shares a deep link, or references continuing earlier work.
@@ -0,0 +1,82 @@
+---
+name: creating-tasks-through-lunatask
+description: 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.
+compatibility: Requires Lunatask MCP or CLI tools
+license: AGPL-3.0-or-later
+metadata:
+ author: Amolith <amolith@secluded.site>
+---
+
+**Tasks**: Reminders, todos, bug reports, feature ideas. Self-contained; the note captures what and why for the user.
+
+**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.
+
+If unclear which type, ask the user "is this a task or a handoff?"
+
+## Tone
+
+Always 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.
+
+## Formatting
+
+### Title
+
+Titles must be clear:
+
+- Useful and concise
+- Conversational
+- Include the project name
+
+Examples:
+
+- `Accept 'complete' as status alias in lune`
+- `Implement ACP event sink in Crush`
+- `Investigate why lune habit track silently fails`
+
+### Status
+
+New tasks usually get status `later`.
+
+### Note structure
+
+**Tasks:**
+
+```markdown
+> [Friendly greeting], [context if helpful]
+>
+> [What needs doing and why]
+>
+> [Optional: relevant links, files, or commands if they'd help]
+```
+
+**Handoffs:**
+
+```markdown
+> [Friendly greeting], [context if helpful]
+>
+> [What needs doing and why]
+
+---
+
+[See references/handoff.md for how to write this section]
+```
+
+### References
+
+Include relevant links when they'd help—issues, commits, docs, files. For handoffs, gather these proactively from previous messages; for tasks, include what's useful.
+
+## Appending to existing notes
+
+Only append; never overwrite unless explicitly asked.
+
+Lunatask only supports full replacement, so reproduce the original note verbatim, then add:
+
+```markdown
+---
+
+[New content here]
+```
+
+---
+
+If `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).
@@ -1,5 +1,3 @@
-# CLI Reference
-
When MCP tools are unavailable, use `lune` CLI.
## Creating tasks
@@ -17,10 +15,10 @@ EOF
```
<task_add_flags>
--a --area Area key (required)
+-a --area Area key (required)
-s --status Status (workflow-dependent)
--n --note Task note (use - for stdin)
--g --goal Goal key
+-n --note Task note (use - for stdin)
+-g --goal Goal key
</task_add_flags>
Output includes the task ID.
@@ -0,0 +1,79 @@
+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:
+
+```markdown
+[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:
+
+```markdown
+References:
+
+- https://github.com/coder/acp-go-sdk/blob/main/agent.go (Agent interface to implement)
+- ./1302.diff (old PR; useful patterns but avoid its duplication of setup logic)
+- charmbracelet/crush/commit/8a3f2d1 (added AgentCoordinator pattern—reuse, don't duplicate)
+- `lune task add --help` (current flag behavior to preserve)
+```
+
+Prefer web links; fall back to paths, `organisation/project/type/id` format, or commands to run.
@@ -1,111 +0,0 @@
----
-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
-
-```markdown
-[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](lunatask://deep/link) 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:
-
-```markdown
-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:
-
-```markdown
----
-
-[New content here]
-```
-
-Use well-formed markdown with proper whitespace between sections.
-
----
-
-If `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).