Introduction

Codex excels at analyzing vast, intricate codebases, collaborating with developers on tasks, and generating superior code updates. Modernizing legacy systems has emerged as one of its top applications. Here, developers concentrate on high-level architecture and business logic, with Codex tackling the intensive work: converting outdated patterns, suggesting secure refactoring, and maintaining aligned documentation and tests during evolution.

This guide demonstrates how to employ OpenAI's Codex CLI for modernizing a legacy repository, ensuring it's:

• Easy for new developers to grasp
• Reviewable by architects and compliance teams
• Replicable across multiple systems

We'll follow a COBOL-driven investment portfolio system as our example, targeting a single pilot workflow. Feel free to adapt it to any legacy technology (like Java monoliths or PL/SQL) involving old programs, scheduling (jobs, schedulers, scripts), or common data stores.

High Level Overview

The process is divided into 5 phases centered on an executive plan (ExecPlan), a design document that guides the agent through the system transformation.

For our chosen pilot workflow, we'll produce 4 key documents:

• pilot_execplan.md - The ExecPlan directing the pilot, detailing scope, importance, steps, and completion criteria.

• pilot_overview.md - Details on legacy programs (COBOL here), orchestration jobs (JCL), data sources, data movement between them, and the actual business process.

• pilot_design.md - Vision for the updated system: the service/module handling this workflow, new data structures, and public APIs or batch interfaces.

• pilot_validation.md - Outlines proof of equivalence: critical scenarios, shared input sets, side-by-side execution of old vs. new, and practical definition of matching results.

These 4 documents clarify code modifications, the desired new system form, and precise methods to verify no behavioral regressions.

Phase 0 - Set up AGENTS and PLANS

Goal: Establish a simple framework for planning in this repository using Codex, avoiding excessive bureaucracy.

Drawing from the Using PLANS.md for multi-hour problem solving cookbook, we'll add AGENTS.md and PLANS.md in a .agent directory.

• AGENTS.md: If missing, generate it with the /init command. Then, add a section directing the agent to consult PLANS.md.

• PLANS.md: Start with the cookbook's template.

These files define ExecPlans, their creation/update triggers, locations, and required sections.

Where Codex CLI helps

To customize AGENTS or PLANS for your repo, execute:

Please read the directory structure and refine .agent/AGENTS.md and .agent/PLANS.md so they are a clear, opinionated standard for how we plan COBOL modernization work here. Keep the ExecPlan skeleton but add one or two concrete examples.

Phase 1 - Pick a pilot and create the first ExecPlan

Goal: Select a practical, contained pilot workflow and document the Phase 1 plan in one ExecPlan file.

Key artifact: pilot_execplan.md

1.1 Choose pilot flow

Without a predefined flow, prompt Codex for suggestions from the repo root:

Look through this repository and propose one or two candidate pilot flows for modernization that are realistic but bounded.
For each candidate, list:
- COBOL programs and copybooks involved
- JCL members involved
- The business scenario in plain language
- End with a clear recommendation for which flow we should use as the first pilot

We'll select a reporting workflow for this pilot.

1.2 Ask Codex to create the pilot ExecPlan

Create pilot_execplan.md following .agent/PLANS.md. Scope it to the daily reporting flow. The plan should cover four outcomes for this one flow:
- Inventory and diagrams
- Modernization Technical Report content
- Target design and spec
- Test plan for parity
Use the ExecPlan skeleton and fill it in with concrete references to the actual COBOL and JCL files.

This ExecPlan serves as the central hub for all pilot activities.

Phase 2 - Inventory and discovery

Goal: Document the current pilot workflow: involved programs, jobs, data paths, and rules. This lets engineers assess changes without poring over every legacy line.

Key artifact: pilot_reporting_overview.md

Where engineers can focus:

• Verify production-executed jobs
• Supply context Codex can't derive from code (SLAs, ops details, owners)
• Review diagrams and summaries

2.1 Ask Codex to draft the overview

Create or update pilot_reporting_overview.md with two top-level sections: “Inventory for the pilot” and “Modernization Technical Report for the pilot”.
Use pilot_execplan.md to identify the pilot flow.
 
