java-agentic-devkit: Java 8 → 21 Migration

Quick start · Migration evidence · How it works · Detailed setup · Contributing

Migrate legacy Java 8 applications to Java 21 with small, reversible changes, evidence gates, and human sign-off.

java-agentic-devkit gives Java teams a repeatable migration environment and an AI-assisted workflow that treats the existing Java 8 application as the behavioral baseline. It does not ask an agent to rewrite the project in one large change. It guides the migration through explicit phases:

Baseline → Characterization → Planning → Implementation → Validation → Audit

Each implementation slice is reviewed and validated before the next one begins. Java 21 results are compared with captured Java 8 evidence, and unresolved risks remain visible instead of being hidden behind a successful compile.

This is not a one-click source rewrite. It is a controlled migration workflow for teams that need reviewable changes, reproducible evidence, and an explicit release decision.

Why Use It?

Compiling on Java 21 does not prove that an application is safe to release. Enterprise Java migrations can change API payloads, XML contracts, persistence behavior, transactions, messaging, security, startup, and operational behavior without producing a compilation error.

This devkit makes those risks part of the workflow.

Typical migration	With java-agentic-devkit
One large upgrade that is difficult to review	Small migration slices that can be reviewed and reverted independently
“The tests pass”	Java 8 baseline evidence compared with Java 21 candidate evidence
Compatibility risks discovered late	Risk map and test gaps captured from the baseline
Runtime, dependency, and source changes mixed together	Build, dependency, source, and behavior changes isolated when practical
Informal decisions scattered across chats and commits	Architecture, decisions, status, evidence, and human sign-off recorded in the project
Ad hoc upgrade process	Baseline → plan → implementation → validation → audit

What You Get

• A Docker-based environment with Java 8, Java 21, Maven, OpenCode, and oh-my-openagent ready to use.
• A migration orchestrator that selects the next valid phase from project state and evidence.
• Focused skills for baseline capture, characterization tests, planning, implementation, validation, and audit.
• Guardrails against broad refactors, opportunistic modernization, and unapproved behavior changes.
• Explicit build, test, contract, runtime, evidence, and rollback gates.
• Shared project memory for architecture, decisions, risks, blockers, and next actions.
• A concise human sign-off tracker for the final Go, Go with conditions, or No-go decision.

The primary use case is Java 8 to Java 21 migration. The devkit also includes templates for Java 8 maintenance and Java 21 development.

Best Fit

• Maven-based Java applications with behavior that must remain stable.
• Enterprise systems using REST, SOAP, JMS, JDBC, JPA, Spring, JSP, or external integrations.
• Teams that need an auditable migration record rather than a single generated patch.
• Developers who want AI assistance while retaining human control over scope and release decisions.

Start In Three Commands

Docker Desktop must be running, and the target project must contain the migration docker-compose.yml.

From the target project root:

docker compose pull
docker compose run --rm devkit
opencode

The second command opens the devkit shell. Run the third command inside that shell, then use one prompt:

Start the Java 21 migration.

The workflow first establishes what the Java 8 application does, identifies risks and missing evidence, and then proposes the next safe action. It does not modify production code during baseline capture.

For setup details, Windows and macOS notes, and alternative VS Code Dev Container usage, see the Java 8 to Java 21 migration guide.

Designed For Real Java Migration Risk

The workflow explicitly checks affected areas such as:

• Java EE and Jakarta EE boundaries, including javax.* to jakarta.* decisions
• Maven plugins, annotation processors, generated sources, and removed JDK APIs
• REST/JSON and SOAP/XML contracts
• JMS delivery, retries, ordering, acknowledgement, and transactions
• JDBC/JPA mappings, lazy loading, flush behavior, and transaction boundaries
• Spring configuration, proxying, and bean lifecycle
• concurrency, thread pools, virtual threads, and blocking calls
• timezone, locale, charset, date/time, numbers, and BigDecimal
• authentication, authorization, TLS, deserialization, and external commands
• startup, shutdown, logging, metrics, health checks, and deployment behavior

Only checks relevant to the target project are applied. The goal is evidence, not ceremony.

What A Migration Produces

Phase	Reviewable output
Baseline	Reproducible Java 8 commands, raw build/test output, known failures, risk map, and readiness verdict
Characterization	Focused tests that lock critical behavior not protected by the existing suite
Planning	Ordered migration slices with affected modules, proof commands, stop conditions, and rollback steps
Implementation	One focused compatibility change with its diff and gate evidence
Validation	Java 8 vs. Java 21 comparison across applicable build, test, contract, and runtime behavior
Audit	Traceable residual risks and a human-reviewed Go, Go with conditions, or No-go recommendation

Raw baseline and candidate outputs stay in the target repository under docs/migration-results/. Concise architecture, decision, and status records stay under opencode/memory/, making the work reviewable by developers who did not participate in every agent session.

How The DevKit Works

The target Java project is mounted at /workspace; the devkit remains outside it. On startup, migration templates bootstrap the agent rules, workflow, human tracker, and shared memory required by the target project. OpenCode and oh-my-openagent then execute the migration using the project-local rules and evidence.

