Add agent-task-management skill and references for task management CLI

7 files changed, 333 insertions, 0 deletions

diff --git a/prompts/skills/agent-task-management/SKILL.md b/prompts/skills/agent-task-management/SKILL.md
new file mode 100644
index 0000000..c69dc8e
--- /dev/null
+++ b/prompts/skills/agent-task-management/SKILL.md
@@ -0,0 +1,57 @@
+---
+name: agent-task-management
+description: "Manage agent tasks scoped to the current git project using the `ask` CLI. Use when asked to list, add, start, complete, annotate, or organize tasks for the project. Prefer compaction over starting a new context when beginning a new task. May start work in parallel (e.g. multiple sub-agents on different tasks) as long as agents do not conflict with each other. Triggers on: tasks, todo, task list, pick next task, what's next."
+---
+
+# Agent Task Management
+
+Tasks are scoped to the current git repository via the `ask` CLI. **Load only the files you need** for the current action so the whole skill does not need to be in context.
+
+The `ask` CLI provides subcommands (`list`, `add`, `info`, `start`, `stop`, `done`, `annotate`, `modify`, `tag`, `priority`, `dep`, `delete`, `urgency`) that operate on agent-managed tasks in the current project. `ask` is not a natural-language interface and does not understand skill names. Use normal subcommand syntax only.
+
+Valid examples:
+
+- `ask list`
+- `ask ready`
+- `ask add +cli "Add feature X"`
+- `ask info uuid:<uuid>`
+- `ask start uuid:<uuid>`
+- `ask annotate uuid:<uuid> "progress note"`
+- `ask done uuid:<uuid>`
+
+Invalid examples:
+
+- `ask agent-task-management ...`
+- `ask list tasks`
+- `ask show task 298`
+- any other natural-language phrasing passed to `ask`
+
+**UUIDs are the stable identifiers.** Task IDs are ephemeral working-set indices that shift after completions. Always resolve a task's UUID after creation and use `uuid:<uuid>` selectors for anything that must survive across sessions or agents.
+
+## Context and compaction
+
+When beginning a new task, **prefer running a compaction** over starting a completely new context. If starting a new context for a new task is not possible, run a compaction instead.
+
+## When to Use
+
+- User asks to **list**, **add**, **start**, **complete**, **annotate**, or **organize** tasks for the project.
+- Triggers: *tasks*, *todo*, *task list*, *pick next task*, *what's next*.
+- You may start work **in parallel** (e.g. multiple sub-agents on different tasks) as long as agents do not conflict with each other.
+
+## When to load what
+
+| Action | Load |
+|--------|------|
+| **Create task** | `references/00-context.md` + `references/1-create-task.md` (include refs to all context required) |
+| **Start task** | `references/00-context.md` + `references/2-start-task.md` (start with fresh context; use task refs) |
+| **Complete task** | `references/00-context.md` + `references/3-complete-task.md` |
+| **Annotate / update task** | `references/00-context.md` + `references/4-annotate-update-task.md` |
+| **Review / overview tasks** | `references/00-context.md` + `references/5-review-overview-tasks.md` |
+
+Always load `references/00-context.md` first (project name resolution and global rules); then load the one action file that matches what you are doing.
+
+## Task lifecycle (overview)
+
+1. Create task → 2. Start task → 3. Annotate as you go → 4. **Completion criteria** (best practices, compilable, all tests pass, negative tests where plausible) → 5. Sub-agent review (fresh context) → 6. Main agent addresses all review comments → 7. **Repeat sub-agent review + fixes until no issues are found** → 8. **Commit all changes to git** → 9. Complete task → 10. **Automatically progress to the next task in the list** (when all tests and required sub-agent review(s) pass).
+
+A task is not done until criteria are met, all review comments are addressed, **and the sub-agent review cycle has completed with no remaining issues**, and all changes are committed to git. After completing a task, start the next task in the list (if any). Details are in `references/3-complete-task.md`.
\ No newline at end of file
diff --git a/prompts/skills/agent-task-management/references/00-context.md b/prompts/skills/agent-task-management/references/00-context.md
new file mode 100644
index 0000000..1acf7b9
--- /dev/null
+++ b/prompts/skills/agent-task-management/references/00-context.md
@@ -0,0 +1,24 @@
+# Agent task management — shared context
+
+Load this with any of the action files (1–5) when working with tasks. It defines project scope and rules that apply to all task operations.
+
+## Project name
+
+Derive the project name from the git repository:
+
+```bash
+basename -s .git "$(git remote get-url origin 2>/dev/null)" 2>/dev/null || basename "$(git rev-parse --show-toplevel)"
+```
+
+The `ask` command automatically injects this as `project:<name> +agent` into every command — you never need to specify these manually.
+
+## Rules that apply to all task commands
+
+- **Always use `ask <subcommand>` for all task operations.** The `ask` CLI provides subcommands (`list`, `add`, `info`, `start`, `stop`, `done`, `annotate`, `modify`, `tag`, `priority`, `dep`, `delete`, `urgency`) that operate on agent-managed tasks. It is not a natural-language interface and does not understand skill names.
+- **Project and tag matching:** The agent only reads, modifies, or creates tasks that have **both** `project:<name>` **and** the `+agent` tag. Do not touch any task that does not have `+agent` set.
+- **NEVER modify, delete, complete, start, or annotate tasks from other projects or tasks without `+agent`.** Only act on tasks where `project:<name>` matches the current git repo and the task has the `+agent` tag.
+- **One task in progress per project.** Do not start a second task while another is started and not completed, unless the user explicitly asks.
+- **Parallel work via sub-agents** — the agent may spawn sub-agents to work on tasks in parallel only **after the user approves**.
+- **IDs are ephemeral; use UUIDs for stability.** Task IDs are working-set indices and can be renumbered when the working set is rebuilt. Use numeric IDs only within a single `list` → immediate command sequence.
+- **Use UUIDs for any long-lived reference.** For anything that must survive beyond a single report (handoffs between agents, saved notes, dependencies you mention in text, "next task" pointers, etc.), resolve and use the task's UUID (from the creation annotation) and prefer `uuid:<uuid>` selectors in commands.
+- **Record the UUID at creation time.** After creating a task, immediately annotate it with its UUID so it can be recovered even if numeric IDs are renumbered.
\ No newline at end of file
diff --git a/prompts/skills/agent-task-management/references/1-create-task.md b/prompts/skills/agent-task-management/references/1-create-task.md
new file mode 100644
index 0000000..d204a21
--- /dev/null
+++ b/prompts/skills/agent-task-management/references/1-create-task.md
@@ -0,0 +1,55 @@
+# Create task
+
+Use with `00-context.md`. Project name and global rules apply. New tasks get `+agent` so they are agent-managed; when setting dependencies (`dep:add:<uuid>`), use UUIDs of tasks that have `+agent` (from `ask list` output).
+
+## Rules for new tasks
+
+- **When creating a new task, always check whether the new task depends on other (existing) tasks.** If it does, add the dependency to the new task using `dep:add:<uuid>` with the other task's UUID. Use UUIDs of tasks that have `+agent` in this project.
+- **Create tasks in smaller chunks that fit into the context window.** Break work into multiple tasks so that each task's scope, description, and required context (refs, files, docs) can fit in one context window when the agent works on it with a fresh context. Do not create single tasks that would require more context than available.
+- **Every task MUST have at least one tag** for sub-project/feature/area (e.g. `+integrationtests`, `+flamegraph`, `+bpf`, `+cli`, `+refactor`, `+bugfix`).
+- **When an agent creates a task, always add the tag `+agent`** so agent-created tasks can be identified.
+- **After creating a task, add two annotations** — one with the agent workflow reminder and one recording the UUID:
+  ```
+  ask annotate uuid:<uuid> "Agent workflow: load the agent-task-management skill as instructions only, not as a shell command. Never run ask agent-task-management ... or other natural-language ask commands. Use only normal ask subcommand syntax. Also load and apply: (1) the best-practices skill for the programming language used in the project, (2) solid-principles, and (3) beyond-solid-principles. When all tests and sub-agent reviews pass, commit and automatically progress to the next ready task."
+  ```
+  ```
+  ask annotate uuid:<uuid> "UUID: <uuid>"
+  ```
+- **Include references to all context required** to work on the task. So that work can be done with a fresh context, every task must list or link everything needed: relevant files, docs, specs, other tasks, or project guidelines (e.g. paths, doc links, `AGENTS.md`, `README` sections). Put these in the task description or in an initial annotation so that an agent starting with no prior conversation has everything they need in the task itself.
+- When tasks refer to other tasks in free text (annotations, descriptions, docs, or commit messages), **use the other task's UUID**, not just its numeric ID.
+
+## Add a task
+
+`ask add` already injects `project:<name> +agent`, so only add the extra feature tag(s) and description:
+
+```bash
+ask add +<tag> "Description"
+```
+
+Then add the workflow annotation and UUID annotation (use the UUID shown in the `info` output):
+
+```bash
+ask annotate uuid:<uuid> "Agent workflow: load the agent-task-management skill as instructions only, not as a shell command. Never run ask agent-task-management ... or other natural-language ask commands. Use only normal ask subcommand syntax. Also load and apply: (1) the best-practices skill for the programming language used in the project, (2) solid-principles, and (3) beyond-solid-principles. When all tests and sub-agent reviews pass, commit and automatically progress to the next ready task."
+```
+
+```bash
+ask annotate uuid:<uuid> "UUID: <uuid>"
+```
+
+## With dependency
+
+```bash
+ask add +<tag> "Description" dep:add:<uuid>
+```
+
+Multiple dependencies: `dep:add:<uuid1> +dep:add:<uuid2>`.
+
+After adding (with or without dependency), run the same annotations using the UUID from `ask info uuid:<uuid>`.
+
+## Conventions
+
+- **Keep tasks small:** each task should be a chunk that fits in the context window (description + refs + work to do). Split large efforts into multiple dependent tasks.
+- Pick or create a meaningful tag for the sub-project or feature.
+- **Always check for dependencies:** before adding a task, determine if it depends on other tasks in the project; if so, add `dep:add:<uuid>` with the other task's UUID.
+- Add dependencies when one task must complete before another can start.
+- When creating a task, add references to all required context (files, docs, specs) so the task is self-contained for fresh-context work.
\ No newline at end of file
diff --git a/prompts/skills/agent-task-management/references/2-start-task.md b/prompts/skills/agent-task-management/references/2-start-task.md
new file mode 100644
index 0000000..df096b9
--- /dev/null
+++ b/prompts/skills/agent-task-management/references/2-start-task.md
@@ -0,0 +1,24 @@
+# Start task
+
+Use with `00-context.md`. Project name and global rules apply (including one task in progress per project unless the user says otherwise). Only start tasks that have both `project:<name>` and the `+agent` tag — use UUIDs from `ask list` output.
+
+## Start each new task with a fresh context
+
+Work on each new task **must begin with a fresh context** — e.g. a new session or a sub-agent with no prior conversation. That way the task is executed with clear focus and no carry-over from other work. The task itself should already contain references to all required context (added when the task was created); read the task description and all annotations to get files, docs, and specs before starting.
+
+## Mark task as started
+
+When you begin working on a task, **always mark it as started** so current work is visible:
+
+```bash
+ask start uuid:<uuid>
+```
+
+Do this as soon as you start work on the task.
+
+## Conventions
+
+- Start each new task with a fresh context; rely on the task's description and annotations for all required context.
+- Run `ask start uuid:<uuid>` when you start working on the task, not only when listing or completing.
+- Do not start a second task for the same project while one is already started and not done, unless the user explicitly asks.
+- When a task is selected via the review/overview step, use the stored UUID from the task's annotations for subsequent `start` operations.
\ No newline at end of file
diff --git a/prompts/skills/agent-task-management/references/3-complete-task.md b/prompts/skills/agent-task-management/references/3-complete-task.md
new file mode 100644
index 0000000..531c6a4
--- /dev/null
+++ b/prompts/skills/agent-task-management/references/3-complete-task.md
@@ -0,0 +1,63 @@
+# Complete task
+
+Use with `00-context.md`. Project name and global rules apply. Only complete tasks that have both `project:<name>` and the `+agent` tag — use UUIDs from `ask list` output or task annotations.
+
+## Completion criteria (required before "done")
+
+A task is **not** considered done until all of the following are true:
+
+- **Best practices** — the codebase (or changed parts) follows the project's best practices.
+- **Compilable** — all code compiles successfully (e.g. full build succeeds).
+- **Tests pass** — all tests pass (e.g. full test suite green).
+- **Negative tests where plausible** — for any new or changed tests, include negative tests (invalid input, errors, failure cases) wherever plausible.
+- **All changes committed to git** — on completion of the task, all changes must be committed to git (e.g. a single commit or logical commits with a clear message referencing the task).
+
+If any of these fail, fix the issues and recheck. Do not mark the task complete until they are all met.
+
+## What the review sub-agent must check
+
+Review sub-agents **must always**:
+
+- **Unit test coverage** — double-check that coverage is as desired for the changed or added code (e.g. project expectations or thresholds are met).
+- **Tests are testing real things** — confirm that tests exercise real behavior and assertions, not only mocks. Flag tests that merely assert on mocks or stubs without verifying real logic, integration points, or outcomes. Tests should give confidence that the code actually works.
+- **Negative tests where plausible** — for all tests created, ensure there are also negative tests (invalid input, error paths, edge cases that should fail, unauthorized access, etc.) wherever plausible. If positive/happy-path tests exist but no corresponding negative tests, flag it unless there is a clear reason none are plausible.
+
+Include these checks in the sub-agent's review report.
+
+## Self-review before any sub-agent handoff
+
+**Before signing off work to sub-agents for review** (before the first review, and again before a second review if needed), the main agent must **ask itself**:
+
+- Did everything I did make sense?
+- Isn't there a better way to do it?
+
+If the answer suggests improvements or inconsistencies, address them first. Only then hand off to the sub-agent. Do not skip this step.
+
+## Before marking complete (after criteria are met)
+
+**Once the completion criteria above are met:**
+
+1. **Self-review** (see above). Then spawn a **sub-agent** with **fresh context** (no prior conversation).
+2. Sub-agent reviews the diff, code, or deliverables for the task (including test coverage and test quality — see "What the review sub-agent must check") and **reports back** to the main agent (review comments, suggestions, issues).
+3. Main agent **addresses all review comments** from the sub-agent — no exceptions. Fix or respond to every point.
+4. If code changed after review comments were addressed: **Self-review again** (see above), then **spawn another sub-agent** (fresh context again) to **review the updated code** (including test coverage and test quality) and confirm the fixes. If this follow-up review finds further issues and additional code changes are made, repeat this step until the review is satisfied.
+5. **Commit all changes to git** (e.g. `git add` and `git commit` with a message that references the task). Do not mark the task complete with uncommitted changes.
+6. Only then:
+
+```bash
+ask done uuid:<uuid>
+```
+
+Use the UUID that identifies the task (from its annotations or from the selection step), rather than relying on a numeric ID that may have been renumbered since the last report.
+
+7. **Automatically progress to the next task in the list.** After marking the task done, if there are more agent-managed tasks in the project (e.g. `ask list` shows pending/ready tasks), start the next one: load `00-context.md` and `2-start-task.md`, pick the next task from the list (respecting dependencies and "one task in progress" rule), and begin work on it. Do not stop after completing a task when a next task is available — continue to the next task in the list.
+
+## Conventions
+
+- When creating or changing tests, add negative tests (invalid input, errors, failure paths) wherever plausible; the review sub-agent will check for this.
+- A task is not done until: best practices met, code compiles, all tests pass, negative tests included where plausible, and all first-round review comments are addressed (including coverage and test-quality checks), **and all changes are committed to git**. If code changed after review comments, a second sub-agent review must confirm the updated code.
+- Before every sub-agent review handoff, do the self-review: "Did it all make sense? Is there a better way?" Fix anything that comes up, then hand off.
+- **On completion, commit all changes to git** before running `ask done uuid:<uuid>`; do not leave uncommitted work when marking a task complete.
+- Complete with `ask done uuid:<uuid>` only after completion criteria, self-review(s), first review, addressing all comments, and git commit are satisfied. Add a follow-up sub-agent review only when code changed after review comments.
+- When completing a task, note which tasks were unblocked (dependents that became ready), if any.
+- **After completing a task, automatically progress to the next task in the list** (when all tests and required sub-agent review(s) pass and the task is done). Start the next ready task from `ask ready`; do not stop unless no next task is available or the user asks to stop.
\ No newline at end of file
diff --git a/prompts/skills/agent-task-management/references/4-annotate-update-task.md b/prompts/skills/agent-task-management/references/4-annotate-update-task.md
new file mode 100644
index 0000000..72c2392
--- /dev/null
+++ b/prompts/skills/agent-task-management/references/4-annotate-update-task.md
@@ -0,0 +1,45 @@
+# Annotate / update task
+
+Use with `00-context.md`. Project name and global rules apply. Only annotate, modify, or delete tasks that have both `project:<name>` and the `+agent` tag. Use numeric IDs only within a single report; for any stored or shared reference (annotations, docs, handoffs), **refer to tasks by UUID** and use `uuid:<uuid>` selectors when running commands.
+
+## Reading task context
+
+When working on a task, **always read the full context:** description, summary, and **all annotations**. Annotations often contain progress, challenges, and references to files or documents — use them for further reference.
+
+View full task (including annotations):
+
+```bash
+ask info uuid:<uuid>
+```
+
+## Annotate a task
+
+```bash
+ask annotate uuid:<uuid> "Note about progress or context"
+```
+
+While making progress, **add annotations** to reflect progress, challenges, or decisions. You may refer to files, documents, or other resources (paths, doc links, snippets) so the task history stays useful for later work and for the pre-completion review.
+
+Whenever you mention another task inside an annotation (for example, as a dependency or related work), include that other task's **UUID**, not just its numeric ID.
+
+## Modify a task
+
+```bash
+ask modify uuid:<uuid> +<tag>
+ask modify uuid:<uuid> dep:add:<uuid2>
+ask modify uuid:<uuid> priority:H
+```
+
+Use `uuid:<uuid>` when modifying tasks selected earlier or referenced from annotations or other docs, so changes are applied to the correct task even if IDs have been renumbered.
+
+## Delete a task
+
+```bash
+ask delete uuid:<uuid>
+```
+
+## Conventions
+
+- Read description, summary, and all annotations when working on a task.
+- Annotate with implementation notes, progress, challenges, and references to files or documents as you go.
+- Annotations should be detailed enough that a fresh-context agent can pick up work without needing to ask clarifying questions.
\ No newline at end of file
diff --git a/prompts/skills/agent-task-management/references/5-review-overview-tasks.md b/prompts/skills/agent-task-management/references/5-review-overview-tasks.md
new file mode 100644
index 0000000..d5a281d
--- /dev/null
+++ b/prompts/skills/agent-task-management/references/5-review-overview-tasks.md
@@ -0,0 +1,65 @@
+# Review / overview tasks
+
+Use with `00-context.md`. Project name and global rules apply.
+
+## List tasks for the project
+
+Only list tasks that have `+agent` (project + tag matching). When listing, order by **priority first, then urgency**:
+
+```bash
+ask list sort:priority-,urgency-
+```
+
+By tag (keep `+agent`, same order):
+
+```bash
+ask list +<tag> sort:priority-,urgency-
+```
+
+## Picking what to work on (next task)
+
+**Order by priority first, then by urgency.** When choosing among tasks, always consider priority first (e.g. H then M then L), then urgency as a tiebreaker.
+
+**Check already-started tasks first.** Before suggesting or starting a new task:
+
+```bash
+ask list start.any: sort:priority-,urgency-
+```
+
+- If any tasks are already started, **use one of those** (pick by priority, then urgency) — do not start a second task unless the user explicitly asks.
+- Only if no tasks are in progress, show the next actionable (READY) task, ordered by priority then urgency:
+
+```bash
+ask ready
+```
+
+Once you have chosen a task from one of these lists, **use its UUID** from the list output for all subsequent operations and handoffs. When returning or recording the chosen task for another agent or a later step, **include its UUID**.
+
+## View task details
+
+```bash
+ask info uuid:<uuid>
+```
+
+Only work with task UUIDs that came from the filtered lists above (project + `+agent`). Always read description, summary, and **all annotations** when working on or reviewing a task.
+
+## Visualization
+
+Dependency tree (all agent tasks):
+
+```bash
+ask list
+```
+
+Blocked vs ready (with `+agent`):
+
+```bash
+ask list +BLOCKED sort:priority-,urgency-
+ask ready
+```
+
+## Conventions
+
+- When picking the next task: first list already-started (`start.any:`); if any exist, continue one of those; only if none, pick from `+READY`. **Always order by priority first, then urgency** (e.g. `sort:priority-,urgency-`).
+- Among ready or started tasks, choose by priority (H then M then L), then by urgency.
+- When returning a chosen task to the user or another agent, include its UUID and description.