In the inventory section, include:
1. The COBOL programs and copybooks involved, grouped as batch, online, and utilities if applicable
2. The JCL jobs and steps that call these programs
3. The data sets or tables they read and write
4. A simple text diagram that shows the sequence of jobs and data flows
 
In the modernization technical report section, describe:
1. The business scenario for this flow in plain language
2. Detailed behavior of each COBOL program in the flow
3. The data model for the key files and tables, including field names and meanings
4. Known technical risks such as date handling, rounding, special error codes, or tricky conditions

This doc equips engineers with a clear view of the pilot's structure and logic sans full code review.

Example of the flow diagram in pilot_reporting_overview.md

2.2 Update the ExecPlan

With the overview ready, prompt Codex for alignment:

Update pilot_execplan.md to reflect the new pilot_reporting_overview.md file.
- In Progress, mark the inventory and MTR sections as drafted.
- Add any notable findings to Surprises and discoveries and Decision log.
- Keep the ExecPlan readable for someone new to the repo.

By Phase 2's end, you have a unified pilot overview acting as both inventory and technical report.

Phase 3 - Design, spec, and validation plan

Goal

• Define the modernized pilot workflow's form
• Outline the target service and data structures
• Specify parity validation via tests and parallel execution.

Post-phase, the build targets and proof methods are set.

Key artifacts

• pilot_reporting_design.md

• pilot_reporting_validation.md

• modern/openapi/pilot.yaml

• modern/tests/pilot_parity_test.py

3.1 Target design document

Based on pilot_reporting_overview.md, draft pilot_reporting_design.md with these sections:
 
# Target service design
- Which service or module will own this pilot flow in the modern architecture.
- Whether it will be implemented as a batch job, REST API, event listener, or a combination.
- How it fits into the broader domain model.
 
# Target data model
- Proposed database tables and columns that replace the current files or DB2 tables.
- Keys, relationships, and any derived fields.
- Notes about how legacy encodings such as packed decimals or EBCDIC fields will be represented.
 
# API design overview
- The main operations users or systems will call.
- A short description of each endpoint or event.
- A pointer to modern/openapi/pilot.yaml where the full schema will live.

3.2 API specification

We define the pilot's external interface in OpenAPI for a precise, language-independent contract. This anchors development, testing, integrations, and gives Codex a solid base for code and test generation.

Using pilot_reporting_design.md, draft an OpenAPI file at modern/openapi/pilot.yaml that describes the external API for this pilot. Include:
- Paths and operations for the main endpoints or admin hooks
- Request and response schemas for each operation
- Field types and constraints, aligning with the target data model

Example output:

3.3 Validation and test plan

Create or update pilot_reporting_validation.md with three sections:
 
# Test plan
- Key scenarios, including at least one happy path and a couple of edge cases.
- Inputs and outputs to capture for each scenario.
 
# Parity and comparison strategy
- How you will run the legacy COBOL flow and the modern implementation on the same input data.
- What outputs will be compared (files, tables, logs).
- How differences will be detected and triaged.
 
# Test scaffolding
- Notes about the test file modern/tests/pilot_parity_test.py, including how to run it.
- What needs to be filled in once the modern implementation exists.

Then scaffold tests:

Using pilot_reporting_validation.md, create an initial test file at modern/tests/pilot_parity_test.py.
 
Include placeholder assertions and comments that reference the scenarios in the test plan, but do not assume the modern implementation is present yet.

3.4 Update the ExecPlan

Update pilot_execplan.md so that Plan of work, Concrete steps, and Validation and acceptance explicitly reference:
1. pilot_reporting_overview.md
2. pilot_reporting_design.md
3. pilot_reporting_validation.md
4. modern/openapi/pilot.yaml
5. modern/tests/pilot_parity_test.py

Phase 3 yields a defined design, spec, and test framework for parity proof.

Phase 4 - Implement and compare

Goal: Build the modern pilot, execute alongside COBOL, and confirm matching outputs for planned cases.

Key artifacts

• Code in modern//pilot (e.g., modern/java/pilot)

• Finished tests in modern/tests/pilot_parity_test.py

