Implementing Code Execution Plans with Codex CLI and PLANS.md: A Complete Guide

You can automate multi-step development workflows by storing milestones and validation commands in a PLANS.md file that Codex CLI reads to plan, edit, validate, and repair code iteratively.

The openai/openai-cookbook repository demonstrates how to use Codex CLI—OpenAI's agentic coding assistant—to execute long-running development workflows through structured plan files. By implementing code execution plans with Codex CLI and PLANS.md, teams create a living source of truth that tracks milestones, validation criteria, and decision logs across hours or days of autonomous development.

Architectural Role of PLANS.md in the Agentic Loop

The Codex CLI operates through a deterministic Plan → Edit → Validate → Repair → Document loop defined in examples/codex/long_horizon_tasks.md (see lines 45-53). The PLANS.md file serves as the persistent memory and control plane for this agentic loop, enabling Codex to resume complex tasks without context drift.

How Codex CLI Consumes Plan Files

When you invoke codex run --plan .agent/PLANS.md --step next, the CLI parses the markdown file to locate the first unchecked milestone (marked with - [ ]). According to the code modernization walkthrough in examples/codex/code_modernization.md (see lines 34-43), Codex expects these specific sections:

• Milestones – Numbered checkpoints with Command: and Accept: criteria
• Validation Commands – Shell commands run after each generation step
• Decision Log – Timestamped rationale for architectural choices
• Progress – Current status tracking

State Management and Audit Trails

By rewriting the checklist after each successful iteration (converting - [ ] to - [x]), PLANS.md functions as stateful memory that survives across separate CLI invocations. This design satisfies compliance requirements by maintaining a human-readable audit trail of every automated decision and code change.

Creating Your First PLANS.md File

To begin implementing code execution plans, initialize your agent directory and author the plan specification.

Required Sections for Codex Recognition

Codex specifically scans for the headings defined in the repository's canonical examples. Your PLANS.md must include executable command blocks under each milestone so the CLI knows which operations to perform.

Example Skeleton Structure

Create .agent/PLANS.md with this template derived from the cookbook's reference implementation:

# ExecPlan – My Project

## Milestones

- [ ] **M1 – Scaffold repository**  
  *Command:* `codex run scaffold --output .`  
  *Accept:* Files created, no errors.

- [ ] **M2 – Implement core API**  
  *Command:* `codex run generate --spec openapi.yaml --output src/`  
  *Accept:* `src/` builds and passes `pytest`.

- [ ] **M3 – Add tests & CI**  
  *Command:* `codex run test --path tests/`  
  *Accept:* 100 % test pass.

## Validation Commands

```sh

# Run after each milestone

pytest
flake8 .

Decision Log

2026‑03‑02 – Chose FastAPI for the API because of built‑in OpenAPI support.

Progress

• Last completed milestone: None

## Executing Plans with Codex CLI Commands

Once your plan file is defined, use the Codex CLI to advance through milestones automatically.

### Initializing the Agent Directory

Run the initialization command to generate the required scaffolding:

```bash
codex init --agent-dir .agent

This creates both AGENTS.md (which declares the Codex agent capabilities as referenced by the CLI) and a starter PLANS.md in the specified directory.

Running the Next Pending Milestone

Execute the first unchecked task with:

codex run --plan .agent/PLANS.md --step next

The --step next flag instructs Codex to:

1. Parse the plan file for the first - [ ] entry
2. Execute the Command: line for that milestone
3. Run the Validation Commands block
4. Rewrite the file with [x] upon success, or enter Repair mode on failure

Targeting Specific Milestones

To re-run or debug a specific checkpoint, reference the milestone label directly:

codex run --plan .agent/PLANS.md --step M2

This command bypasses the automatic next-step detection and targets the M2 milestone specifically.

Integrating with CI/CD Pipelines

The openai/openai-cookbook demonstrates productionizing this workflow through continuous integration, as shown in examples/codex/secure_quality_gitlab.md (see lines 1-7).

GitHub Actions Configuration

Add this workflow to .github/workflows/codex.yml to automatically advance your plan on every push:

name: Codex Plan CI
on:
  push:
    branches: [ main ]

jobs:
  codex:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Install Codex CLI
        run: npm i -g @openai/codex
      - name: Run next plan step
        run: codex run --plan .agent/PLANS.md --step next
        env:
          OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}

Validation Automation

The CI job invokes the identical codex run command used locally, ensuring that Validation Commands defined in your plan (such as pytest && flake8 .) execute in a clean environment before the milestone is marked complete.

Key Repository Files for Reference

Understanding the source material in openai/openai-cookbook deepens implementation accuracy:

• README.md – Entry point linking to Codex guides and explaining the cookbook philosophy
• AGENTS.md – Declares Codex agent capabilities; referenced during codex init
• examples/codex/code_modernization.md – Complete walkthrough showing .agent/PLANS.md creation for real-world modernization pilots
• examples/codex/long_horizon_tasks.md – Describes the 7-step agentic loop (Plan → Edit → Run tools → Observe → Repair → Update docs → Repeat)
• examples/codex/secure_quality_gitlab.md – Demonstrates embedding Codex CLI in CI pipelines
• registry.yaml – Metadata making notebooks discoverable on the cookbook site

Summary

• Create an .agent folder using codex init --agent-dir .agent to establish the required AGENTS.md and PLANS.md structure
• Structure your plan with Milestones, Validation Commands, Decision Log, and Progress sections so Codex CLI can parse checkpoints
• Execute the next pending task with codex run --plan .agent/PLANS.md --step next, which automatically validates and marks milestones complete
• Integrate the same commands into GitHub Actions or GitLab CI to automate plan advancement on every commit
• Maintain the plan file as a living document, committing changes to Git after each iteration to preserve the audit trail

Frequently Asked Questions

What is the purpose of PLANS.md in Codex CLI?

PLANS.md serves as the single source of truth for multi-step development workflows. It stores milestone definitions, validation criteria, and decision logs that Codex CLI reads before each generation step, enabling the model to maintain context across hours or days of work without drift.

How does Codex CLI validate milestones automatically?

After executing a milestone's Command: line, Codex automatically runs the shell commands listed in the Validation Commands section of your plan file. If validation succeeds (exit code 0), Codex updates the milestone from - [ ] to - [x]; if it fails, the CLI enters Repair mode to fix the issue before proceeding.

Can I run Codex CLI plans in CI/CD environments?

Yes. The openai/openai-cookbook provides examples in examples/codex/secure_quality_gitlab.md and GitHub Actions configurations showing how to invoke codex run --plan .agent/PLANS.md --step next in automated pipelines. This ensures that the same plan drives both local development and production validation.

Where can I find real-world examples of plan execution?

The examples/codex/code_modernization.md file contains a complete end-to-end walkthrough demonstrating how to create .agent/PLANS.md for a codebase modernization pilot. It shows the exact structure Codex expects and how the 5-step agentic loop applies to long-running refactoring tasks.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}