What the agent does
The agent reads the build before it adds a check to it. In a project laid out like spring-guides/gs-rest-service, the complete/pom.xml inherits spring-boot-starter-parent 4.0.8, sets java.version to 17, depends on spring-boot-starter-webmvc and spring-boot-starter-webmvc-test, and lists one plugin, spring-boot-maven-plugin. A Maven wrapper (mvnw, .mvn/wrapper/maven-wrapper.properties) sits beside a build.gradle that builds the same sources with a Java 17 toolchain. The code is three classes and one test: RestServiceApplication, a Greeting record, GreetingController with a private static final String template and a @GetMapping("/greeting"), and GreetingControllerTests using RestTestClient. The files use two-space indentation. .github/workflows runs ./mvnw --batch-mode clean package in each variant on Temurin JDK 17 with cache: maven, and test/run.sh does the same locally. Nothing checks style.
It adds maven-checkstyle-plugin under <build><plugins> in complete/pom.xml, pinned to the current release on Maven Central (3.6.0 when this page was written) with the plugin's com.puppycrawl.tools:checkstyle dependency overridden to a current Checkstyle (14.3.0), because the version the plugin bundles lags behind. One <execution> binds the check goal to the validate phase with failOnViolation true, consoleOutput true and includeTestSourceDirectory true, so test code is held to the same rules. The rule set is a file in the repository, complete/checkstyle.xml, started from the bundled google_checks.xml because its two-space indentation matches the sources, with violationSeverity set to warning since the Google configuration reports at that level and would otherwise never fail a build. A checkstyle-suppressions.xml is added for generated or vendored paths, empty to begin with.
The first ./mvnw --batch-mode checkstyle:check is the point of the exercise. On code like this the Google rules report the kind of thing a human would not bother with: CustomImportOrder on the blank line that separates java.util.concurrent.atomic.AtomicLong from the org.springframework imports, and MissingJavadocType on the public classes. The agent fixes what the report names (reorders imports, adds the short Javadoc), re-runs until the goal passes, and records in the pull request which rules fired and what it changed. Rules that the prompt says to relax are relaxed in checkstyle.xml, with the reason as an XML comment, rather than silenced per file.
No workflow change is needed: validate runs inside the existing ./mvnw --batch-mode clean package, so the GitHub Actions job and test/run.sh now fail on a violation. For the report, ./mvnw checkstyle:checkstyle writes HTML under target/site. The build.gradle is left as it is; the pull request notes that Gradle's checkstyle plugin can read the same checkstyle.xml if the team wants both builds to agree, and leaves that as a follow-up.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Checkstyle to the Maven build of this Spring Boot project. Read pom.xml, the Maven wrapper properties, every Java file under src, test/run.sh and the workflows under .github first. Add maven-checkstyle-plugin to the build plugins with its checkstyle dependency overridden to a current release, bind the check goal to the validate phase with failOnViolation, consoleOutput and includeTestSourceDirectory, and point configLocation at a checkstyle.xml committed in the project, based on google_checks.xml with violationSeverity set to warning. Add an empty checkstyle-suppressions.xml and reference it. Run ./mvnw --batch-mode checkstyle:check, fix every violation it reports in the sources, and run ./mvnw --batch-mode clean package until it passes. Do not change build.gradle. Open a pull request that lists the rules that fired and the fixes made.",
"resources": [
{
"url": "https://github.com/your-org/your-app"
}
]
}- Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
- Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
- Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.
What comes back
The pull request changes complete/pom.xml (the plugin block, two version properties, the check execution), adds complete/checkstyle.xml and complete/checkstyle-suppressions.xml, and touches the Java files the report named. Its description lists each rule that fired with the file and line, shows the final checkstyle:check output, and states how the check is wired into the build so the reader knows a violation now fails clean package.
A reviewer reads checkstyle.xml first, since that file decides what the team is signing up for: which Google rules stay, which were relaxed and why. Then they read the source changes, which should be small and mechanical, and confirm the plugin is pinned rather than floating. If the team prefers Sun or a house style, swapping the base file is a one-line change and the agent can be asked to re-run against it.
From then on a pull request that breaks a rule fails the existing Maven job with the rule name and line in the log, and the HTML report is one goal away for anyone who wants the full picture.
Run it on every Java repository without a style check
A team with many Maven services sends this body once per repository from its own server, each POST /o/{org}/sessions naming that repository in resources and carrying a request_id that is a UUID v5 of the repository name, so a retried call returns the run already started. Each run reads its own pom.xml, so a multi-module build gets the plugin in the parent's pluginManagement and the rule set at the root, while a single module gets what this page describes.
An automation on the Project with a github trigger on pull_request.opened and the prompt "run ./mvnw checkstyle:check on this branch and post the violations as a review, citing file and line" turns the same rules into a review on every pull request until the team is comfortable letting the validate phase fail the build. The trigger adds the pull request after the prompt and fills in nothing else.
The use case this job follows, with its automation and trigger: Hand off a long task.
Why run it on Rush?
The slow part of adding Checkstyle is not the XML, it is the first run: dozens of findings in code nobody wants to reformat by hand, and a few rules that argue with the way the team already writes Java. The agent runs the check in its own sandbox against the real build, makes the mechanical fixes, and brings back the list of rules that fired so the decision about each one is made once, in review, with the evidence in the pull request.
A reviewer reads one rule file and a small source diff. A platform team starts the same request across every Maven repository at once, each with its own JDK and wrapper, and gets one pull request per repository with the same rule set.
Frequently asked questions
Which rule set does it use?
Google's, as shipped in the Checkstyle jar, because this project is indented with two spaces. The file is copied into the repository as checkstyle.xml rather than referenced by name, so the team can edit it and so a Checkstyle upgrade cannot change the rules silently.
Why override the Checkstyle version?
The plugin bundles an older Checkstyle than the latest release, and the Google configuration in a newer jar names modules the older engine does not know. Pinning the dependency to a current version keeps the rule file and the engine in step; the pull request records both numbers.
Will it fail the build on day one?
Only if a violation is left, and the agent fixes every one it finds before it opens the pull request. Google's rules report at warning severity, so without violationSeverity set to warning the goal would pass regardless; the agent sets it so a new violation fails validate.
Does it cover the Gradle build too?
Not in this pull request. The Gradle build in the same directory is left unchanged, and the description points out that Gradle's checkstyle plugin can read the same checkstyle.xml so both builds enforce one rule set.