Prompt templates

The prompt passed via -Prompt is what the coding agent sees on every iteration. It is the single biggest lever on overnight quality. Fill the placeholders; do not send a bare one-liner.

Worker prompt (new run)

Objective: <one concrete outcome>.

Work in this repository. Treat this as a long-running unattended task — nobody is watching, so
never wait for confirmation and never leave the tree in a broken state between commits.

Before changing anything, read the relevant code, docs, and recent commits to understand current
behavior. Preserve existing user work. Do not refactor anything outside <scope>.

Non-goals: <what must not change — files, APIs, behavior, dependencies>.

After each meaningful slice, run: <verification command>. If it fails, fix it before moving on.

If you hit a genuine blocker, stop and write the blocker plus the evidence into your notes. Never
fabricate success, never disable or skip a test to make something pass, and never commit a change
you have not verified.

Stop only when: <observable completion condition>.

Writing the scope and non-goals

Vague scope is the main cause of a morning spent reading an unwanted refactor. Be concrete:

Good scope: "only files under src/utils/"
Good non-goal: "do not change any public export signature; do not add dependencies"
Bad: "don't break anything"

Writing the stop condition

It must be checkable by looking at the repo, not by asking an opinion.

Bad	Good
the code is cleaner	`npm test` exits 0 and no file outside `src/utils/` is modified
tests look fine	the full suite passes with zero skipped tests
done with the refactor	`npm run typecheck` and `npm test` both exit 0, and `git diff --stat` shows no change to `package.json`

Steering prompt (continue after a partial success)

Continue from the current repository state. A previous run partially succeeded: <specific evidence
— commits, files, what now works>.

Do not redo that completed work and do not revisit <areas already settled>.

Focus only on: <single bounded correction>.

The specific problem to fix is: <observed issue, with file and line where known>.

Verify with: <commands or checks>.

Stop only when: <observable condition for this correction alone>.

Findings prompt (user rejected the result)

One finding per run. Bundling corrections is how scope drift restarts.

Continue from the current repository state on this branch.

A review found this blocking issue: <finding, in the user's own words, with severity and file/line
scope preserved>.

Keep all other completed work intact — do not revert or rewrite anything unrelated to this finding.

Fix only that issue. Verify with: <commands>.

Stop only when: <the finding is demonstrably no longer true>.

Research-first prompt (exploratory work)

Use when the objective is not yet well understood. Forces investigation before edits.

Objective: <outcome>.

First deliverable, before any code change: investigate <question> and write your findings into your
notes — what you examined, what you concluded, and which approach you chose with the reason.

Only after recording that, implement the chosen approach in <scope>.

Verify with: <command>. Non-goals: <...>.

Stop only when: <observable condition>.

Anti-patterns

No verification command. The agent grades its own homework and always passes.
Unbounded scope. "Improve the codebase" produces a diff nobody wants to review.
Opinion stop conditions. The run either never stops or stops arbitrarily.
Multiple objectives in one prompt. Split them into separate runs, or use -Worktree.
Omitting non-goals. Agents reformat, upgrade dependencies, and rename things when unconstrained.

3.7 KiB Raw Blame History