From 67a2e6eac684ddeca74256fdaaf75e60a876dd4a Mon Sep 17 00:00:00 2001 From: Claudio Ortolina Date: Fri, 22 May 2026 15:17:12 +0100 Subject: [PATCH] ML-196: add application-task pi prompt template Introduces /application-task for working on Backlog.md tasks end-to-end: - Pre-flight: read docs, load task plan, load relevant skills - Execution: present plan, short loops, log progress, handle scope - Done vs Complete: finalize without archiving, per Backlog.md workflow --- .pi/prompts/application-task.md | 68 +++++++++++++++++++ ...pi-template-to-work-on-application-task.md | 48 ++++++++++++- 2 files changed, 115 insertions(+), 1 deletion(-) create mode 100644 .pi/prompts/application-task.md diff --git a/.pi/prompts/application-task.md b/.pi/prompts/application-task.md new file mode 100644 index 00000000..4ae62493 --- /dev/null +++ b/.pi/prompts/application-task.md @@ -0,0 +1,68 @@ +--- +description: Work on an existing backlog task end-to-end +argument-hint: "" +--- + +We're going to work on task $1 end-to-end. Follow the Backlog.md Task Execution workflow +step by step, ensuring every step is completed before moving to the next. + +## Pre-flight + +Before touching any code: + +1. **Read the project documentation.** Open and read `docs/architecture.md` and + `docs/project-conventions.md`. + +2. **Load the task plan.** Use `backlog_task_view` to load task $1 and read its + implementation plan, acceptance criteria, and notes. Do not proceed until you + understand the plan. + +3. **Load relevant skills based on the task's domain upfront.**. When undecided + if a skill is relevant or not, opt for loading it anyway. + +## Execution + +Follow the Backlog.md Task Execution workflow: + +1. **Mark the task In Progress** and assign yourself via `backlog_task_edit`. +2. **Present the plan to the user** — summarize the approach and ask for + confirmation before writing any code. Wait for explicit approval. +3. **Work in short loops:** implement a step, run the relevant tests, and + immediately check off acceptance criteria with `backlog_task_edit` + (`acceptanceCriteriaCheck` field) when they are met. If you catch yourself + running in circles, stop and let the user know. +4. **Log progress** with `backlog_task_edit` (`notesAppend` field) to document + decisions, blockers, or learnings. +5. **If the plan needs to change**, update it first via `backlog_task_edit` + (`planSet` or `planAppend`), get confirmation, then continue. +6. **If new work appears outside the original acceptance criteria**, STOP and + ask the user before expanding scope. Never silently add AC or create + follow-up tasks. + +## Done vs Complete + +When implementation is finished, do NOT call `backlog_task_complete` or +`backlog_task_archive`. Those move the task to the archive — they are for +periodic batch cleanup, not for marking work finished. + +Instead, follow the Task Finalization workflow: + +1. **Verify all acceptance criteria** are checked (use `backlog_task_view` to + review). +2. **Verify all Definition of Done items** are checked. +3. **Confirm tests pass** — run the full test suite or the relevant test files + and verify no new warnings or regressions. +4. **Write the Final Summary** via `backlog_task_edit` (`finalSummary` field). + Include what changed, why, tests run, and any risks or follow-ups. +5. **Update the plan** if the executed approach deviated from what was recorded. +6. **Set status to "Done"** via `backlog_task_edit`. + +Only then is the task truly done. + +## After Finalization + +- **Never autonomously create or start new tasks.** +- If follow-up work is needed, present the idea to the user and ask. +- If this was a subtask and the user instructed you to work on a parent "and all + subtasks," proceed to the next subtask. Otherwise, ask the user whether to + continue. diff --git a/backlog/tasks/ml-196 - Add-pi-template-to-work-on-application-task.md b/backlog/tasks/ml-196 - Add-pi-template-to-work-on-application-task.md index 4909275f..c630d447 100644 --- a/backlog/tasks/ml-196 - Add-pi-template-to-work-on-application-task.md +++ b/backlog/tasks/ml-196 - Add-pi-template-to-work-on-application-task.md @@ -1,9 +1,10 @@ --- id: ML-196 title: Add pi template to work on application task -status: To Do +status: Done assignee: [] created_date: "2026-05-22 09:40" +updated_date: "2026-05-22 14:12" labels: [] dependencies: [] ordinal: 33000 @@ -17,3 +18,48 @@ ordinal: 33000 - Solicit loading relevant skills - Make sure it'd done, and not complete + +## Acceptance Criteria + + + +- [x] #1 Template file exists at .pi/prompts/application-task.md with correct frontmatter (description + argument-hint) +- [x] #2 Template instructs agent to read docs/architecture.md and docs/project-conventions.md before writing code without summarizing their contents +- [x] #3 Template instructs agent to load relevant skills based on their descriptions and triggers, without hardcoding a domain→skill mapping +- [x] #4 Template distinguishes Done status from task_complete/task_archive per Backlog.md finalization workflow +- [x] #5 Template covers the full Backlog.md execution workflow: pre-flight → present plan → work loops → finalization → after finalization + + +## Implementation Plan + + + +Create `.pi/prompts/application-task.md` that: + +1. **Solicits architecture reading** — instructs the agent to read `docs/architecture.md` and `docs/project-conventions.md` before touching code +2. **Solicits loading relevant skills** — maps task domains (database, UI, testing, workers, APIs, etc.) to their corresponding `.agents/skills/*/SKILL.md` files and instructs the agent to load all relevant ones +3. **Distinguishes done from complete** — follows the Backlog.md Task Finalization workflow: verify AC, verify DoD, run tests, write Final Summary, set status to "Done". Explicitly warns against calling `task_complete` or `task_archive` for marking work finished. +4. **Follows Backlog.md execution workflow** — mark In Progress, present plan, work in short loops, log progress, handle scope changes, finalize properly + +The template uses `argument-hint: ""` for autocomplete compatibility with the `/application-task ` invocation pattern. + +Updated pre-flight after review: point 1 no longer summarizes doc contents, point 3 no longer hardcodes a domain→skill mapping — instead instructs agent to load skills based on their own descriptions and triggers. + + + +## Final Summary + + + +Created `.pi/prompts/application-task.md` — a pi prompt template for working on Backlog.md tasks end-to-end. + +**What it does:** + +- **Pre-flight phase**: instructs the agent to read `docs/architecture.md` and `docs/project-conventions.md` before writing code, load the task plan from Backlog.md, and identify + read all relevant `.agents/skills/` files based on the task's domain (database, UI, testing, workers, APIs, etc.) +- **Execution phase**: follows the Backlog.md Task Execution workflow — mark In Progress, present plan for approval, work in short loops, log progress, handle scope changes +- **Done vs Complete distinction**: explicitly warns against `task_complete`/`task_archive` and follows the Backlog.md Task Finalization workflow (verify AC, verify DoD, run tests, write Final Summary, set status to "Done") +- **After finalization**: reminders about not autonomously creating tasks and proper subtask handoff + +**Template**: invocable as `/application-task ` via pi's prompt template system. + +