Mainframe Modernization Toolkit

Deterministic tools and agent instructions for migrating a JCL-bounded COBOL workload to Python or PySpark.

The toolkit discovers source relationships, validates configuration and record layouts, extracts SQL and business rules, generates typed boundaries, compiles validated relational IR to PySpark, and compares final outputs with an authoritative Golden Dataset. It does not invent missing source semantics.

Install

Python 3.10 or newer is required.

python -m pip install mainframe-modernization-toolkit
mainframe-toolkit --version

Optional runtime dependencies:

python -m pip install "mainframe-modernization-toolkit[pyspark]"
python -m pip install "mainframe-modernization-toolkit[aws]"

Initialize A Workspace

mainframe-toolkit workspace init . --target vscode
mainframe-toolkit workspace init . --target claude
mainframe-toolkit workspace init . --target all

The initializer adds mainframe-migration.json, JSON schemas, and the selected agent integration without overwriting existing files. Configure source directories, encoding, extensions, known external dependencies, transport profiles, environment facts, and targetCapabilities in mainframe-migration.json.

For Claude Code, verify the project MCP server with claude mcp list or /mcp.

Migration Workflow

A migration starts from one JCL. A compact campaign inventories the job, then processes one program at a time so large jobs do not produce one huge preflight response.

mainframe-toolkit run migration_campaign -- init . --jcl MYJOB --format json
mainframe-toolkit run migration_campaign -- next . --jcl MYJOB --worker local --format json

For each selected program:

1. Resolve dependencies, callers, copybooks, impact, and blockers.
2. Generate canonical record contracts and readers.
3. Extract SQL and business rules.
4. Generate one program capsule containing machine-readable I/O and partial IR.
5. Implement cohesive business logic and focused tests.
6. Validate relational IR and compile PySpark when appropriate.
7. Mark the program complete and claim the next one.

After all programs are implemented, compose the JCL pipeline and compare its final output with an authoritative Golden Dataset.

mainframe-toolkit validate-golden . --manifest validation/job-output.json --format json

Intermediate program outputs do not require Golden files when the migrated job passes DataFrames in process. Validate those boundaries with explicit contracts and focused tests.

Core Commands

Run any command through the stable entry point:

mainframe-toolkit run <command> -- <arguments>

AWS Glue And Local PySpark

Use the aws-glue-pyspark starter profile when creating a new configuration:

mainframe-toolkit run migration_preflight -- . --write-template --profile aws-glue-pyspark

Keep transformations in transform_frames(). Production wrappers can use Glue Catalog, S3, and Iceberg descriptors; local runners can load semicolon-delimited CSV files with explicit schemas and invoke the same transformations.

The toolkit does not provision AWS resources. IAM, Lake Formation, buckets, Glue jobs, Catalog tables, bookmarks, connectors, and Iceberg configuration belong in deployment infrastructure.

Safety Boundaries

• Missing copybooks, PROCs, conflicting sources, parse failures, and unsafe layouts block the affected migration.
• Unknown external programs remain explicit adapter TODOs.
• Synthetic fixtures validate ingestion, not business equivalence.
• Only mainframe output or a verified equivalent implementation is an authoritative Golden Dataset.
• Generated relational IR with TODOs is non-executable.

See docs/JCL-MIGRATION-GUIDE.md for the concise end-to-end procedure.