What the agent does
The agent starts with what the build is, because a formatter has to attach to it. In a project like spring-guides/gs-rest-service, complete/pom.xml and initial/pom.xml each inherit from spring-boot-starter-parent 4.0.8, set java.version to 17, depend on spring-boot-starter-webmvc and its test starter, and declare only the spring-boot-maven-plugin. Both folders carry a Maven wrapper whose .mvn/wrapper/maven-wrapper.properties pins Maven 3.9.16, and the same two folders also have a build.gradle; complete-kotlin and initial-kotlin are Gradle-only. .github/workflows/continuous-integration-build.yml sets up JDK 17 and runs ./mvnw --batch-mode clean package in initial and complete before the Gradle builds, and test/run.sh does the same by hand.
Then it reads the sources to pick a style that fits them rather than one that rewrites everything. complete/src/main/java/com/example/restservice holds a Greeting record, a GreetingController with one @GetMapping and a RestServiceApplication, and the test GreetingControllerTests uses RestTestClient in chained calls; all of it is indented with two spaces. That matches google-java-format's output, so the agent picks the googleJavaFormat step, which also orders imports and removes unused ones, and expects a small first diff, mostly in the test's chained calls, which it keeps in its own commit so the reviewer can see the formatter's taste separately from the plugin.
The change to each pom.xml is one plugin under build/plugins: spotless-maven-plugin with a <java> block that sets googleJavaFormat and the default includes, src/main/java and src/test/java, and an <execution> that binds the check goal to the validate phase. That phase matters: the workflow runs clean package, which never reaches verify, so a check left on the goal's default phase, verify, which the plugin's README names, would pass CI without running. Bound to validate, an unformatted file fails ./mvnw --batch-mode clean package before compilation, in both folders, with no workflow change. The agent pins the plugin version it resolves at run time and notes the ratchetFrom option in the pull request for a repository with a large unformatted history.
It then runs the formatter once with ./mvnw spotless:apply in initial and complete, commits the result, and runs ./mvnw --batch-mode clean package in both to prove the check passes and the two tests in GreetingControllerTests still do. To prove the check fails when it should, it re-indents one line, runs ./mvnw spotless:check, keeps the failure output for the run's record, and restores the line. The Gradle builds and the Kotlin folders are left as they are; the pull request says that the Spotless Gradle plugin would cover them and that this change is scoped to Maven.
Start it with one API call
POST https://api.phoenix.so/o/{org}/sessions with this body:
{
"agent": "claude",
"input": "Add Spotless formatting to the Maven builds in this repository. Read .github/workflows/continuous-integration-build.yml, test/run.sh, .github/dependabot.yml, complete/pom.xml, initial/pom.xml, complete/.mvn/wrapper/maven-wrapper.properties and every Java file under complete/src and initial/src first. Add spotless-maven-plugin to both pom.xml files with a java block using googleJavaFormat on the default includes, and bind the check goal to the validate phase so that the workflow's existing ./mvnw --batch-mode clean package fails on an unformatted file without any workflow change. Pin the plugin version you resolve. Run ./mvnw spotless:apply in both folders and commit the formatting changes as their own commit, separate from the plugin commit. Run ./mvnw --batch-mode clean package in both folders, then break the formatting of one line, run ./mvnw spotless:check to show it fails, and restore it. Leave the Gradle builds and the Kotlin folders unchanged and say so. Open a pull request that explains the phase choice and mentions ratchetFrom for repositories with a large unformatted history.",
"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
What comes back is a pull request with two commits: one that adds the plugin to complete/pom.xml and initial/pom.xml, and one that holds every formatting change spotless:apply made. The description explains why check is bound to validate and not verify, with the line from the workflow that shows clean package stops short of verify, and lists the Gradle and Kotlin folders as out of scope with the plugin that would cover them.
The run's record keeps the spotless:apply diff summary, the passing clean package in both folders with the GreetingControllerTests output, and the deliberate spotless:check failure with its message, so a reviewer can see the check both pass and fail without running Maven.
Before merging, a reviewer decides whether google-java-format's import ordering is what the team wants, whether to add ratchetFrom so only files changed since a base commit are checked, and whether the Gradle builds should get the matching plugin in the same pull request or a later one. The agent takes no position on the last and shows the Gradle snippet in the description.
Run it on every pull request
Once the plugin is in, CI enforces it on every push. For a review that explains failures, an automation on the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "run ./mvnw spotless:check in each Maven folder this pull request touches; if it fails, comment with the files and the diff spotless:apply would make" reads each new pull request. The trigger puts the pull request after the prompt; only work by an owner, member or collaborator fires it, never a fork's.
The same automation can take a branch_patterns filter so it runs only for pull requests against main, and its max_runs_per_hour cap bounds a busy afternoon of pushes.
The use case this job follows, with its automation and trigger: Review every pull request.
Why run it on Rush?
A formatter added without running it ships one of two surprises: a first diff nobody expected, or a check bound to a phase CI never reaches. The agent runs the formatter and the build in its own sandbox, commits the formatting apart from the plugin, and breaks a line on purpose to see the check fail, so the pull request shows both outcomes.
Every command stays with the run, from spotless:apply to the deliberate failure, and the pull request can cite them. Doing the same across every Maven repository a team owns at once costs no more attention than one, because each run has its own machine and its own record.
Frequently asked questions
Why bind check to validate instead of verify?
Because .github/workflows/continuous-integration-build.yml runs ./mvnw --batch-mode clean package, and package comes before verify in Maven's lifecycle. A check bound to verify would never run in CI. validate is the first phase, so an unformatted file fails before anything compiles, and the workflow needs no new step.
Will the first commit reformat a lot?
The sources already use two-space indentation, which is google-java-format's style, so the diff is small: import order and the wrapping of the chained RestTestClient calls in the test. The agent keeps it in its own commit so the reviewer can judge the formatter's output on its own.
What about the Gradle builds and the Kotlin folders?
Unchanged. complete and initial also have a build.gradle, and the Kotlin folders are Gradle-only; Spotless has a Gradle plugin and a ktlint step for them. The question was about Maven, so the pull request shows the Gradle snippet and leaves the decision to the reviewer.
Can the check be limited to changed files?
Yes, with ratchetFrom, which tells Spotless to check only files that differ from a base commit or branch. It suits a repository with years of unformatted history; this one is small enough to format in one commit, so the agent mentions the option without using it.