goal-setter

name	goal-setter
description	Draft, audit, or activate a compact /goal when the user asks for a persistent objective or wants Codex to work until a verifiable outcome is true. Defines Done, evidence, constraints, stop conditions, optional one-question-at-a-time clarification, and only necessary worker use. Not for ordinary implementation, Q&A, one-off edits, loose brainstorming, or subjective work with no rubric.

Goal Setter

Turn a rough request into a compact /goal that says what result is expected, what Done means, how to check it, what must not be broken, when to stop, and how Codex should run it. Treat this as Goal intake: decide whether to ask, briefly explore, draft, activate, or say a normal prompt is a better fit.

A Goal states the user's requested outcome and how to know it worked; it is not an implementation recipe. Favor verification targets and feedback loops over detailed procedure rules: long rule sets can fit sample tasks while failing real work, but outcome, evidence, and stop constraints travel across projects. Never shrink or reinterpret the outcome; minimize only the surrounding prompt. Start from the smallest prompt that preserves the requested product/task outcome, then add only clauses that change execution, verification, safety, or output. Default to an inline condition. Set the goal through the runtime's native mechanism, or emit the exact /goal … line; never claim it was set unless it was.

When to use

A Goal fits when the task has one durable objective, may take many iterations, and Done can be verified by commands, artifacts, diffs, screenshots, benchmarks, sourced evidence, or a written rubric. Bad fits: one small edit, "make it better" with no rubric, subjective output with no evidence, high-risk changes with no approval boundary — say so and suggest a normal prompt or a planning pass. If the only blocker is a missing way to verify it, offer a preliminary Goal that builds it first (rubric, eval + baseline, checklist, or reproduction), with the main Goal to follow.

Before drafting

If this intake will need tools, first send a one- or two-sentence visible preamble naming the first evidence you will check. Keep it concrete; do not write a plan that substitutes for doing the work.

Reconstruct what the user is trying to create and why, in 2-4 sentences. This is the highest-leverage step — a wrong starting image is amplified across the whole autonomous run. The image fixes what and why; objective, evidence, constraints, and Done all follow from it. When the prompt is rough, mirror the image back compactly, bundling any critical questions, for one-pass correction before the long run begins.

Before drafting, answer three plain questions: what must be achieved, what would prove it, and what must be understood first. Proof may be commands, screenshots, runtime state, primary sources, citations, reproduced failures, generated files, reviewer verdicts, or a user checklist. Starting context may be repo behavior, existing docs, source landscape, materials, constraints, risks, or prior hypotheses. If any answer is missing and materially changes Done, ask or make the first Goal define it.

For any request whose result is a working system, workflow, or user-facing artifact, recover the path from the user's request to the expected result before drafting. Do not substitute a representation of the thing — a mock UI, screenshot, scaffold, static dashboard, isolated component, or demo data loop — for the thing the user expected unless they explicitly asked for a mock/prototype. Ask what must actually run, connect, persist, produce, or be inspectable for the user to say the outcome worked. If that path is unclear and could change the build, ask one bundled clarification round or write a preliminary Goal that defines the pass/fail checks before implementation.

If the user asks to be grilled, stress-tested, or have ambiguity fully clarified, switch to clarification mode before drafting: ask one material question at a time, give the recommended answer, wait for feedback, and continue only while the answer could change the outcome, evidence, scope, risk, or stop condition. If the answer is discoverable from code, docs, or sources, explore instead of asking. Do not run this mode for ordinary goal requests.

Resolve ambiguity by risk:

• Ask first only when missing information could change the objective, where evidence comes from, Done, validation, scope, or a high-risk boundary (auth, security, billing, data handling, public behavior, external side effects). Bundle the questions into one round trip.
• Encode low-risk, reversible ambiguity as a stated assumption and continue.
• Explore briefly — read anchors, search — when the proof source, validation, baseline, or blockers are discoverable rather than guessable. Use the smallest evidence pass that can settle the goal: read one or two anchors first, repeat only when a required fact, command, boundary, or source is still missing. Do not start implementation during exploration.
• For broad or novel product/system requests, do not collapse uncertainty into an implementation plan. Ask or set a preliminary Goal that defines Done and pass/fail checks when mock vs working system, first user path, required runtime/backend/tool/data integration, deployment surface, or verification evidence would change what Done means.
• For broad research, strategy, or unfamiliar-domain work, do not treat the first hypothesis as the conclusion. If the task is hypothesis-driven, require a question-and-hypothesis loop: state the central question, decision it informs, out-of-scope questions, initial and competing hypotheses, what evidence would weaken or reject each one, and how evidence gathering will update, reject, merge, split, or generate hypotheses before synthesis.

What the goal should contain

Write it in the task's own terms as plain prose, no labeled fields. Open with the final state and who it serves. Prefer decision rules over step sequences. Pin only the outcome, evidence, safety boundaries, and true constraints; leave implementation order, internal design, decomposition details, and replace-vs-adapt choices to the executor after it reads the repo or source material. Use hard words like "must", "never", and "only" only for true invariants. Drop any clause that would not change this run.

