How does Atlas prevent accidental changes to COBOL programs during planning?

Atlas uses a dedicated plan agent with strict permission gating. It denies all edit tools for your COBOL codebase (.cbl files, copybooks) and only allows writing to a specific plan markdown file under .atlas/plans/*.md, ensuring no accidental modifications.

Can Atlas understand COBOL copybooks and PIC clauses during the planning phase?

Yes, Atlas leverages its lsp tool and AST indexing (via tree-sitter) to understand COBOL copybooks, IDENTIFICATION, DATA, and PROCEDURE divisions, and to explain complex PIC clauses in plain English.

What COBOL tools does Atlas integrate with for planning and verification?

For planning, Atlas uses its internal research tools. For verification during implementation, Atlas integrates with GnuCOBOL cobc for compilation and COBOL Check for running test cases, ensuring changes are valid.

How do I get my COBOL change plan reviewed before any code is modified?

You document your multi-file COBOL change plan in .atlas/plans/*.md. After drafting, you use the plan_exit tool, which prompts for approval to switch to the build agent, allowing time for team review of the markdown plan.

Does Atlas support fixed-format COBOL column rules when applying changes?

Yes, Atlas is designed to respect COBOL's fixed-format column rules. It computes a unified diff for every file edit and surfaces it for your approval, allowing you to review changes against these rules before writing.

Can Atlas use local embeddings for searching my COBOL codebase?

Yes, Atlas can build its code index with local Ollama embeddings, keeping your COBOL code off third-party servers while enabling powerful semantic and keyword codebase_search capabilities.

What happens if I decide not to proceed with a COBOL change plan?

If you decide not to proceed or need more refinement, answering "No" to the plan_exit prompt keeps you in the read-only plan agent. This allows you to discard the plan or continue refining it without ever touching your COBOL source files.

How does Atlas handle multi-file COBOL changes that involve many copybooks?

Atlas's codebase_search and lsp tools are designed to index and understand dependencies across .cbl programs and copybooks. This allows you to plan changes that fan out across many files, ensuring all affected COPY members are considered in your .atlas/plans/*.md document.

Plan a multi-file change before editing in COBOL with Atlas in 2026

Atlas enables COBOL developers in 2026 to design multi-file changes and secure review before modifying any code, integrating directly with GnuCOBOL cobc for compilation and COBOL Check for testing within a secure planning environment. This ensures that complex updates affecting multiple .cbl programs and copybooks are thoroughly vetted, preventing unintended impacts on forty years of batch logic.

How Atlas Plans Multi-File COBOL Changes Safely

Atlas's dedicated plan agent ensures that designing multi-file COBOL changes in 2026 is a read-only process, preventing any accidental modifications to your .cbl programs or copybooks. This agent disallows all edit tools for your codebase, permitting writes only to a single markdown file for your design.

When you initiate a planning session with Atlas, it automatically switches to a specialized plan agent. This agent is configured with a strict permission set: it denies all edit operations for every path ('*') except for files located under .atlas/plans/*.md. This crucial safeguard means that while you are researching and designing your multi-file COBOL change, Atlas cannot inadvertently alter any of your IDENTIFICATION, DATA, or PROCEDURE divisions, nor any of your critical copybooks. This read-only environment is fundamental for maintaining the integrity of your COBOL codebase, allowing you to explore and document changes without the risk of premature or unapproved modifications. The plan agent's primary role is to facilitate thorough research and design, ensuring that every aspect of a complex COBOL update, potentially touching dozens of files, is considered before a single line of code is committed.

Researching COBOL Codebases with Atlas's Plan Agent

Within the plan agent, COBOL developers in 2026 can leverage powerful research tools like codebase_search, grep, read, and lsp to understand existing .cbl programs and copybooks. These tools provide deep insights into forty years of batch logic without altering any source files.

To effectively design a multi-file COBOL change, comprehensive understanding of the existing codebase is paramount. Atlas's plan agent provides a suite of tools specifically designed for this purpose, all operating in a read-only capacity. codebase_search allows you to find relevant COBOL code snippets, declarations, or usage patterns across your entire project, including within copybooks, using hybrid semantic and keyword retrieval. You can use grep to locate specific strings or patterns within your .cbl programs or JCL. The read tool enables you to inspect the contents of any COBOL source file, from its IDENTIFICATION DIVISION to its PROCEDURE DIVISION, or to examine the structure of a specific copybook. Furthermore, the lsp tool provides language server protocol capabilities, allowing Atlas to understand the structure of COBOL programs, resolve references, and explain complex PIC clauses or data definitions, ensuring that your design accounts for the precise behavior of the existing COBOL logic. These tools ensure that your research is thorough and accurate, forming a solid foundation for your proposed changes.

Documenting Your COBOL Change Plan for Review

Your proposed multi-file COBOL change is documented exclusively in a markdown file under .atlas/plans/*.md, the only path the plan agent is permitted to write to in 2026. This ensures a clear, reviewable artifact separate from your .cbl source code.

The core output of the planning phase is a detailed design document outlining your proposed multi-file COBOL change. Atlas's plan agent is specifically configured to allow writing only to files within the .atlas/plans/ directory, typically a markdown file like my_cobol_update.md. This strict permission boundary means that all your research, analysis, and design decisions regarding modifications to IDENTIFICATION, DATA, or PROCEDURE divisions, or changes impacting multiple copybooks, are captured in this single, designated document. This separation is critical for the review process: your team can review the comprehensive plan, including proposed changes to PIC clauses or CALL statements, without any risk of directly interacting with or accidentally modifying the actual COBOL source files. The plan serves as a concrete artifact for discussion and approval, ensuring that all stakeholders agree on the design before any implementation begins.

Reviewing and Approving COBOL Design Changes with plan_exit

Once your multi-file COBOL change plan is complete, the plan_exit tool initiates the review and approval process, asking for confirmation before transitioning from the read-only plan agent to the build agent in 2026. This ensures a deliberate handoff.

After you have thoroughly researched and documented your multi-file COBOL change plan in .atlas/plans/*.md, you use the plan_exit tool to signal its completion. This tool does not immediately switch to implementation; instead, it prompts you with a clear question: "Plan at <path> is complete. Would you like to switch to the build agent and start implementing?" This crucial step provides a formal gate for review. You can share your .atlas/plans/*.md document with your team for feedback on the proposed COBOL modifications, including any changes to PIC clauses, PERFORM statements, or COPY members. If the plan requires further refinement based on feedback, answering "No" to the prompt keeps you in the plan agent, allowing you to continue iterating on the design without touching any .cbl files. Only upon answering "Yes" and receiving approval does Atlas transition to the build agent, where it can then begin to implement the approved COBOL changes, always presenting a unified diff for every file edit for final approval against fixed-format column rules.

Ensuring COBOL Code Integrity with Atlas Permission Gating

Atlas's permission-gated tool calls are fundamental for maintaining COBOL code integrity, especially in 2026, by strictly controlling what actions the plan agent can perform. This prevents any unintended modifications to .cbl programs or copybooks.

The robust security model of Atlas is a cornerstone for safe COBOL development. Every tool call made by Atlas, whether it's codebase_search, read, or any other, is permission-gated against allow, ask, and deny rules. In the context of planning a multi-file COBOL change, the plan agent's permissions are meticulously set to deny all edit tools for '*' (the entire codebase) and explicitly allow writing only to the designated plan markdown file under .atlas/plans/*.md. This means that even if the agent were to attempt an edit operation on a .cbl program, a copybook, or any other critical COBOL asset, the permission system would block it. This granular control ensures that the research and design phase remains strictly read-only for your COBOL source code, providing an unparalleled level of safety and preventing any accidental or unauthorized modifications to your valuable forty years of batch logic before the design is fully approved and the build agent takes over.

Step by step

01Initiate Plan Agent: Start Atlas in plan mode by running `atlas plan` in your COBOL project directory, where your .cbl programs and copybooks reside.
02Search COBOL Code: Use `atlas codebase_search "PERFORM 1000-PROCESS-RECORD"` to semantically and keyword search for specific COBOL paragraphs or CALL statements across your .cbl files and copybooks.
03Read COBOL Source: Examine the IDENTIFICATION, DATA, and PROCEDURE divisions of a relevant COBOL program using `atlas read "MYPROG.cbl"` to understand its current logic.
04Inspect Copybook Definitions: Utilize `atlas lsp "MYCOPY.cpy" "WS-CUSTOMER-NAME"` to get detailed information about a data item like WS-CUSTOMER-NAME and its PIC clause within a COBOL copybook.
05Draft the Plan: Write your proposed multi-file COBOL change, detailing modifications to .cbl programs and copybooks, into a markdown file like `.atlas/plans/new_feature_cobol.md`.
06Signal Plan Completion: Call `atlas plan_exit` to indicate that your COBOL change plan is complete and ready for review, prompting Atlas to ask about switching to the build agent.
07Review the Plan: Share the `.atlas/plans/new_feature_cobol.md` document with your team for review and feedback on the proposed COBOL design.
08Approve Transition: Answer "Yes" to the `plan_exit` prompt to switch to the build agent, allowing Atlas to proceed with implementing the approved COBOL modifications, ready to compile with `GnuCOBOL cobc` and test with `COBOL Check`.

Frequently asked questions

How does Atlas prevent accidental changes to COBOL programs during planning?: Atlas uses a dedicated plan agent with strict permission gating. It denies all edit tools for your COBOL codebase (.cbl files, copybooks) and only allows writing to a specific plan markdown file under .atlas/plans/*.md, ensuring no accidental modifications.
Can Atlas understand COBOL copybooks and PIC clauses during the planning phase?: Yes, Atlas leverages its lsp tool and AST indexing (via tree-sitter) to understand COBOL copybooks, IDENTIFICATION, DATA, and PROCEDURE divisions, and to explain complex PIC clauses in plain English.
What COBOL tools does Atlas integrate with for planning and verification?: For planning, Atlas uses its internal research tools. For verification during implementation, Atlas integrates with GnuCOBOL cobc for compilation and COBOL Check for running test cases, ensuring changes are valid.
How do I get my COBOL change plan reviewed before any code is modified?: You document your multi-file COBOL change plan in .atlas/plans/*.md. After drafting, you use the plan_exit tool, which prompts for approval to switch to the build agent, allowing time for team review of the markdown plan.
Does Atlas support fixed-format COBOL column rules when applying changes?: Yes, Atlas is designed to respect COBOL's fixed-format column rules. It computes a unified diff for every file edit and surfaces it for your approval, allowing you to review changes against these rules before writing.
Can Atlas use local embeddings for searching my COBOL codebase?: Yes, Atlas can build its code index with local Ollama embeddings, keeping your COBOL code off third-party servers while enabling powerful semantic and keyword codebase_search capabilities.
What happens if I decide not to proceed with a COBOL change plan?: If you decide not to proceed or need more refinement, answering "No" to the plan_exit prompt keeps you in the read-only plan agent. This allows you to discard the plan or continue refining it without ever touching your COBOL source files.
How does Atlas handle multi-file COBOL changes that involve many copybooks?: Atlas's codebase_search and lsp tools are designed to index and understand dependencies across .cbl programs and copybooks. This allows you to plan changes that fan out across many files, ensuring all affected COPY members are considered in your .atlas/plans/*.md document.

Try Atlas in your terminal

The terminal-native AI coding agent. Free core, single binary.

Install Atlas

Related guides

Plan a Multi-File Change Before Editing with Atlas in 2026

How to plan a multi-file change with Atlas in 2026: the plan agent denies all edit tools, you research with codebase_search and lsp, then plan_exit hands off.

Atlas for COBOL: Copybooks, PIC Clauses, and GnuCOBOL in 2026

Atlas is a terminal-native AI coding agent for COBOL in 2026. It reads your divisions and copybooks, explains a paragraph before touching it, and compiles with cobc under GnuCOBOL.

Upgrade a COBOL Dependency and Fix Breakage with Atlas in 2026

COBOL developers in 2026 can use Atlas to upgrade major library versions, automatically fixing compile and test failures. Leverage GnuCOBOL cobc, COBOL Check, and Z Open Editor formatter for a streamlined workflow.

Rename a symbol across the repo in COBOL with Atlas in 2026

Rename COBOL functions, classes, or constants across your entire repository with Atlas in 2026. Leverage lsp, grep, and edit for precise, verified refactoring.

Run Atlas Headless in CI for COBOL in 2026

Automate COBOL development in CI with Atlas. Run Atlas headless to get machine-readable output, integrate with GnuCOBOL cobc and COBOL Check, and ensure safe code changes.

Run the COBOL Test Suite and Triage Failures with Atlas in 2026

In 2026, COBOL developers use Atlas to run COBOL Check test suites, triage failures into distinct root causes, and fix issues efficiently, all within the terminal.

Debug a single failing test in COBOL with Atlas in 2026

Pinpoint and fix failing COBOL tests efficiently with Atlas in 2026. Leverage GnuCOBOL cobc, COBOL Check, and Z Open Editor formatter for precise debugging.

Self-review your working diff before committing in COBOL with Atlas (2026)

Catch your own mistakes in COBOL code before they reach a reviewer or CI. Atlas helps COBOL developers in 2026 self-review uncommitted diffs, integrating with GnuCOBOL cobc, COBOL Check, and Z Open Editor formatter.

Browse this resource hub