fix annotate short UUID usage, clarify dependency and annotation rules

7 files changed, 20 insertions, 37 deletions

diff --git a/prompts/skills/agent-task-management/SKILL.md b/prompts/skills/agent-task-management/SKILL.md
index c69dc8e..2a426ef 100644
--- a/prompts/skills/agent-task-management/SKILL.md
+++ b/prompts/skills/agent-task-management/SKILL.md
@@ -16,9 +16,11 @@ Valid examples:
 - `ask add +cli "Add feature X"`
 - `ask info uuid:<uuid>`
 - `ask start uuid:<uuid>`
-- `ask annotate uuid:<uuid> "progress note"`
+- `ask annotate <short-uuid> "progress note"`
 - `ask done uuid:<uuid>`
 
+**UUID selector quirk:** `ask annotate` requires the **short 8-character UUID** (first segment only, no `uuid:` prefix), e.g. `ask annotate 530ac084 "note"`. Using `uuid:<full-uuid>` with `ask annotate` fails. All other subcommands (`info`, `start`, `done`, `dep`, etc.) accept `uuid:<full-uuid>` normally.
+
 Invalid examples:
 
 - `ask agent-task-management ...`
diff --git a/prompts/skills/agent-task-management/references/00-context.md b/prompts/skills/agent-task-management/references/00-context.md
index 1acf7b9..18a1fa0 100644
--- a/prompts/skills/agent-task-management/references/00-context.md
+++ b/prompts/skills/agent-task-management/references/00-context.md
@@ -4,21 +4,8 @@ Load this with any of the action files (1–5) when working with tasks. It defin
 
 ## 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
+- **Parallel work via sub-agents** — the agent may spawn sub-agents to work on tasks in parallel if those tasks would not conflict each other.
diff --git a/prompts/skills/agent-task-management/references/1-create-task.md b/prompts/skills/agent-task-management/references/1-create-task.md
index d204a21..10b93aa 100644
--- a/prompts/skills/agent-task-management/references/1-create-task.md
+++ b/prompts/skills/agent-task-management/references/1-create-task.md
@@ -4,19 +4,17 @@ Use with `00-context.md`. Project name and global rules apply. New tasks get `+a
 
 ## 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.
+- **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. 
 - **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:
+- **After creating a task, add annotation** — one with the agent workflow reminder:
+  **Important:** `ask annotate` requires the short 8-character UUID (first segment, no `uuid:` prefix). Using `uuid:<full-uuid>` fails for `annotate`.
   ```
-  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>"
+  ask annotate <short-uuid> "Agent workflow: load the agent-task-management skill as instructions only, not as a shell command. 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. When all tests and sub-agent reviews pass, commit and automatically progress to the next ready task."
   ```
+
 - **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.
+- When tasks refer to other tasks in free text (annotations, descriptions, docs, or commit messages).
 
 ## Add a task
 
@@ -26,14 +24,10 @@ Use with `00-context.md`. Project name and global rules apply. New tasks get `+a
 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."
-```
+Then add the workflow annotation and UUID annotation. The UUID returned by `ask add` is the full UUID; use only its **first 8 characters** (short UUID) for `ask annotate`:
 
 ```bash
-ask annotate uuid:<uuid> "UUID: <uuid>"
+ask annotate <short-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."
 ```
 
 ## With dependency
@@ -52,4 +46,4 @@ After adding (with or without dependency), run the same annotations using the UU
 - 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
+- When creating a task, add references to all required context (files, docs, specs) so the task is self-contained for fresh-context work.
diff --git a/prompts/skills/agent-task-management/references/2-start-task.md b/prompts/skills/agent-task-management/references/2-start-task.md
index df096b9..1ea248f 100644
--- a/prompts/skills/agent-task-management/references/2-start-task.md
+++ b/prompts/skills/agent-task-management/references/2-start-task.md
@@ -21,4 +21,4 @@ Do this as soon as you start work on the task.
 - 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
+- When a task is selected via the review/overview step, use the stored UUID from the task's annotations for subsequent `start` operations.
diff --git a/prompts/skills/agent-task-management/references/3-complete-task.md b/prompts/skills/agent-task-management/references/3-complete-task.md
index 531c6a4..cb1d3b1 100644
--- a/prompts/skills/agent-task-management/references/3-complete-task.md
+++ b/prompts/skills/agent-task-management/references/3-complete-task.md
@@ -1,6 +1,6 @@
 # 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.
+Use with `00-context.md`. Project name and global rules apply.
 
 ## Completion criteria (required before "done")
 
@@ -60,4 +60,4 @@ Use the UUID that identifies the task (from its annotations or from the selectio
 - **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
+- **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.
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
index 72c2392..81b1ec5 100644
--- a/prompts/skills/agent-task-management/references/4-annotate-update-task.md
+++ b/prompts/skills/agent-task-management/references/4-annotate-update-task.md
@@ -1,6 +1,6 @@
 # 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.
+Use with `00-context.md`. Project name and global rules apply.
 
 ## Reading task context
 
@@ -20,7 +20,7 @@ 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.
+Whenever you mention another task inside an annotation (for example, as a dependency or related work), include that other task's **UUID**.
 
 ## Modify a task
 
@@ -42,4 +42,4 @@ ask delete uuid:<uuid>
 
 - 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
+- Annotations should be detailed enough that a fresh-context agent can pick up work without needing to ask clarifying questions.
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
index d5a281d..509952e 100644
--- a/prompts/skills/agent-task-management/references/5-review-overview-tasks.md
+++ b/prompts/skills/agent-task-management/references/5-review-overview-tasks.md
@@ -41,7 +41,7 @@ Once you have chosen a task from one of these lists, **use its UUID** from the l
 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.
+Always read description, summary, and **all annotations** when working on or reviewing a task.
 
 ## Visualization