Codex CLI /goal workflows with AGENTS.md

A good /goal workflow keeps the intent of a task alive after the person who started it logs off. The /goal command in Codex CLI, OpenAI's coding agent, sets a persistent goal that rides along through a session so the agent does not lose the plot mid-task. The trick is pairing it with AGENTS.md, a plain Markdown file in your repo that holds the boundaries: which model to use, what counts as done, and which connectors are allowed. Goals carry intent, AGENTS.md carries boundaries, and the receipts you leave behind carry proof for whoever inherits the branch.

This matters most at a handoff. A branch ships at 6pm and the goal that shaped it stays in the author's chat scrollback. By morning the parent intent and the child scope quietly disagree, and nobody can say why the agent touched a file. A /goal routine is the habit that stops that from happening.

Set the goal, then write down the boundaries

The official slash commands reference explains what /goal does and stops there. That is the right scope for docs, but it leaves the team part to you.

Here is the split that works. The persistent goal holds the intent for this session. AGENTS.md holds the things that should be true every session: the pinned default model, the rule for when to escalate to a stronger one, and the verification snippet every run has to end with. Casual model swaps wobble review expectations, so pinning the default in the file lets a lead reason about how much can go wrong before they read a single diff.

Keep the file boring and explicit. Tighter prompts cannot replace a repo contract, and the day someone duplicates an edit nobody reconciled, you will wish the scope had lived in a file instead of a chat.

# AGENTS.md

- Default model: pin it here, with the escalation rule for risky changes.
- Every Codex CLI run ends with a transcript snippet reviewers can replay.
- Pair browser evidence with the project's normal CLI checks before merge.
- List allowed actions beside each connector name if MCP servers are enabled.

Require proof after every codegen run

Exec shortcuts that skip tests let regressions slip back in quietly. The fix is a small ritual: every run ends with a transcript snippet showing the tests actually ran after the code was generated.

Speed wins once. The habit of pasting proof wins every week. Once the snippet is required, a green merge starts to mean the checks really ran, not that someone felt confident. The evidence is mundane on purpose, which is exactly why it survives a crunch.

The same idea covers browser work. When a Chrome workflow diverges from your CLI habits, reviewers end up looking at two different stories. Write the staging URL and the credential boundary down next to the browser task so the demo and the CI artifacts stop contradicting each other.

Keep MCP connectors honest

Connectors pile up quietly, and least-privilege erodes one harmless-looking addition at a time. Each MCP server you enable widens the blast radius of a bad run.

A short Markdown roster checked into the repo root fixes this. Name every connector and what it is allowed to do, so a security review starts from a written list instead of guesswork. It also turns agent output back into work the team owns, rather than something that happened in one person's terminal.

Use this table as the gate you run before merge.

For the mechanics themselves, the Codex CLI docs and features page cover what a run can do, the quickstart gets a new machine going, and the openai/codex and openai/skills repos track what ships next. None of them will write your receipt format for you.

Common questions

• How do /goal and AGENTS.md work together in a Codex CLI workflow?

  The goal set by /goal carries intent across the session, and AGENTS.md carries the boundaries: the pinned default model, the escalation rule, and the verification snippet every run must end with. That split keeps the parent intent and the child scope from quietly disagreeing during a handoff, since the durable rules live in a file instead of a chat thread.

• What should reviewers check before merging a /goal-driven change?

  Check four things: verification output is pasted or linked, forked agent work lists parent and child responsibilities, sensitive paths got explicit human acknowledgement, and the scopes named in the PR body match the folders actually in the diff. The checks are deliberately boring, which is what makes them repeatable when everyone is under pressure to ship.

• Why require a verification transcript after codegen?

  Because shortcuts that skip tests let regressions return without anyone noticing. Requiring a transcript snippet that shows tests ran after the code was generated makes the proof a habit rather than a mood. The payoff is plain: a green merge starts correlating with checks that actually ran, so you trust the merge button again.

• How do these workflows stop MCP privilege creep?

  A Markdown connector roster checked into the repo root keeps least-privilege from eroding as connectors accumulate. Every MCP server widens the blast radius, so the roster names what is allowed before a security review begins. Reviews then start grounded in a written list instead of someone guessing which servers the agent might have reached.

• Where does the /goal release fit in?

  The /goal command shows up as a line item in the Codex CLI 0.128.0 release notes. A release note tells you the command exists. It does not tell you how a team keeps the goal honest across a handoff, which is the part this routine handles.

Try it on a real handoff

Bring one live repo and one recent handoff to a training session and we will wire the /goal routine into both. More patterns live under CLI workflows.