agent-goal

name	agent-goal
description	Write `/goal` prompts for long-running agent work in Codex or Claude Code. Use for slash goal, agent goal, durable objective, autonomous coding run.

Agent Goal

Write one /goal line that a coding agent can keep pursuing across turns until it can prove the work is done.

The best goal is both a directive and a completion condition:

/goal [do the work] until [observable condition is true].

Treat the goal as a contract. It should tell the agent what to do, what evidence proves it, and where to start.

The highest-signal goal answers three questions:

What should change?
How will the agent prove it changed?
Where should the agent start?

Core Shape

Use this structure unless the user needs a different format:

/goal Complete [single objective] in [lane]. First read [required context]. Work in checkpoints. After each checkpoint, surface evidence from [validation]. Continue until [verifiable end state].

Include only execution-critical details:

• Objective: one concrete outcome.
• Lane: files, package, app, branch, issue, spec, backlog label, or intended work area.
• Context: plans, docs, issue links, logs, screenshots, traces, commands, or acceptance criteria to inspect first.
• Evidence: command output, tests, build result, screenshot comparison, eval score, file count, clean git status, or reviewed artifact.
• Done condition: the exact state that means the goal is achieved.

Rules

1. Start the answer with /goal when the user asks for the goal text.
2. Name one main objective. If the request contains a backlog, make the goal "finish this named queue/spec" and define what empty or complete means.
3. Make "done" observable. Prefer "bun test packages/workspace exits 0" over "tests pass"; prefer "all checked items in PLAN.md are complete" over "finish the plan."
4. Tell the agent to surface evidence in the transcript. Goal evaluators judge what the worker has shown, not private intent.
5. Put long requirements in a plan or spec, then point the goal at that file. Do not paste a huge spec into /goal.
6. Ask for checkpoints when the work spans multiple turns. Each checkpoint should produce a small status note: changed, verified, remaining, questions.
7. Bound runaway work with evidence. For example: "after 3 failed attempts on the same test, report the root cause and the next product or ownership question."
8. Ordinary focus should not stop grounded fixes.
9. Do not use /goal for vague wishes, unrelated chores, open-ended research, or work where the agent cannot produce evidence.
10. Keep the condition judgeable from the transcript. If a separate verifier read only the conversation after each turn, it should be able to tell whether the goal is met.

Distilled Pattern

Think in this order:

Outcome
  What must be true?

Evidence
  What command, artifact, or visible behavior proves it?

Lane
  What is the intended work area?

Method
  What should the agent read first, and how should it checkpoint?

Start
  Where should the agent begin?

Then compress that into one goal.

Platform Notes

Codex:

• Write the goal as a durable objective attached to the active thread, with a verifiable stopping condition.
• Codex docs do not describe Claude's separate evaluator model. Do not assume Codex uses the same evaluation mechanism.

Claude Code:

• /goal sets a session-scoped completion condition.
• Claude uses a separate small model after each turn to decide whether the condition has been met.
• The evaluator does not run tools or read files independently.

Shared rule: the goal should not rely on hidden state. Tell the agent to run checks and surface evidence in the transcript.

Verifier Test

Before finalizing the goal, imagine a checker can see only the transcript, not the filesystem.

Good evidence:

`bun test packages/auth` exited 0.
All checklist items in `specs/auth.md` are checked.
The final screenshot shows the empty state and no overlap at 390px and 1440px.
`git diff --name-only` only lists files under `apps/api`.

Weak evidence:

The implementation looks complete.
The agent believes the migration is done.
Most tests should pass.
The UI seems better.

If the evidence is weak, rewrite the goal until completion can be judged from command output, visible artifact checks, or an explicit final status.

Templates

Plan execution:

/goal Implement `specs/[file].md` in checkpoints until every checklist item is complete, the review section is filled in, and `[final validation command]` exits 0. First read the spec and the files it names. After each checkpoint, update the checklist and surface the validation result. Continue unless the spec conflicts with current code or needs a product decision.

Failing tests:

/goal Fix the failing tests in `[lane]` until `[test command]` exits 0 and no unrelated speculative changes are present. First run the command and inspect the failures. Work from the owning boundary outward. After each fix, rerun the targeted test and report the result. Ask before deleting tests or weakening assertions.

Migration:

/goal Migrate `[old path or system]` to `[new path or system]` until all callers use the new path, parity checks pass, and `[final validation command]` exits 0. First read `[migration plan or docs]` and identify callers. Work in checkpoints with validation after each checkpoint. Ask before changing unrelated public APIs, or if compatibility, data migration, or rollback policy is ambiguous.

Prototype:

/goal Build a polished first version of `[app or feature]` inside `[lane]` until the primary flow works end to end, the app builds and runs, and `[visual or command validation]` confirms the expected behavior. First read `[plan or reference]`. Work in checkpoints and surface screenshots or command output as evidence. Ask if the data model or user flow is unclear.

Backlog or issue queue:

/goal Work through `[queue or label]` until every item is closed or has a documented reason it needs user input. First list the queue and choose the item with the clearest owner and validation path. For each item, make the correction at its owning boundary, run `[validation]`, and report the result before moving on. Stop when the queue is empty.

Eval or prompt loop:

/goal Improve `[prompt or system]` until `[eval command]` reaches `[target score]` or no further targeted improvement is justified. First run the eval and inspect failures. Make direct design corrections, rerun the eval after each change, and report score changes. Ask if improvement requires product or policy guidance.

Bad To Good

Weak:

/goal Make the app better and fix bugs.

Strong:

/goal Fix the checkout regressions tracked in `issues/checkout.md` until every listed reproduction passes, `bun test apps/storefront` exits 0, and the final status names any intentionally deferred issues. Work only in `apps/storefront` and shared checkout packages. Ask before changing payment provider contracts or deleting tests.

Weak:

/goal Finish the migration.

Strong:

/goal Complete `specs/20260514T120000 auth-migration.md` until every checklist item is checked, all auth callers compile against the new service, `bun test packages/auth apps/api` exits 0, and `git diff` shows no unrelated speculative edits. Update the spec after each checkpoint. Ask if the old API has undocumented behavior that needs a compatibility decision.

Final Check

Before handing back a goal, verify:

• It begins with /goal.
• It has one main objective.
• It names the evidence that proves completion.
• It tells the agent to surface that evidence.
• It names where to start.
• It tells the agent to continue until the evidence proves completion.