Do not let the Goal become a task list pretending to define success. "Build UI, add API, write tests" is a plan; it is not Done. The Goal should first define the user-visible outcome and the evidence that the expected thing works. Implementation phases are allowed only after Done is clear.

Before emitting, run a compression pass around six elements: outcome, verification surface, constraints, boundaries, iteration policy, and blocked stop condition. Cut explanations, examples, broad file lists, ordinary command-parallelism, and tool-mechanics text that does not change one of those elements. Keep spawn_agent or create_thread names only when the Goal is meant to make those tools launch; leave normal command ordering and shell/tool parallelization to the executor.

• Objective — one sentence naming the final, verifiable state. Not "improve X"; "X does Y, verified by Z."
• Evidence / verification — where Done is checked (running app, test output, benchmark, screenshot, sourced comparison, reviewable artifact). When possible, make the check concrete: counts, named files, named screens, exact cases, timings, error messages, before/after states, or a short list of items. Do not force fake numbers onto subjective work, but avoid vague goals like "better", "good", or "works" when a concrete check can be named. If none exists, require building the smallest practical one, or stop if that needs unavailable credentials or services.
• Core flow / pass-fail checks — for working systems, experiences, and ambiguous product builds, require the smallest complete path first: user intent/input through the real layers to the expected output, decision, artifact, or state change. Named items require checks for those exact items; substitutes are supporting evidence only unless the user accepts them. If real runtimes, services, storage, generated files, or deployment define the outcome, check those channels or mark them out of scope. If a requested spreadsheet, report, checklist, doc, dashboard, or tracking file already has a clear existing primary file, update that file instead of creating a duplicate. Itemized checks must not hide a broken whole; include one holistic check when first-use coherence matters.
• Read first — one or two mandatory anchors plus "discover adjacent docs/tests as needed." A path earns a place only if it is the scope boundary or where evidence comes from, or is genuinely not discoverable; the executor can find files, and enumerated paths go stale. This is a grounding budget, not a traversal script.
• Constraints — a scope rule (the simplest thing that meets the objective; no refactors, features, or abstractions beyond it), the 1-3 hard boundaries this task could actually break (named concretely), and compatibility only when the user asks for it, external/public behavior depends on it, safety requires it, or validation requires it. If the user explicitly allows breaking compatibility, prefer a simpler replace-over-adapt design and require cleanup or migration evidence instead of speculative adapters, fallback paths, or format preservation. Do not alter other externally visible behavior or cross destructive boundaries unless the objective requires it. When metrics, tests, or coverage are involved, checks must not pass by deleting, weakening, bypassing, or narrowing required behavior, tests, or data.
  • For user-facing work: no visible dead ends. Every visible primary control, generated artifact, command, route, or advertised capability either works through the real path, is honestly disabled/marked out of scope with a clear reason, or is omitted. Do not present placeholders, fake traces, stubbed interactions, "coming soon" features, or local-only state as the completed outcome.
• Validation — the real commands or artifact checks, with concrete targets by domain. Require the most relevant validation available, not every possible check:
  • bugs: reproduce first; Done is the failing case passing with no related regressions
  • performance: metric, threshold, method, and runs (e.g. p95 < 250 ms over 3 runs)
  • tests/CI: the exact command and its pass condition
  • working systems and user-facing experiences: test the user goal, not only implementation tasks or component existence. Require evidence for each relevant success/failure/blocked path, with functional checks before UX polish. If the request includes several named items, check each item separately and report whether it passed, failed, was not checked, or was blocked. For UI-backed systems, require a real browser or equivalent end-to-end run through the core path and inspect the resulting runtime/API/storage/artifact state when those channels define the outcome.
  • migration/batch: counts verified by query or grep, with the coverage bound stated
  • research/investigation: define the decision, understanding, or next action the work must enable. For uncertain work, track the central question, competing hypotheses, what would weaken each one, evidence updates, and a stop rule. At least one pass must try to disprove the leading conclusion. Report missing evidence as "unconfirmed," not as a factual "no," unless the search scope justifies it.
  • quality: an observable bar — lint/types/tests green, N reviewed examples, readable/local/low-branching changes for code, or a clear, non-duplicative, easy-to-revise artifact for non-code work
  • if full validation is too expensive or unavailable, require the next honest check and a final report explaining the gap
  • Where outcomes have distinct classes (success / failure / timeout), require evidence that each relevant class fired; a check that could not have failed proves nothing.
