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

> Automate multi-step development with Codex CLI and PLANS.md. Store milestones and commands in PLANS.md for iterative code planning, editing, validation, and repair.

- Repository: [OpenAI/openai-cookbook](https://github.com/openai/openai-cookbook)
- Tags: how-to-guide
- Published: 2026-03-02

---

**You can automate multi-step development workflows by storing milestones and validation commands in a [`PLANS.md`](https://github.com/openai/openai-cookbook/blob/main/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`](https://github.com/openai/openai-cookbook/blob/main/examples/codex/long_horizon_tasks.md) (see lines 45-53). The [`PLANS.md`](https://github.com/openai/openai-cookbook/blob/main/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`](https://github.com/openai/openai-cookbook/blob/main/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`](https://github.com/openai/openai-cookbook/blob/main/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`](https://github.com/openai/openai-cookbook/blob/main/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`](https://github.com/openai/openai-cookbook/blob/main/.agent/PLANS.md) with this template derived from the cookbook's reference implementation:

```markdown

# 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`](https://github.com/openai/openai-cookbook/blob/main/AGENTS.md) (which declares the Codex agent capabilities as referenced by the CLI) and a starter [`PLANS.md`](https://github.com/openai/openai-cookbook/blob/main/PLANS.md) in the specified directory.

### Running the Next Pending Milestone

Execute the first unchecked task with:

```bash
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:

```bash
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`](https://github.com/openai/openai-cookbook/blob/main/examples/codex/secure_quality_gitlab.md) (see lines 1-7).

### GitHub Actions Configuration

Add this workflow to [`.github/workflows/codex.yml`](https://github.com/openai/openai-cookbook/blob/main/.github/workflows/codex.yml) to automatically advance your plan on every push:

```yaml
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`](https://github.com/openai/openai-cookbook/blob/main/README.md)** – Entry point linking to Codex guides and explaining the cookbook philosophy
- **[`AGENTS.md`](https://github.com/openai/openai-cookbook/blob/main/AGENTS.md)** – Declares Codex agent capabilities; referenced during `codex init`
- **[`examples/codex/code_modernization.md`](https://github.com/openai/openai-cookbook/blob/main/examples/codex/code_modernization.md)** – Complete walkthrough showing [`.agent/PLANS.md`](https://github.com/openai/openai-cookbook/blob/main/.agent/PLANS.md) creation for real-world modernization pilots
- **[`examples/codex/long_horizon_tasks.md`](https://github.com/openai/openai-cookbook/blob/main/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`](https://github.com/openai/openai-cookbook/blob/main/examples/codex/secure_quality_gitlab.md)** – Demonstrates embedding Codex CLI in CI pipelines
- **[`registry.yaml`](https://github.com/openai/openai-cookbook/blob/main/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`](https://github.com/openai/openai-cookbook/blob/main/AGENTS.md) and [`PLANS.md`](https://github.com/openai/openai-cookbook/blob/main/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`](https://github.com/openai/openai-cookbook/blob/main/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`](https://github.com/openai/openai-cookbook/blob/main/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`](https://github.com/openai/openai-cookbook/blob/main/examples/codex/code_modernization.md) file contains a complete end-to-end walkthrough demonstrating how to create [`.agent/PLANS.md`](https://github.com/openai/openai-cookbook/blob/main/.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.