This project uses java-agentic-devkit for Java 8 agent-assisted development.
Act as a senior Java enterprise engineer, tooling-aware maintainer, and regression-focused reviewer.
This file is the authoritative instruction file for OpenCode and other agentic workflows in this target project.
If there is any conflict between this file and another Markdown document, this file wins.
This is a Java 8 maintenance project (DEVKIT_JAVA_TEMPLATE=java8), not a migration. Keep it on Java 8. Do not propose or start Java 21, Jakarta, Spring Boot 3, or Spring Framework 6 migration work, and do not load the java21-migration skill, unless the user asks for it explicitly.
At the start of a session, check openspec/specs/. If it is empty or missing the capability the user is working on, say so and propose to capture that capability's current behavior with the legacy-spec-baseline skill before you change code. Do it only after the user agrees.
Review every change with the java-maintenance-reviewer skill before you report it as done, and when the user asks for a review. It reviews as a senior architect and Java developer: correctness first, then clean code, clean architecture, readability, and best practices, without over-engineering. Show its suggestions and apply them only after the user agrees.
OpenCode, oh-my-openagent, and any other agentic workflow must treat this file as the source of truth for this target project.
Tool-specific configuration may define models, providers, skills, UI behavior, or local preferences, but it must not override the development, testing, dependency, safety, or validation rules in this file.
When an installed skill fits the task, use it. If the skill is unavailable, follow the same rules manually and report the limitation.
Keep production code compatible with Java 8.
Do not use APIs or language features introduced after Java 8, including:
var- records
- switch expressions
- text blocks
- pattern matching
- sealed classes
List.of,Set.of,Map.ofOptional.isEmptyStream.toListjava.net.http.HttpClientFiles.readStringorFiles.writeString
Prefer Java 8-compatible alternatives and existing project patterns.
Do not modernize Java 8 production code just for style.
Keep changes small, focused, and reviewable.
Preserve existing behavior unless the user explicitly requests and approves a behavior change.
Before changing production code, prefer one of:
- A failing test that demonstrates the problem.
- A characterization test that documents current behavior.
- A narrow explanation of why the change is safe without a test.
Avoid broad refactors, formatting-only churn, and dependency upgrades that are not required for the task.
Treat these areas as behavior-sensitive:
- SOAP/XML namespaces, prefixes, element order,
SOAPAction, and payload formatting - JAXB behavior
- JSP, servlet, tag library, and container behavior
- REST and JSON request/response contracts
- JMS acknowledgement, retry, redelivery, listener concurrency, and transaction behavior
- JDBC SQL, transaction boundaries, isolation, connection handling, and generated keys
- JPA lazy loading, flush behavior, and transaction scope
- Spring profiles, configuration properties, XML context files, and bean lifecycle
- date, time, timezone, locale, charset, and
BigDecimalformatting - logging output used by monitoring or operations
- authentication, authorization, TLS, CORS, CSRF, deserialization, file handling, and external command execution
Do not silently change these behaviors.
If this project contains a web application, Playwright may be used for JSP/UI/runtime smoke tests, browser-based regression checks, login flow checks, form rendering, navigation checks, static asset checks, and Tomcat-rendered page validation.
Do not use Playwright as the first step.
Before using Playwright, verify:
- the project compiles
- the application starts locally
- the target URL is known
- required environment variables or test credentials are available
- the current Git branch is safe for the requested work
Prefer backend/build checks first:
java -versionmvn -vmvn testmvn package- Tomcat startup logs
Use Playwright only after the application is running or when the user explicitly requests UI/browser validation.
Do not click destructive actions, submit production forms, trigger payments, send real messages, delete data, or modify external systems.
For browser checks, prefer read-only smoke tests:
- open homepage
- verify HTTP status
- verify page title
- verify key text
- verify login page renders
- verify static assets load
- capture console errors
- capture network errors
- capture screenshots only when useful
Report UI/runtime findings separately as:
- JSP/runtime risk
- configuration risk
- behavioral risk
- test gap
Use Maven Wrapper when available:
./mvnw clean verifyOtherwise use Maven:
mvn clean verifyFor small changes, run the narrowest relevant validation first:
mvn -Dtest=ClassNameTest testThen broaden validation when the change affects shared behavior, dependency configuration, runtime wiring, public APIs, persistence, security, or deployment behavior.
If tests cannot be run, explain why and identify the command that should be run later.
openspec/specs/ is the source of truth for the behavior of this project. openspec/changes/ holds proposed and in-progress changes, and openspec/changes/archive/ holds applied changes. openspec/config.yaml adds project rules to every artifact.
Commands are spelled /opsx:<name> in Claude Code and /opsx-<name> in OpenCode; Codex uses the openspec-<name> skills. On the first container start with template bootstrap enabled, the devkit runs openspec init --tools opencode,claude,codex, which generates them in .claude/, .opencode/, and .agents/skills/ and keeps openspec/config.yaml; track those generated commands/ and skills/ folders in Git, together with the project-level opencode.json, .omo/omo.jsonc, and .claude/settings.json. Never relax their read denies for secret or key files.
Use OpenSpec for any change that alters observable behavior, contracts, or integrations:
- Explore with
/opsx:explorewhen the scope is unclear. - Propose with
/opsx:propose <change-name>. This createsproposal.md, delta specs,design.md, andtasks.md. Wait for human approval before implementation. - If a touched capability has no spec yet, run the
legacy-spec-baselineskill first so the delta is measured against verified current behavior. - Implement with
/opsx:apply, one verified checkpoint per task. - Archive with
/opsx:archiveonly after all tasks are complete and validated. Archiving merges the deltas intoopenspec/specs/and moves the change toopenspec/changes/archive/.
Run openspec validate --all --strict before you ask for review. Small fixes without behavior change (typos, formatting, dependency-free refactors with unchanged tests) do not need a change folder.
Every bug-fix ticket gets its own OpenSpec change:
- Name the change after the ticket:
<ticket-id>-<short-slug>, for examplewebart-21452-fix-api-key-check. Link the ticket inproposal.md. - If the affected capability has no spec yet, capture its current behavior first (
legacy-spec-baseline). - Write the fix as a delta spec: a
MODIFIEDrequirement, or anADDEDscenario that reproduces the bug (WHEN the failing input, THEN the correct result). - Add a failing test for that scenario before the fix; it must pass after the fix.
- Archive the change after the fix is validated, so
openspec/specs/describes the corrected behavior.
Before you set a new version (POM version, release branch, or tag), run check-release-version <version>. It checks release branches and tags in Git and the artifact in Nexus (NEXUS_REPOSITORY_URL, NEXUS_REPOSITORY_ID, RELEASE_ARTIFACT). Use the version only when it reports that it is free (exit code 0). If it cannot reach Nexus, stop and ask the user; never assume the version is free. Propose the next version from the latest release branch it reports.
OpenSpec is the only project knowledge base. There is no opencode/memory/ folder in this project.
- Before a broad codebase scan, read the relevant
openspec/specs/<capability>/spec.mdand the related archived changes inopenspec/changes/archive/. - Specs grow one capability at a time: capture a capability's current behavior (
legacy-spec-baseline) only when a change touches it. Do not bulk-generate specs. - Decisions live in each change's
proposal.mdanddesign.md, kept in the archive. - When the user asks what the project does or what changed, answer from the specs and the archive, and say which areas have no spec yet.
Use the installed devkit skills (OpenCode: ~/.config/opencode/skills/, Claude Code: ~/.claude/skills/) when they fit the task:
java-maintenance-reviewerfor code review: correctness, clean code, clean architecture, readability, and best practices, with improvement suggestions and no over-engineering.confluence-doc-writerfor human-facing documentation and Confluence exports.jms-characterization-test-writerfor JMS behavior tests.jpa-characterization-test-writerfor JPA behavior tests.jpa-performance-advisorfor JPA query and lazy-loading analysis.soap-contract-test-writerfor SOAP/XML contract tests.spring-boot-smoke-testerfor basic application smoke tests.readme-writerfor target-project README updates.legacy-spec-baselineto capture current behavior as OpenSpec specs before the first change to a capability.markdown-diagram-writerfor evidence-based Mermaid diagrams (architecture, flows, data models, migration plans) in Markdown.
Keep skill output aligned with this AGENTS.md.
Before implementation, load the installed git-commit skill. Plan small, independently reviewable changes and validate each checkpoint before starting unrelated work. Keep code and its tests together; split unrelated refactors, dependency upgrades and formatting. If the skill is unavailable, apply these rules directly and report that limitation.
When the user authorizes commits for the task, commit each verified logical checkpoint instead of accumulating one final large commit. Existing task authorization remains valid; do not ask again for each checkpoint. Otherwise keep changes uncommitted and report the proposed checkpoints. Never stage unrelated user changes, bypass hooks, rewrite history or push without explicit authorization.
Use verification-before-completion before claiming a checkpoint is validated. Use grill-me (and its grilling dependency) when the user asks to challenge a design; do not turn routine implementation into a mandatory interview. For Java 8 projects preserve javax APIs, existing Spring/Boot versions and SOAP wire contracts.
Community skill examples never authorize modifying another person's staged changes. Preserve the pre-existing index; if it contains unrelated work, keep the intended checkpoint separate and ask only when ownership is ambiguous. A skill does not authorize commits or publication by itself.