• Done — pass/fail and bounded by evidence; requires the whole requested outcome, not every related improvement. Before calling Done, require the executor to check its own diff, output, and test evidence; independent review supplements this, it does not replace ordinary checking. Evidence from a substitute, demo, fixture, fake service, or nearby example is supporting evidence only; it cannot complete a named requirement unless that substitution was allowed. Choose the lightest review tier that could change the Done decision: low-risk work with strong automated checks needs those checks rerun, no spawn_agent; medium risk, incomplete evidence, or broad behavior change gets one read-only subagent; high-risk correctness, safety, security, billing, privacy, UX, research, or evidence-quality claims get adversarial read-only review that tries to find counterexamples, unsupported claims, missing checks, and overclaims. On Codex, name spawn_agent only when the chosen tier needs it; self-review cannot substitute for required independent review. State who decides findings: those touching correctness, safety, or Done block until fixed; the rest are the executor's call (fix, or keep with the reason recorded).
• Run rules (long or high-risk runs only) — report progress only against tool results, never claim unverified work as done; act on sufficient information and never end a turn on a plan or a promise; pivot within constraints when approaches stall; do not silently change the objective, Done, evidence, or scope (that is an amendment — stop and ask). On long autonomous runs, keep a concise execution-notes.md: maintain the current open items, evidence checked, pass/fail/blocked state, and material decisions. After each evidence pass, update that state; if Done is not met and no block condition applies, choose the next highest-risk or least-certain open item and continue. Do not stop with only "next steps" while unblocked required evidence remains. Keep notes as resume/audit state, not a verbose log. GOAL.md is not needed — the active /goal is the source of truth.
• Block — stop instead of thrashing when required behavior cannot be safely inferred, validation fails the same way after ~3 distinct approaches, a needed capability/credential/approval is blocked with no honest substitute, or a decision would touch schema/auth/billing/production without permission. For blocked external assets, accounts, services, or permissions, do not use a substitute as completion. Leave the smallest next user action and, when practical, the exact command or check to rerun after that action. Report state, evidence, attempts, the exact blocker, and the smallest decision needed.
• Final report — outcome first, plain words, the user's language, written for a reader who watched none of the run; name any decision the Goal left undefined that you settled by judgment.

Length. Optimize for the shortest contract that is still sufficient, not the lowest character count. Start with one sentence or one short paragraph: final state, evidence, and the most important constraint. Add a clause only when removing it could change the outcome, evidence, true constraint, boundary, iteration behavior, or blocked-stop decision. Treat 800-1,800 characters as normal only for genuinely complex goals; 2,500 means re-check necessity, and 4,000 is a hard runtime cap, not a quality target. Validate length once with python3 -B scripts/validate_goal_length.py <file> (bundled; stdin also works); pass means it fits the runtime, not that it is a good Goal. If python3 is unavailable, estimate once and move on.

Parallel (decomposable work)

Use separate workers only when they could change Done enough to justify their cost.

Use spawn_agent for read-only investigation, multi-aspect review, adversarial review, and final verification when the work is risky, broad, or unclear. Do not fix the count unless the user requested one. The parent chooses a small first wave, integrates it, and launches more only if another pass could still change Done. Subagents return evidence, counterevidence, uncertainty, gaps, or read-only findings; the parent keeps write decisions and final judgment.

Use write fan-out only when the outcome splits into independent, separately verifiable units. Judge independence by behavior, shared state, and integration risk before file layout. If used, the Goal must name the unit discovery rule, each unit's owned area and evidence, item-by-item progress, a parent integration check, and the instruction to send units to parallel workers and synthesize.

• Claude Code can realize the structure as a dynamic workflow. Describe the units, evidence, and synthesis; do not micromanage the mechanism.
• Codex launches spawn_agent and create_thread only from a user-sent /goal line, not from an auto-set goal. If a Codex Goal must launch either tool, emit the /goal … line for the user to send.

In Codex, include create_thread only when at least two write units are behaviorally independent, each has stable ownership and validation, shared interfaces are understood, the time saved exceeds setup/review cost, and a usable git/worktree base already exists. Each child thread gets exactly one unit, owned area, evidence, integration rule, and an instruction to set its own unit-scoped goal before editing. Never initialize git, scaffold architecture, or create shared interfaces solely to parallelize; if the workspace is not suitable, keep writes serial or ask before changing repo structure. Name tools, not hidden schema arguments.

When conditions do not hold — an interlocking refactor, a single-cause bug, or a serially tuned metric — keep one write goal. A read-only investigation can still use subagents.

Activate

Use the runtime's native goal tool when visible (Codex create_goal; check get_goal first and reuse a matching active goal instead of duplicating) only when the Goal does not need Codex to launch spawn_agent or create_thread. Otherwise emit the exact /goal … line. Exception — the linchpin for Codex worker tools: for any Codex goal that must launch spawn_agent or create_thread, do not auto-set. Emit the /goal … line for the user to send, and tell them plainly that their sending it is what fires those tools — an auto-set goal (or one the user never sends) runs fully in the main thread. Never claim the goal was set unless it was.

Readiness check (before activating)

Confirm, dropping n/a items: the intended outcome is clear; Done is pass/fail and evidence-bounded; evidence source and validation are explicit or discoverable; constraints name the real boundaries and forbid weakening required checks; clarification mode was used only when needed or requested; review is proportionate to risk; long runs have progress and stop rules; Codex goals that must launch spawn_agent or create_thread are returned as user-sent /goal lines; decomposable work carries only the necessary worker directive; length checked once. If anything essential is missing or a critical decision is unresolved, fix it or ask before activating.