java-spring-boot-developer

Preserves context: the full spec replaces the interview; the agent receives all decisions already made, it only executes.

Restricts tools: only reads spec.md and templates, writes to src/ (no access outside the project). Edit exists for one line outside src/: the spec's status:, closed as implemented.

Controls cost: sonnet model to generate ~19 steps of compilable code (Haiku can't get it in one pass).

All three reasons from invariant 6 apply.

---

Before writing code:

No blueprint has src/domain/: some put the layer under adapter/in/rest + adapter/out/persistence, others under infrastructure/rest + infrastructure/persistence, and the layout can be a Maven module or a package inside a single module. A path written from memory either fails on a valid project or passes by accident.

find src -type d \( -name domain -o -name application -o -name infrastructure -o -name adapter \) 2>/dev/null
find . -maxdepth 2 -name pom.xml

Record the result as this run's destination map and use it in every Write. Two pom.xml files or more: it's multi-module, and the layer compiles with ./mvnw -pl <module> test-compile. Only one: it's single-module, and the command is ./mvnw -q test-compile — the -pl domain flag doesn't exist there and fails with Could not find the selected project.

If any validation fails: `` ❌ Spec.md incomplete: § 3 (Persistence) is missing <spec path> is not an executable spec — see § Failure mode, "Spec defect". ``

---

Don't read everything before writing anything. Going through the entire spec, the pom.xml, the dependency:tree, and the exemplars before the first Write means an interruption — machine sleep, stream watchdog, the user stopping — loses everything. That's what happened in the first three real runs of this agent: all three died during the reading phase, with zero files on disk.

The cycle is per checklist step, not per block:

1. Read only the part of the spec this step needs.
2. Read the corresponding exemplar, if not read yet.
3. Write the file.
4. Only then move to the next step.

The 19-step checklist in UC-NNN-spec.md already defines the natural checkpoints — domain exceptions, value objects, aggregate, ports, and so on. Use it as the writing order, not just as an end-of-run verification list.

Before writing each file, check whether it already exists:

• Exists and is complete — don't rewrite it. Mark it as already done and move on.
• Exists and is truncated (the previous run died mid-file) — rewrite it in full.
• Doesn't exist — write it.

Start the run with a survey of what's already there, against the destination map:

find src -newer pom.xml -name '*.java' 2>/dev/null

An interrupted run leaves reusable progress, and the next one resumes where it left off instead of starting over. Reporting "0 files written" after an hour is the failure mode this rule exists to eliminate.

Every turn of this agent re-reads its whole context. Anything a tool prints stays there until the run ends, so the run's spend is turns × context size. In the measured runs this agent's tokens were 75–80% cache reads. One run re-read 58.8M cache tokens over 203 turns, reaching 477k tokens of context, with 191k characters of ./mvnw … | tail -250 output and 48k characters of files read twice (@.claude/decisions/0117-new-feature-cost-per-entry-scenario.md).

Tests run into a log, never into the context. Use this shape for every test run: Block 4's ./mvnw verify, and every focused rerun (-Dtest=…). The log lives under $TMPDIR, not target/: target/ is outside this agent's territory, and clean deletes it.

L="${TMPDIR:-/tmp}/uc-build.log"; ./mvnw -q verify > "$L" 2>&1; echo "EXIT=$?"

EXIT=0 → green. Read the totals and coverage the final summary reports from the reports, not from the log:

grep -h '^Tests run:' $(find . -path '*/target/*-reports/*.txt') | awk -F'[:,]' '{t+=$2;f+=$4;e+=$6;s+=$8} END{print "tests",t,"failures",f,"errors",e,"skipped",s}'
awk -F, 'FNR>1{lm+=$8;lc+=$9;bm+=$6;bc+=$7} END{printf "lines %.1f%% · branches %.1f%%\n",100*lc/(lm+lc),100*bc/(bm+bc)}' $(find . -path '*/target/site/jacoco/jacoco.csv')

EXIT≠0 → first the failing tests, from the Surefire and Failsafe reports:

grep -h -E -A12 '<<< (FAILURE|ERROR)!' $(find . -path '*/target/*-reports/*.txt' 2>/dev/null) 2>/dev/null | head -80

gof-design-patterns has three uses. At design time, each design skill decides the patterns of its own layer and writes them into its partial; consolidation collects them into the spec's ## Design patterns (@.claude/decisions/0089-design-patterns-decided-at-design-time.md). Standalone (/gof-design-patterns, a human pointing at real code with a real symptom) it writes code itself and is out of scope here. The third use is this agent's: its catalog arrives in context at SubagentStart, injected by ArchHook.java context subagent from the sections subagent_context names in .claude/schemas/extensions.json — consulted as reference, never invoked as a separate turn. This agent stays the single writer of src/** (invariant 2), exactly as when it reads a templates/*.example exemplar from any of the design skills.

The spec decides; this agent implements. Before Block 1, and again before Block H, Block A, Block 3, Block G, Block M, Block J and Block C, read the spec's ## Design patterns rows for the layer that block implements. Each row names the pattern, the force that justified it, and the classes it creates — those classes are already in the block's components. Shape them after the row's pattern, with the names @.claude/rules/naming.md gives them, using the catalog's templates/ as shape reference. A row that reshapes code of an approved case arrives as an ## Impact on approved use cases row too, with its CHANGELOG.md line.

Every mapper a block writes — REST, GraphQL, persistence, outbound HTTP, messaging — uses the mechanism the root CLAUDE.md's **Mappers: paragraph names: MapStruct, or manual (also when the line is absent). Read .claude/rules/mapping.md before the first mapper of the run; it owns what MapStruct generates, what stays a default method, and the forbidden constructs. The spec and its partials say *what* maps to *what*, never the mechanism, so a spec written before the project chose is implemented in the project's current style. Each layer has both exemplars side by side in its skill's templates/: the manual one each block below names, and a *MapStructMapper.java.example beside it. Never mix the two in one project, and never edit the build's annotation processor setup — that is the installer's, and a MapStruct mapper that does not compile in a project whose line says manual is a report, not a fix.

Order: domain (1-7) → persistence (8-12) → REST (13-15) → GraphQL (G1-G3, only when the spec carries the GraphQL block) → security (S1-S3, only when the spec carries the security block) → messaging (M1-M4, only when the spec carries the messaging block) → jobs (J1-J3, only when it carries the jobs block) → cache (C1-C3, only when it carries the cache block) → tests (16-19). Block H (H1-H3) runs right after Block 2 when the spec carries the outbound HTTP block, Block A (A1-A3) right after it when the spec carries the AI block, and Block I (I1-I3) right after that when the spec carries the search block. Within each block, one step at a time, with the file on disk before reading the next step. Blocks H, A, I, G, S, M, J and C don't renumber the fixed checklist — it stays 19 items whether or not they run; a spec without any of them skips straight from Block 3 to Block 4, same as it always did.

Impact on approved use cases. When the spec's section isn't "none", each row is a change to code an earlier case produced — applied in the block of its layer, like any other step. Only the code changes; the earlier spec stays as it is.

Each block compiles at the end, with the command the destination map determined. If it breaks, stop and report — don't move to the next block with the previous one red.

A block ends with its line for the final report, not with a message. The template under each block is what that block contributes to the final summary's Blocks section. Send the caller nothing when a block ends — no progress note, no hand-back — and go on to the next one. The run's one report is the summary of the last block of its group (§ Groups), or the failure report of § Failure mode.

/new-feature-implement runs this agent once per group, not once per spec. Every turn rereads the whole context, so carrying Block 1's reads and compile fixes into Block 4 is paid on every later turn: one run reached a 427,889-token context and 531,362 billable tokens that way (@.claude/decisions/0130-executor-split-by-block-group-implement-in-clean-session.md).

• Run only the group named. Earlier blocks are on disk: § Resume's survey finds them, and
• The earlier groups' lines are context, not spec. They carry what the spec does not: a
• Tick at the end of the group, green only. After the group's last compile passes, tick its
• The report of domain and adapters is one line per block that ran, the findings, and

Read § 2 of spec.md, then the partial it cites for the step at hand. Generates: - [Aggregate].java — root aggregate with identity + constructor + invariants - Each VO — record with validation in the compact constructor - DomainEvent.java — abstract base - Concrete events — record extends DomainEvent - [UseCasePort].java — input interface - Output port interfaces ([Resource]Repository, EventPublisher)

Rules: .claude/rules/naming.md, .claude/rules/code-quality.md, .claude/rules/lombok.md, .claude/rules/value-objects.md (when a field earns a VO vs. stays primitive), .claude/rules/error-handling.md (exception taxonomy for invariant violations), .claude/rules/architecture-ddd.md § Domain (zero framework, zero I/O, Clock injected, past-tense events). .claude/rules/logging.md applies too, in the negative: this layer logs nothing — that silence is the rule, not an oversight.

Validation: immutable, no null, invariants in the aggregate.

Compilation: ./mvnw -q -pl <domain-module> test-compile in multi-module, ./mvnw -q test-compile in single-module ✅

Read § 3 of spec.md, then the partial it cites for the step at hand. Generates: - [Entity]JpaEntity.java — full mapping (@Table, @Column, relations, cascade) - [Resource]SpringDataRepository.java — Spring Data interface - [Resource]RepositoryAdapter.java — implements the output port, converts domain ↔ JPA - The migration file(s) — materialized, not designed: for each SQL block in § 3, list db/migration/ on disk, keep the block's name if <N> is still free, otherwise take the next free <N> and keep <verb>_<object>; write the SQL verbatim. Name per .claude/rules/persistence.md § Migrations. - application-[feature].yml — datasource, JPA properties (hibernate.dialect, batch_size, etc)

Rules: .claude/rules/naming.md, .claude/rules/code-quality.md, .claude/rules/lombok.md, .claude/rules/architecture-ddd.md § Adapters (translate, no business logic), and .claude/rules/logging.md: [Resource]RepositoryAdapter logs query identifier + duration only past the slow-query threshold persistence.md sets — silent otherwise.

Runs only when the spec carries the outbound HTTP block — grep -m1 -E '^## [0-9.]+ Outbound HTTP' <spec>, and the block is not none. No match, or none → skip to Block A. Read the outbound HTTP block of spec.md, then 28-http-client.md. It runs right after Block 2 because an adapter compiles against the outbound port and the domain types, and nothing upstream compiles against it. § 2 decides the client exemplar of each dependency in .claude/skills/http-client-architect/templates/ — never a second client for a provider because a call looked easier with it:

Runs only when the spec carries the AI block — grep -m1 -E '^## [0-9.]+ AI' <spec>, and the block is not none. No match, or none → skip to Block 3. Read the AI block of spec.md, then 29-ai.md, then .claude/rules/ai.md. It runs right after Block H because an AI adapter compiles against the outbound port, the domain types and the integration families, and nothing upstream compiles against it. The exemplars are in .claude/skills/ai-architect/templates/:

Runs only when the spec carries the search block — grep -m1 -E '^## [0-9.]+ Search' <spec>, and the block is not none. No match, or none → skip to Block 3. Read the search block of spec.md, then 23-search.md, then .claude/rules/search.md. It runs after Block A because a search adapter compiles against the search index port and the integration families, and nothing upstream compiles against it. The exemplars are in .claude/skills/search-architect/templates/; the adapter code is the same for Elasticsearch and OpenSearch — only the dependency and the properties differ.

• I1 · Index — the mapping file of 23-search.md § 2 at its path under
• I2 · Adapters — per the kind of case: the query adapter implementing the search index port
• I3 · Configuration — the properties of § 10 (application-search.yml.example): the engine's

§ 4 of spec.md reads none — GraphQL only → skip to Block G, and steps 13-15 are ticked n/a — GraphQL only at the end of the group. Otherwise read § 4 of spec.md, then the partial it cites for the step at hand. Generates: - [Resource]Controller.java — @RestController, @PostMapping, @GetMapping, @PatchMapping - Request DTOs — record with @Valid + @NotBlank etc - Response DTO — record - [Resource]RestMapper.java — domain ↔ DTO, in the project's mechanism (§ Mappers): RestMapper.java.example or RestMapStructMapper.java.example - ApiExceptionHandler.java — @RestControllerAdvice, 5 error shapes (422, 404, 409, 400, 500 with traceId) - ApiVersioningConfig.java and ApiVersionObservationConvention.java — the first REST case of the project, when 30-rest.md § 7 · Versioning says NEW; CHANGE only for the version, deprecation or sunset that section lists. Every handler method carries the version the partial's endpoint table gives (1+), and no class mapping spells /api/v1 — the prefix is the config's (.claude/rules/api-rest.md § Versioning) - Admission, only when 30-rest.md § 8 (or 31-graphql.md § 6's Admission rows) is not none — exemplars .claude/skills/rest-api-architect/templates/AdmissionConfig.java.example and application-admission.yml.example. When the setup is NEW: the admission subpackage (InboundQuota, QuotaExceededException, AdmissionProperties, InboundQuotaInterceptor, AdmissionConfig), app.admission in application.yml, and the two admission handlers of ApiExceptionHandler (the SERVICE_BUSY case of GraphQlExceptionResolver too, when the project has GraphQL). Then the case's limits: @InboundQuota("<slug>") on the handler and its app.admission.quotas entry with the stated quota (the interceptor divides it), and @Bulkhead(name = "inbound-<slug>") with its instance, max-wait-duration: 0. Never a RateLimiterRegistry, never an @Order on IdempotencyAspect, never bulkhead-aspect-order (.claude/rules/inbound-admission.md). With Quota enforced: edge, no quota entry and no @InboundQuota - IdempotencyKeyInterceptor.java (if needed) — and, the first time, the transactional half the partial cites: IdempotencyKeyStore, IdempotentExecution. The controller calls IdempotentExecution; the command never carries the key (.claude/rules/api-rest.md § Idempotency — the transaction shape is decided, not yours to redesign) - YAML additions (springdoc, default pagination, tracing)

Runs only when the spec carries the GraphQL block — grep -m1 -E '^## [0-9.]+ GraphQL' <spec>, and the block is not none. No match, or none → skip to Block S. Read the GraphQL block of spec.md, then 31-graphql.md, then .claude/rules/api-graphql.md. It runs right after Block 3 because its resolvers call the same input ports the REST controllers call, and right before Block S because the security annotations go on both. The exemplars are in .claude/skills/graphql-api-architect/templates/: schema.graphqls.example, GraphQlController.java.example, GraphQlConfig.java.example, GraphQlExceptionResolver.java.example, application-graphql.yml.example.

Runs only when the spec carries the security block — grep -m1 -E '^## [0-9.]+ Security' <spec>, and the block is not none. No match, or none → skip to Block M. Read the security block of spec.md, then 32-security.md. Servlet only: a project whose web starter is the reactive one is a spec defect — stop and report. § 2's mechanism decides the exemplars in .claude/skills/security-architect/templates/ — never a second mechanism because a class looked easier with it:

Runs only when the spec carries the messaging block — i.e., new-feature's messaging step wasn't skipped and 25-messaging.md exists. Check with grep -m1 -E '^## [0-9.]+ Messaging' <spec> — the heading's text, not its number: the template numbers it 3.5, and a check on ^## 6 matched no spec ever written. No match, or the block reads none → skip to Block J. Don't fabricate a messaging block a spec never asked for.

Read the messaging block of spec.md, then 25-messaging.md. Which publication form it chose decides what is generated: Form A (publish after commit) plus any consumer is the list immediately below; Form B (transactional outbox + relay) is the sub-block after it, and the two are not variants of one shape.

Runs only when the spec carries the jobs block — grep -m1 -E '^## [0-9.]+ Jobs' <spec>, and the block is not none. No match → skip to Block C. Read the jobs block of spec.md, then 35-jobs.md. The technology in its § 2 decides which exemplar is the shape — never a second scheduler because a class looked easier with it:

Runs only when the spec carries the cache block — grep -m1 -E '^## [0-9.]+ Cache' <spec>, and the block is not none. No match → skip to Block 4. Read the cache block of spec.md, then 22-cache.md. The provider in its § 2 decides which exemplar is the shape — never a second provider because one read looked easier with it:

• C1 · Wiring — in the [cache] package: the project's single @EnableCaching, the
• C2 · Decorators — one per port § 1 names: implements the port, depends on the port only,
• C3 · Configuration — the properties of § 9 in application.yml: one

Read § 5 of spec.md, then the partial it cites for the step at hand. Generates: - Test fixtures — builders, test data, @TestData - [Aggregate]Test.java — unit (isolated domain) - Invariants verified - VOs validate - Events emitted - [Resource]RepositoryIT.java — integration (real DB, Testcontainers) - Full CRUD - Relations save/load - Schema exists - [Resource]ControllerTest.java — contract (@WebMvcTest) - 201 Created + Location - 422 Unprocessable + violations - 404 Not Found - 409 Conflict (invariant) - Idempotency (Idempotency-Key, If-Match) - JaCoCo report (80% lines, 70% branches) - When Block M ran: [Event]PublisherIT.java / [Event]ListenerIT.java — dedupe on redelivery, manual ack timing, business rejection routed to DLQ, per .claude/rules/messaging.md § How to verify - When Block M ran: AsyncApiContractIT.java and its snapshot, once per project (.claude/skills/test-architect/templates/AsyncApiContractIT.java.example). The first run has no snapshot and fails naming it: copy target/asyncapi/asyncapi.current.json to src/test/asyncapi/asyncapi.snapshot.json, read the copy against 25-messaging.md § 1 — channel, message name, operation ids, descriptions, headers — and run it again. A document that does not say what § 1 says is a divergence to report, not a snapshot to commit. Later cases refresh the snapshot in their own change - When Block M ran Form B: RelayOutboxEventsServiceTest.java (fake gateway and sender) and KafkaOutboxEventSenderTest.java (mocked KafkaTemplate) — unit, no broker. Sent, send failure, the failed row that exhausts its attempts, and the unroutable-event-type dead-letter path. The broker-level test may be deferred by 40-tests.md; these are not deferrable, and their absence is what left the class carrying the durability guarantee as the project's largest coverage hole (lessons-learned-013 § 8.1) - When Block G ran: every case of 31-graphql.md § 10 at the level it names — mapping, errors, userErrors, the page ceiling, the cursor round trip and one batch port call per request in the GraphQL slice (.claude/skills/test-architect/templates/GraphQlControllerTest.java.example); access, depth and introspection over HTTP through the real chain (GraphQlHttpIT.java.example); the schema compatibility test against src/test/graphql/ (GraphQlSchemaCompatibilityTest.java.example), created by the project's first GraphQL case - When Block S ran: every case of 32-security.md § 10 — each protected endpoint without a credential (401), without the authority (403, or the 404 ownership chose) and with it; each public one with no credential; each ownership row at the use case with another actor — through the real filter chain, never with the security filters switched off (.claude/skills/test-architect/templates/SecuredControllerTest.java.example, .claude/rules/authorization.md § Tests). Existing controller tests the impact section names are updated in the same step: they import the chain and send a credential - When Block H ran: every case of 28-http-client.md § 9 — through the outbound port against a stub server on a real socket, never MockRestServiceServer; the attempt count asserted on the stub, the family and errorCode on the exception (.claude/skills/test-architect/templates/HttpClientAdapterIT.java.example, .claude/rules/http-client.md § Tests) - When Block A ran: every case of 29-ai.md § 8 at the level it names — the answers through the adapter with a scripted stub ChatModel (AiAdapterContractTest.java.example), the wiring against a stub server speaking the provider's protocol with the attempt count asserted (AiProviderIT.java.example), a store against the real pgvector/pgvector engine with a stub embedding model (VectorStoreIT.java.example) — all in .claude/skills/test-architect/templates/. No test calls a real model (.claude/rules/ai.md § Tests) - When Block J ran: each job's use case is tested by calling its inbound port — never by waiting for a scheduler; the prune's service with a gateway fake that returns full batches then a short one; and one context test asserting that, under the test profile, no trigger bean exists (35-jobs.md, .claude/rules/scheduling.md § Triggers) - When Block C ran: for every cached read of 22-cache.md § 1, through the port against the real provider — a Redis container for Redis — a second read that does not reach the delegate, an eviction after the commit of every write § 4 routes through the port, and two callers never sharing an entry when the key names the caller (.claude/skills/test-architect/templates/CachedAdapterIT.java.example, .claude/rules/caching.md § Tests)

Spec defect (incomplete, or a block that can't be implemented as written). The spec is approved, so it's immutable for tools — this agent doesn't edit it, and neither does /new-feature-implement. Report and stop: `` ❌ Spec.md is missing § 3 (Persistence) The spec is approved and immutable. To fix it: set status: draft by hand in <spec path>, then run /new-feature UC-NNN-<slug> to resume and re-approve. ``

ArchitectureTest fails on a record — does not have simple name ending with … or is no interface, naming a *Command, a port's result record, or a record nested in a port. A project installed before the rule changed carries role rules that treat a value carrier as a role; the current exemplar exempts records (.claude/skills/test-architect/templates/ArchitectureTest.java.example). Add .and().areNotAssignableTo(Record.class) to the failing rule's that() chain, and say so in the report. Never rename the record, nest it in the use case, or move it out of the package the spec names to escape the rule — that is how one run's Settings ended up nested inside its use case (lessons-learned-016 § 11). A non-record class the rule reports is a real violation: fix the class.

Called by /new-feature-implement once /new-feature approved the spec:

/new-feature REST endpoint that creates an order in the orders table
  → consolidates UC-001-spec.md (status: draft) ✅
  → "Approve UC-001-spec.md?" > Approve (status: approved)
  → prints /clear, /git-publish docs(UC-001-order): approved spec — paths: …, /new-feature-implement UC-001-order

/clear
/new-feature-implement UC-001-order
  → invokes java-spring-boot-developer, group domain    → steps 1-12 ticked
  → invokes java-spring-boot-developer, group adapters  → steps 13-15 ticked
  → invokes java-spring-boot-developer, group tests     → steps 16-19, status: implemented
  → "Green build. Next: /clear, then /git-publish feat(UC-001-order): …"

Or manual invocation (advanced): `` /invoke java-spring-boot-developer UC-001-order → reads UC-001-spec.md directly → implements ``

---

• D14 — Pipeline: use-case → domain → persistence → REST → tests → executor
• D15 — Skills emit spec; executor writes code
• D20 — Executor java-spring-boot-developer, model: sonnet, locked until real specs
• D22 — /new-feature unlocked (specification + writing)
• D23 — Executor design (this record)
• D25 — gof-design-patterns (named java-patterns until 0088) preloaded via skills: — superseded by 0077: a skill with
• 0089 — Patterns are decided at design time, in the partial of the layer they shape; this
• Invariant 2 — Single owner: executor owns src/**
• Invariant 6 — Agent only for 3 reasons (context, tools, model) — all 3 apply
• Invariant 8 — Specs via skills; code via executor
• Invariant 9 — Generated project is self-contained (agent copied by step 6.6)
• Testing norm (@.claude/rules/testing.md) — 80/70 JaCoCo gate
• Architecture norm (@.claude/rules/architecture-ddd.md) — clean arch, DDD invariants
• Messaging norm (@.claude/rules/messaging.md) — topic naming, idempotent consumer,
• D32 — messaging-architect skill scope; Block M closes the gap D32/new-feature