prompts: use ask ids in task workflows

8 files changed, 49 insertions, 48 deletions

diff --git a/prompts/commands/work-on-tasks.md b/prompts/commands/work-on-tasks.md
index 5fd2423..770e5ad 100644
--- a/prompts/commands/work-on-tasks.md
+++ b/prompts/commands/work-on-tasks.md
@@ -33,25 +33,25 @@ You are the **orchestrator**. You pick tasks, mark them started, launch a sub-ag
 2. **Pick the next task** (default strategy: `{{strategy|highest-impact}}`):
    - Choose one actionable task based on impact, urgency, and clarity
    - If two tasks are equivalent, prefer the one that unblocks other work
-   - Run `ask info uuid:<uuid> 2>&1 | head -20` to preview the task — this caps the output at 20 lines so long descriptions do not flood the screen
+   - Run `ask info <id> 2>&1 | head -20` to preview the task — this caps the output at 20 lines so long descriptions do not flood the screen
 
 3. **Mark the task started**:
-   - Run `ask start uuid:<uuid>`
+   - Run `ask start <id>`
 
 4. **Delegate to a fresh sub-agent**:
    - Spawn a **new sub-agent** with a self-contained prompt that includes:
-     - The task UUID and a one-line summary of what the task is about
-     - Instruction to run `ask info uuid:<uuid>` as its **first action** to get the full description and all annotations (do not paste the description inline — the sub-agent fetches it fresh, keeping the prompt short)
+     - The task ID and a one-line summary of what the task is about
+     - Instruction to run `ask info <id>` as its **first action** to get the full description and all annotations (do not paste the description inline — the sub-agent fetches it fresh, keeping the prompt short)
      - The absolute path of the project root
-     - Instruction to run `ask annotate uuid:<uuid> "<progress notes>"` as it works
+     - Instruction to run `ask annotate <id> "<progress notes>"` as it works
      - Instruction to commit all changes to git when done
      - Instruction to **not** mark the task done (the orchestrator does that)
    - The sub-agent must complete all implementation, tests, and a git commit before returning
    - Wait for the sub-agent to finish
 
 5. **Close and record**:
-   - Run `ask done uuid:<uuid>` to mark the task complete
-   - Run `ask annotate uuid:<uuid> "<summary of what was delivered>"` if the sub-agent did not already add a final annotation
+   - Run `ask done <id>` to mark the task complete
+   - Run `ask annotate <id> "<summary of what was delivered>"` if the sub-agent did not already add a final annotation
 
 6. **Auto-progress**:
    - Immediately return to step 1 and select the next pending task
@@ -61,7 +61,7 @@ You are the **orchestrator**. You pick tasks, mark them started, launch a sub-ag
      - the sub-agent reports a hard blocker (surface it to the user, then stop)
 
 7. **Final report**:
-   - List completed task UUIDs/titles
+   - List completed task IDs/titles
    - List any skipped/blocked tasks with reasons
    - State what remains pending for the project
 
diff --git a/prompts/skills/agent-task-management/SKILL.md b/prompts/skills/agent-task-management/SKILL.md
index 4035c67..b20105c 100644
--- a/prompts/skills/agent-task-management/SKILL.md
+++ b/prompts/skills/agent-task-management/SKILL.md
@@ -7,17 +7,18 @@ description: "Manage agent tasks scoped to the current git project using the `as
 
 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.
