Implement Task

Implementing a task

Ten steps. Every task passes all of them, and most collapse to a sentence on a small change — Verify and Diff review never collapse. They are internal structure rather than a script to recite: name a step in prose where you need to ("the Verify step"), never a bare number, and don't narrate the walk through them at whoever asked.

Plans live under .agents/plans.local/ (gitignored) or .agents/plans/ (shared), each with a .ledger.md beside it. A branch you did not create may carry some, and the ledger is the only record of where that work stopped — so read them at Intake rather than re-deriving the task.

Unattended when you cannot get an answer before the next step — no user in the loop, empty stdin, or CI/GITHUB_ACTIONS set. Where a step below would have you ask, the unattended answer is given alongside it; where none is given, stop and report rather than guess. A stopped task is a useful result; a wrong base or an invented issue number is not.

Skip only what this table names; an unstated skip is still an oversight.

The hand-back is what you say when the work is done, and it is the same four things whether the reader is a terminal or a pull request body: what changed, and why where the diff doesn't say so; checks, which ran, what they said, which were skipped and what was missing; assumptions, every point where you decided something the request left open; and left out, anything in scope you did not do. An empty "left out" is a claim about the work rather than a formality — make sure it is true.

Issue number

A task has an issue number, and Intake is where you get it. Attended, ask for it whenever the request arrives without one, and ask before the branch exists — the branch name embeds the number, and renaming a branch that already carries commits is worse than a question.

If the answer is that no issue exists, say that the task needs one and offer to file it (the file-issue skill): the state/* labels, the branch, the pull request and the verification that follows all key off the number, so work without one is invisible to everyone not in the room. Only once the person declines does the change proceed unnumbered, on a feature/ or fix/ branch, and the hand-back records that as an assumption.

Unattended, the trigger names the number or states that there is none. Neither: stop and report.

Never invent a number, and never reach for a plain descriptive subject to sidestep the question — a number belonging to an unrelated issue silently attaches your change to someone else's work.

Workspace

A task gets its own branch. What varies is whether you ask first.

The base is an exact ref name, or the current HEAD. A version like "0.16", a release line or a description is not one — ask, or stop and report where you cannot. Never fall back to develop: it is the base only when it is what is checked out.

CONTRIBUTIONS.md → "Branch naming" owns the name. The rule to get right is that the area is a _<area> suffix and never a second path segment: issue_4538/tags/<area> makes issue_4538/tags permanently unusable. Given a name, use it exactly.

Where that branch already exists and it is this task's branch, it is the branch — a re-run continues on it rather than inventing a -2. Where you cannot tell whose branch an existing one is, treat it as someone else's and pick another name.

Once the branch exists, add state/underway to the issue if it doesn't carry it already.

Worktree

A new branch is what gets a worktree. Attended, ask whether to work in one, together with the branch question rather than as a second round; staying in this checkout is a legitimate answer, not the default you assume. Unattended, always use one.

Its path is .worktrees/<branch>, which is gitignored. A vendor's own worktree action picks its own location and names the branch itself, so use it only if it can be pointed at that path — the name is CONTRIBUTIONS.md's to decide.

Copy or link the gitignored working state a check needs — installed dependencies, build caches, .agents/localenv/, local environment files — from the main checkout instead of reinstalling it. Copy an environment file without opening it: those are among the files agents must not read.

Remove the worktree once the branch has been handed back.