diff options
| -rw-r--r-- | prompts/skills/agent-task-management/SKILL.md | 2 | ||||
| -rw-r--r-- | prompts/skills/agent-task-management/references/2-start-task.md | 33 |
2 files changed, 34 insertions, 1 deletions
diff --git a/prompts/skills/agent-task-management/SKILL.md b/prompts/skills/agent-task-management/SKILL.md index e952433..dc851b7 100644 --- a/prompts/skills/agent-task-management/SKILL.md +++ b/prompts/skills/agent-task-management/SKILL.md @@ -56,7 +56,7 @@ When beginning a new task, **always use a fresh context** — spawn a sub-agent | Action | Load | |--------|------| | **Create task** | `references/00-context.md` + `references/1-create-task.md` (include refs to all context required) | -| **Start task** | `references/00-context.md` + `references/2-start-task.md` (start with fresh context; use task refs) | +| **Start task** | `references/00-context.md` + `references/2-start-task.md` (start with fresh context; use task refs; **stay within task scope** — never patch vendored/upstream deps, flag as a blocker) | | **Recover a stalled/interrupted task** | `references/00-context.md` + `references/6-recover-stalled-task.md` (detect partial edits, revert cleanly, resume) | | **Complete task** | `references/00-context.md` + `references/3-complete-task.md` | | **Annotate / update task** | `references/00-context.md` + `references/4-annotate-update-task.md` | 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 8f16c39..3429d3d 100644 --- a/prompts/skills/agent-task-management/references/2-start-task.md +++ b/prompts/skills/agent-task-management/references/2-start-task.md @@ -12,6 +12,38 @@ Work on each new task **must begin with a fresh context** — a new sub-agent wi The task itself should already contain references to all required context (added when the task was created); read the task description and all annotations to get files, docs, and specs before starting. +## Stay within task scope + +A task gives you a **scope boundary**. Only touch the code the task asked you to +change. Do **not** edit out-of-scope code: + +- **Vendored / third-party dependencies** — `vendor/`, `node_modules/`, anything + pulled from upstream and committed under the project. These are not yours to patch. +- **Generated files** — generated bindings, protobuf/`*.pb.go`, mocks, build + artifacts. Fix the generator or its input, never the generated output by hand. +- **Upstream code the task did not name** — modules, libraries, or subsystems + outside what the task description and annotations call for. + +**If completing the task appears to require changing a vendored or upstream +dependency, STOP — treat it as a blocker, do not patch the dependency.** Patching +a vendored dep (e.g. editing `libbpfgo` under `vendor/`) gets reverted and wastes +the work. Instead: + +1. Record the blocker with an annotation explaining what the task needs and which + out-of-scope dependency stands in the way (see `4-annotate-update-task.md`): + + ```bash + ask annotate <id> "Blocked: completing this needs a change to vendored <dep>; that is out of scope. Flagging instead of patching." + ``` + +2. **Report it back** (to the orchestrator or user) as a blocker so the dependency + change can be scoped as its own task or decided upstream. + +This is about *not making* the out-of-scope edit in the first place. It is +distinct from — but complements — leaving unrelated dirty files uncommitted at +completion (see "Commit only in-scope files" in `3-complete-task.md`) and +reverting a stalled worker's broken edits (see `6-recover-stalled-task.md`). + ## Finding a task ```bash @@ -38,6 +70,7 @@ Before resuming, check for and clean up that situation: see ## Conventions - Start each new task with a fresh context; rely on the task's description and annotations for all required context. +- **Stay within task scope.** Never edit vendored/third-party deps (`vendor/`, `node_modules/`), generated files, or upstream code the task did not name. If the task seems to require a vendored/upstream change, flag it as a blocker (annotate + report) instead of patching the dep — see "Stay within task scope". - When picking up an already-started task, check for a stalled-worker situation (dirty worktree, broken build) before assuming a clean state — see `6-recover-stalled-task.md`. - 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. |