Setup

---

name: setup description: > Wire the Spring Boot guardrails into this project — install the jpa-guardrail PostToolUse hook + ruleset, register it in settings.json, copy the springboot-reviewer agent, and inject the Spring Boot rule block into CLAUDE.md. Short interview fills project slots (base entity, migration tool, strict mode). Trigger phrases: "set up spring boot guardrails", "install java backend toolkit", "wire jpa guardrails", "setup springboot toolkit". argument-hint: "[--strict] [--no-agent]"

Spring Boot Toolkit — Setup

Installs the enforcement layer into the project's .claude/ so it is committed and shared with the whole team — a teammate who clones the repo gets the guardrails even without installing this plugin. The authoring skills (jpa-entity, spring-rest-endpoint, db-migration) stay plugin-provided and are not copied.

Plugin source root (where templates live): the directory containing this skill's parent, i.e. plugins/java-backend-toolkit/. Resolve files relative to it.

Step 1 — Verify this is a Spring Boot + JPA project

Confirm at least one of:

• pom.xml containing spring-boot-starter, or
• build.gradle / build.gradle.kts containing spring-boot.

And JPA in use: spring-boot-starter-data-jpa (or jakarta.persistence / javax.persistence imports).

If not a Spring Boot + JPA project → stop and say so. This toolkit's v1 paved road is Spring Boot 3.x + Spring Data JPA only (no Kotlin, reactive, or non-Spring).

Step 2 — Detect project slots (smart defaults, confirm — do not interrogate)

Scan, propose, ask only to confirm:

Slot	Detect from	Default if absent
MIGRATION_TOOL	flyway-core dep or src/main/resources/db/migration/ → Flyway; liquibase-core → Liquibase	Flyway
BASE_ENTITY	a @MappedSuperclass class and/or AuditingEntityListener usage	a @MappedSuperclass BaseEntity with Spring Data JPA auditing
PROJECT_NAME	CLAUDE.md identity / repo dir name	repo directory name
strict mode	--strict arg	jpql-injection blocks (already the default in guardrails-config.json)

Show the resolved slot values in one block and get a single confirmation.

Step 3 — Install the guardrail hook (copy flat into .claude/hooks/)

Copy these three files from the plugin's hooks/ and rules/ into the project's .claude/hooks/ (flat — the hook finds its ruleset beside itself):

• hooks/jpa-guardrail.py → .claude/hooks/jpa-guardrail.py
• rules/ruleset.json → .claude/hooks/ruleset.json
• hooks/guardrails-config.json → .claude/hooks/guardrails-config.json

If --strict was NOT passed and the user wanted advisory-only for injection too, edit the copied guardrails-config.json to set "strictChecks": []. Otherwise leave the default (["jpql-injection"]).

Do not modify the plugin's source files — only the copies in the project.

Step 4 — Register the hook in .claude/settings.json (merge, never clobber)

Read .claude/settings.json (create {} if absent). Under hooks.PostToolUse, add this entry only if an equivalent is not already present:

{ "matcher": "Write|Edit", "hooks": [{ "type": "command", "command": "python3 .claude/hooks/jpa-guardrail.py" }] }

Preserve every existing hook (e.g. protect-files.py, observe.py). Append; do not replace the array. If a jpa-guardrail.py entry already exists, skip (idempotent).

Step 5 — Inject the Spring Boot rule block into CLAUDE.md

Load assets/rules/springboot-rules.md.tmpl, substitute {{PROJECT_NAME}}, {{BASE_ENTITY}}, {{MIGRATION_TOOL}}, {{TEMPLATE_VERSION}} (= toolkit version).

• If the project keeps rules in .claude/rules/, write .claude/rules/springboot.md.
• Otherwise append a ## Spring Boot conventions section to CLAUDE.md (do not duplicate if a prior install already added it — replace that section instead).

Step 6 — Install the reviewer agent (unless --no-agent)

Copy agents/springboot-reviewer.md → .claude/agents/springboot-reviewer.md. This makes the reviewer available to teammates and keeps its checklist (the same ruleset.json) in the repo.

Step 7 — Report

Print a summary:

Installed Spring Boot guardrails:
  .claude/hooks/jpa-guardrail.py        (PostToolUse: Write|Edit on *.java)
  .claude/hooks/ruleset.json            (6 rules — 5 hook-enforced, 1 reviewer-only)
  .claude/hooks/guardrails-config.json  (strict: <strictChecks>)
  .claude/agents/springboot-reviewer.md
  CLAUDE.md                             (Spring Boot conventions block)

Try it: create an @Entity without @Version → the hook reminds you at write time.
Authoring helpers (from the plugin): jpa-entity, spring-rest-endpoint, db-migration.
Tune checks in guardrails-config.json (disabledChecks / strictChecks); suppress per-file
with `// jbt:ignore <rule-id>`.

Failure modes — do NOT

• Do NOT clobber existing hooks in settings.json — merge only.
• Do NOT copy the scaffold skills into the project — they are plugin-provided.
• Do NOT edit the plugin's source ruleset.json/guardrails-config.json; only project copies.
• Do NOT install on a non-Spring-Boot or Kotlin/reactive project — stop with a clear message.
• Do NOT invent slot values you did not detect or confirm.
• Do NOT register the hook twice — check for an existing entry first.