Spring Boot Copilot

GitHub Copilot skills and verification for Java 25, Spring Boot 4, and Maven. The rules target recent framework changes and recurring coding mistakes. Each rule states when it applies, shows a correction, documents exceptions, and explains how to verify it.

The plugin follows each application's architecture documents and ArchUnit tests. It works with layered MVC, hexagonal, and mixed-module repositories. Modules that declare hexagonal or clean architecture roles also get rules for dependency direction, aggregates, use cases, SOLID decisions, and design patterns, plus an import-direction check.

What is included

There are 56 rules with 88 primary sources, a rule index, and 56 evaluation tasks. SOLID, Clean Code, and design patterns are applied through concrete decisions and exceptions; the plugin does not require an interface, factory, or extra layer for every class.

Java defaults include records for value-like DTOs/domain data, clear var locals, declarative transformations, sealed domain variants with exhaustive switches, and named validators for reusable domain rules. Every rule has explicit exceptions and verification guidance. The Java 11–25 index routes newer syntax and API choices to their version-specific contracts.

Clean and hexagonal architecture

clean-architecture turns the layout used by the Full Cycle FC3 subscription service and its Java 25 / Boot 4 descendants into 25 rules in seven categories, ordered by impact like Vercel's React best-practices skill:

Rules talk about roles (domain, application, adapter, configuration) rather than folders. init detects common layouts, including split domain/application/infrastructure Maven modules, and drafts the mapping for review. The read-only boundaries command then reports imports that point outward or bring Spring, Jakarta, Jackson, or Hibernate into the core:

node <plugin-root>/dist/cli.mjs boundaries --root .

The PostToolUse hook runs the same check after edits and gives the agent the violating file and line. It inspects import declarations only and does not replace architecture tests. See the usage guide, the role mapping, and the vertical-slice walkthrough.

COBOL migration and repair

The new skill covers characterization, domain responsibilities, state lifetime, decimal arithmetic, copybook boundaries, transactions, batch restart, and equivalence evidence. Read the usage guide and research findings. Existing architecture rules still govern placement.

node /absolute/path/to/springboot-plugin/dist/cli.mjs migration-audit --root /path/to/application --path src/main/java

The read-only scanner reports review candidates and limitations. A successful scan is not an acceptance gate; confirmed repairs need behavioral tests and the configured Maven/ArchUnit checks.

Updating from 0.1, 0.2 or 0.3

Version 0.4 adds clean-architecture, the boundaries command, and architecture roles in .springboot-agent/project.json. Rerun init --root <application> to preview detected roles: an existing configuration is never rewritten, and the preview lists them under suggestedArchitecture. Copy the reviewed style, roles, and frameworkFree fields into the module, then run init --apply to refresh the managed instruction block.

Version 0.3 adds cobol-to-springboot, its audit command, and synthetic regression fixtures. Rerun init --root <application> --apply to refresh the managed skill index after updating.

Version 0.2 merges java-best-practices into springboot-best-practices. Update the plugin, rerun init --root <application> --apply to refresh its managed instruction block, and start a fresh Copilot session. Existing project configuration and unmanaged instructions are preserved. Update any manually authored pointers to the former skill.

Install locally

Requirements: Node.js 22.17+ on the host's PATH; the consuming application's Maven/JDK and existing quality tools. The checked-in dist/cli.mjs includes its runtime dependencies, so plugin users do not need to run npm install.

Copilot CLI

Load this checkout for one session:

copilot --plugin-dir /absolute/path/to/springboot-plugin

Recent CLI versions also support persistent installation from a local path:

copilot plugin install /absolute/path/to/springboot-plugin

Use --plugin-dir if your CLI's install command does not accept local paths. Start a fresh session after changing repository instructions. The plugin uses the Agent Plugins 1.0 package layout.

VS Code

Add the checkout to your VS Code settings:

{
  "chat.plugins.enabled": true,
  "chat.pluginLocations": {
    "/absolute/path/to/springboot-plugin": true
  }
}

VS Code also discovers plugins installed through Copilot CLI. These installation mechanisms are documented in VS Code's plugin guide. Confirm the five skills appear in Chat: Configure Skills and that hooks are enabled for the selected harness. See the tested compatibility and limitations.

Connect an application

Run from the application's Maven reactor root. Replace <plugin-root> with the installed plugin directory.

node <plugin-root>/dist/cli.mjs inspect --root .
node <plugin-root>/dist/cli.mjs inspect --root . --resolve
node <plugin-root>/dist/cli.mjs init --root .
node <plugin-root>/dist/cli.mjs init --root . --apply

