From e8d7ca0fbe3f20667d8dd603e3962df53b1cb46a Mon Sep 17 00:00:00 2001 From: Amolith Date: Sun, 28 Dec 2025 13:42:28 -0700 Subject: [PATCH] docs: improve Lunatask skill clarity and examples Add broader-context guidance to deferring skill, restructure resuming skill around navigation-first philosophy, and expand CLI reference examples. Assisted-by: Claude Opus 4.5 via Crush --- .../deferring-work-through-lunatask/SKILL.md | 24 +++++++------- .../references/cli.md | 25 ++++++++++++--- .../resuming-work-through-lunatask/SKILL.md | 31 ++++++++++++++----- .../references/cli.md | 20 ++++++++++++ 4 files changed, 76 insertions(+), 24 deletions(-) diff --git a/skills/deferring-work-through-lunatask/SKILL.md b/skills/deferring-work-through-lunatask/SKILL.md index 194a5b945234470d8356e686644c0e830d491ce2..8d25923011be5b1f63e7ba4a5ef3856cdc556b38 100644 --- a/skills/deferring-work-through-lunatask/SKILL.md +++ b/skills/deferring-work-through-lunatask/SKILL.md @@ -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: diff --git a/skills/deferring-work-through-lunatask/references/cli.md b/skills/deferring-work-through-lunatask/references/cli.md index 6e279b007769d8283a4d89a775a246e760dc9f2a..3fdddcba541d4a6c3873cb40f55106d676f3ea22 100644 --- a/skills/deferring-work-through-lunatask/references/cli.md +++ b/skills/deferring-work-through-lunatask/references/cli.md @@ -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 -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' ``` diff --git a/skills/resuming-work-through-lunatask/SKILL.md b/skills/resuming-work-through-lunatask/SKILL.md index d81e8b3631258ad6582e7d83a7dab31f7a49db38..1eb8f59e15fdb429f36aa3b732edb42df7bdd8bb 100644 --- a/skills/resuming-work-through-lunatask/SKILL.md +++ b/skills/resuming-work-through-lunatask/SKILL.md @@ -7,14 +7,29 @@ metadata: author: Amolith --- -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`. --- diff --git a/skills/resuming-work-through-lunatask/references/cli.md b/skills/resuming-work-through-lunatask/references/cli.md index e066dc1b735e423cb58f774e8a533fb238301a3f..23a979a162bc8d7f12fcb1890c709581c195d4c6 100644 --- a/skills/resuming-work-through-lunatask/references/cli.md +++ b/skills/resuming-work-through-lunatask/references/cli.md @@ -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