spring-boot-team-harness
Use when a team wants every developer's coding agent (Claude Code or Codex) to follow the same rules on a Maven or Gradle Spring Boot 4 repository: setting up AGENTS.md, guardrails, shared agent settings, or build and CI checks that agents must pass before code merges. It adds ./
Install
npx skills add https://github.com/a-pavithraa/springboot-skills-marketplace/tree/main/plugins/springboot-architecture/skills/spring-boot-team-harness
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install a-pavithraa-springboot-skills-marketplace@llmmart
git clone https://github.com/a-pavithraa/springboot-skills-marketplace.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole a-pavithraa/springboot-skills-marketplace collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
Spring Boot team harness
The harness steers the agent in three places. AGENTS.md tells it how this repository works before it starts. Hooks check its work before a turn ends, so it fixes its own mistakes. ./mvnw verify (./gradlew build on Gradle) in CI holds the same gates for every developer and every tool. Rules live in the build wherever they can: a gate holds whoever writes the code and costs no context.
Apply it
Run the script from the project root. Preview with
--dry-runfirst:python3 ${CLAUDE_SKILL_DIR}/scripts/apply_harness.py . --dry-run python3 ${CLAUDE_SKILL_DIR}/scripts/apply_harness.py .${CLAUDE_SKILL_DIR}is this skill's folder. Codex doesn't set it, so there use the folder thisSKILL.mdis in. Run it in the folder with thepom.xml, or thebuild.gradleorbuild.gradle.kts. On Gradle, the gates go ingradle/harness.gradle, which the harness owns like its tests, so a rerun updates it while nobody has edited it; the build file gets one line that applies it, and the team'splugins {}block stays as it is. A build's own Spotless stays as it is, as on Maven; the script only narrows it to the session's files for the Stop hook. It stops on a multi-project build, and when the build already applies Error Prone: remove that, or mergeassets/gradle/harness.gradleby hand. Starters are found in the build file andgradle/libs.versions.toml. The rest of this skill names the Maven commands; on Gradle they are./gradlew buildforverify,harnessCheckfor the Stop hook's gates, andspotlessApply(orformat) for the formatter. When that folder is inside a larger repository (for examplebackend/next tofrontend/), the CI workflow,.claude/settings.json, the hooks and.gitattributesgo to the repository root, where GitHub and Claude Code read them, and the rootAGENTS.mdgets a line pointing to the project's own. The Stop hook then reacts only to changes in that folder.The observability pack comes by default: dependencies, safe defaults, a local Grafana stack, Service health and JVM dashboards, a filter that logs and marks every handled 5xx, a test check that fails on logged emails and credentials, and
docs/observability.md. Telemetry stays off in deployments untilOTLP_EXPORT_ENABLED=true. It narrowsmanagement.endpoints.web.exposure.includeto what's safe on the public port, and says so. Pass--no-observabilityto skip it.Pass
--no-moduleswhen the base package's subpackages are layers (controller,service,domain) rather than modules; Spring Modulith would report them as cycles. Rerunning with--no-modulesafter a run without it removesModuleBoundariesTestsand theadd-moduleskill unless they were edited, and names what to remove fromAGENTS.mdby hand.NullAway checks every class under the base package by default. On an existing codebase with many null findings, offer
--nullaway marked: NullAway then checks only packages whosepackage-info.javahas@NullMarked, so the team adopts null-safety one package at a time instead of marking classes@NullUnmarkedacross the codebase. The script reports how many packages are marked. With none, NullAway checks nothing, so mark at least the packages the team changes most. A rerun keeps the pom's mode unless--nullawayis passed again. Switch to--nullaway allonce every package is marked.It adds only what the project lacks. In the pom, it skips any property, dependency or plugin that is already declared, so an existing Spotless or Spring Modulith setup stays as it is. It adds
CLAUDE.md(one line,@AGENTS.md),.claude/settings.jsonand its two hook scripts,.codex/hooks.json, which registers the same scripts for Codex,.mvn/jvm.config, the three tests, a CI workflow, the CI integrity check, and project skills in both.claude/skills/and.agents/skills/. It merges its permissions, hooks and plugin into an existing.claude/settings.json, and its hooks into an existing.codex/hooks.json, adds its CI workflow only when no workflow runs Maven (asharness-verify.ymlifverify.ymlis taken), appends its gate section to an existingAGENTS.md, skips the boundary test when a test already callsApplicationModules.of(...), and never overwrites a file the team has edited. Rerun it after updating this plugin: it adds the pieces the project is missing and updates the files it owns (hooks, tests, project skills, its workflow) that nobody has changed since, which it tracks in.claude/harness.lock. It reports each edited one so you can merge the new version by hand. It raises the tool versions it pinned in its own pom blocks (theharness:begin propertiesblock and ArchUnit's) to this release's, keeps a version the team raised further, and names each one it raised: run./mvnw verifyafter, since a newer Error Prone or NullAway can find new errors. It replaces its own hook entries in.claude/settings.jsonand.codex/hooks.json, the ones that run a script under.claude/hooks/, with this release's, and leaves the team's hooks alone. Don't copy harness files into a project by hand: rerun the script instead. A rerun also fills in template placeholders left inAGENTS.md, and reports anarchunit.propertiesthat allows store creation. If<build><plugins>already configuresmaven-compiler-plugin, it stops: merge that part ofassets/pom/plugins.xmlby hand and run it again.Run
./mvnw spotless:apply(spring-javaformat:applyon a project that uses Spring Java Format: the script adds no Spotless there, andbaseline.py, the Stop hook andAGENTS.mduse the project's formatter; the hook only checks the session's files, since Spring Java Format can't format some files alone) and commit the result on its own, so the reformat stays out of later diffs. On an existing codebase, add that commit's hash to.git-blame-ignore-revssogit blameskips it.Get
./mvnw verifygreen. New code must meet the gates; code that already fails them is recorded, not rewritten:- If there are only a few findings, fix them with the user. Each NullAway finding is a question about what a missing value means, so don't guess.
- Otherwise run
python3 ${CLAUDE_SKILL_DIR}/scripts/baseline.py .. It marks each class NullAway rejects today@NullUnmarked, records today'sCodeRulesTestsviolations insrc/test/resources/archunit_store, and today's module-boundary violations insrc/test/resources/modulith_store. New classes are checked in full, and a fixed violation drops out of the record. NullAway skips all of a marked class, including code added to it later, so remove@NullUnmarkedfrom a class once it's fixed; the templateAGENTS.mdtells agents to try when they change one. When an update of the harness adds rules, runbaseline.pyagain: a rule the record doesn't list fails on existing code too, and the rerun records only the new rules' violations. Don't suppress warnings or skip tests to get green. The Stop hook only blocks on problems in files the agent changed, but untilverifyis green it can't fully check those either.
Draft the
Modules,Run and testandTeam conventionssections ofAGENTS.mdfrom the code, then go through them with the user. Read the packages, the pom, compose files, the test setup, and repeated patterns such as error handling, DTO mapping and naming. Write only what an agent would get wrong without being told: one line per module, naming the section of the project's glossary (GLOSSARY.mdorCONTEXT.md) it owns, the commands and services the app needs, and the conventions the code follows. Mark each convention you inferred(inferred); the user confirms or deletes it. Leave out generic Spring advice and anything the code makes obvious, and keep the file short: every session reads all of it.Commit everything, including
.claude/settings.json, the marked classes andarchunit_store.On an existing codebase, find the files where comments make up a large share of the lines, often DTOs and records. Agents write comments as densely as the code they read, so the comment rule in
AGENTS.mdholds only once those files follow it. Offer to prune them module by module, each module in its own pull request, withcode-reviewer's comment pass: it changes only comments.Offer a project verification skill, which proves behaviour the gates can't see. Read the repository and recommend one generator from pstack. Only the user can start them:
- The app has a UI, or signs users in with
oauth2Login:/pstack:create-verification-skill. It generates a skill that drives the real app and saves evidence. For a browser app, tell it to followreferences/browser-verification.md. - The riskiest code is a state machine, retries, idempotency or concurrent updates:
/pstack:create-formal-verification-skill. It checks one property of that code against every case in a stated scope. - Both apply: start with the first; the second can follow in its own pull request.
If the project has
docs/observability.md, tell the generator to read it, so journeys also check for server errors the page hides. If pstack isn't installed, say so and skip this step. Adding the skill toAGENTS.mddoesn't make agents use it. They verify when the task asks for proof, so tell the team to ask for it in the task.
- The app has a UI, or signs users in with
What each piece does
| File | Effect |
|---|---|
AGENTS.md |
Instructions both Claude Code and Codex read. Says that done means ./mvnw verify passed, and how to fix each gate |
CLAUDE.md |
Imports AGENTS.md for Claude Code versions that don't read it directly |
REVIEW.md |
At the repository root, for reviewers: the failures the code doesn't show, which changes are high risk, what not to report, and how to report. The code-reviewer skill and Claude Code's GitHub review read it. Added only when missing; the team fills in the failures, one line each time a review misses a bug |
.claude/settings.json |
Lets ./mvnw run without prompts, blocks reading .env files, enables this plugin for every teammate with this marketplace set to update itself, and registers the hooks. For the other skills the team uses, each developer runs install.py from this marketplace once |
.codex/hooks.json |
Registers the same two hook scripts for Codex: the guard on Bash and apply_patch, the check on SessionStart and Stop. Codex runs them only after each developer trusts them with /hooks, and asks again whenever the file changes |
.claude/hooks/verify-on-stop.sh |
SessionStart and Stop hook, for Claude Code and Codex. It records the code each session starts from. When a turn ends and the session has changed the code under src or pom.xml, committed or not, it formats the code and runs the gates that need no Docker (compile with NullAway, CodeRulesTests, ConfigurationKeysTests, BuildSetupTests, the module and ArchUnit tests). It blocks the turn only on errors in files the session changed, so the agent fixes its own mistakes and never code it didn't touch; when the build fails only elsewhere, it tells the user the change couldn't be fully verified. A formatting failure blocks too. It skips code that already passed, and gives up after one failed retry on the same code. In a session with no recorded starting point, such as one that began before the hooks were installed, it tells the user the turn wasn't checked instead of passing it silently. A session that changes no code costs nothing; a check takes 25 to 75 s |
.claude/hooks/guard.sh |
PreToolUse hook, for Claude Code and Codex (which edits files with apply_patch; the hook reads each file the patch updates, deletes or moves to). Refuses git push --force, git reset --hard, git clean -f, edits to a Flyway migration that is already on the main branch, edits to the ArchUnit freeze record or modulith_store, any edit or shell write to a module's package-info.java, since telling a widening edit from a harmless one would take parsing Java (creating one for a new module passes), and edits to the rule tests (CodeRulesTests, ConfigurationKeysTests, BuildSetupTests, ModuleBoundariesTests, LogLeakCheck, and progen's ArchUnitTests and ModularityTests). A developer changes a rule by hand. It also refuses Bash commands that write to those files and the Maven flags that record violations as accepted (allowStoreCreation=true, freeze.refreeze=true, modulith.store.record=true). It is advisory, not a boundary: a command it doesn't recognise gets through, so harness-integrity.yml backs it up in CI |
scripts/report.py |
Summarises what the hooks did in this clone: turns checked, passed and blocked, blocks by gate, how many the agent fixed, check times, and what the guard refused. Both hooks append one line per run to .git/harness/events.jsonl (no paths, commands or file contents; capped at 2000 lines). Run python3 ${CLAUDE_SKILL_DIR}/scripts/report.py . when the team asks whether the hooks are worth their time |
scripts/baseline.py |
For an existing codebase: marks the classes NullAway rejects today @NullUnmarked, records today's CodeRulesTests violations, and records today's ModuleBoundariesTests violations in modulith_store, so verify passes while new code is held to the gates |
ConfigurationKeysTests |
Fails on spring., management., server. and logging. keys that no dependency defines, or that are deprecated. Boot ignores those keys silently |
BuildSetupTests |
Fails on shortcuts that pass the tests while production runs without the feature: a Boot starter or module in test scope, spring-boot-autoconfigure-classic, Flyway migrations without spring-boot-starter-flyway (Boot 4 doesn't run them with flyway-core alone), unless the app builds Flyway itself, and, when the project has migrations, ddl-auto set to create or update the schema or code that writes flyway_schema_history |
UnusedCodeTests |
Fails on a non-private method that only tests call: dead code its tests keep alive, or an internal opened up so a test can look inside. Getters, Spring entry points, overrides and methods named in @PreAuthorize expressions are left out. It runs in verify but not in the Stop hook, because a service is often written and tested before anything calls it |
ModuleBoundariesTests |
Spring Modulith's checks: no use of another module's internal types, no cycles, no dependency that a module's allowedDependencies leave out. It also fails on what verify() lets through: a published class whose public constructor takes an internal type, and an allowedDependencies entry no code uses (the guard hook stops an agent widening the list, but an unused entry is already open to it). An @ApplicationModuleTest checks the module's boundaries again when it starts, without the record, so on an existing codebase set verifyAutomatically = false on module tests and leave the boundaries to this test. Violations listed in src/test/resources/modulith_store are tolerated. Each is keyed by what it is, not by line: a cycle by its modules, so another call along a recorded cycle passes while a new cycle fails; a disallowed dependency by its two modules; an internal-type access by caller and callee. A fixed violation drops out of this violation record when the test runs. Only baseline.py adds to it. IntelliJ IDEA Ultimate's Spring Modulith plugin flags internal-type access and disallowed dependencies in the editor, but not cycles and not the violation record, so recorded violations still show red there. Declaring allowedDependencies on each module gives developers the editor warning before the build fails |
CodeRulesTests |
ArchUnit rules for mistakes that compile and pass most tests: a class calling its own @Transactional, @Async, @Cacheable or @Retryable method (the proxy is skipped), controllers that start transactions, use repositories, or take or return JPA entities, @Retryable or @ConcurrencyLimit with nothing switching them on, @ManyToMany fields that aren't a Set (with a List, removing one element rewrites every join row), @ManyToOne and @OneToOne without fetch = LAZY, enum columns stored by position, a @Transactional method calling an HTTP client, an HTTP interface or an AWS SDK client, directly or through the project's own classes (it holds a database connection for the whole call), RestClient.create(), WebClient.create(), new RestTemplate(), or the static builder() in a class that sets no request factory (no timeouts), proxy annotations on private, final or static methods, @Async or @Scheduled with nothing switching them on, services that throw ResponseStatusException, use the servlet API or return ResponseEntity, @Deprecated code outside controllers (update the callers and delete it), @Autowired fields, System.out, Jackson 2 (Boot 4 ignores it), Spring's deprecated nullness annotations, JUnit 4 tests (never run), and @Disabled tests. Each failure message says how to fix it. It uses the project's ArchUnit or Taikai, and adds ArchUnit only when neither is declared |
.github/workflows/harness-integrity.yml, .github/harness/check-protected.sh |
Fails a pull request that adds entries to the ArchUnit freeze record or modulith_store, widens a module's rules in package-info.java (adds to or removes allowedDependencies, lists an entry that isn't a quoted module name, such as a constant, or changes the module's type; dropping entries passes), changes archunit.properties, changes or deletes an existing rule test, changes or deletes a migration on the base branch, changes the hooks or this check, unregisters a harness hook or narrows its matcher in .claude/settings.json or .codex/hooks.json, changes the harness's plugin block in the pom (NullAway, Spotless) or gradle/harness.gradle, stops a Gradle build file applying that script, removes a line from .mvn/jvm.config, changes or deletes the verify workflow the harness added, or stops LogLeakCheck running by unregistering it or turning off extension autodetection, whichever tool made the change. Removing fixed violations from the record and adding new migrations or rule tests pass, and so do other edits to those two JUnit files, which aren't checked at all in a project without LogLeakCheck. It runs the base branch's copy of the script, so a pull request can't weaken it. A maintainer accepts an intended change, such as a harness update, with the harness-rule-change label; the files are still listed for the reviewer. Make it a required status check and put .github/ and the rule tests under CODEOWNERS. Added for every project, also when CI already runs Maven |
.github/workflows/verify.yml |
Runs ./mvnw verify on every pull request, so the gates hold for code nobody ran locally. Added only when no workflow already runs mvnw |
gradle/harness.gradle |
On Gradle, the pom gates below, plus harnessCheck, the task the Stop hook runs, and a report of the declared dependencies that BuildSetupTests reads, since a Gradle build file can't be read from Java. Only baseline.py passes -Pharness.record=true, which turns on both record flags; the guard refuses it |
| pom gates | NullAway in JSpecify mode on main code at compile time (tests are excluded, since they routinely dereference response bodies), Spotless check (none on a project with Spring Java Format, which keeps its own) |
| Project skills | add-module (module layout and test, for module-based projects), move-code (moves a class or package with OpenRewrite's ChangeType or ChangePackage, which update imports, Javadoc links, properties values and META-INF/services entries; it then greps for the old name, since class names in Java string literals stay, and runs verify, which catches package-private code left behind. Agents can't call IntelliJ's move refactoring: its MCP server offers only rename) and db-migration (Flyway naming and safe changes, when the pom uses Flyway). Each tool sees only their names and descriptions until one is used |
Limits
- Single-project builds only: a Maven project, or a Gradle build in Groovy or Kotlin DSL. A Gradle build that includes other projects needs the script applied to each by hand.
- On Gradle, javac runs on the toolchain's JDK, so Error Prone needs a toolchain of 21.0.8 or later. With an older toolchain, build on a newer JDK and set
options.releaseinstead. - Error Prone needs JDK 21.0.8 or later to build. Projects that set up the compiler plugin before the
-XDaddTypeAnnotationsToSymbol=trueargument was added need it added by hand to build on JDK 21. - Codex runs the project's hooks only once the developer trusts the project's
.codex/folder and the hooks themselves with/hooks. It records trust against each hook's hash, so a rerun of the script that changes.codex/hooks.jsonmeans every developer trusts it again. Until then Codex sessions getAGENTS.md, the project skills and the CI gates. - The hooks are bash scripts. On Windows, Claude Code runs them with Git for Windows; without it they fail. Codex 0.166 on Windows runs them the same way.
- The hooks refuse and block by printing a decision as JSON (
permissionDecision: deny,decision: block), which both tools honour; Codex 0.166 let anapply_patchedit through when the guard exited 2. - The integrity check reads the hook registrations with
python3, which GitHub'subuntu-latestrunners have. - Tool versions are pinned in the pom properties and move only when the plugin is updated and the script rerun. To move one sooner, raise it in the pom and run
./mvnw verify; a rerun keeps a version newer than the harness's. On Gradle they are pinned ingradle/harness.gradle, which a rerun replaces while nobody has edited it and keeps as it is once someone has.
MCP servers
Add none by default. Each server's tool definitions take context in every session, and the gates above need none. If the team already runs SonarQube, its MCP server (sonarsource/sonarqube-mcp) can show issues and quality gates. It needs a SonarQube Cloud or Server token and Docker. Limit it with SONARQUBE_TOOLSETS=issues,quality-gates and SONARQUBE_READ_ONLY=true, and keep the token in each developer's environment, never in the repository.
Files (springboot-skills-marketplace)
-
assets
-
gradle
-
harness.gradle 5.3 KB · in bundle
-
-
observability
-
dashboards
-
jvm-resources.json 7.7 KB
Loading… -
service-health.json 10.7 KB
Loading…
-
-
application-observability-defaults.yml 1.9 KB
Loading… -
application-observability.yml 445 B
Loading… -
check_dashboards.py 3.4 KB
Loading… -
check_request.py 6.6 KB
Loading… -
compose.observability.yml 704 B
Loading… -
grafana-provider.yaml 133 B
Loading… -
HandledFailureFilter.java 2.1 KB · in bundle
-
InstallOpenTelemetryAppender.java 877 B · in bundle
-
logback-spring.xml 736 B · in bundle
-
LogLeakCheck.java 3.3 KB · in bundle
-
observability.md 7.4 KB
Loading…
-
-
pom
-
dependencies.xml 236 B · in bundle
-
managed-dependencies.xml 355 B · in bundle
-
modules-dependencies.xml 269 B · in bundle
-
observability-dependencies.xml 833 B · in bundle
-
plugins.xml 2 KB · in bundle
-
properties.xml 642 B · in bundle
-
rules-dependencies.xml 268 B · in bundle
-
-
project
-
.claude
-
hooks
-
guard.sh 6.7 KB
Loading… -
verify-on-stop.sh 11.3 KB
Loading…
-
-
settings.json 1.4 KB
Loading…
-
-
.codex
-
hooks.json 858 B
Loading…
-
-
.github
-
harness
-
check-protected.sh 10 KB
Loading…
-
-
workflows
-
harness-integrity.yml 1.1 KB
Loading… -
verify.yml 440 B
Loading…
-
-
-
.mvn
-
jvm.config 644 B · in bundle
-
-
AGENTS.md 9.6 KB
Loading… -
CLAUDE.md 11 B
Loading… -
REVIEW.md 2.6 KB
Loading…
-
-
project-skills
-
add-module
-
SKILL.md 2.3 KB
Loading…
-
-
db-migration
-
SKILL.md 1.6 KB
Loading…
-
-
move-code
-
SKILL.md 3.3 KB
Loading…
-
-
-
tests
-
archunit.properties 106 B · in bundle
-
BuildSetupTests.java 11.1 KB · in bundle
-
CodeRulesTests.java 36.9 KB · in bundle
-
ConfigurationKeysTests.java 13 KB · in bundle
-
ModuleBoundariesTests.java 8.6 KB · in bundle
-
UnusedCodeTests.java 7.3 KB · in bundle
-
-
-
references
-
browser-verification.md 18.1 KB
Loading…
-
-
scripts
-
apply_harness.py 56.8 KB
Loading… -
baseline.py 8.9 KB
Loading… -
report.py 6.1 KB
Loading…
-
-
SKILL.md 22.5 KB
--- name: spring-boot-team-harness description: "Use when a team wants every developer's coding agent (Claude Code or Codex) to follow the same rules on a Maven or Gradle Spring Boot 4 repository: setting up AGENTS.md, guardrails, shared agent settings, or build and CI checks that agents must pass before code merges. It adds ./mvnw verify or ./gradlew build gates that fail on null-safety bugs (NullAway with JSpecify), module-boundary breaches (Spring Modulith), unknown or deprecated Boot property keys, Spring mistakes that compile (ArchUnit) and unformatted code, Claude Code and Codex hooks that run those gates before a turn ends, and a CI workflow." --- # Spring Boot team harness The harness steers the agent in three places. `AGENTS.md` tells it how this repository works before it starts. Hooks check its work before a turn ends, so it fixes its own mistakes. `./mvnw verify` (`./gradlew build` on Gradle) in CI holds the same gates for every developer and every tool. Rules live in the build wherever they can: a gate holds whoever writes the code and costs no context. ## Apply it 1. Run the script from the project root. Preview with `--dry-run` first: ```bash python3 ${CLAUDE_SKILL_DIR}/scripts/apply_harness.py . --dry-run python3 ${CLAUDE_SKILL_DIR}/scripts/apply_harness.py . ``` `${CLAUDE_SKILL_DIR}` is this skill's folder. Codex doesn't set it, so there use the folder this `SKILL.md` is in. Run it in the folder with the `pom.xml`, or the `build.gradle` or `build.gradle.kts`. On Gradle, the gates go in `gradle/harness.gradle`, which the harness owns like its tests, so a rerun updates it while nobody has edited it; the build file gets one line that applies it, and the team's `plugins {}` block stays as it is. A build's own Spotless stays as it is, as on Maven; the script only narrows it to the session's files for the Stop hook. It stops on a multi-project build, and when the build already applies Error Prone: remove that, or merge `assets/gradle/harness.gradle` by hand. Starters are found in the build file and `gradle/libs.versions.toml`. The rest of this skill names the Maven commands; on Gradle they are `./gradlew build` for `verify`, `harnessCheck` for the Stop hook's gates, and `spotlessApply` (or `format`) for the formatter. When that folder is inside a larger repository (for example `backend/` next to `frontend/`), the CI workflow, `.claude/settings.json`, the hooks and `.gitattributes` go to the repository root, where GitHub and Claude Code read them, and the root `AGENTS.md` gets a line pointing to the project's own. The Stop hook then reacts only to changes in that folder. The observability pack comes by default: dependencies, safe defaults, a local Grafana stack, Service health and JVM dashboards, a filter that logs and marks every handled 5xx, a test check that fails on logged emails and credentials, and `docs/observability.md`. Telemetry stays off in deployments until `OTLP_EXPORT_ENABLED=true`. It narrows `management.endpoints.web.exposure.include` to what's safe on the public port, and says so. Pass `--no-observability` to skip it. Pass `--no-modules` when the base package's subpackages are layers (`controller`, `service`, `domain`) rather than modules; Spring Modulith would report them as cycles. Rerunning with `--no-modules` after a run without it removes `ModuleBoundariesTests` and the `add-module` skill unless they were edited, and names what to remove from `AGENTS.md` by hand. NullAway checks every class under the base package by default. On an existing codebase with many null findings, offer `--nullaway marked`: NullAway then checks only packages whose `package-info.java` has `@NullMarked`, so the team adopts null-safety one package at a time instead of marking classes `@NullUnmarked` across the codebase. The script reports how many packages are marked. With none, NullAway checks nothing, so mark at least the packages the team changes most. A rerun keeps the pom's mode unless `--nullaway` is passed again. Switch to `--nullaway all` once every package is marked. It adds only what the project lacks. In the pom, it skips any property, dependency or plugin that is already declared, so an existing Spotless or Spring Modulith setup stays as it is. It adds `CLAUDE.md` (one line, `@AGENTS.md`), `.claude/settings.json` and its two hook scripts, `.codex/hooks.json`, which registers the same scripts for Codex, `.mvn/jvm.config`, the three tests, a CI workflow, the CI integrity check, and project skills in both `.claude/skills/` and `.agents/skills/`. It merges its permissions, hooks and plugin into an existing `.claude/settings.json`, and its hooks into an existing `.codex/hooks.json`, adds its CI workflow only when no workflow runs Maven (as `harness-verify.yml` if `verify.yml` is taken), appends its gate section to an existing `AGENTS.md`, skips the boundary test when a test already calls `ApplicationModules.of(...)`, and never overwrites a file the team has edited. Rerun it after updating this plugin: it adds the pieces the project is missing and updates the files it owns (hooks, tests, project skills, its workflow) that nobody has changed since, which it tracks in `.claude/harness.lock`. It reports each edited one so you can merge the new version by hand. It raises the tool versions it pinned in its own pom blocks (the `harness:begin properties` block and ArchUnit's) to this release's, keeps a version the team raised further, and names each one it raised: run `./mvnw verify` after, since a newer Error Prone or NullAway can find new errors. It replaces its own hook entries in `.claude/settings.json` and `.codex/hooks.json`, the ones that run a script under `.claude/hooks/`, with this release's, and leaves the team's hooks alone. Don't copy harness files into a project by hand: rerun the script instead. A rerun also fills in template placeholders left in `AGENTS.md`, and reports an `archunit.properties` that allows store creation. If `<build><plugins>` already configures `maven-compiler-plugin`, it stops: merge that part of `assets/pom/plugins.xml` by hand and run it again. 2. Run `./mvnw spotless:apply` (`spring-javaformat:apply` on a project that uses Spring Java Format: the script adds no Spotless there, and `baseline.py`, the Stop hook and `AGENTS.md` use the project's formatter; the hook only checks the session's files, since Spring Java Format can't format some files alone) and commit the result on its own, so the reformat stays out of later diffs. On an existing codebase, add that commit's hash to `.git-blame-ignore-revs` so `git blame` skips it. 3. Get `./mvnw verify` green. New code must meet the gates; code that already fails them is recorded, not rewritten: - If there are only a few findings, fix them with the user. Each NullAway finding is a question about what a missing value means, so don't guess. - Otherwise run `python3 ${CLAUDE_SKILL_DIR}/scripts/baseline.py .`. It marks each class NullAway rejects today `@NullUnmarked`, records today's `CodeRulesTests` violations in `src/test/resources/archunit_store`, and today's module-boundary violations in `src/test/resources/modulith_store`. New classes are checked in full, and a fixed violation drops out of the record. NullAway skips all of a marked class, including code added to it later, so remove `@NullUnmarked` from a class once it's fixed; the template `AGENTS.md` tells agents to try when they change one. When an update of the harness adds rules, run `baseline.py` again: a rule the record doesn't list fails on existing code too, and the rerun records only the new rules' violations. Don't suppress warnings or skip tests to get green. The Stop hook only blocks on problems in files the agent changed, but until `verify` is green it can't fully check those either. 4. Draft the `Modules`, `Run and test` and `Team conventions` sections of `AGENTS.md` from the code, then go through them with the user. Read the packages, the pom, compose files, the test setup, and repeated patterns such as error handling, DTO mapping and naming. Write only what an agent would get wrong without being told: one line per module, naming the section of the project's glossary (`GLOSSARY.md` or `CONTEXT.md`) it owns, the commands and services the app needs, and the conventions the code follows. Mark each convention you inferred `(inferred)`; the user confirms or deletes it. Leave out generic Spring advice and anything the code makes obvious, and keep the file short: every session reads all of it. 5. Commit everything, including `.claude/settings.json`, the marked classes and `archunit_store`. 6. On an existing codebase, find the files where comments make up a large share of the lines, often DTOs and records. Agents write comments as densely as the code they read, so the comment rule in `AGENTS.md` holds only once those files follow it. Offer to prune them module by module, each module in its own pull request, with `code-reviewer`'s comment pass: it changes only comments. 7. Offer a project verification skill, which proves behaviour the gates can't see. Read the repository and recommend one generator from pstack. Only the user can start them: - The app has a UI, or signs users in with `oauth2Login`: `/pstack:create-verification-skill`. It generates a skill that drives the real app and saves evidence. For a browser app, tell it to follow `references/browser-verification.md`. - The riskiest code is a state machine, retries, idempotency or concurrent updates: `/pstack:create-formal-verification-skill`. It checks one property of that code against every case in a stated scope. - Both apply: start with the first; the second can follow in its own pull request. If the project has `docs/observability.md`, tell the generator to read it, so journeys also check for server errors the page hides. If pstack isn't installed, say so and skip this step. Adding the skill to `AGENTS.md` doesn't make agents use it. They verify when the task asks for proof, so tell the team to ask for it in the task. ## What each piece does | File | Effect | | --- | --- | | `AGENTS.md` | Instructions both Claude Code and Codex read. Says that done means `./mvnw verify` passed, and how to fix each gate | | `CLAUDE.md` | Imports `AGENTS.md` for Claude Code versions that don't read it directly | | `REVIEW.md` | At the repository root, for reviewers: the failures the code doesn't show, which changes are high risk, what not to report, and how to report. The `code-reviewer` skill and Claude Code's GitHub review read it. Added only when missing; the team fills in the failures, one line each time a review misses a bug | | `.claude/settings.json` | Lets `./mvnw` run without prompts, blocks reading `.env` files, enables this plugin for every teammate with this marketplace set to update itself, and registers the hooks. For the other skills the team uses, each developer runs `install.py` from this marketplace once | | `.codex/hooks.json` | Registers the same two hook scripts for Codex: the guard on `Bash` and `apply_patch`, the check on SessionStart and Stop. Codex runs them only after each developer trusts them with `/hooks`, and asks again whenever the file changes | | `.claude/hooks/verify-on-stop.sh` | SessionStart and Stop hook, for Claude Code and Codex. It records the code each session starts from. When a turn ends and the session has changed the code under `src` or `pom.xml`, committed or not, it formats the code and runs the gates that need no Docker (compile with NullAway, `CodeRulesTests`, `ConfigurationKeysTests`, `BuildSetupTests`, the module and ArchUnit tests). It blocks the turn only on errors in files the session changed, so the agent fixes its own mistakes and never code it didn't touch; when the build fails only elsewhere, it tells the user the change couldn't be fully verified. A formatting failure blocks too. It skips code that already passed, and gives up after one failed retry on the same code. In a session with no recorded starting point, such as one that began before the hooks were installed, it tells the user the turn wasn't checked instead of passing it silently. A session that changes no code costs nothing; a check takes 25 to 75 s | | `.claude/hooks/guard.sh` | PreToolUse hook, for Claude Code and Codex (which edits files with `apply_patch`; the hook reads each file the patch updates, deletes or moves to). Refuses `git push --force`, `git reset --hard`, `git clean -f`, edits to a Flyway migration that is already on the main branch, edits to the ArchUnit freeze record or `modulith_store`, any edit or shell write to a module's `package-info.java`, since telling a widening edit from a harmless one would take parsing Java (creating one for a new module passes), and edits to the rule tests (`CodeRulesTests`, `ConfigurationKeysTests`, `BuildSetupTests`, `ModuleBoundariesTests`, `LogLeakCheck`, and progen's `ArchUnitTests` and `ModularityTests`). A developer changes a rule by hand. It also refuses Bash commands that write to those files and the Maven flags that record violations as accepted (`allowStoreCreation=true`, `freeze.refreeze=true`, `modulith.store.record=true`). It is advisory, not a boundary: a command it doesn't recognise gets through, so `harness-integrity.yml` backs it up in CI | | `scripts/report.py` | Summarises what the hooks did in this clone: turns checked, passed and blocked, blocks by gate, how many the agent fixed, check times, and what the guard refused. Both hooks append one line per run to `.git/harness/events.jsonl` (no paths, commands or file contents; capped at 2000 lines). Run `python3 ${CLAUDE_SKILL_DIR}/scripts/report.py .` when the team asks whether the hooks are worth their time | | `scripts/baseline.py` | For an existing codebase: marks the classes NullAway rejects today `@NullUnmarked`, records today's `CodeRulesTests` violations, and records today's `ModuleBoundariesTests` violations in `modulith_store`, so `verify` passes while new code is held to the gates | | `ConfigurationKeysTests` | Fails on `spring.`, `management.`, `server.` and `logging.` keys that no dependency defines, or that are deprecated. Boot ignores those keys silently | | `BuildSetupTests` | Fails on shortcuts that pass the tests while production runs without the feature: a Boot starter or module in `test` scope, `spring-boot-autoconfigure-classic`, Flyway migrations without `spring-boot-starter-flyway` (Boot 4 doesn't run them with `flyway-core` alone), unless the app builds Flyway itself, and, when the project has migrations, `ddl-auto` set to create or update the schema or code that writes `flyway_schema_history` | | `UnusedCodeTests` | Fails on a non-private method that only tests call: dead code its tests keep alive, or an internal opened up so a test can look inside. Getters, Spring entry points, overrides and methods named in `@PreAuthorize` expressions are left out. It runs in `verify` but not in the Stop hook, because a service is often written and tested before anything calls it | | `ModuleBoundariesTests` | Spring Modulith's checks: no use of another module's internal types, no cycles, no dependency that a module's `allowedDependencies` leave out. It also fails on what `verify()` lets through: a published class whose public constructor takes an internal type, and an `allowedDependencies` entry no code uses (the guard hook stops an agent widening the list, but an unused entry is already open to it). An `@ApplicationModuleTest` checks the module's boundaries again when it starts, without the record, so on an existing codebase set `verifyAutomatically = false` on module tests and leave the boundaries to this test. Violations listed in `src/test/resources/modulith_store` are tolerated. Each is keyed by what it is, not by line: a cycle by its modules, so another call along a recorded cycle passes while a new cycle fails; a disallowed dependency by its two modules; an internal-type access by caller and callee. A fixed violation drops out of this violation record when the test runs. Only `baseline.py` adds to it. IntelliJ IDEA Ultimate's Spring Modulith plugin flags internal-type access and disallowed dependencies in the editor, but not cycles and not the violation record, so recorded violations still show red there. Declaring `allowedDependencies` on each module gives developers the editor warning before the build fails | | `CodeRulesTests` | ArchUnit rules for mistakes that compile and pass most tests: a class calling its own `@Transactional`, `@Async`, `@Cacheable` or `@Retryable` method (the proxy is skipped), controllers that start transactions, use repositories, or take or return JPA entities, `@Retryable` or `@ConcurrencyLimit` with nothing switching them on, `@ManyToMany` fields that aren't a `Set` (with a `List`, removing one element rewrites every join row), `@ManyToOne` and `@OneToOne` without `fetch = LAZY`, enum columns stored by position, a `@Transactional` method calling an HTTP client, an HTTP interface or an AWS SDK client, directly or through the project's own classes (it holds a database connection for the whole call), `RestClient.create()`, `WebClient.create()`, `new RestTemplate()`, or the static `builder()` in a class that sets no request factory (no timeouts), proxy annotations on private, final or static methods, `@Async` or `@Scheduled` with nothing switching them on, services that throw `ResponseStatusException`, use the servlet API or return `ResponseEntity`, `@Deprecated` code outside controllers (update the callers and delete it), `@Autowired` fields, `System.out`, Jackson 2 (Boot 4 ignores it), Spring's deprecated nullness annotations, JUnit 4 tests (never run), and `@Disabled` tests. Each failure message says how to fix it. It uses the project's ArchUnit or Taikai, and adds ArchUnit only when neither is declared | | `.github/workflows/harness-integrity.yml`, `.github/harness/check-protected.sh` | Fails a pull request that adds entries to the ArchUnit freeze record or `modulith_store`, widens a module's rules in `package-info.java` (adds to or removes `allowedDependencies`, lists an entry that isn't a quoted module name, such as a constant, or changes the module's type; dropping entries passes), changes `archunit.properties`, changes or deletes an existing rule test, changes or deletes a migration on the base branch, changes the hooks or this check, unregisters a harness hook or narrows its matcher in `.claude/settings.json` or `.codex/hooks.json`, changes the harness's plugin block in the pom (NullAway, Spotless) or `gradle/harness.gradle`, stops a Gradle build file applying that script, removes a line from `.mvn/jvm.config`, changes or deletes the verify workflow the harness added, or stops `LogLeakCheck` running by unregistering it or turning off extension autodetection, whichever tool made the change. Removing fixed violations from the record and adding new migrations or rule tests pass, and so do other edits to those two JUnit files, which aren't checked at all in a project without `LogLeakCheck`. It runs the base branch's copy of the script, so a pull request can't weaken it. A maintainer accepts an intended change, such as a harness update, with the `harness-rule-change` label; the files are still listed for the reviewer. Make it a required status check and put `.github/` and the rule tests under CODEOWNERS. Added for every project, also when CI already runs Maven | | `.github/workflows/verify.yml` | Runs `./mvnw verify` on every pull request, so the gates hold for code nobody ran locally. Added only when no workflow already runs `mvnw` | | `gradle/harness.gradle` | On Gradle, the pom gates below, plus `harnessCheck`, the task the Stop hook runs, and a report of the declared dependencies that `BuildSetupTests` reads, since a Gradle build file can't be read from Java. Only `baseline.py` passes `-Pharness.record=true`, which turns on both record flags; the guard refuses it | | pom gates | NullAway in JSpecify mode on main code at compile time (tests are excluded, since they routinely dereference response bodies), Spotless check (none on a project with Spring Java Format, which keeps its own) | | Project skills | `add-module` (module layout and test, for module-based projects), `move-code` (moves a class or package with OpenRewrite's `ChangeType` or `ChangePackage`, which update imports, Javadoc links, properties values and `META-INF/services` entries; it then greps for the old name, since class names in Java string literals stay, and runs `verify`, which catches package-private code left behind. Agents can't call IntelliJ's move refactoring: its MCP server offers only rename) and `db-migration` (Flyway naming and safe changes, when the pom uses Flyway). Each tool sees only their names and descriptions until one is used | ## Limits - Single-project builds only: a Maven project, or a Gradle build in Groovy or Kotlin DSL. A Gradle build that includes other projects needs the script applied to each by hand. - On Gradle, javac runs on the toolchain's JDK, so Error Prone needs a toolchain of 21.0.8 or later. With an older toolchain, build on a newer JDK and set `options.release` instead. - Error Prone needs JDK 21.0.8 or later to build. Projects that set up the compiler plugin before the `-XDaddTypeAnnotationsToSymbol=true` argument was added need it added by hand to build on JDK 21. - Codex runs the project's hooks only once the developer trusts the project's `.codex/` folder and the hooks themselves with `/hooks`. It records trust against each hook's hash, so a rerun of the script that changes `.codex/hooks.json` means every developer trusts it again. Until then Codex sessions get `AGENTS.md`, the project skills and the CI gates. - The hooks are bash scripts. On Windows, Claude Code runs them with Git for Windows; without it they fail. Codex 0.166 on Windows runs them the same way. - The hooks refuse and block by printing a decision as JSON (`permissionDecision: deny`, `decision: block`), which both tools honour; Codex 0.166 let an `apply_patch` edit through when the guard exited 2. - The integrity check reads the hook registrations with `python3`, which GitHub's `ubuntu-latest` runners have. - Tool versions are pinned in the pom properties and move only when the plugin is updated and the script rerun. To move one sooner, raise it in the pom and run `./mvnw verify`; a rerun keeps a version newer than the harness's. On Gradle they are pinned in `gradle/harness.gradle`, which a rerun replaces while nobody has edited it and keeps as it is once someone has. ## MCP servers Add none by default. Each server's tool definitions take context in every session, and the gates above need none. If the team already runs SonarQube, its MCP server (`sonarsource/sonarqube-mcp`) can show issues and quality gates. It needs a SonarQube Cloud or Server token and Docker. Limit it with `SONARQUBE_TOOLSETS=issues,quality-gates` and `SONARQUBE_READ_ONLY=true`, and keep the token in each developer's environment, never in the repository.
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.