Migration & Modernization
Forward engineering AWS Transform-generated business requirements with OpenAI Codex
This post is co-written with Sudeesh Sasidharan and Nick Sciarrilli from OpenAI
AWS Transform for mainframe handles the reverse engineering of the critical business logic embedded in your COBOL, PL/I, and JCL codebase, discovering business functions, extracting business rules with source-line traceability, and generating technology-agnostic requirements in a structured format. Modernization at enterprise scale demands more than a technology upgrade. It calls for a complete business transformation, one that reaches well beyond converting code from one language to another.
With source behavior recovered into reviewable requirements, forward engineering is where an agentic AI coding tool comes in, turning the requirements into working cloud-native applications. Specification generation, database migration, test case creation, and infrastructure provisioning follow the same overall strategy across agentic tools, and each tool brings its own advanced features. For customers who have adopted OpenAI Codex as their coding agent of choice, this post walks through the Reimagine workflow and the Codex capabilities teams can put to work at each step.
Figure 1: From mainframe requirements to verified cloud-native assets, Codex provides the forward-engineering loop in the AWS Transform Reimagine workflow
The Reimagine approach
Reverse-engineering recovers your mainframe application’s domain structure and business behavior. You then forward-engineer new cloud-native services to match your target architecture and engineering standards, in Java, Python, .NET, or any stack you prefer, with full control over which behavior to retain, extend, or redesign.
Figure 2: The three-phase Reimagine workflow – reverse engineering, forward engineering and deployment
Assess and reverse engineer with AWS Transform: AWS Transform agents analyze your COBOL and PL/I programs, JCL jobs, copybooks, and data stores to discover business functions and extract business rules with their acceptance criteria. The agents then generate structured requirements with source-line traceability.
Forward engineer with Codex: Download the AWS Transform artifacts, configure Codex with project context and methodology guidance, and generate microservice specifications. Human-in-the-loop (HITL) validation is essential here, and application experts must review the generated specifications before Codex produces the code, tests, migration scripts, and infrastructure.
Validate and deploy: Automated testing combines with human verification across code review, test execution, integration testing, and user acceptance testing before the application is ready for production.
The separation between these phases matters. Extracted requirements are evidence awaiting business approval, and generated code is a candidate implementation that has to prove itself through testing. Human validation connects recovered behavior to intended business outcomes, while deterministic build and test gates provide evidence about the implementation.
Getting started
Prerequisites:
- A completed AWS Transform Assess and Reimagine job, with business requirement artifacts in Amazon S3
- Access to Codex through the App, CLI or IDE extension, with cloud and GitHub capabilities enabled as needed
High-level steps:
- Target Specification generation following Domain Driven Design
- Code and script generation
-
- In a new workspace create AGENTS.md with product context, target stack, project structure, and architecture conventions
- Copy the in-scope specification documents from previous workspace
- Generate code and tests
- Complete code review, testing, and human validation before deployment
What AWS Transform produces
AWS Transform analyzes source and data, discovers business functions, extracts rules, and generates technology-agnostic requirements with source-line traceability. Each business-function folder contains requirements.md, with numbered REQ-* requirements and testable acceptance criteria, and traceability.yaml, which records each rule’s disposition. These reviewed artifacts become bounded inputs to forward engineering.
Figure 3: Sample AWS transform generated requirements from CardDemo – Account Management
Figure 4: AWS Transform output artifacts per business function opened in Codex App
For a detailed walkthrough of reverse engineering, EARS requirements, DDD-based specification generation, and traceability validation, see Specification-Driven Mainframe Modernization with AI Agents. This blog focuses on applying Codex to the forward-engineering phase.
Setting up Codex for forward engineering
Codex reads an AGENTS.md file at the root of your workspace as persistent project context. It captures the product context and modernization goals, the target technology stack (for example, Spring Boot, PostgreSQL, AWS Cloud Development Kit), project structure and naming conventions, and the deterministic build, test, and synthesis commands Codex runs to validate its own work.
Codex supports skills, reusable instruction packages that encode a methodology. Skills follow the open Agent Skills standard, so they are portable across Codex, Kiro, and other compatible tools. To distribute the setup at scale, package them as a plugin, with availability governed through workspace plugin controls.
First pass to generate a reproducible mechanism
Keep the first run deliberately narrow: select one business function and start with target specification generation (refer to the blog).
Place requirements.md and traceability.yaml for the selected business function under a version-controlled input directory. Add AGENTS.md at the repository root with the target stack, architecture preferences, naming standards, and build, test, and infrastructure-generation guidelines.
Invoke the specification-generation skill with a bounded instruction such as: Generate a microservice specification for Account Management from the AWS Transform artifacts; preserve every REQ-* identifier and flag unresolved business decisions.
Generating microservice specifications
Guided by the specification-generation skill, Codex applies DDD to consolidate business functions, identify bounded contexts, and define aggregates, entities, value objects, and domain events. It then produces implementation-ready service definitions covering boundaries, data ownership, domain models, API contracts, event schemas, and integration patterns.
Each specification retains the original REQ-* identifiers, and a deterministic check verifies complete requirement coverage.
Figure 5: Generated microservice specification with REQ-* traceability (excerpt) for sample CardDemo application
Codex will write specification documents, one per bounded context under /specs/{context-name}/, in Markdown with embedded YAML for API contracts and event schemas.
Architects and SMEs approve the specifications before code generation, confirming that service boundaries fit the target architecture and behavior reflects business intent. Ambiguous policies and undocumented edge cases remain open until the business resolves them. Using the skills run a deterministic traceability check to verify that every REQ-* identifier from requirements.md appears in at least one specification.
Generating code with Codex
Once the specifications are approved, Codex performs repository-scale target code generation. This is where its agentic capabilities differentiate the workflow.
Full-repo context and coordinated multi-file edits: Implementing one microservice touches database migrations, domain entities, service and controller layers, API and event contracts, tests, and infrastructure as code. Codex can inspect repository context and coordinate edits across these file types in a single task, working in dependency order from schema to domain logic to contracts and tests to infrastructure, so every layer of a service stays consistent.
Sandboxed execution with build-verify-fix loops: Codex runs shell commands inside a configurable sandbox with explicit approval policies, so Maven or Gradle builds, test suites, container operations, and infrastructure synthesis run safely as part of generation. After each unit of work, Codex compiles the code, runs the tests, reads the failures, and repairs them autonomously before continuing. This feedback loop turns generation into engineering, because the agent keeps working until the build passes.
Long-running autonomous execution: A decomposed mainframe application yields a large, well-ordered backlog of implementation tasks. Within configured permissions and environmental limits, Codex can work through well-scoped backlogs over extended runs, using higher reasoning-effort settings for complex work and pausing when a task requires a human decision. Teams can match the model to the task, reserving the strongest reasoning for complicated workflows.
For example, AWS Transform organized the open-source CardDemo mainframe application into roughly a thousand requirements across eight business functions. After human review, Codex produced Java Spring Boot services, PostgreSQL migrations, OpenAPI and AsyncAPI contracts, automated tests, and TypeScript AWS CDK infrastructure. The feedback loops resolved defects autonomously. Early CDK synthesis exposed a cross-stack security-group dependency cycle that Codex diagnosed and restructured, and an integration-test run surfaced a Docker API version mismatch that Codex resolved by upgrading the dependency and rerunning the suite. These loops also mark a boundary. Codex can repair an invalid infrastructure definition because the synthesis tools and tests define a valid state. Decision on an ambiguous business policy stays with your SMEs.
These CardDemo outcomes describe the implementation evaluated for this article; they are case-study results, not general product benchmarks.
Scaling the workflow with a Codex plugin
Review, refine, and update the agent skills as needed to fit your organization’s or project’s requirements, architecture, and guidelines, turning them into repeatable assets for forward engineering.
A Codex plugin packages reusable capabilities for installation and governance across workspaces. In this reimagine workflow, a plugin can bundle the previous specification-generation and code-generation skills, and it can optionally expose approved connectors backed by Model Context Protocol (MCP) servers. The plugin is the distribution boundary; skills provide the repeatable methodology, while connectors provide controlled access to external systems.
- Repeatability – Teams use the same build-repair, traceability and validation instructions across every business function, reducing prompt drift.
- Governance – Workspace controls determine which plugin versions and connectors are available, making the approved workflow easier to review and manage.
- Faster onboarding – Engineers install one curated package instead of assembling prompts, skills, and integrations independently.
- Maintainability – Methodology changes can be versioned and distributed centrally while project-specific architecture rules remain in AGENTS.md.
- Extensibility – Approved MCP-backed connectors can bring issue trackers, documentation systems, or internal services into the workflow without embedding credentials or system-specific instructions in prompts.
A plugin does not replace repository context or engineering approval. AGENTS.md should continue to define project-specific constraints, and architects, SMEs, security reviewers, and delivery teams remain responsible for approving specifications and production changes.
Maintaining traceability from COBOL to cloud
Traceability is enforced as a build gate, and Codex can generate the annotations and tooling that back it. In the CardDemo implementation, the code-generation skill instructs Codex to define two annotations in the shared Java module and apply them as it writes each service.
- @LegacyRules associates a java method with the source requirements it implements
- @CoversLegacyRules associates a test with the business requirements it verifies
Codex is reading those requirements to implement the behavior, so tagging each method comes as a byproduct of generation, and declaring the convention once in AGENTS.md allows Codex to apply it across every service.
A generated traceability tool parses the requirements, scans the annotations, and emits a coverage ledger in Markdown, CSV, or JSON. The build fails when a requirement has no disposition, when an implemented requirement lacks production or test evidence, when code references an unknown rule, or when a test claims a rule that no method implements. The tool verifies that the evidence chain is complete and internally consistent, while confirming that a method faithfully implements its requirement remains the job of human review.
The below sample CardDemo authorization class shows the ledger entry that records the source, disposition and other details in the code itself.
Figure 6: Sample Java class showing the annotations with legacy business requirements
Similarly, the corresponding Java test class AccountPolicyTest encodes the @CoversLegacyRules annotation that records the coverage of the business requirements.
Figure 7: Traceability chain from COBOL source to deployed infrastructure
The result is a chain an organization can audit from either end. An SME can review the requirement, a developer can inspect the method, a tester can run the case, and an architect can verify the runtime boundary, without depending on the history of an agent conversation.
Validating and reviewing at scale
Codex operates across the full delivery pipeline, from specification/code generation through to production validation. Codex runs in the terminal, in your IDE, on the web as a cloud agent, in GitHub, on mobile, and programmatically through the Codex SDK, with workflows that can move between local and cloud environments while retaining the relevant task context.
- Parallel cloud tasks: Independent business functions can be forward-engineered or validated as parallel Codex cloud tasks, each in its own sandboxed environment, converting a serial backlog into concurrent workstreams. Parallelism is mainly a latency choice, so apply it where elapsed time matters.
- Codex Code Review with custom rules: Codex reviews every pull request against custom repository rules in AGENTS.md, enforcing the conventions the coding agent followed: traceability annotations present, service ownership boundaries respected, no cross-service database access, and contracts versioned.
- CI/CD integration through the Codex SDK: The validation workflow that runs interactively also runs headlessly in CI through the Codex SDK and GitHub Actions, making generation and verification into pipeline stages that the whole team relies on.
- Requirements as inputs to generated tests: Acceptance criteria arrive in EARS format, making them strong inputs for generating concrete test cases, including property-based tests that exercise behavioral contracts across randomized inputs. Every failure traces back to a numbered requirement, pointing either to a defect in the code or to a specification that needs re-examination against the COBOL source. Both outcomes advance the modernization toward verified behavioral equivalence.
Considerations for production adoption
Generated code accelerates modernization, and it still has to earn its way into production through the usual evidence, testing, and approvals. Before deployment, a modernization team needs to:
- Resolve open business questions with the appropriate SMEs
- Validate retained behavior with approved input and output examples from the mainframe system
- Perform end-to-end, reconciliation, performance, resilience, security, and user acceptance testing
- Review data migration and rollback plans, recovery point and recovery time requirements, network boundaries, encryption keys, secrets, alarms, and runbooks
- Complete organizational architecture, security, and change approvals
Conclusion
AWS Transform, human review, and Codex play complementary roles in the Reimagine pattern. AWS Transform recovers business knowledge at enterprise scale and keeps every rule connected to its source. Application experts decide which behavior carries forward, and which questions remain open. Codex turns approved specifications into coordinated changes across code, tests, contracts, and infrastructure, verifying its own output as it goes and extending the same rigor into code review and CI/CD.
To begin your own mainframe business transformation, launch an Assess and Reimagine job in the AWS Transform console, then follow the workflow in this post to configure Codex and generate your first microservice specifications.
Related resources:
- Getting started with AWS Transform to launch a workspace and create your first Assess and Reimagine job
- Codex documentation for the CLI, IDE extension, cloud agent, code review, and SDK
- AWS Transform for mainframe for detailed documentation