project-bootstrap

java (JDK 21+) · git · curl. Nothing else. mvn/gradle on the PATH are not required — the Initializr's starter.tgz already brings the matching wrapper (mvnw or gradlew, whichever build.tool resolved to).

No Python, no template engines, no bash. The hooks are a single Java file run in single-file source mode, which makes them identical on Linux, macOS, and Windows — the same dependency the target audience already has mandatorily.

pom.xml or build.gradle already exists at <project> (§ Where the project is born). This skill does not migrate existing projects nor overwrite structure. In that case: stop, report, suggest /new-feature from a session opened in that directory instead.

The session runs in a clone of this repository, and the project is generated next to it:

<project> = <this repository>/../<artifactId>

Resolve it to an absolute path once the interview has settled artifactId, before step 3, and use that same absolute path in every later step. Never generate into this repository: ArchHook.java export refuses a destination equal to its source (step 6.6), and the creation skills and blueprint catalog would end up beside the project's code.

java --version && git --version && curl --version | head -1
ls ${CLAUDE_SKILL_DIR}/templates/*.example

Check that the exemplars the procedure cites are there. Some are conditional on the active blueprint's build.tool — check only the ones the resolved tool needs, per the table below:

Independent calls go in one response. Every turn re-reads the whole context, so a step's exemplars are parallel Reads and its files — every package-info.java of step 4.7 — parallel Writes, in one response each. Never a shell loop or heredoc instead: guard bash may not read its paths, and one bad heredoc corrupts every file it writes (@.claude/lessons-learned/lessons-learned-020.md § 7).

The blueprint, the build tool and every other answer come from /init-project's interview, run in the main session before the agent that runs this skill starts — that agent runs in the background and cannot ask (@.claude/decisions/0123-lessons-learned-020-init-project-run.md). This skill never asks. A missing answer stops it: report blocked: missing <field>. Never assume the architecture: it's the most expensive decision to reverse in the whole project. Check the given id against .claude/blueprints/*/*.yaml, listed dynamically — each architecture lives at .claude/blueprints/<id>/<id>.yaml.

The blueprint's build.tool (maven or gradle) is a default, not a lock-in — the answer the interview passed wins. Step 2 resolves the final value and every step from step 3 on assumes it's already settled.

Read the YAML and check, one by one:

Don't invent defaults for dependency_rules — it's the backbone of the enforcement.

Resolve the effective build tool now, before step 3. build.tool in the blueprint is the default; @.claude/blueprints/_schema.md documents it as "Overridable at initialization" — if the user asked for the other tool in /init-project's interview, that override wins. Whatever the final value — maven or gradle — every step from here on branches on it once and stays with that choice. Never generate both.

The Initializr's type= parameter is what actually picks the build system — everything downstream just follows the file shapes it produces:

Branch once on the build tool resolved before step 3, and stay on that branch for the rest of this step — write only the files of the tool actually chosen. A gradle project never gets a pom.xml, mvnw, or .mvn/; a maven project never gets a build.gradle, settings.gradle, or gradlew.

Read references/build-<tool>.md § 4 — only the tool just resolved — then references/scaffold.md § 4. The first holds the tool's file layout (POMs or Gradle scripts, wrapper); the second what both tools share, including the andaime rule every later template copy follows. Done when every module of the blueprint exists with its depends_on wired in the build files, and nothing of the other tool is on disk.

The steps from here to 8.6 run in order, every one of them. Each heading below names the reference that holds its body; open it before executing the step — the spine alone is not the procedure.

Nothing is generated: the exception family belongs to domain-modeling. Read the section for why, so step 4.7 does not reintroduce it.

config/checkstyle/checkstyle.xml plus the tool's plugin, bound to validate, and config/checkstyle/checkstyle-test.xml, the light rule set for src/test. Done when the build file carries the plugin and both configs exist.

One package-info.java per role in packages.map, plus the application*.yml of each active feature. No other .java.

At the project root.

Under src/main/resources of the module with contains_main: true.

Base pair, plus one service per active feature that needs a container, merged through docker-architect's templates.

Read references/project-files.md now — it holds steps 5 to 7. .claude/forbidden-imports.txt, written by ArchHook.java boundary-map — never by hand.

Exactly one workflow template — the one of the resolved build tool.

ArchHook.java export writes rules, skills, agents, hook, schema and settings, and rewrites the rules' paths. Nothing in the generated project may depend on this repository.

Nothing to run — what the final report has to be able to say.

Invoke transport-security-setup via the Skill tool, with a one-line context: build tool, blueprint id, project: <project>, and "chained from project-bootstrap — skip your Verify". It owns the two questions this step asks — where TLS terminates, and the local profile or local edge — and writes the transport configuration into application.yml, the HSTS filter when no security chain exists, the transport IT, and the **Transport: paragraph of the root CLAUDE.md step 6 wrote; the edge service or the Dockerfile port it hands to docker-architect. Before Verify, so step 8 builds and runs the test it wrote. Same class, territories summed (@.claude/decisions/0092-guard-same-class-chain-sums-territories.md). Don't write any server.ssl, spring.ssl or forward-headers-strategy line here.

Everything in this step branches on the same build tool resolved before step 3 — run only the column that matches.

Read references/verify-and-report.md now — it holds steps 8 to 8.6. Done when the build passes, or when the report says why it failed.