The canonical workflow is the Java 21 migration skill. The migration agent rules define behavior preservation, change discipline, risk handling, dependency policy, and validation standards.

Created and maintained by Yuneysi Gerat Gil. Licensed under the MIT License.

If you use the devkit, open a GitHub Issue with the project type, what worked, what failed, and how long the migration took. Real migration feedback drives the roadmap.

Repository Structure

View the repository tree

java-agentic-devkit/
├── .devcontainer/
│   ├── devcontainer.json
│   └── Dockerfile
├── .github/
│   ├── workflows/
│   │   └── publish-image.yml
</details>

## Setup Options

| Option | Use when | Start here |
|---|---|---|
| Project-owned Docker Compose | Recommended for a shared team workflow | Copy the selected template `docker-compose.yml` into the target project |
| VS Code Dev Container | The team works directly in VS Code containers | Follow the platform-specific examples in the migration guide |
| Local helper scripts | Developing or testing the devkit itself | Use `scripts/container/start-devkit-container.sh` |

Template bootstrapping is controlled by `DEVKIT_BOOTSTRAP_TEMPLATES`. Container-based target-project flows enable it so required files are copied when missing. The local helper script disables it by default to avoid modifying an arbitrary mounted workspace.

See the [migration setup guide](templates/java21-migration/README.md) for complete macOS, Windows, Compose, and Dev Container instructions.

## Shared Project Memory

The devkit maintains three concise target-project files:

| File | Purpose |
|---|---|
| `opencode/memory/architecture.md` | Current system shape, critical flows, integrations, and constraints |
| `opencode/memory/decisions.md` | Accepted or rejected migration decisions and rationale |
| `opencode/memory/status.md` | Current phase, evidence, blockers, risks, and next action |

Bootstrap files are seeds, not verified project facts. The migration workflow initializes them from repository evidence before baseline execution and updates them only when their owned information changes.

## Documentation

| Guide | Use for |
|---|---|
| [Migration setup guide](templates/java21-migration/README.md) | Full Java 8 to Java 21 setup and startup options |
| [Migration agent rules](templates/java21-migration/AGENTS.md) | Behavior preservation, change discipline, and validation standards |
| [Migration workflow](templates/java21-migration/skills/java21-migration/SKILL.md) | Phase order, shared gates, evidence, and state transitions |
| [Human sign-off tracker](templates/java21-migration/docs/migration-progress-checklist.md) | Migration slices, risks, evidence, and release decision |
| [OpenCode guide](opencode/README.md) | OpenCode, oh-my-openagent, configuration, and installed skills |
| [Container reference](opencode/container-and-env.md) | Runtime tools, paths, and environment variables |

## Contributing

Issues and pull requests are welcome. Before contributing, read the [contribution guide](.github/CONTRIBUTING.md), [code of conduct](.github/CODE_OF_CONDUCT.md), and [security policy](.github/SECURITY.md).

The script sets DEVKIT_BOOTSTRAP_TEMPLATES=false by default. To copy missing files from the selected template into the mounted project during startup, run:

DEVKIT_BOOTSTRAP_TEMPLATES=true ./scripts/container/start-devkit-container.sh /path/to/java/project java21-migration

Template options:

./scripts/container/start-devkit-container.sh /path/to/java/project java21
./scripts/container/start-devkit-container.sh /path/to/java/project java21-migration

Memory-First Context (Token Saving)

This devkit uses shared memory files under opencode/memory/: architecture.md, decisions.md, and status.md.

The files under templates/*/opencode/memory/ are only seed files. Users should not edit those template files in normal target-project work. After the devkit bootstraps a target project, users should update the target project's own files:

• opencode/memory/architecture.md
• opencode/memory/decisions.md
• opencode/memory/status.md

To initialize or refresh them, start OpenCode inside the target project container and use this prompt:

Use the project-architecture-memory-writer skill.
Initialize or refresh opencode/memory/architecture.md, opencode/memory/decisions.md, and opencode/memory/status.md for this target project.
Read AGENTS.md first, inspect only the evidence needed, replace template seed values with verified project facts, keep unknowns explicit, and summarize the files changed.

For Java 8 to Java 21 migrations, run this prompt before starting the migration. Refresh memory after a phase only when architecture, decisions, risks, or delivery status changed.

Agents read these concise files first, so they avoid repeating wide codebase scans for recurring context. This reduces token usage and usually improves response speed for follow-up questions.

Keep these files updated whenever architecture, decisions, or project status changes.

Guides

Each template has its own AGENTS.md with template-specific agent rules.

Guide	Use for
opencode/README.md	AI stack guide: OpenCode, oh-my-openagent (OMO), and skills.
opencode/container-and-env.md	Container contents and environment variables.
templates/java8/AGENTS.md	Agent rules for Java 8 target projects.
templates/java21/AGENTS.md	Agent rules for Java 21 target projects.
templates/java21-migration/AGENTS.md	Agent rules for Java 8 to Java 21 migration projects.
templates/java21-migration/README.md	Java 8 to Java 21 migration setup and workflow.