⚡ Zeus RPG PromptKit – Evidence-First Analysis for IBM i, RPG, and Long-Lived Legacy Systems

🧩 Why IBM i Analysis Needs More Than a Single Source Member

AI demonstrations for software engineering can be genuinely impressive: explain a program, generate documentation, propose tests, or outline a modernization path. Those capabilities can be valuable in IBM i environments as well.

In a real production landscape, however, a single RPG source member is rarely enough. An application is typically a network of connected elements:

• RPG, CL, and DDS sources
• programs, procedures, service programs, and call structures
• source members spread across multiple libraries
• physical and logical files
• Db2 tables, views, aliases, keys, and triggers
• field usage and data flows
• dynamic SQL and external interfaces
• special-case logic accumulated over many years

Without that wider context, plausible explanations can quickly turn into unreliable conclusions. An AI assistant may describe what a program appears to do in polished, confident language while still missing an indirect dependency, a trigger, or a reference resolved only at runtime.

Zeus RPG PromptKit prepares that context while keeping resolved relationships, open questions, and the underlying evidence visible.

⚙️ What an Evidence Preparation Layer Actually Does

Zeus is not positioned as a magical modernization engine. It is a technical layer that collects evidence from source code and metadata, normalizes it, and turns it into a structured model that people can inspect and challenge.

The goal is not to hide uncertainty. Quite the opposite: confidently resolved relationships should remain distinguishable from incomplete, ambiguous, or unresolved references.

That helps teams answer questions such as:

• Which programs, procedures, files, and tables are connected?
• Where is a particular field read, changed, or passed downstream?
• What could be affected by a planned change?
• Which references have been resolved confidently, and which remain uncertain?
• Which Db2 metadata is still missing from the analysis?
• Which parts of the resulting context can be shared with an AI client in a controlled way?

Zeus is vendor-neutral when it comes to AI. Its artifacts can be used with ChatGPT, GitHub Copilot, Claude, local models, or no AI at all. They are equally useful in architecture reviews, tickets, documentation, QA processes, and onboarding.

🔄 From Source Code to a Reviewable Analysis Model

The standard workflow is intentionally explicit and easy to audit:

This process is deliberately less dramatic than a “modernize everything with one click” promise. For business-critical systems, that restraint is a feature rather than a limitation.

✨ What Zeus Already Covers Today

The project has expanded considerably since the first version of this article. What began with a focus on analysis and AI-ready prompts is evolving into an extensible, safety-first analysis platform.

Not every area has the same maturity level. MCP, the local viewer, PUI-related functionality, and the VS Code integration should still be treated as experimental. The generated tool catalog in the repository remains the authoritative reference for current commands, options, scopes, and safety levels.

📊 Reports, Graphs, and Canonical Analysis Artifacts

An analysis run does not produce one opaque block of generated prose. It produces a set of connected, inspectable files.

An important distinction: ai-knowledge.json is not a permanent, reusable knowledge base. It is a projection of one analysis run and may contain project-specific or sensitive information.

For future project-neutral knowledge assets, Zeus maintains a separate knowledge pipeline with explicit areas for raw evidence, sanitized candidates, final catalog contracts, and fail-closed privacy gates. Project data derived from source code does not automatically become reusable toolkit knowledge.

🔍 Investigation, Impact, and Review Workflows

Analysis rarely ends with one report. Reading the first results usually raises better questions: Where does a value originate? Which error paths exist? Which programs use a field indirectly? Which tables might be affected by a proposed change?

Zeus now provides dedicated search, investigation, and review paths. Relevant commands include:

• investigate – deepen an existing analysis around a specific goal
• search-source – search local source trees for concrete patterns
• field-search – inspect field and table usage locally or remotely
• trace and xref – follow relationships and references
• impact – generate reverse-impact analysis by program, field, or target
• assess-risk – summarize technical risk in a structured form
• generate-test – prepare test scenarios and test plans
• generate-checklist – create change and deployment checklists
• qa – render QA findings as Markdown, JSON, or Jira-oriented output
• bundle – package selected artifacts for review or safer sharing

Workflow presets are also available for common tasks such as onboarding, architecture reviews, security reviews, modernization assessment, dependency risk, refactoring, and test generation.

node cli/zeus.js analyze \
  --source ./rpg_sources \
  --program ORDERPGM \
  --out ./output \
  --optimize-context \
  --dense full

node cli/zeus.js investigate \
  --program ORDERPGM \
  --profile dev \
  --goal "Review error paths and potential side effects"

node cli/zeus.js impact \
  --field RECORD_ID \
  --program ORDERPGM \
  --source ./rpg_sources \
  --out ./output

🛠️ CLI-First and Reproducible by Design

Zeus RPG PromptKit remains deliberately CLI-first. The command line is not a fallback interface; it is the primary supported path for reproducible analysis and context-building workflows.

That brings several practical advantages:

• Commands can be documented and repeated.
• Profiles and environments remain traceable.
• Outputs can be versioned, compared, and integrated into CI pipelines.
• Reviewers can see which step created which artifact.
• AI clients interact with defined tools and files instead of an invisible black box.

Useful options for larger programs and stable runs include:

The local browser interface started through serve can make reports and graphs easier to review. It does not replace explicit shell environment loading or the CLI and MCP commands used for analysis, source collection, Db2 access, and remote validation.

🤖 Local MCP Integration for Controlled AI Agents

A major step in the project’s development is its local MCP integration. Through MCP, Zeus can expose selected tools and resources to compatible AI clients.

The design goal is explicitly not: “Let the agent do everything.”

Instead, the emphasis is on boundaries and traceability:

• local stdio transport rather than an openly reachable remote service
• a safe, read-oriented default surface
• an explicit tool allowlist for each task
• masking of common secrets in responses and errors
• an append-only audit trail under .local/mcp/audit/
• timeouts and response-size limits
• workspace boundaries, including checks for absolute paths
• write operations blocked by default

node cli/zeus.js mcp serve --stdio true --verbose

SQL write operations are handled particularly strictly. Planning and execution are separate. An apply path requires several explicit approvals, compatible profile rules, and a confirmation token. Production profiles remain blocked for such paths.

That distinction matters. The objective is not maximum autonomy, but controlled assistance with visible, enforceable boundaries.

🧩 Extensible API and VS Code Integration

In addition to the CLI, the package exports a programmatic API that can be used to register custom analyzers, analysis stages, plugins, and MCP tools.

const { zeus } = require('zeus-rpg-promptkit/api');

zeus.analyzers.registerAnalyzer('my-analyzer', {
  run(context) {
    return { customEvidence: true };
  }
});

zeus.registerPlugin(myPlugin);

This moves Zeus beyond a fixed command-line utility and toward an extensible analysis and context engine.

An experimental editor integration is also taking shape under vscode-extension/. Its intended capabilities include:

• analyzing the currently open RPG program or source member,
• displaying local analyses and reports inside the editor,
• using the same Zeus API as the CLI and MCP integration,
• working alongside Code for IBM i,
• and remaining useful through a local fallback when no IBM i connection is active.

The extension is still a foundation under development and is not yet the project’s primary delivery path. Strategically, however, it matters: it brings the analysis engine closer to the everyday workspace of IBM i developers.

⚡ Local Quickstart

You do not need access to an IBM i system to get a first impression. The repository includes a synthetic mini-system with reproducible demo artifacts.

Requirements

• Node.js 20 or newer
• Java 11 or newer for JT400- and Db2-related functions
• optional: IBM i access for source collection, discovery, or Db2 workflows

Install and run the demo

git clone https://github.com/gzeuner/zeus-rpg-promptkit.git
cd zeus-rpg-promptkit
npm install
npm run demo:run

Typical demo output:

examples/demo-rpg-mini-system/output-baseline/report.md
examples/demo-rpg-mini-system/output-baseline/architecture-report.md
examples/demo-rpg-mini-system/output-baseline/ai-knowledge.json
examples/demo-rpg-mini-system/output-baseline/dependency-graph.mmd

Optionally, start the local viewer:

node cli/zeus.js serve \
  --source-output-root ./examples/demo-rpg-mini-system/output-baseline

The local interface will then be available at http://127.0.0.1:4782.

Analyze your own local sources

node cli/zeus.js analyze \
  --source ./rpg_sources \
  --program ORDERPGM \
  --out ./output \
  --optimize-context \
  --dense full

For a new IBM i environment, the documented onboarding sequence is:

1. create a local profile,
2. load the environment variables,
3. run doctor --probe --show-resolved,
4. inspect the environment in read-only mode with discover-environment,
5. verify objects with resolve-object,
6. collect the required sources and analyze them locally.

👥 Who Zeus RPG PromptKit Is For

The toolkit is aimed at people and teams that need to understand, document, review, or modernize long-lived IBM i environments in a controlled way.

Typical users include:

• IBM i and RPG developers
• software and solution architects
• modernization and migration teams
• QA and testing teams
• consultants and technical project leads
• onboarding and documentation teams
• teams using AI-assisted analysis or review workflows

Zeus is particularly valuable when a system runs reliably but knowledge about it is scattered across people, source members, libraries, and historical documents.

Many legacy systems do not suffer primarily because they are old. They suffer because their relationships, assumptions, and side effects are difficult to see.

🧭 What the Toolkit Deliberately Does Not Replace

Zeus RPG PromptKit does not replace domain expertise or responsible engineering.

The project does not:

• autonomously write business code to IBM i,
• perform unreviewed production changes,
• guarantee a complete analysis when the available sources are incomplete,
• turn an AI-generated answer into a reliable decision by default,
• replace testing, peer review, approval, deployment, or operational processes,
• act as an official IBM product or claim any affiliation with IBM.

Even an excellent dependency graph remains a model of the evidence available to the tool. Dynamic calls, generated code, external systems, and missing sources can all impose limits. Serious analysis also means making those limits visible.

🌍 Open Source, Transparency, and Trademark Notice

Zeus RPG PromptKit is licensed under the Apache License 2.0 and developed publicly on GitHub.

Its transparency model includes:

• open source code,
• local execution,
• reproducible CLI commands,
• visible reports and JSON artifacts,
• a generated tool catalog as the authoritative reference,
• explicit safety levels and documented guardrails,
• a clear separation between the toolkit, the AI client, and human responsibility.