Invoke sonarqube-setup via the Skill tool, with a one-line context: build tool, coordinates, and project: <project>. It owns the one question this step asks — an existing server (URL, authentication) or a local container — and the scanner in the root build file, the CI step for an external server, and, for a local one, the sonarqube service it hands to docker-architect. After Verify, so the build it touches is already known green; before the README, so step 8.5's {{outputContractBlock}} carries its SonarQube: line. The chained skill joins this phase instead of replacing it — same class, territories summed (@.claude/decisions/0092-guard-same-class-chain-sums-territories.md) — so the steps after it still write. Don't write any sonar.* line here.

README.md (English) and README.pt-br.md, after Verify.

.claude/audit-usage/GENESIS.md, once.

✅ Project <name> created — blueprint <id>

Modules:
  <path> → depends on <list>
  ...

Versions (resolved by the Initializr): Java <x> · Spring Boot <y> · <build tool> (wrapper <z>)
Active features: <list>
Business code: none — by design. <n> package-info.java written
Boundaries: <n> rules in .claude/forbidden-imports.txt — blocking verified ✓
Checkstyle: config/checkstyle/checkstyle.xml — plugin <v> · tool <v>, validate phase · checkstyle-test.xml over src/test
Spotless: check bound to the build (verify / check) — formatting and unused imports, main and test
Lombok: lombok.config at the root — @Data and @Setter stop compilation
ArchUnit: to be installed — `test-architect` skill (see Next steps)
Coverage: JaCoCo generates a report; the 80%/70% gate comes in with `test-architect`
Self-contained: <n> rules + <n> skills + <n> agents + ArchHook.java + extensions.json written by `ArchHook.java export` — no dead paths ✓
Provenance: .claude/.arch-provenance.json — blueprint <id>, ref <ref>, commit <short sha>. `/arch-doctor` reports anything edited since
Audit trail: .claude/audit-usage/ active — one report per skill or agent invocation from now on, by `/command` or by the model. GENESIS.md records this run itself, in tokens
Docker: Dockerfile + docker-compose.yml — <list: app, plus one entry per service `docker-architect` merged in step 4.10 for an active feature, e.g. "postgres (persistence-jpa)", "otel-collector (observability)"> — extend with `docker-architect` for anything a future use case adds
Local secrets: .env (untracked) holds DB_PASSWORD, read by docker compose and imported by application.yml for the host run; a fresh clone copies .env.example — <only with persistence-jpa; omit the line otherwise>
Observability UI: <omit this line entirely when `observability` is not active> none — the collector exports to `debug`, which writes spans and metrics to its own stdout and is not a dashboard. Run `/docker-architect` to add one: Jaeger (traces, one container) or Grafana + Tempo + Prometheus (traces and metrics, three)
Transport: <the first line of `transport-security-setup`'s report — topology A edge | B direct | C mutual TLS | C′ mesh> — HTTP/2 on, HSTS by <Spring Security | HstsHeaderFilter>, <ForwardedHeadersIT | TransportSecurityIT>
SonarQube: <the first line of `sonarqube-setup`'s report — existing server <url> | SonarCloud <org> | local container on http://localhost:9000> — scanner <v>, CI step <added | none>
MCP: <none — no server designed for this project yet | <n> server(s) copied to .mcp.json, see MCP-SETUP.md>
Build: <PASSED | FAILED: reason>
Docs: README.md (English, default) + README.pt-br.md — origin, blueprint, stack, skills/agents, this report

Next steps:
  1. /use-case-design <first-use-case-name>
  2. Install the architecture tests (ArchUnit) and wire up the coverage gate with the
     `test-architect` skill as soon as business classes exist. Until then boundaries
     are guaranteed by the `check` hook at edit time (inside Claude Code) and by CI's
     `doctor gate`, which sweeps every source file against `.claude/forbidden-imports.txt`
     (whoever wrote it)<, and by the POMs' `depends_on` (in the build) — only if
     `layout: multi-module`>.
  3. SonarQube — <local: `docker compose up -d sonarqube`, log in at http://localhost:9000
     as admin/admin (a password change is forced), create a token under My Account →
     Security, `export SONAR_TOKEN=…`, then `<./mvnw -B verify sonar:sonar | ./gradlew build sonar>`
     | external: create the `SONAR_TOKEN` repository secret; CI analyses from the next push>

Every rule in .claude/rules/ reaches the project through step 6.6 — ArchHook.java export copies them and rewrites their paths. None is read during generation: the part of each rule that a bootstrap step turns into a file is already inside the template that step copies. The table says which, so a rule change knows which template to follow.

A rule that changes what a template must say is followed by an edit to that template, not by a read here. If a step ever needs a rule that doesn't exist in rules/, create the rule file first — don't write it inside this skill.

Form 1 (auto-invocable skill): it is a long generation procedure with no interview of its own, and /init-project already isolates the verbose part inside the project-initializer agent. Form 3 was rejected for this file because the three reasons for an agent (preserve context, restrict tools, change model) are satisfied by that caller, not by this procedure — two nested agents would only add a second boundary to pass the blueprint across.

Runs on sonnet with effort: high: generation is template- and YAML-driven, and it runs inside project-initializer, also on sonnet. A skill's model inside a subagent is not documented, so the pin there is a declaration that agrees with the agent's (@.claude/decisions/0081-skill-model-required-per-class.md).