/java-scaffold

description: Scaffolds a brand-new Spring Boot project from scratch — build file, package structure, and a starter feature. Use when user asks to "create a new Spring Boot project", "bootstrap a project", "start a new project", "generate a new app", or "scaffold a new service".
argument-hint: "[describe the project, e.g. 'e-commerce REST API with user management']"

/java-scaffold — New Spring Boot Project Generator

You are a Spring Boot project bootstrapper. Use this skill to create a **new project from scratch**.

> **Already have a project?** Use `/java-crud` instead — it adds a CRUD feature to an existing codebase.

Step 1 — Gather requirements (all at once)

Ask these questions in a single message:

1. **Project name** — e.g., `shop-api`, `user-service` 2. **Java version** — 8, 11, 17, or 21 (recommend 21 for new projects) 3. **Spring Boot version** — 2.7.x, 3.2.x, 3.3.x, or 4.0.x (recommend 3.3.x; 4.0.x requires Java 17+) 4. **Build tool** — Maven or Gradle 5. **Base package** — e.g., `com.example.shop` 6. **First domain entity** — e.g., `Product`, `User`, `Order` 7. **Database** — PostgreSQL, MySQL, or H2 (H2 only for throwaway prototypes)

Confirm before generating:

Scaffolding: shop-api
Java 21 | Spring Boot 3.3.x | Maven
Package: com.example.shop
First entity: Product
Database: PostgreSQL (Testcontainers for tests)
Generate? (yes to proceed)

Step 2 — Generate build file

Use the Maven or Gradle template from `references/templates.md`. Fill in `{spring-boot-version}`, `{project-name}`, and `{java-version}`.

For Spring Boot 4.0.x: uses `jakarta.persistence.*` (same as 3.x). Requires Java 17 minimum.

Step 3 — Generate package structure

Use the directory layout from `references/templates.md`.

Step 4 — Generate application.yml

Use the `application.yml` and `application-dev.yml` templates from `references/templates.md`.

**Note:** Never commit real credentials. Use environment variables or Spring Vault for production secrets.

Step 5 — Generate starter feature

Generate the first entity using the same templates as `/java-crud`:

• Entity class (with `@PrePersist` / `@PreUpdate` timestamps)
• Repository extending `JpaRepository`
• Service with `@Transactional(readOnly = true)` reads
• Controller with `ResponseEntity` returns
• Request/Response DTOs (records for Java 16+, classes for Java 8–15)
• `GlobalExceptionHandler` with `@RestControllerAdvice` — see `references/templates.md`
• Unit test (Mockito)
• Repository integration test (Testcontainers)

**Spring Boot version rules:**

• 3.x+: use `jakarta.persistence.*`, `@SQLRestriction` for soft delete
• 2.x: use `javax.persistence.*`, `@Where(clause = "deleted = false")` for soft delete

Step 6 — Post-generation checklist

• [ ] Run `mvn spring-boot:run` or `./gradlew bootRun` to verify it starts
• [ ] Start a local PostgreSQL: `docker run -p 5432:5432 -e POSTGRES_PASSWORD=postgres postgres:16-alpine`
• [ ] Add Flyway or Liquibase for schema management before going to production
• [ ] Add Spring Boot Actuator for health checks: `spring-boot-starter-actuator`

Next Steps

• Add more features → `/java-crud <EntityName>`
• Review the generated code → `/java-review`
• Generate more tests → `/java-test`
• Security review → `/java-security-check` or `java-security-reviewer` agent