Prefer ask in taskwarrior skill

7 files changed, 39 insertions, 34 deletions

diff --git a/prompts/skills/taskwarrior-task-management/SKILL.md b/prompts/skills/taskwarrior-task-management/SKILL.md
index d554f9e..6d88e7f 100644
--- a/prompts/skills/taskwarrior-task-management/SKILL.md
+++ b/prompts/skills/taskwarrior-task-management/SKILL.md
@@ -7,6 +7,8 @@ description: "Manage Taskwarrior tasks scoped to the current git project. Use wh
 
 Taskwarrior tasks are scoped to the current git repository. **Load only the files you need** for the current action so the whole skill does not need to be in context.
 
+Prefer `ask ...` for agent-managed project tasks. `ask` is Taskwarrior-compatible because it pre-sets `project:<name> +agent` while preserving normal Taskwarrior commands, reports, filters, and UUID workflows. `hexai task ...` is a compatibility alias with the same behavior.
+
 Taskwarrior numeric IDs are **ephemeral working-set indices** and may be renumbered; this skill treats **UUIDs as the stable identifiers** for tasks. Use numeric IDs only within a single “report → immediate command” flow, and use UUIDs for anything that must survive across sessions, agents, or reports.
 
 ## Context and compaction
diff --git a/prompts/skills/taskwarrior-task-management/references/00-context.md b/prompts/skills/taskwarrior-task-management/references/00-context.md
index fc4ea60..20c41fe 100644
--- a/prompts/skills/taskwarrior-task-management/references/00-context.md
+++ b/prompts/skills/taskwarrior-task-management/references/00-context.md
@@ -14,10 +14,11 @@ Use it as `project:<name>` in every `task` command.
 
 ## Rules that apply to all task commands
 
+- **Prefer `ask ...` for project-scoped agent tasks.** `ask` automatically injects `project:<name> +agent` and otherwise behaves like normal Taskwarrior. `hexai task ...` is a compatibility alias with the same behavior.
 - **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.
-- **EVERY `task` command MUST include `project:<name>`** — no exceptions. When listing or querying, also include `+agent` so only agent-managed tasks are shown (e.g. `task project:<name> +agent list`). Never run a bare `task` without the project filter. When using a task ID, confirm the task belongs to the current project **and** has the `+agent` tag before acting on it.
+- **If you use raw `task` instead of `ask`, EVERY command MUST include `project:<name>`** — no exceptions. When listing or querying, also include `+agent` so only agent-managed tasks are shown (e.g. `task project:<name> +agent list`). Never run a bare `task` without the project filter. When using a task ID, confirm the task belongs to the current project **and** has the `+agent` tag before acting on it.
 - **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.** Taskwarrior numeric 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 (for example, `task <id> _uuid` or `task <filter> uuids`) and prefer `uuid:<uuid>` selectors in commands.
+- **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 (for example, `ask <id> _uuid` or `ask <filter> uuids`) and prefer `uuid:<uuid>` selectors in commands.
diff --git a/prompts/skills/taskwarrior-task-management/references/1-create-task.md b/prompts/skills/taskwarrior-task-management/references/1-create-task.md
index 7ba98e7..df6819a 100644
--- a/prompts/skills/taskwarrior-task-management/references/1-create-task.md
+++ b/prompts/skills/taskwarrior-task-management/references/1-create-task.md
@@ -8,38 +8,40 @@ Use with `00-context.md`. Project name and global rules apply. New tasks get `+a
 - **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 an annotation** so any agent working on the task is reminded to use this skill and to auto-progress: `task <id> annotate "Agent: be aware of taskwarrior-task-management skill. When working on this task, 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, automatically progress to the next task in the list."` This ensures agents (including those with fresh context) know to load and follow the taskwarrior-task-management skill, respect code-quality skills (best-practices, SOLID, beyond-SOLID), and continue to the next task after completion.
+- **After creating a task, add an annotation** so any agent working on the task is reminded to use this skill and to auto-progress: `ask <id> annotate "Agent: be aware of taskwarrior-task-management skill. When working on this task, 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, automatically progress to the next task in the list."` This ensures agents (including those with fresh context) know to load and follow the taskwarrior-task-management skill, respect code-quality skills (best-practices, SOLID, beyond-SOLID), and continue to the next task after completion.
 - **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.
-- **Record the task’s UUID for future reference.** After creating a task, resolve its UUID (for example, `task <id> _uuid`) and include it in an annotation such as `UUID: <uuid>` so the exact task can be recovered even if IDs are renumbered.
+- **Record the task’s UUID for future reference.** After creating a task, resolve its UUID (for example, `ask <id> _uuid`) and include it in an annotation such as `UUID: <uuid>` so the exact task can be recovered even if IDs are renumbered.
 - 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
-task add project:<name> +<tag> +agent "Description"
+ask add +<tag> "Description"
 ```
 
 Then add the agent-awareness annotation (use the ID from the add output):
 
 ```bash
-task <id> annotate "Agent: be aware of taskwarrior-task-management skill. When working on this task, 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, automatically progress to the next task in the list."
+ask <id> annotate "Agent: be aware of taskwarrior-task-management skill. When working on this task, 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, automatically progress to the next task in the list."
 ```
 
 Also add an annotation that records the task’s UUID, for example:
 
 ```bash
-task <id> annotate "UUID: $(task <id> _uuid)"
+ask <id> annotate "UUID: $(ask <id> _uuid)"
 ```
 
 ## With dependency
 
 ```bash
-task add project:<name> +<tag> +agent "Description" depends:<id>
+ask add +<tag> "Description" depends:<id>
 ```
 
 Multiple dependencies: `depends:<id1>,<id2>`.
 
