# A Practical Guide to Using /goal in Codex > Use Codex goals as completion contracts with explicit outcomes, verification, constraints, iteration rules, and safe stop conditions. - Author: AI Kai - Published: 2026-06-05 - Updated: 2026-08-23 - Topic: Codex - Tags: codex, goals, agent-workflows - Canonical: https://hqman.me/blog/codex-goal-completion-contract/ - Original: https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex Codex's /goal has been out for a while now, and it's genuinely powerful. But after setting a goal, Codex often drifts off course or delivers something well below what you expected. The problem isn't the model. The problem is your goal prompt is missing a completion contract. Here's what I learned from getting it wrong, and how to get it right. --- ## What /goal actually is /goal is not a longer prompt. It's a persistent, thread-scoped completion contract. You give Codex an objective, and it keeps working until the objective is met, the budget runs out, or it hits a blocker it can't solve. Normal prompt: ``` You ask -> Codex works -> outputs result -> waits for your next instruction ``` /goal: ``` Codex works -> checks if done -> not done, keeps going -> done, stops ``` Put simply: with a prompt, you push Codex forward step by step. With /goal, you set the destination and Codex finds the path. The 5 lifecycle commands: ``` /goal Set and start a goal /goal View current goal /goal pause Pause active goal /goal resume Resume paused goal /goal clear Remove current goal ``` --- ## Why your /goal drifts Three gaps: **1. No clear finish line** Codex doesn't know what "done" means. You say "improve performance," it changes one line and calls it complete. **2. No process constraints** Codex doesn't know what's off-limits. It might modify things you never wanted touched just to hit the target. **3. No verification surface** Codex can't prove the work is actually complete. Without a test command, a benchmark, or a checkable output, it relies on its own judgment. That judgment is often wrong. Think of it like delegating to a teammate without giving them scope or acceptance criteria. They either keep asking you questions, or they deliver something they think is fine but you don't. --- ## The 6 elements of a strong /goal This is the most important section. A strong /goal isn't about writing more. It's about making these 6 things explicit: ### 1. Outcome What should be true when the work is done. Not "improve latency." Instead: "p95 latency below 120ms." ### 2. Verification surface What evidence proves the goal is met. A command output, a test suite result, a benchmark score, or a checkable file. ### 3. Constraints What must not regress while Codex works. Example: "All existing tests must stay green." Or: "Do not remove any public API endpoints." ### 4. Boundaries What Codex is allowed to touch, and what it isn't. Example: "Only modify files in the checkout service." Or: "Do not change the database schema." ### 5. Iteration policy How Codex should decide what to try next between rounds. Tell it: record what changed, what the evidence showed, and what experiment to try next. This prevents it from retrying the same approach. ### 6. Blocked stop condition When Codex should stop and report instead of continuing blindly. Example: "If the benchmark can't run, permissions are missing, or no viable path remains, stop and explain the blocker, what you tried, and what input is needed to continue." --- ## Weak goals vs strong goals **Weak:** ``` /goal Improve performance ``` **Strong:** ``` /goal Reduce p95 latency on the checkout endpoint below 120ms, verified by the benchmark suite, while keeping all existing tests green ``` --- **Weak:** ``` /goal Migrate to Rust ``` **Strong:** ``` /goal Migrate the auth module from TypeScript to Rust. Verification: all existing tests pass against the Rust version with identical behavior. Do not change public API interfaces. ``` --- **Weak:** ``` /goal Fix this flaky test ``` **Strong:** ``` /goal Find the root cause of auth/session-refresh.spec.ts and fix it. Verification: concurrent scenario tests pass, no random failures across 10 consecutive runs. Do not change public interface behavior. If the root cause is in an upstream dependency, stop and report evidence with a recommended approach. ``` --- ## Reusable /goal template Copy this and fill in your own task: ``` /goal verified by while preserving Scope: - Work on: [files/modules/features to touch] - Do not touch: [out-of-scope areas] Between iterations: - Record what changed, what evidence showed, and the next experiment to try. If blocked: - Stop with: attempted paths, evidence gathered, blocker description, and what input is needed to unblock. Acceptance criteria: - [Criterion 1: measurable result] - [Criterion 2: test or command passes] - [Criterion 3: user-visible outcome] Final report: - What was done - Files changed - Verification commands run and results - Remaining risks or follow-ups ``` --- ## Pre-launch checklist: 8 things to verify before starting /goal Run through this before you hit enter: 1. Is the outcome specific? Not vague like "optimize this" or "improve performance"? 2. Is scope defined? What to change, what not to touch? 3. Are there objective acceptance criteria? Tests passing, score hitting a threshold, expected command output? 4. Is the verification method clear? What command does Codex run to prove completion? 5. Did you tell Codex to keep fixing on failure, not stop at the first error? 6. Are stop conditions defined? Success, budget exhausted, or unresolvable blocker? 7. If you used plan mode earlier, did you exit it? (Plan mode blocks file edits, which will cause /goal to fail.) 8. Did you ask for a final report covering changes, verification results, and remaining risks? Miss one and Codex is more likely to drift. --- ## Two tools that help ### /grill-me: let Codex interrogate you before you start Before writing your /goal, use the /grill-me skill to let Codex ask you the hard questions: Where are the boundaries? What counts as done? What's off-limits? When should it stop? You think you've thought it through. Then it asks one question and you realize there's an edge case you missed entirely. After the interrogation, the 6 elements basically write themselves. Codex's built-in plan mode works similarly. Just remember: exit plan mode before starting /goal. Plan mode blocks file edits, so /goal will fail if it's still active. ### goalbuddy: structured goal management When your requirements are vague (like "improve desktop performance"), try goalbuddy. It asks clarifying questions upfront, then generates a structured goal file (go.md + state.yaml) so you can see task breakdowns, current status, and progress at any time without digging through chat history. Good for large tasks that span multiple days and need ongoing tracking. https://github.com/tolibear/goalbuddy --- ## When not to use /goal One-line edits, quick explanations, short code reviews, or anything without a clear finish line. A normal prompt is better when you want one answer and then stop. Also: if you can't articulate what "done" looks like, /goal won't help. Figure out your acceptance criteria first, then decide whether to use it. --- /goal comes down to three things: a clear finish line, a way to verify it, and constraints that keep things on track. The template and checklist are above. Next time you have a multi-step task, use them. --- References: - https://developers.openai.com/cookbook/examples/codex/using_goals_in_codex - https://x.com/dkundel/status/2062650378089594955