Why PLANS.md Exists
Steering long-running work toward successful completion
RESEARCH DESIGN IMPLEMENTATION

Codex + gpt-5.2-codex can implement complex tasks that require research, design, and implementation phases.

★ GOAL
Make big efforts predictable, reviewable, and less error-prone

◎ A PLANS.md approach helps steer complex work from start to finish

What a Plan Is
And why it helps
Plans Are
  • Thorough design documents
  • Living documents that evolve
  • Reviewable before implementation begins
Benefits
  • Review/verify approach before long work starts
  • Catch design issues early
  • Keep implementation aligned with intent
★ PROVEN USE CASE
Supports multi-hour work from a single prompt

◎ Users can verify the approach before Codex spends hours implementing

How Codex Is Instructed to Use Plans
Enable the workflow via AGENTS.md
AGENTS.md
→
define term
→
PLANS.md
→
implement()
Steps
  • Update your AGENTS.md
  • Add a simple convention / shorthand term
  • Example: "ExecPlan"
★ KEY POINT
The term is user-defined and it works because you define it in the repo instructions. #no_magic
Example AGENTS.md Rule
Defining the ExecPlan convention
Example Rule
# ExecPlans

For complex features or significant 
refactors, use an ExecPlan described 
in `.agent/PLANS.md`.

An ExecPlan covers the work from 
design through implementation:

1. Research the problem space
2. Document the approach
3. Get user approval
4. Implement step-by-step
5. Verify against the plan
Rule of Thumb
  • For complex features
  • For significant refactors
  • Use an ExecPlan in .agent/PLANS.md
  • Cover work from design → implementation
★ BENEFIT
Prompts become consistent: "Make an ExecPlan first"
Adapting PLANS.md to Your Team
Customize sections to match your workflow
Document Structure Goals
  • Provide lots of feedback to users
  • Guide Codex to implement exactly what's specified
  • Create reviewable checkpoints
Recommended Practice
  • Customize sections to match your team's needs
  • Add/remove required sections as your workflow evolves
  • Treat it as a living convention
★ REMEMBER
Make big efforts predictable, reviewable, and less error-prone
Example Sections
  • Problem Statement
  • Research / Context
  • Proposed Approach
  • Implementation Steps
  • Verification Criteria
  • Rollback Plan
◈
Predictable consistent workflow
⚙
Reviewable verify before implementing
★
Customizable adapt to your team
1 / 5