-After adding (with or without dependency), run the same annotation: `task <id> annotate "Agent: be aware of taskwarrior-task-management skill. When working on this task, 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, automatically progress to the next task in the list."`
+After adding (with or without dependency), run the same annotation: `ask <id> annotate "Agent: be aware of taskwarrior-task-management skill. When working on this task, 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, automatically progress to the next task in the list."`
 
 ## Conventions
 
diff --git a/prompts/skills/taskwarrior-task-management/references/2-start-task.md b/prompts/skills/taskwarrior-task-management/references/2-start-task.md
index 6b44811..90a8986 100644
--- a/prompts/skills/taskwarrior-task-management/references/2-start-task.md
+++ b/prompts/skills/taskwarrior-task-management/references/2-start-task.md
@@ -11,7 +11,7 @@ Work on each new task **must begin with a fresh context** — e.g. a new session
 When you begin working on a task, **always mark it as started in Taskwarrior** so current work is visible:
 
 ```bash
-task uuid:<uuid> start
+ask uuid:<uuid> start
 ```
 
 Do this as soon as you start work on the task.
@@ -19,6 +19,6 @@ 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 `task uuid:<uuid> start` when you start working on the task, not only when listing or completing.
+- Run `ask uuid:<uuid> start` 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 (for example, `uuid:<uuid>`) for subsequent `start` operations, not a freshly-looked-up numeric ID from a new report.
diff --git a/prompts/skills/taskwarrior-task-management/references/3-complete-task.md b/prompts/skills/taskwarrior-task-management/references/3-complete-task.md
index 6f05093..911ac62 100644
--- a/prompts/skills/taskwarrior-task-management/references/3-complete-task.md
+++ b/prompts/skills/taskwarrior-task-management/references/3-complete-task.md
@@ -45,19 +45,19 @@ If the answer suggests improvements or inconsistencies, address them first. Only
 6. Only then:
 
 ```bash
-task uuid:<uuid> done
+ask uuid:<uuid> done
 ```
 
 Use the UUID that identifies the task (for example, 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. `task project:<name> +agent 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.
+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 `task <id> done`; do not leave uncommitted work when marking a task complete.
-- Complete with `task <id> done` 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.
+- **On completion, commit all changes to git** before running `ask <id> done`; do not leave uncommitted work when marking a task complete.
+- Complete with `ask <id> done` 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 in `project:<name> +agent`; do not stop unless no next task is available or the user asks to stop.
+- **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 list`; do not stop unless no next task is available or the user asks to stop.
diff --git a/prompts/skills/taskwarrior-task-management/references/4-annotate-update-task.md b/prompts/skills/taskwarrior-task-management/references/4-annotate-update-task.md
index 067af8b..19da7d5 100644
--- a/prompts/skills/taskwarrior-task-management/references/4-annotate-update-task.md
+++ b/prompts/skills/taskwarrior-task-management/references/4-annotate-update-task.md
@@ -9,13 +9,13 @@ When working on a task, **always read the full context:** description, summary,
 View full task (including annotations):
 
 ```bash
-task <id>
+ask <id>
 ```
 
 ## Annotate a task
 
 ```bash
-task uuid:<uuid> annotate "Note about progress or context"
+ask uuid:<uuid> annotate "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.
@@ -25,9 +25,9 @@ Whenever you mention another task inside an annotation (for example, as a depend
 ## Modify a task
 
 ```bash
-task <id> modify +<tag>
-task <id> modify depends:<id2>
-task <id> modify priority:H
+ask <id> modify +<tag>
+ask <id> modify depends:<id2>
+ask <id> modify priority:H
 ```
 
 Use `uuid:<uuid>` in place of `<id>` 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.
@@ -35,7 +35,7 @@ Use `uuid:<uuid>` in place of `<id>` when modifying tasks selected earlier or re
 ## Delete a task
 
 ```bash
-task <id> delete
+ask <id> delete
 ```
 
 ## Conventions
diff --git a/prompts/skills/taskwarrior-task-management/references/5-review-overview-tasks.md b/prompts/skills/taskwarrior-task-management/references/5-review-overview-tasks.md
index dbf09dc..e7bf1b7 100644
--- a/prompts/skills/taskwarrior-task-management/references/5-review-overview-tasks.md
+++ b/prompts/skills/taskwarrior-task-management/references/5-review-overview-tasks.md
@@ -7,13 +7,13 @@ Use with `00-context.md`. Project name and global rules apply.
 Only list tasks that have `+agent` (project + tag matching). When listing, order by **priority first, then urgency**:
 
 ```bash
-task project:<name> +agent list sort:priority-,urgency-
+ask list sort:priority-,urgency-
 ```
 
 By tag (keep `+agent`, same order):
 
 ```bash
-task project:<name> +agent +<tag> list sort:priority-,urgency-
+ask +<tag> list sort:priority-,urgency-
 ```
 
 ## Picking what to work on (next task)
@@ -23,14 +23,14 @@ task project:<name> +agent +<tag> list sort:priority-,urgency-
 **Check already-started tasks first.** Before suggesting or starting a new task:
 
 ```bash
-task project:<name> +agent start.any: list sort:priority-,urgency-
+ask start.any: list 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
-task project:<name> +agent +READY list sort:priority-,urgency- limit:1
+ask +READY list sort:priority-,urgency- limit:1
 ```
 
 (Or use `next limit:1` with a report that sorts priority first, then urgency, if your Taskwarrior config supports it.)
@@ -38,19 +38,19 @@ task project:<name> +agent +READY list sort:priority-,urgency- limit:1
 Once you have chosen a task from one of these lists, **immediately resolve its UUID** and use that for all subsequent operations and handoffs:
 
 ```bash
-task <id> _uuid
+ask <id> _uuid
 # or, for a filtered selection:
-task project:<name> +agent +READY limit:1 uuids
+ask +READY limit:1 uuids
 ```
 
-When returning or recording the chosen task for another agent or a later step, **include its UUID**, and in follow-up commands prefer a UUID selector (for example, `task uuid:<uuid> ...`) instead of relying on the numeric ID from a previous report.
+When returning or recording the chosen task for another agent or a later step, **include its UUID**, and in follow-up commands prefer a UUID selector (for example, `ask uuid:<uuid> ...`) instead of relying on the numeric ID from a previous report.
 
 ## View task details
 
 ```bash
-task <id>
+ask <id>
 # or, when you already have the UUID:
-task uuid:<uuid>
+ask uuid:<uuid>
 ```
 
 Only work with task IDs that came from the filtered lists above (project + `+agent`). Always read description, summary, and **all annotations** when working on or reviewing a task.
@@ -60,14 +60,14 @@ Only work with task IDs that came from the filtered lists above (project + `+age
 Dependency tree (export, agent tasks only):
 
 ```bash
-task project:<name> +agent export
+ask export
 ```
 
 Blocked vs ready (with `+agent`):
 
 ```bash
-task project:<name> +agent +BLOCKED list
-task project:<name> +agent +READY list
+ask +BLOCKED list
+ask +READY list
 ```
 
 ## Conventions