• Updated parallel run details in pilot_reporting_validation.md

4.1 Generate a first draft of the modern code

Using pilot_reporting_design.md and the COBOL programs listed in pilot_reporting_overview.md, generate initial implementation code under modern/<stack>/pilot that:
- Defines domain models and database entities for the key records and tables.
- Implements the core business logic in service classes, preserving behavior from COBOL paragraphs.
- Adds comments that reference the original COBOL paragraphs and copybooks.
- Treat this as a first draft for engineers to review.

Iterate by targeting modules.

4.2 Wire up the parity tests

Extend modern/tests/pilot_parity_test.py so that it:
- Invokes the legacy pilot flow using whatever wrapper or command we have for COBOL (for example a script that runs the JCL in a test harness).
- Invokes the new implementation through its API or batch entry point.
- Compares the outputs according to the “Parity and comparison strategy” in pilot_reporting_validation.md.

4.3 Document the parallel run steps

Integrate into validation doc, not a new file:

Update the Parity and comparison strategy section in pilot_reporting_validation.md so that it includes a clear, ordered list of commands to:
- Prepare or load the input data set
- Run the COBOL pilot flow on that data
- Run the modern pilot flow on the same data
- Compare outputs and interpret the results
- Include precise paths for outputs and a short description of what success looks like

4.4 (If needed) Use Codex for iterative fixes

For test failures or discrepancies, loop tightly:

Here is a failing test from modern/tests/pilot_parity_test.py and the relevant COBOL and modern code. Explain why the outputs differ and propose the smallest change to the modern implementation that will align it with the COBOL behavior. Show the updated code and any test adjustments.

After chunks of progress, sync ExecPlan:

Update pilot_execplan.md so that Progress, Decision log, and Outcomes reflect the latest code, tests, and validation results for the pilot.

The ExecPlan's progress/outcomes might update like:

Progress  
- [x] Inventory and diagrams drafted (`pilot_reporting_overview.md` plus supporting notes in `system-architecture.md`).  
- [x] Modernization technical report drafted (`pilot_reporting_overview.md` MTR section).  
- [x] Target design spec drafted (`pilot_reporting_design.md` and `modern/openapi/pilot.yaml`).  
- [x] Parity test plan and scaffolding documented (`pilot_reporting_validation.md` and `modern/tests/pilot_parity_test.py`).
 
Outcomes  
- `pilot_reporting_overview.md`, `pilot_reporting_design.md`, and `pilot_reporting_validation.md` now provide an end-to-end narrative (inventory, design, validation).  
- `modern/openapi/pilot.yaml` describes the API surface, and `modern/python/pilot/{models,repositories,services}.py` hold the draft implementation.  
- `modern/tests/pilot_parity_test.py` exercises the parity flow using placeholders and helpers aligned with the validation strategy.  
- Remaining work is limited to updating the operations test appendix and wiring the services to the real runtime.

Phase 5 - Turn the pilot into a scalable motion

Goal: Deliver templates for additional workflows and a concise repo guide for Codex usage.

Key artifacts

• template_modernization_execplan.md

• how_to_use_codex_for_cobol_modernization.md

6.1 Template ExecPlan

Look at the pilot files we created:
1. pilot_reporting_overview.md
2. pilot_reporting_design.md
3. pilot_reporting_validation.md
4. pilot_execplan.md
 
Create template_modernization_execplan.md that a team can copy when modernizing another flow. It should:
1. Follow .agent/PLANS.md
2. Include placeholders for “Overview”, “Inventory”, “Modernization Technical Report”, “Target design”, and “Validation plan”
3. Assume a similar pattern: overview doc, design doc, validation doc, OpenAPI spec, and tests.

6.2 How-to guide

Using the same pilot files, write how_to_use_codex_for_cobol_modernization.md that:
1. Explains the phases at a high level (Pick a pilot, Inventory and discover, Design and spec, Implement and validate, Factory pattern).
2. For each phase, lists where coding agents helps and points to the relevant files and example prompts.

Wrap up

Following this cookbook for any pilot yields a folder structure like: ExecPlan, three pilot ... [content truncated]