Java Spring Boot Code One Task

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Implements a single task from a Spring Boot implementation_plan.md-style task list — the implementation, its unit tests, and its checkbox update — in a DDD/hexagonal Maven reactor.

Purpose

iru-java-springboot-code-one-task is the narrowest execution unit for a Spring Boot service in the iru-code pipeline, registering the java-springboot language/framework key. It is the counterpart to Java Code One Task for services scaffolded by Setup Java Spring Boot, and it differs from that skill in two ways that follow from the architecture rather than from preference:

The module boundary is resolved before any code is written. In a hexagonal reactor the same class placed in the wrong module is a structural defect the build rejects — via the maven-enforcer-plugin banned-dependencies rules and the ArchUnit test — so discovering it later costs a full build cycle. Step 2 settles which module the code belongs in, what that module may import, and (for a task spanning modules) the inside-out order to write them in.
It runs unit tests itself, and only unit tests. iru-java-code-one-task defers all testing to its group skill; this one validates its own work with a scoped Surefire run, because domain and application carry no framework on their classpath and their tests are near-instant. Integration tests are categorically out of scope: mvn verify, Failsafe, any *IT class, anything Docker- or Testcontainers-backed, and install/deploy/bare mvn are each named as forbidden. A task-level integration run would start the same container stack once per task, which is precisely the redundancy group-level validation exists to remove.

The bundled reference library

This skill ships a reference/ directory alongside its SKILL.md — the first skill in this catalog to do so — holding the Spring Boot best practices and architectural patterns a task must be implemented against. Its plain-Java counterpart, Java Code One Task, now ships one too, covering the language-level code agreements (var, final, declaration order, Javadoc, tests); those still apply here, and the files below add the architecture-specific rules on top of them rather than replacing them. It is read by progressive disclosure: reference/README.md is a short routing table, two files are always read, and the other three only when the task’s shape calls for them. Reading all six on every task is the context waste the split exists to avoid.

File Read when Covers

File	Read when	Covers
`hexagonal-architecture.md`	Always	The module table and each module’s allowed dependencies, the violations that fail the build, a "where does this piece of work go" lookup, the inside-out order for a cross-module task, and why ports are named for intent rather than technology.
`code-style.md`	Always	Records for immutable types (with defensive copying and compact-constructor validation), Lombok where it earns its place and where it hurts, MapStruct only for simple mappers, `var` type inference, `final` wherever possible, the public-to-private member ordering every type follows (shared with `iru-java-code-one-task`, which documents it in full), and full Javadoc on everything.
`ddd-tactical-patterns.md`	The task touches `domain`	Value objects, entities, aggregates and aggregate roots, domain services versus use cases, domain events, domain exceptions, and ubiquitous language.
`solid.md`	The task changes an interface, adds a branch on type, or grows a class’s responsibilities	The five principles as they land in this architecture — including why one class per use case beats a god-service, and why a port’s Javadoc is what makes substitutability checkable.
`distributed-patterns.md`	The task involves Kafka, a second datastore, or eventual consistency	CQRS, the transactional outbox, sagas, eventual consistency, and listen-to-yourself — each with its mechanism, its costs, where the code goes in this module layout, and a table for choosing between them.

hexagonal-architecture.md

Always

The module table and each module’s allowed dependencies, the violations that fail the build, a "where does this piece of work go" lookup, the inside-out order for a cross-module task, and why ports are named for intent rather than technology.

code-style.md

Always

Records for immutable types (with defensive copying and compact-constructor validation), Lombok where it earns its place and where it hurts, MapStruct only for simple mappers, var type inference, final wherever possible, the public-to-private member ordering every type follows (shared with iru-java-code-one-task, which documents it in full), and full Javadoc on everything.

ddd-tactical-patterns.md

The task touches domain

Value objects, entities, aggregates and aggregate roots, domain services versus use cases, domain events, domain exceptions, and ubiquitous language.

solid.md

The task changes an interface, adds a branch on type, or grows a class’s responsibilities

The five principles as they land in this architecture — including why one class per use case beats a god-service, and why a port’s Javadoc is what makes substitutability checkable.

distributed-patterns.md

The task involves Kafka, a second datastore, or eventual consistency

CQRS, the transactional outbox, sagas, eventual consistency, and listen-to-yourself — each with its mechanism, its costs, where the code goes in this module layout, and a table for choosing between them.

The reference files state explicitly that the distributed patterns are documented so a plan’s request is implemented correctly, never so the skill introduces an outbox, projection, or saga on its own initiative — that is a blocker to report instead.

