/spring-boot-team-harness

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 and coding conventions on a Maven or Gradle Spring Boot 4 repository: setting up AGENTS.md, coding standards, 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:

   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, and do so on an existing service when the task says behaviour must not change: the narrowed exposure and the filter change what the running app does. Say in the setup report that it was skipped and why, so the user can add it later in its own change.

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`, adds `ModuleBoundariesTests` even when a test already calls `ApplicationModules.of(...)` and says which `verify()` call to remove, since only its own test honours the violation record and checks unused `allowedDependencies`, and never overwrites a file the team has edited. If `<build><plugins>` already configures `maven-compiler-plugin`, as MapStruct and Lombok projects do, it moves that plugin to `<pluginManagement>`, where the harness's block appends Error Prone and NullAway to its processor paths and arguments. It stops only when `<pluginManagement>` configures the compiler too: 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