Introduction

Codex excels at analyzing vast, intricate codebases, collaborating with developers on planning, and generating precise code updates. Modernizing legacy code has emerged as one of its top applications. Here, developers concentrate on architecture and core business logic, while Codex manages the intensive tasks: converting outdated patterns, suggesting secure refactorings, and maintaining alignment in docs and tests as the codebase advances.

This guide demonstrates how to employ OpenAI's Codex CLI to revamp a legacy repo ensuring it's:

• Easy for newcomers to grasp
• Reviewable by architects and compliance teams
• Reproducible across multiple projects

We'll demonstrate with a COBOL-driven investment portfolio system, zeroing in on a single pilot workflow. Feel free to adapt it to any outdated tech stack (e.g., Java monoliths, PL/SQL) involving legacy apps, schedulers (jobs, scripts), or common data stores.

High Level Overview

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

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

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

• pilot_overview.md - Lists involved legacy programs (COBOL here), orchestration jobs (JCL), data sources, data movement, and the actual business process.

• pilot_design.md - Envisions the modern structure: owning service/module, updated data schema, and exposed APIs or batch interfaces.

• pilot_validation.md - Outlines parity verification: critical scenarios, shared inputs, side-by-side execution of old vs. new, and practical output matching rules.

These 4 documents clarify code changes, target architecture, and precise regression checks.

Phase 0 - Set up AGENTS and PLANS

Goal: Establish a simple framework for planning in this repo, avoiding process overload.

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, use the /init command to generate it. Then, add a section directing the agent to consult PLANS.md.

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

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

Where Codex CLI helps

To customize AGENTS or PLANS for your repo, try:

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 focused, feasible pilot workflow and document Phase 1 plan in one ExecPlan.

Key artifact: pilot_execplan.md

1.1 Choose pilot flow

Need ideas? Prompt Codex from 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 as our 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 becomes your central hub for pilot activities.

Phase 2 - Inventory and discovery

Goal: Document the current pilot workflow: components, jobs, data paths, business logic. Enables reasoning without deep code dives.

Key artifact: pilot_reporting_overview.md

Where engineers can focus:

• Verify production jobs
• Add code-inferable details (SLAs, ops context, 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 gives engineers a quick grasp of the pilot's form and function.

Example of the flow diagram in pilot_reporting_overview.md

2.2 Update the ExecPlan

With overview ready, sync the plan:

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, one overview doc serves as inventory and technical report.

Phase 3 - Design, spec, and validation plan

Goal

• Define the modern pilot's form
• Detail target service and data schema
• Specify parity proof via tests and parallels.

End result: Clear build targets and verification methods.

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

OpenAPI captures external behavior for a neutral contract, aiding implementation, tests, integrations, and code scaffolding.

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 design docs, spec, and test framework for parity assurance.

Phase 4 - Implement and compare

Goal: Build modern pilot, execute alongside COBOL, confirm matching outputs for scenarios.

Key artifacts

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

• Finished tests in modern/tests/pilot_parity_test.py

• Updated pilot_reporting_validation.md with parallel steps

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 module as needed.

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

Enhance validation doc:

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 failures:

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.

Sync ExecPlan post-chunks:

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

ExecPlan updates might read:

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: Craft templates for reuse and a repo-specific Codex guide.

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

If you follow the steps in this cookbook for any pilot, you should end up with a folder layout that looks roughly like this: ExecPlan, three pilot ... [content truncated]