On MapStruct the reference deliberately overrides the prevailing published advice: it is used only for field-for-field mappings, with hand-written mappers preferred once conditional logic, value-object factories, flattening, or more than a couple of expression = "java(…)" entries are involved.

Purpose group

Spring Boot Development Tooling

Invocation

/iru-java-springboot-code-one-task <task description>

Inputs

Argument Required Description Default

Argument	Required	Description	Default
`<task description>`	Yes	The task’s own text from `implementation_plan.md` — including its exact checkbox line(s) for itself and its sub-tasks, so Step 7 can find and flip them, plus its sub-tasks' text and any relevant "Current code state" context.	None
`reference/`	No	The skill’s own bundled reference directory. If it is missing (the skill directory was copied without it), the skill falls back to the repository’s `CLAUDE.md` conventions and the surrounding code’s style, and says so in its report rather than guessing at what the reference would have said.	Bundled with the skill

<task description>

Yes

The task’s own text from implementation_plan.md — including its exact checkbox line(s) for itself and its sub-tasks, so Step 7 can find and flip them, plus its sub-tasks' text and any relevant "Current code state" context.

None

reference/

The skill’s own bundled reference directory. If it is missing (the skill directory was copied without it), the skill falls back to the repository’s CLAUDE.md conventions and the surrounding code’s style, and says so in its report rather than guessing at what the reference would have said.

Bundled with the skill

Outputs

The implementation, in whichever module Step 2 resolved — with no outward-pointing import, full Javadoc on every type and public/protected member, and no <version> added to any module pom.
Unit tests covering the new behaviour and the edge cases implied by the Javadoc @throws contracts: plain JUnit plus Mockito with no Spring context for domain/application, and mapper/translation/conversion tests for infrastructure/api. In infrastructure/clients/<name> that means mocking the generated client with Mockito and testing the adapter’s own mapping and error translation around it — never starting the compose stack’s API mock, which is a container and therefore the group’s business, even though it starts far faster than a database. A task adding a downstream call also checks that the adapter reads clients.<name>.base-url from configuration, since a hardcoded host silently defeats the integration harness’s redirect to that mock.
This task’s checkbox in implementation_plan.md flipped to [x] with a note naming the module and files and a "group validation pending" marker — edited in place, touching only this task’s own line(s), so a sibling task in a parallel bucket can’t be clobbered.
A report naming the modules touched, the ports added or implemented, the unit-test result, anything deliberately left to the group’s integration pass, any blocker, and any deviation from reference/ made on purpose.

Execution flow

flowchart TD A["Start /iru-java-springboot-code-one-task"] --> B["Step 1: Read reference/README.md,\nthen only the files this task needs"] B -- reference/ missing --> B2["Fall back to CLAUDE.md + surrounding style;\nreport it"] B2 --> C B --> C["Step 2: Resolve target module,\nits allowed imports, and cross-module order"] C -- task's path violates the module rules --> STOP["Step 5: stop and ask —\nthe answer changes what gets built"] C --> D["Step 3: Re-check current code state;\nread neighbouring files in the same module"] D --> E["Step 4: Implement exactly what the task specifies"] E -->|"ambiguous, infeasible, needs a new\nruntime dep or a new distributed pattern"| STOP E --> F["Step 6: Write unit tests;\nrun scoped Surefire (-DskipITs)"] F -- unit test red --> G["Fix implementation or test"] G --> F F -- only verifiable by an integration test --> H["Write the meaningful unit tests,\nleave the rest to the group; report it"] H --> I F --> I["Step 7: Flip this task's checkbox\nwith 'group validation pending'"] STOP --> J["Step 8: Report as blocked;\nleave the checkbox untouched"] I --> K["Step 8: Report modules, ports, tests,\ndeferrals and deviations"]

Dependencies

Invokes

None. It reads its own reference/ directory, edits code and tests, and runs mvn unit-test commands directly.

Invoked by

Java Spring Boot Code One Task Group — once per task in a bucket, in parallel agents when the group is marked parallelizable, via the iru-isolated-skill-executor agent. That skill then performs the bucket-wide validation this one deliberately omits, including the integration tests.

Reachable through the pipeline as a whole because Plan discovers the java-springboot key from this skill’s directory name, and Code One Task Group dispatches that key’s bucket to the group skill above. Also runs standalone as a slash command for a single task.

Related agents

None spawned directly — this skill runs its own scoped unit tests inline, since a Surefire run limited to a couple of test classes produces little output. Delegation to iru-gate-runner happens one level up, in the group skill, where the runs are reactor-wide or container-backed.

Source

SKILL.md on GitHub — the file this page was generated from. The bundled best-practice files live alongside it under reference/.