How I use GitHub Copilot’s Ask, Agent, and Plan modes — plus custom instructions, agents, and skills — to navigate, understand, and extend a 30,000+ line open-source Minecraft server written entirely in COBOL.
Introduction
I work on CobolCraft — an open-source Minecraft 1.21.4 server written entirely in COBOL.
Yes, COBOL. The same language running the world’s banking systems, insurance claims, and government payroll is also running a multiplayer game server with infinite terrain generation, real-time physics, networking, NBT encoding, and a full Minecraft protocol implementation.
If you work on mainframe COBOL, enterprise batch processing, or legacy modernization — this article is for you. The patterns I demonstrate here with CobolCraft apply directly to any COBOL codebase: from z/OS CICS programs to GnuCOBOL microservices.
GitHub Copilot in VS Code now offers three powerful interaction modes — Ask, Agent, and Plan — plus deep customization through custom instructions, prompts, agents, and skills. Together, these transform how we work with COBOL.
The CobolCraft Codebase at a Glance
Before diving into Copilot, let’s understand what we’re working with. This is a non-trivial application featuring 60+ source files, 62 copybooks, and a C++ interop layer.
src/
├── main.cob # Entry point: CALL "Server"
├── server.cob # Game loop (20 TPS), initialization, networking
├── packets.cob # Minecraft protocol packet registration
├── encoding/ # VarInt, NBT, JSON, UUID encoders/decoders
├── packets/ # Serverbound and Clientbound handlers
├── blocks/ # Block-specific behaviors (doors, slabs, signs...)
├── world/ # Chunk loading, region files, persistence
└── _copybooks/ # Shared data structures (.cpy files)
Part 1: The Three Modes — Ask, Agent, and Plan
GitHub Copilot in VS Code now offers three distinct ways to interact with your code.
1. Ask Mode
The “Codebase Librarian.” Use this for pure comprehension without modifying files. It reads your workspace and answers questions in plain English.
- Official Guide: Asking questions about code in your IDE
For mainframe developers: Ask mode is a lifesaver for onboarding. Ask: “What JCL step calls this program?” or “Explain this complex REDEFINES clause.”
2. Agent Mode
The “Pair Programmer.” Agent mode can read, search, create, edit, and run terminal commands across your entire workspace. It takes autonomous action.
- Example: “Add a new /tp command following the pattern in help.cob.”
- Official Guide: Using Copilot Agent Mode
3. Plan Mode
The “Architect.” This generates a step-by-step implementation plan for your approval before execution. This is critical for high-stakes legacy systems where you want to “think twice, code once.”
- Example: “Plan adding mob entity support. List the new copybooks required.”
- Official Guide: Using Copilot Plan Mode
Note: Please be aware that in the latest versions of GitHub Copilot for VS Code, the Edit Mode may not be visible by default.
Part 2: The Power User’s Toolkit (Customization)
To turn Copilot into a COBOL specialist, you need to use the four “Customization Levers.”
1. Custom Instructions
These are global rules that tell Copilot your specific COBOL dialect (e.g., GnuCOBOL vs. IBM Fixed-format).
# COBOL Development Standards
## Language Specifics
- Dialect: GnuCOBOL 3.1+ (Free-format).
- Always use `IDENTIFICATION DIVISION` and `PROGRAM-ID`.
- Prefer `BINARY-LONG` for integers and `PIC X(n)` for strings.
- Use `GOBACK` instead of `STOP RUN` for subprograms.
## Naming Conventions
- Data items: `UPPER-KEBAB-CASE` (e.g., `PLAYER-DATA`).
- Programs: `PascalCase-Hyphenated` (e.g., `Register-Block`).
- Copybooks: Prefix with `DD-` (e.g., `DD-ENTITY.cpy`).
## Architecture
- Use `COPY REPLACING` for parameterized logic.
- All network packets must be registered via the `Packet-Registry`.
- Where to save: .github/copilot-instructions.md
- Official Guide: Adding repository custom instructions
2. Custom Prompts (.prompt.md)
Create reusable templates for recurring tasks like “Create New Packet” or “Explain JCL.”
---
description: "Create a new server command"
mode: "agent"
---
I want to add a new command to the server.
Command Name: {{name}}
Description: {{description}}
Steps:
1. Create `src/commands/{{name}}.cob`.
2. Use the callback pattern found in `help.cob`.
3. Include `COPY DD-CALLBACK-COMMAND-EXECUTE` in the LINKAGE SECTION.
4. Add the registration CALL in `server.cob`.
- Where to save: .github/prompts/
- Official Guide: Creating and using custom prompts
3. Custom Agents (.agent.md)
Build specialized personas like a “COBOL Tester” or “Architecture Expert.”
---
name: "COBOL Tester"
description: "Specialist in writing unit tests for CobolCraft"
tools:
- read_file
- create_file
- run_in_terminal
---
You are an expert in COBOL Unit Testing.
When a user asks you to test a program:
1. Analyze the Linkage Section of the target file.
2. Create a test file in `tests/` using the `TEST-SUITE` copybook.
3. Use `TEST-ASSERT` to validate edge cases (null values, overflows).
4. Run `make test` and report any failures.
- Where to save: .github/agents/
- Official Guide: Creating your own Copilot Agents
4. Skills (SKILL.md)
Package deep domain knowledge (like DB2 SQL patterns or Minecraft protocol specs) so Copilot knows how to apply them.
# Skill: COBOL SQL & Error Handling
## DB2 Access Pattern
Always check SQLCODE immediately after an EXEC SQL block:
```cobol
EXEC SQL
SELECT NAME INTO :WS-NAME FROM USERS WHERE ID = :WS-ID
END-EXEC.
EVALUATE SQLCODE
WHEN 0 CONTINUE
WHEN 100 MOVE 'N' TO WS-FOUND
WHEN OTHER PERFORM 999-DB2-ERROR
END-EVALUATE.
- Where to save: .github/skills/SKILL.md
- Official Guide: Enhancing Copilot with Skills
The “Copilot-Ready” Folder Structure
Place .github folder at the root of your repository:
my-cobol-project/
├── .github/
│ ├── copilot-instructions.md <-- [GLOBAL] Coding standards & styles
│ └── copilot/
│ ├── agents/ <-- [PERSONAS] Specialized AI roles
│ │ └── cobol-tester.agent.md
│ ├── prompts/ <-- [TEMPLATES] Reusable prompt tasks
│ │ └── new-command.prompt.md
│ └── skills/ <-- [KNOWLEDGE] Domain-specific rules
│ └── cobol-patterns/
│ └── SKILL.md
├── src/
└── _copybooks/
Part 3: Real-World Scenarios for Mainframe Developers
Scenario 1: Inheriting “Spaghetti” Code
Use Ask Mode to find all GO TO statements and map the control flow they create. Then, use Agent Mode to refactor those paragraphs into structured EVALUATE logic.
Scenario 2: Propagating Copybook Changes
Need to add a field to a central customer copybook? Agent mode can find every program that uses COPY CU-CUSTOMER-REC, update the WORKING-STORAGE, and modify the associated EXEC SQL statements across dozens of files simultaneously.
Scenario 3: Modernization Planning
Use Plan Mode to outline how to wrap a legacy batch program as a REST API using CICS web services and JSON request/response handling.
Part 4: Setting It All Up — Quick Start
- Install: Get the GitHub Copilot Extension and Copilot Chat.
- Configure: Add your .github/copilot-instructions.md with your specific standards (Fixed vs. Free format).
- Structure: Organize your /prompts and /agents folders so new team members or candidates can learn from your best practices.
Conclusion
COBOL isn’t going anywhere — it processes 95% of ATM transactions and 80% of in-person transactions worldwide. The developers maintaining these systems deserve modern tooling.
GitHub Copilot doesn’t just autocomplete COBOL — it understands it. CobolCraft proves that COBOL can do anything, and GitHub Copilot proves that working with COBOL can be a modern, productive experience.
Try it yourself: Clone CobolCraft, open it in VS Code, and start asking questions.
Resources
COBOL Development with GitHub Copilot was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.