update prompts

7 files changed, 49 insertions, 14 deletions

diff --git a/prompts/skills/project-taskwarrior/00-context.md b/prompts/skills/project-taskwarrior/00-context.md
index 5c2c741..256dd13 100644
--- a/prompts/skills/project-taskwarrior/00-context.md
+++ b/prompts/skills/project-taskwarrior/00-context.md
@@ -19,3 +19,5 @@ Use it as `project:<name>` in every `task` command.
 - **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.
diff --git a/prompts/skills/project-taskwarrior/1-create-task.md b/prompts/skills/project-taskwarrior/1-create-task.md
index 3c39cb3..c2f318a 100644
--- a/prompts/skills/project-taskwarrior/1-create-task.md
+++ b/prompts/skills/project-taskwarrior/1-create-task.md
@@ -10,6 +10,8 @@ Use with `00-context.md`. Project name and global rules apply. New tasks get `+a
 - **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 project-taskwarrior skill. 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 project-taskwarrior skill and to 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.
+- 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
 
@@ -23,6 +25,12 @@ Then add the agent-awareness annotation (use the ID from the add output):
 task <id> annotate "Agent: be aware of project-taskwarrior skill. 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)"
+```
+
 ## With dependency
 
 ```bash
diff --git a/prompts/skills/project-taskwarrior/2-start-task.md b/prompts/skills/project-taskwarrior/2-start-task.md
index ec34f25..6b44811 100644
--- a/prompts/skills/project-taskwarrior/2-start-task.md
+++ b/prompts/skills/project-taskwarrior/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 <id> start
+task uuid:<uuid> start
 ```
 
 Do this as soon as you start work on the task.
@@ -19,5 +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 <id> start` when you start working on the task, not only when listing or completing.
+- Run `task 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/project-taskwarrior/3-complete-task.md b/prompts/skills/project-taskwarrior/3-complete-task.md
index c82e595..6f05093 100644
--- a/prompts/skills/project-taskwarrior/3-complete-task.md
+++ b/prompts/skills/project-taskwarrior/3-complete-task.md
@@ -16,7 +16,7 @@ If any of these fail, fix the issues and recheck. Do not mark the task complete
 
 ## What the review sub-agent must check
 
-Review sub-agents (first and second review) **must always**:
+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.
@@ -26,7 +26,7 @@ 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 the second), the main agent must **ask itself**:
+**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?
@@ -40,22 +40,24 @@ If the answer suggests improvements or inconsistencies, address them first. Only
 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. **Self-review again** (see above). Then **spawn another sub-agent** (fresh context again) to **review the code again** (including test coverage and test quality) and confirm the fixes. If this second review finds further issues, address them and repeat the sub-agent review until the review is satisfied.
+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
-task <id> done
+task 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.
 
 ## 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, all first-round review comments addressed (including coverage and test-quality checks), a second sub-agent review has confirmed the code, **and all changes are committed to git**.
+- 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, follow-up sub-agent review, and git commit are satisfied.
+- 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.
 - 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 sub-agent reviews 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 in `project:<name> +agent`; do not stop unless no next task is available or the user asks to stop.
diff --git a/prompts/skills/project-taskwarrior/4-annotate-update-task.md b/prompts/skills/project-taskwarrior/4-annotate-update-task.md
index ee45a4a..067af8b 100644
--- a/prompts/skills/project-taskwarrior/4-annotate-update-task.md
+++ b/prompts/skills/project-taskwarrior/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 task IDs from `project:<name> +agent` filtered lists, or verify the task has `+agent` before acting).
+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 prefer `uuid:<uuid>` selectors when running commands.
 
 ## Reading task context
 
@@ -15,11 +15,13 @@ task <id>
 ## Annotate a task
 
 ```bash
-task <id> annotate "Note about progress or context"
+task 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.
 
+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
@@ -28,6 +30,8 @@ task <id> modify depends:<id2>
 task <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.
+
 ## Delete a task
 
 ```bash
diff --git a/prompts/skills/project-taskwarrior/5-review-overview-tasks.md b/prompts/skills/project-taskwarrior/5-review-overview-tasks.md
index 51a5a54..dbf09dc 100644
--- a/prompts/skills/project-taskwarrior/5-review-overview-tasks.md
+++ b/prompts/skills/project-taskwarrior/5-review-overview-tasks.md
@@ -35,10 +35,22 @@ task project:<name> +agent +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.)
 
+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
+# or, for a filtered selection:
+task project:<name> +agent +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.
+
 ## View task details
 
 ```bash
 task <id>
+# or, when you already have the UUID:
+task 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.
diff --git a/prompts/skills/project-taskwarrior/SKILL.md b/prompts/skills/project-taskwarrior/SKILL.md
index c32e5a4..7c999b2 100644
--- a/prompts/skills/project-taskwarrior/SKILL.md
+++ b/prompts/skills/project-taskwarrior/SKILL.md
@@ -1,12 +1,18 @@
 ---
 name: project-taskwarrior
-description: "Manage Taskwarrior tasks scoped to the current git project. Use when asked to list, add, start, complete, annotate, or organize tasks for the project. 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."
+description: "Manage Taskwarrior tasks scoped to the current git project. 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."
 ---
 
 # Project Taskwarrior
 
 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.
 
+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
+
+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.
@@ -27,6 +33,6 @@ Always load `00-context.md` first (project name resolution and global rules); th
 
 ## 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. **Second sub-agent review** (fresh context again) to confirm fixes → 8. **Commit all changes to git** → 9. Complete task → 10. **Automatically progress to the next task in the list** (when all tests and sub-agent reviews pass).
+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, a second sub-agent review has confirmed the code, and all changes are committed to git. After completing a task, start the next task in the list (if any). Details are in `3-complete-task.md`.
+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 `3-complete-task.md`.