+The `ask` CLI provides subcommands (`list`, `ready`, `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>`
+- `ask add +cli "Add feature X"`  # prints `created task <alias-id>`
+- `ask add +cli depends:0,1 "Add feature X"`
+- `ask info <id>`
+- `ask start <id>`
+- `ask annotate <id> "progress note"`
+- `ask done <id>`
 
 Invalid examples:
 
@@ -26,7 +27,7 @@ Invalid examples:
 - `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.
+**Alias IDs are the selectors to use for task work.** `ask add` prints `created task <alias-id>`, and subsequent task commands in this workflow should keep using that alias ID throughout the workflow.
 
 ## Context and compaction
 
@@ -54,4 +55,4 @@ Always load `references/00-context.md` first (project name resolution and global
 
 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
+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`.
diff --git a/prompts/skills/agent-task-management/references/00-context.md b/prompts/skills/agent-task-management/references/00-context.md
index 18a1fa0..b4c16e2 100644
--- a/prompts/skills/agent-task-management/references/00-context.md
+++ b/prompts/skills/agent-task-management/references/00-context.md
@@ -6,6 +6,6 @@ Load this with any of the action files (1–5) when working with tasks. It defin
 
 ## 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.
+- **Always use `ask <subcommand>` for all task operations.** The `ask` CLI provides subcommands (`list`, `ready`, `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.
 - **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 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 b9ec5e7..2c4a414 100644
--- a/prompts/skills/agent-task-management/references/1-create-task.md
+++ b/prompts/skills/agent-task-management/references/1-create-task.md
@@ -1,15 +1,15 @@
 # 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).
+Use with `00-context.md`. Project name and global rules apply. New tasks get `+agent` so they are agent-managed. When a new task depends on existing tasks, add those dependencies inline during creation with `depends:<id>,...`.
 
 ## 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. 
+- **When creating a new task, always check whether the new task depends on other (existing) tasks.** If it does, add those dependencies inline with `depends:<id>,...` while creating the task.
 - **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`).
 - **After creating a task, add annotation** — one with the agent workflow reminder:
   ```
-  ask annotate uuid:<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."
+  ask annotate <id> "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.
@@ -17,7 +17,7 @@ Use with `00-context.md`. Project name and global rules apply. New tasks get `+a
 
 ## Add a task
 
-`ask add` already injects `project:<name> +agent`, so only add the extra feature tag(s), optional priority, and description.
+`ask add` already injects `project:<name> +agent`, so only add the extra feature tag(s), optional priority, optional `depends:` modifier, and description.
 
 **Each part must be a separate shell argument — never quote tag and description together:**
 
@@ -25,6 +25,7 @@ Use with `00-context.md`. Project name and global rules apply. New tasks get `+a
 ask add +<tag> "Description"
 ask add priority:H +<tag> "Description"
 ask add priority:M +<tag> "Description"
+ask add +<tag> depends:<id1>,<id2> "Description"
 ```
 
 Do NOT do this (causes tag/priority to appear in the description instead of being applied):
@@ -33,34 +34,33 @@ ask add "+<tag> Description"           # wrong: tag and desc in one quoted strin
 ask add "+<tag> -p M Description"      # wrong: everything in one quoted arg
 ```
 
-Then add the workflow annotation using `uuid:<full-uuid>` as returned by `ask add`:
+`ask add` prints `created task <alias-id>`. Reuse that alias ID directly for follow-up commands:
 
 ```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."
+id=$(ask add +<tag> "Description" | sed -n 's/^created task //p')
+ask annotate "$id" "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
 
-Add the task first, then set the dependency separately:
+Add dependencies inline during task creation:
 
 ```bash
-uuid=$(ask add +<tag> "Description")
-ask dep add uuid:$uuid <dep-uuid>
+id=$(ask add +<tag> depends:<dep-id> "Description" | sed -n 's/^created task //p')
 ```
 
 Multiple dependencies:
 
 ```bash
-ask dep add uuid:$uuid <dep-uuid1>
-ask dep add uuid:$uuid <dep-uuid2>
+id=$(ask add +<tag> depends:<dep-id1>,<dep-id2> "Description" | sed -n 's/^created task //p')
 ```
 
-After adding (with or without dependency), run the same annotations using the UUID from `ask info uuid:<uuid>`.
+After adding (with or without dependency), run the same annotations using that alias ID directly.
 
 ## 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.
+- **Always check for dependencies:** before adding a task, determine if it depends on other tasks in the project; if so, add `depends:<id>,...` during `ask add`.
 - 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.
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 2a7f862..78af213 100644
--- a/prompts/skills/agent-task-management/references/2-start-task.md
+++ b/prompts/skills/agent-task-management/references/2-start-task.md
@@ -23,7 +23,7 @@ ask ready | head
 When you begin working on a task, **always mark it as started** so current work is visible:
 
 ```bash
-ask start uuid:<uuid>
+ask start <id>
 ```
 
 Do this as soon as you start work on the task.
@@ -31,6 +31,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 `ask start uuid:<uuid>` when you start working on the task, not only when listing or completing.
+- Run `ask start <id>` 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.
+- When a task is selected via the review/overview step, use the alias ID from the list or task details 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 cb1d3b1..42aab17 100644
--- a/prompts/skills/agent-task-management/references/3-complete-task.md
+++ b/prompts/skills/agent-task-management/references/3-complete-task.md
@@ -45,10 +45,10 @@ If the answer suggests improvements or inconsistencies, address them first. Only
 6. Only then:
 
 ```bash
-ask done uuid:<uuid>
+ask done <id>
 ```
 
-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.
+Use the alias ID from the selection step or current task details when marking the task complete.
 
 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.
 
@@ -57,7 +57,7 @@ Use the UUID that identifies the task (from its annotations or from the selectio
 - 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.
+- **On completion, commit all changes to git** before running `ask done <id>`; do not leave uncommitted work when marking a task complete.
+- Complete with `ask done <id>` 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.
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 81b1ec5..d7cb651 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
@@ -9,33 +9,33 @@ When working on a task, **always read the full context:** description, summary,
 View full task (including annotations):
 
 ```bash
-ask info uuid:<uuid>
+ask info <id>
 ```
 
 ## Annotate a task
 
 ```bash
-ask annotate uuid:<uuid> "Note about progress or context"
+ask annotate <id> "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**.
+Whenever you mention another task inside an annotation (for example, as a dependency or related work), include that other task's alias ID.
 
 ## Modify a task
 
 ```bash
-ask modify uuid:<uuid> +<tag>
-ask modify uuid:<uuid> dep:add:<uuid2>
-ask modify uuid:<uuid> priority:H
+ask modify <id> +<tag>
+ask dep add <id> <dep-id>
+ask modify <id> 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.
+Use the alias ID shown by `ask list`, `ask ready`, or `ask info` when modifying tasks selected earlier or referenced from annotations or other docs.
 
 ## Delete a task
 
 ```bash
-ask delete uuid:<uuid>
+ask delete <id>
 ```
 
 ## Conventions
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 509952e..324c640 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
@@ -33,12 +33,12 @@ ask list start.any: sort:priority-,urgency-
 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**.
+Once you have chosen a task from one of these lists, **use its alias ID** 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 alias ID**.
 
 ## View task details
 
 ```bash
-ask info uuid:<uuid>
+ask info <id>
 ```
 
 Always read description, summary, and **all annotations** when working on or reviewing a task.
@@ -62,4 +62,4 @@ ask ready
 
 - 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.
+- When returning a chosen task to the user or another agent, include its alias ID and description.