goal-setter

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, use the clarification rule below 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 — or the request is too ambiguous to define an honest pass/fail Goal — switch to clarification mode before drafting. Ask one material question at a time when its answer determines the next useful question; otherwise bundle independent blocking questions into one round. Give the recommended answer, wait for feedback when questions are dependent, and continue only while another 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 prolong the interview once the Goal is safe to define.

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). Ask dependent questions one at a time; bundle independent blockers when their answers do not affect each other.
• 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. When subagent use meets the trigger below, put a concrete imperative in the Goal rather than soft language such as "get an independent review": tell Codex to spawn subagents for the named independent work or verification, wait for their evidence, and synthesize it before acting or declaring Done. Leave worker count and wave shape to the parent unless the user fixed them.

• 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. Low-risk work with strong automated evidence usually needs no subagent. When evidence is incomplete, the change is broad or high-risk, the result is subjective, or a fresh context could expose a material miss, require Codex to spawn a read-only subagent to verify the actual output, runtime, and evidence before Done; do not allow an in-context self-review to satisfy that requirement. Add adversarial or perspective-diverse subagents only when those lenses could still change Done. Do not derive a fixed reviewer count, role, or sequence from a risk label alone. 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.

Write an execution rule into the Goal that tells the running Codex task to use spawn_agent; do not merely describe subagents as available. During Goal execution, spawn subagents when there are independent investigation or review questions that can run in parallel, when noisy exploration should be isolated from the parent context, when another focused pass can test new evidence, or when fresh-context verification could materially change Done. Choose the smallest useful first wave, wait for and synthesize its evidence, then launch another wave only if it could still change Done. Do not fix the count unless the user requested one. Review subagents stay read-only and return evidence, counterevidence, uncertainty, and gaps; the parent keeps integration, write decisions, and final judgment. Goal intake itself stays in the parent context unless understanding the request requires substantial independent investigation.

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 — the running Goal executes the rule above with spawn_agent. When the Goal requires subagent work, spawn it; do not replace the required delegation with an in-context pass, and do not make the user resend /goal solely to authorize it.

Treat create_thread as a user-owned separate Codex task, not as subagent fan-out. Use or mention it only when the user explicitly asks for separate durable tasks, threads, or worktrees; do not infer it merely because work is decomposable. When the explicit request is parallel write fan-out across multiple tasks, require at least two behaviorally independent units, stable ownership and validation for each, understood shared interfaces, time savings that exceed setup/review cost, and a usable git/worktree base. Each parallel 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, stop and explain the smallest missing condition instead of silently creating threads or changing repository structure. A user-requested single handoff or new thread follows that explicit request without applying the multi-task fan-out gates.

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) unless the user asked only for a draft. If no native goal tool is available, emit the exact /goal … line. Possible subagent use does not change the activation path. 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; dependent clarification continued until the Goal became safe to define; required subagent use is proportionate and names the work it must check; a continuing need for delegation appears in the Goal as a concrete spawn, wait, and synthesize instruction; create_thread is absent unless the user explicitly requested separate durable tasks; long runs have progress and stop rules; 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.