inspect reads local POMs. --resolve invokes Maven to resolve effective POMs using the active build configuration; it may download dependencies/plugins. Static results explicitly remain partial.

init previews changes. --apply creates .springboot-agent/project.json, adds a small managed block to .github/copilot-instructions.md, and ignores local reports/cache. It preserves existing instructions and an existing project configuration. When package names show a domain/application/infrastructure (or ports/adapters) layout, the draft includes architecture.style and architecture.roles; review them against the architecture documents and remove them from modules that do not follow them.

Review the generated configuration before relying on it. Confirm module architecture links, required test suites, ArchUnit execution, and existing lint bindings. Initialization cannot determine whether a custom CI profile is mandatory. Add separate required JUnit report patterns for important suites so other passing tests cannot hide a suite that never ran. See configuration and validation and example configuration.

Then verify:

node <plugin-root>/dist/cli.mjs verify --root . --tier complete
node <plugin-root>/dist/cli.mjs evidence --root .

Commands produce JSON and return nonzero for failure or incomplete evidence. Reports and diagnostic logs live in .springboot-agent/reports/. Optional SonarQube checks use a separate remote tier.

How context and correction work

flowchart LR
  A[Small repository instruction index] --> B[Relevant skill]
  B --> C[Matching rules and version sources]
  B --> D[Module architecture docs and ArchUnit]
  C --> E[Code change]
  D --> E
  E --> R[Boundary check for mapped roles]
  R --> F[Configured Maven and quality checks]
  F --> G{Current evidence passes?}
  G -->|No| H[Diagnose and repair within scope]
  H --> F
  G -->|Yes| I[Completion report]

Hooks supply context after changes and request verification at completion, with a bounded repair loop. Heavy builds run through the shared verifier. Required repository CI checks independently rerun validation for the submitted revision. Local hooks can be disabled or time out, so they cannot replace CI acceptance.

The verifier rejects stale JUnit reports, zero executed tests for required suites, skipped Maven tests, timeouts, missing tools, and unavailable required evidence. It fingerprints repository inputs and configuration, preserving separate focused, complete, and remote reports. A Sonar gate must belong to an analysis submitted during the same run.

Documentation and version maintenance

List sources without accessing the network, or explicitly cache one:

node <plugin-root>/dist/cli.mjs docs --root .
node <plugin-root>/dist/cli.mjs docs --root . --fetch boot4-migration

The cache records the URL, scope, retrieval time, SHA-256, discovered project versions, and Maven input fingerprint in .springboot-agent/docs.lock.json. POM and repository Maven configuration changes mark entries stale. Rolling references are labeled as such; a downloaded page is not proof of exact patch compatibility. Rules use the application's resolved versions and do not automatically upgrade its dependencies.

See maintaining rules and releases. Sources were reviewed on 2026-09-28; “latest” requires continued review.

Develop this plugin

npm ci --ignore-scripts
npm run check
npm run test:fixtures
npm run test:java-patterns
npm run test:cobol-migration
npm run test:clean-architecture

check validates catalogs, links and evaluation coverage, runs Node behavior tests, and rebuilds the distributable. Fixture tests need Java 25 and Maven. They build two Boot 4.1.1 applications, deliberately violate each architecture, confirm failures, and confirm recovery in a disposable workspace.

test:java-patterns uses Java 25 without preview flags to verify record ownership, inference, stream/collection contracts, sealed switches, domain invariants, and modern APIs. It also requires deliberate regressions to fail, including a compiler error for a new unhandled sealed variant.

test:cobol-migration verifies synthetic decimal, record, predicate, and state contracts with four deliberate regressions. It does not establish equivalence with an actual COBOL application.

test:clean-architecture compiles a synthetic aggregate, use case, gateway, and strategy registry with Java 25 and no preview flags. Nine deliberate regressions must fail: an event on rehydration, fail-fast validation, a save after errors, an allowed illegal transition, a fake that breaks the port contract, an unhandled sealed state, an instance call before super(), a new per-state status that omits a transition, and a delivery status that regresses on an out-of-order receipt. It then injects outward imports into the Maven fixture's hexagonal domain and requires the boundary check to report them.

The CI workflow runs these checks and rejects outdated generated artifacts. Model comparison tasks and scoring instructions are in evals; no measured improvement in model behavior is claimed yet.

MIT license. Bundled dependency notices are in dist/THIRD-PARTY-NOTICES.txt.