Scaffold Entity

See .github/skills/scaffold-entity/references/entity-spec.example for the format:

ENTITY="Checkpoint"          # PascalCase
PLURAL="Checkpoints"         # For irregular plurals (default: ${ENTITY}s)
TABLE="checkpoints"          # DB table name (default: lowercased + s)
ENDPOINT="/checkpoints"      # REST path (default: /${TABLE})
FIELDS="name:String location:String elevationM:Integer distanceFromStartKm:BigDecimal"

Supported field types: String, Integer, Long, Double, Boolean, BigDecimal, LocalDate, LocalDateTime, LocalTime, Duration.

Step 2 — Run the scaffold script

cd /Users/ronnieschaniel/dev/spring-hexagonal
./.github/skills/scaffold-entity/scripts/scaffold-entity.sh .github/skills/scaffold-entity/references/<entity>.spec

The script generates 14 files and never overwrites existing ones:

Use --dry-run to preview without writing: ./.github/skills/scaffold-entity/scripts/scaffold-entity.sh <spec> --dry-run

Step 3 — Post-scaffold customizations

The script generates standard CRUD. The agent MUST complete these manual steps:

1. Register the NotFoundException — Add the new <Entity>NotFoundException to src/main/java/com/ultratrail/api/ApiExceptionHandler.java:

   • Add the import
   • Add the class to the @ExceptionHandler({...}) list

2. Add enums — If the entity needs a status enum or other enums:

   • Add public enum <Name> { ... } inside the domain entity
   • Add an @Enumerated(EnumType.STRING) field in the JPA entity
   • Update fromDomain() / toDomain() in the JPA entity

3. Add custom finders — If the entity needs queries beyond findAll/findById:

   • Add the method signature to the domain repository port
   • Add the Spring Data query to the JPA repository
   • Implement it in the adapter
   • Create the corresponding use case

4. Add business logic — If the create use case needs defaults, validation, or computed fields beyond the simple field-copy the script generates.

Step 4 — Validate

Run the full test suite to verify ArchUnit compliance, compilation, and tests:

cd /Users/ronnieschaniel/dev/spring-hexagonal && mvn test

All tests MUST pass before considering the task complete.

Step 5 — Frontend sync (if applicable)

If the user wants frontend integration, use the controller-data-to-ts-models skill to generate TypeScript models from the new controller.

Example

User says: "Create a Checkpoint entity with name, location, elevation, and distance from start"

1. Create .github/skills/scaffold-entity/references/checkpoint.spec:

   ENTITY="Checkpoint"
   TABLE="checkpoints"
   ENDPOINT="/checkpoints"
   FIELDS="name:String location:String elevationM:Integer distanceFromStartKm:BigDecimal"
   

2. Run: ./.github/skills/scaffold-entity/scripts/scaffold-entity.sh .github/skills/scaffold-entity/references/checkpoint.spec

3. Add CheckpointNotFoundException to ApiExceptionHandler.java

4. Run: mvn test → all green

5. Done. 14 files created, 0 lines of boilerplate written by the LLM.