Use this skill when building a new Spring Boot REST API backend or transforming an existing Spring Boot project toward a specific, opinionated target architecture. Triggers include: scaffolding Spring Boot APIs, adding backend modules (auth, persistence, exception handling, DTOs, tests), refactoring an existing Spring Boot backend to meet architectural standards, or any task that modifies the backend layer of a Spring Boot application. Do NOT trigger for general Java questions, non-Spring projects, or frontend work.
This skill builds new Spring Boot REST API projects or transforms existing ones toward a defined, opinionated target architecture. It does not infer. It does not generate before it inspects. It evaluates existing conventions against the target architecture and transforms what conflicts.
These rules apply at all times, regardless of phase. They cannot be overridden.
Repository-first reasoning. Never infer versions, stack choices, or architecture when the repository can answer those questions. All technical facts must be grounded in evidence from project files.
Onboarding before everything. No architecture advice, code generation, dependency changes, or structural modifications may occur until onboarding is complete. This rule is not negotiable. See Enforcement.
Target architecture is the authority. Existing conventions are inventoried and evaluated — not preserved by default. What aligns is extended. What conflicts is transformed. What is absent is built.
Documentation and memory are part of the workflow. Phase outputs are written
using the documentation-management skill and the memory-bank skill. Ad-hoc
file writes outside those interfaces are not permitted for phase outputs.
Explicit uncertainty. Facts, inferences, and unknowns must be separated in all outputs. Silent assumption resolution is prohibited.
Convention conflicts require confirmation. When a requested change conflicts with an established project convention, surface the conflict and ask for confirmation before proceeding. See Conflict Resolution Protocol.
Each phase has a dedicated reference file. Load only the reference file for the active phase. Do not load reference files for phases not currently in use.
| Phase | Name | Reference file | Status |
|---|---|---|---|
| 0 | Project Onboarding and Environment Assessment | references/phase-0-onboarding.md | Active |
Future phases (authentication, shared components, entities, etc.) will be added here as new rows. Each will have its own reference file.
At the start of every session, determine the active phase before doing anything else:
memory-bank skill.references/phase-0-onboarding.md
and follow its instructions.When the user explicitly requests a phase transition (e.g., "let's move to building authentication"), update the active phase in memory, then load the corresponding reference file.
When a requested change conflicts with an established project convention:
Default behavior:
Override behavior (--override-convention or natural language equivalent):
Recognized forms: the flag --override-convention, or phrases such as
"I know this deviates from conventions", "override the convention here",
"force this even if it conflicts".
When an override is present:
Note: override signals do not apply to the onboarding gate. See Enforcement.
Onboarding is mandatory and cannot be skipped.
If the user asks to skip onboarding or proceed directly to implementation:
Without onboarding, there is no basis for determining what the project state is, what aligns with the target architecture, or what work is safe to perform.
Never assume any of the following without file evidence:
application.yml is used (may be application.properties)