Generate a detailed specification document for building a Spring Boot 3 REST API application with Spring Modulith packaging. Database (MongoDB, PostgreSQL, MySQL, or none), authentication (Keycloak OAuth2 Resource Server, Spring Security JWT, or none), scheduling (Quartz + Spring Batch or none), and messaging (RabbitMQ pub/sub or none) are configurable based on user input. Standardized input: application name (mandatory), version (mandatory), module (optional). Use this skill whenever the use...
Scanned 5/27/2026
Install via CLI
Skills Directoryopenskills install rashidee/co2-skills---
name: specgen-spring-jpa-restapi
model: claude-opus-4-6
effort: high
description: >
Generate a detailed specification document for building a Spring Boot 3 REST API
application with Spring Modulith packaging. Database (MongoDB, PostgreSQL, MySQL, or none),
authentication (Keycloak OAuth2 Resource Server, Spring Security JWT, or none), scheduling
(Quartz + Spring Batch or none), and messaging (RabbitMQ pub/sub or none) are configurable
based on user input.
Standardized input: application name (mandatory), version (mandatory), module (optional).
Use this skill whenever the user asks to create a spec, specification, blueprint, or
technical design document for a new Spring Boot REST API application.
Also trigger when the user says things like "spec out a new REST API project",
"design a Spring Boot API skeleton", "write a technical spec for my new API",
"scaffold spec for a REST API", or any request for a specification document
describing a Spring Boot REST API application. Even if the user only mentions
a subset of the stack (e.g., "Spring Boot API" or "Spring REST with MySQL" or
"Spring Boot API with Keycloak"), this skill likely applies — ask and confirm.
---
# Spring Boot REST API Specification Generator
This skill generates a comprehensive specification document (Markdown) that serves as a
blueprint for building a Spring Boot 3 REST API application. The spec is intended to be
followed by a developer or a coding agent to produce a fully functional project scaffold.
The specification does NOT generate code. It produces a detailed, opinionated technical
document describing every layer of the application — from Maven configuration to controller
endpoints to security filter chains — so that implementation becomes a mechanical exercise.
## Technology Stack
### Core Stack (Always Included)
These are the fixed versions the spec targets. Do not deviate unless the user explicitly
requests different versions.
| Component | Version |
|--------------------|-----------|
| Java JDK | 21 |
| Spring Boot | 3.5.7 |
| Maven | 4.0.0 |
### Optional Integration Versions
Include in the version table only when the corresponding integration is selected.
| Component | Version | When Selected |
|--------------------|-----------|----------------------|
| MongoDB | 8.0.19 | Database = MongoDB |
| PostgreSQL | 17.x | Database = PostgreSQL|
| MySQL | 8.4.x | Database = MySQL |
| Keycloak | 26.5.3 | Auth = Keycloak |
| RabbitMQ | 4.x | Messaging = yes OR Remote Partitioning = yes |
## Core Dependencies
The spec must include these in the Maven configuration section (always):
- Spring Web (starter-web)
- Spring Modulith (core, events-api)
- Lombok
- Spring Boot DevTools
- MapStruct (with annotation processor)
- Jackson (included via starter-web, for JSON serialization)
- SpringDoc OpenAPI (`springdoc-openapi-starter-webmvc-ui`) for API documentation
### Conditional Dependencies
**If Database = MongoDB:**
- Spring Data MongoDB (`spring-boot-starter-data-mongodb`)
- MongoDB Driver
- Spring Modulith starter-mongodb (`spring-modulith-starter-mongodb`)
**If Database = PostgreSQL or MySQL:**
- Spring Data JPA (`spring-boot-starter-data-jpa`)
- PostgreSQL driver (`org.postgresql:postgresql`) or MySQL driver (`com.mysql:mysql-connector-j`)
- Flyway (`org.flywaydb:flyway-core`) for schema migration
- Spring Modulith starter-jpa (`spring-modulith-starter-jpa`)
**If Auth = Keycloak:**
- Spring Security (`spring-boot-starter-security`)
- Spring Security OAuth2 Resource Server (`spring-boot-starter-oauth2-resource-server`)
**If Auth = Spring Security (JWT):**
- Spring Security (`spring-boot-starter-security`)
- `io.jsonwebtoken:jjwt-api`, `jjwt-impl`, `jjwt-jackson` for JWT token generation/validation
**If Scheduling = yes:**
- Spring Quartz (`spring-boot-starter-quartz`)
- If Database = MongoDB: `io.fluidsonic.mirror:fluidsonic-mirror-quartz` (MongoDB job store for Quartz)
- If Database = PostgreSQL/MySQL: Quartz JDBC job store (built-in)
**If Scheduling = yes AND Spring Batch = yes:**
- Spring Batch (`spring-boot-starter-batch`)
**If Scheduling = yes AND Spring Batch = yes AND Remote Partitioning = yes:**
- Spring Batch Integration (`spring-batch-integration`)
- Spring Integration AMQP (`spring-integration-amqp`)
- Spring Boot AMQP Starter (`spring-boot-starter-amqp`)
**If Messaging = yes:**
- Spring Boot AMQP Starter (`spring-boot-starter-amqp`)
*(shared with Remote Partitioning — if both are selected, include the dependency once)*
**If Reporting = yes:**
- JasperReports (`net.sf.jasperreports:jasperreports:7.0.3`) — report engine with JRDesign API for programmatic layout
- JasperReports Fonts (`net.sf.jasperreports:jasperreports-fonts:7.0.3`)
- OpenPDF (`com.github.librepdf:openpdf:2.0.4`) — PDF export engine for JasperReports 7.x
- Apache POI OOXML (`org.apache.poi:poi-ooxml:5.4.1`) — XLSX export support
## When the Skill Triggers
Generate the spec when the user provides an **application name** and **version** that
corresponds to one of the custom applications defined in `CLAUDE.md`. The skill
reads all required inputs from the project's context files — no interactive Q&A is needed
for the core inputs.
The user invokes this skill by specifying the target application and version, for example:
- `/specgen-spring-jpa-restapi hc_adapter v1.0.0`
- `/specgen-spring-jpa-restapi hc_adapter v1.0.0 module:Job Demand`
- `/specgen-spring-jpa-restapi "HC Adapter" v1.0.0`
The skill then locates the matching context folder and reads all input files automatically.
## Version Gate
Before starting any work, resolve the application folder first (see Input Resolution below), then check `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):
1. If `<app_folder>/CHANGELOG.md` does not exist, skip this check (first-ever execution for this application).
2. If `<app_folder>/CHANGELOG.md` exists, scan all `## vX.Y.Z` headings and determine the **highest version** using semantic versioning comparison.
3. Compare the requested version against the highest version:
- If requested version **>=** highest version: proceed normally.
- If requested version **<** highest version: **STOP immediately**. Print: `"Version {requested} is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected."` Do NOT proceed with any work.
## Input Resolution
This skill uses standardized input resolution. Provide:
| Argument | Required | Example | Description |
|----------|----------|---------|-------------|
| `<application>` | Yes | `hc_adapter` | Application name to locate the context folder |
| `<version>` | Yes | `v1.0.0` | Version to scope processing |
| `module:<name>` | No | `module:Job Demand` | Limit generation to a single module |
### Application Folder Resolution
The application name is matched against root-level application folders:
1. Strip any leading `<number>_` prefix from folder names (e.g., `1_hc_adapter` -> `hc_adapter`)
2. Match case-insensitively against the provided application name
3. Accept snake_case, kebab-case, or title-case input (all match the same folder)
4. If no match found, list available applications and stop
### Auto-Resolved Paths
| File | Resolved Path |
|------|---------------|
| PRD.md | `<app_folder>/context/PRD.md` |
| Module Models | `<app_folder>/context/model/` |
| Output (specification) | `<app_folder>/context/specification/` |
### Example Invocations
- `/specgen-spring-jpa-restapi hc_adapter v1.0.0` (all modules)
- `/specgen-spring-jpa-restapi hc_adapter v1.0.0 module:Job Demand` (one module)
- `/specgen-spring-jpa-restapi "HC Adapter" v1.0.0`
### Version Filtering
When a version is provided, only include user stories, NFRs, and constraints from versions
<= the provided version. For example, if `v1.0.3` is specified:
- Include items tagged `[v1.0.0]`, `[v1.0.1]`, `[v1.0.2]`, `[v1.0.3]`
- Exclude items tagged `[v1.0.4]` or later
- Version comparison uses semantic versioning order
### Module Filtering
When `module:<name>` is provided:
- Only generate the `SPEC.md` for that specific module
- Other existing module spec files remain untouched
- `SPECIFICATION.md` (root) gets a partial update — only that module's entry in the TOC
is added or updated; all other TOC entries are preserved as-is
## Gathering Input
The specification is driven by **five input sources** that are read from the project's
context files. The skill does NOT ask the user for database, authentication, scheduling,
or messaging choices — it **determines** these automatically from the context.
### Input 1: Application Name (from CLAUDE.md)
From CLAUDE.md (already loaded in context), locate the target application under the **Custom Applications**
section. Extract:
- **Application name**: The section heading (e.g., "HC Adapter", "SC Adapter")
- **Application description**: The description paragraph below the heading
- **Dependencies**: The "Depends on" list — this is the primary source for determining
optional components (see [Determining Optional Components](#determining-optional-components))
The application name is used to derive:
- **Artifact ID**: Kebab-case of the application name (e.g., `hc-adapter`)
- **Group ID**: `com.bestinet.urp` (project-level constant)
- **Base package**: `com.bestinet.urp.<artifactid_no_hyphens>` (e.g., `com.bestinet.urp.hcadapter`)
### Input 2: User Stories (from PRD.md)
Read `<app_folder>/context/PRD.md`. This file contains all user stories
organized by module. Extract:
- **System modules**: Modules under the `# System Module` heading (e.g., User, Notification,
Activities, Audit Trail). These become system-level modules in the spec.
- **Business modules**: Modules under the `# Business Module` heading (e.g., Location
Information, Corridor, Employer). These become business-level modules.
- **User stories per module**: Each `### User Story` section contains tagged items like
`[USHC00108] As a user, I want to...`. These define the functional requirements for
each module's service interface and API endpoints.
The user stories directly inform:
- Which CRUD operations each module's service must expose
- Which REST API endpoints are needed
- Which request/response DTOs and validation rules apply
**Important:** Items with strikethrough (`~~text~~`) are deprecated — do NOT include them
as active requirements. Instead, list them in the "Removed / Replaced" subsection of the
traceability table (see spec-template.md) so that developers can see what was removed and
which version removed it. If a deprecated item has a replacement (e.g., `USHC00015` replaced
by `USHC00222`), note the replacement ID.
- **Version tags per item**: Each `### User Story`, `### Non Functional Requirement`,
and `### Constraint` section contains one or more version blocks formatted as `[v1.0.x]`.
Items listed under each version tag belong to that version. The skill must track the
version tag for each item (user story, NFR, constraint) and carry it through to the
generated specification's traceability section. When a version block explicitly lists
"Removed ... from previous version", record those removals in a "Removed / Replaced"
subsection with the version that removed them and the replacement ID (if any).
### Input 3: Non-Functional Requirements (from PRD.md)
Within the same `PRD.md`, each module has a `### Non Functional Requirement` section
with tagged items like `[NFRHC0120]`. These inform:
- Data storage strategies (e.g., "stored in staging database", "stored in the database")
- Integration patterns (e.g., "API call to external service", "sent asynchronously")
- Performance constraints (e.g., "automatically deleted after 30 days")
- Security requirements (e.g., "API key authentication", "JWT validation")
NFRs should be mapped to specific technical decisions in the spec — for example, an NFR
stating "staging database" confirms adapter pattern, while "sent asynchronously" confirms
event-driven processing.
### Input 4: Constraints (from PRD.md)
Within the same `PRD.md`, each module has a `### Constraint` section with tagged
items like `[CONSHC042]`. These define hard boundaries that the spec must enforce:
- Field-level restrictions (e.g., "only accept ISO3 country codes")
- Feature boundaries (e.g., "only 2 message types supported")
- Scope limitations (e.g., "does not manage any user, permissions and roles")
Constraints are embedded directly into the relevant module blueprint — they inform
service interface contracts, validation rules, and API endpoint configurations.
### Input 5: Module Model (from model/ folder)
Read `<app_folder>/context/model/MODEL.md` first as the index, then read the
individual module model files in each module subfolder.
**MODEL.md** provides:
- Summary table of all modules with entity counts and design decisions
- Links to each module's detailed model files
**Per-module files** (e.g., `model/job-demand/model.md`):
- Complete entity field definitions with types and constraints
- Embedded vs. referenced relationships
- Table names
- Index specifications
- Audit field patterns
**Per-module schema** (e.g., `model/job-demand/schemas.json`):
- JSON schemas defining exact field types, required fields, and validation rules
**Per-module diagram** (e.g., `model/job-demand/entity-model.mermaid`):
- Visual representation of entity structure and relationships
The module model directly maps to:
- JPA entities (field-for-field, not placeholder) or MongoDB documents
- Repository methods and query patterns
- MapStruct mapper definitions
- DTO structures matching the actual module fields
- Service interface method signatures
- **Version tracking**: The MODEL.md summary table includes a "Versions" column listing
which versions each module participates in (e.g., "1.0.0, 1.0.1, 1.0.3"). Per-module
model.md files may also include version annotations on fields and indexes. The skill
must carry these version tags into the generated specification.
## PRD.md Extended Sections
Before determining optional components, check PRD.md for the following extended sections and extract their content for use throughout specification generation:
### Architecture Principle Extraction
If PRD.md contains an `# Architecture Principle` section, read it and extract architectural patterns as a structured context object. These patterns serve as **primary signals** for optional component determination and specification content:
| Pattern to Extract | How It Influences the Specification |
|---|---|
| Framework mention (e.g., "Spring Boot") | Validates technology stack choice |
| "Stateless" | Confirms stateless REST API — no HTTP session, JWT validation only; include in Security section |
| "Event-driven" | Enhances event publishing/subscribing sections with event catalog and explicit listener patterns |
| "Message driven" / "message queue" | Validates RabbitMQ integration; include message flow per module |
| "Document based database" / "MongoDB" | Primary signal for Database = MongoDB |
| "At-least-once delivery" | Add Idempotency section with idempotency key header pattern and deduplication |
| "Container based deployment" | Confirms `${ENV_VAR}` syntax for configuration |
| "API gateway" | Adjust base URL configuration for gateway routing |
| "Scale out" / "horizontally scalable" | Note horizontal scaling considerations in deployment section |
If the section is absent, proceed with existing CLAUDE.md-only detection.
### High Level Process Flow Extraction
If PRD.md contains a `# High Level Process Flow` section:
1. Parse all named process flows and their ordered steps
2. Each process flow is an **authoritative source** for messaging pipeline sections in per-module SPEC.md:
- Each step maps to a service method, event listener, or message handler
- Error paths generate exception handlers and dead-letter queue configurations
- ACK/NACK patterns become outbound message publisher specs with defined schemas
3. Include a "Process Flow Implementation" subsection in each affected module's SPEC.md mapping flow steps to service methods
4. Generate an event catalog in SPECIFICATION.md listing all domain events from process flows
If the section is absent, derive messaging patterns from NFRs only (existing behavior).
---
## Determining Optional Components
Instead of asking the user, the skill determines optional components by analyzing the
dependencies listed in `CLAUDE.md`, the `# Architecture Principle` section in PRD.md (if present),
and cross-referencing with PRD.md NFRs and constraints.
### Database Detection
**First check PRD.md `# Architecture Principle`**: If it explicitly mentions a database type (e.g., "document based database", "MongoDB", "relational database", "MySQL"), use that as the primary signal.
**Fallback to CLAUDE.md**: Examine the "Depends on" list in CLAUDE.md for the target application:
| Dependency Pattern | Database Selection |
|---|---|
| References "Hub Database" (MongoDB) | Database = MongoDB |
| References "HC Database" or "SC Database" (MySQL) | Database = MySQL |
| No database dependency listed | Database = none |
Also check `CLAUDE.md`'s database section for the exact database name, host, and
credentials to use in the spec's application configuration. Read `ENVIRONMENT.md` (in the
project root) for host, port, and credentials.
### Authentication Detection
| Dependency Pattern | Auth Selection |
|---|---|
| References "Hub Single Sign On" (Keycloak) | Auth = Keycloak (Resource Server) |
| PRD.md constraint says "does not manage any user, permissions and roles" | Auth = none |
| PRD.md NFRs reference "JWT token" or "Bearer token" | Auth = Keycloak (Resource Server) |
| No SSO/Keycloak dependency but has user management stories | Auth = JWT (self-issued) |
If Auth = Keycloak (Resource Server), also extract from CLAUDE.md:
- Keycloak version from "Hub Single Sign On" section
- Keycloak realm: Default derived from project name
- Keycloak issuer URI: Default `http://localhost:8180/realms/<realm>`
- Keycloak roles: Infer from user stories and NFRs
- The application validates JWT tokens issued by Keycloak (stateless, no session)
### Messaging Detection
| Dependency Pattern | Messaging Selection |
|---|---|
| References "Hub to HC Adapter Message Queue" or "Hub to SC Adapter Message Queue" (RabbitMQ) | Messaging = yes |
| No message queue dependency listed | Messaging = no |
If Messaging = yes, also extract the RabbitMQ version from the corresponding message
queue section in CLAUDE.md.
### Scheduling Detection
Scheduling is determined from PRD.md content:
| Content Pattern | Scheduling Selection |
|---|---|
| NFRs mention "automatically deleted after X days", "scheduled", "periodic", "batch processing" | Scheduling = yes |
| User stories describe recurring jobs, cleanup tasks, or time-triggered operations | Scheduling = yes |
| No scheduling-related requirements found | Scheduling = no |
**If Scheduling = yes**, further determine:
- **Spring Batch = yes** if NFRs mention "batch processing", "ETL", "bulk import/export",
or processing large volumes of data with reader/processor/writer patterns
- **Remote Partitioning = yes** if NFRs mention "distributed processing", "horizontal
scaling", or "partitioned batch jobs"
### Reporting Detection
Reporting is determined from PRD.md content:
| Content Pattern | Reporting Selection |
|---|---|
| NFRs mention "report", "Report interface", "generate report", "report generation" | Reporting = yes |
| User stories describe generating/downloading PDF, Excel, or CSV reports | Reporting = yes |
| A "Report" module exists in PRD.md with NFRs defining a Report interface | Reporting = yes |
| No reporting-related requirements found | Reporting = no |
**If Reporting = yes**, the spec includes:
- JasperReports with JRDesign API for fully programmatic report layout (no .jrxml templates)
- `ReportDefinition` interface with `buildDesign()` method for modules to implement
- `ReportDesignHelper` utility class with static builders for common layout patterns
- `ReportService` orchestrating compile → fill → export via `JRBeanCollectionDataSource`
- Report registry persisted in the database
- REST controller with report list, details, and generation endpoints (JSON + file download)
- Multi-format export: PDF (OpenPDF), XLSX (Apache POI), CSV
### Summary of Determination
After analyzing all inputs, produce a determination summary before generating the spec.
Present it to the user for confirmation:
```
Optional Component Determination:
- Database: MySQL (from CLAUDE.md -> depends on HC Database)
- Authentication: Keycloak Resource Server (from CLAUDE.md -> depends on Hub Single Sign On)
- Scheduling: no
- Messaging: yes (from CLAUDE.md -> depends on Hub to HC Adapter Message Queue)
- Reporting: yes (from PRD.md → Report module with Report interface NFR)
```
If the user disagrees with any determination, allow them to override before proceeding.
## Required Inputs
After determination, these values are needed. Most are derived automatically:
**Auto-derived from context files:**
- **Application name**: From CLAUDE.md section heading
- **Artifact ID**: Kebab-case of application name
- **Group ID**: `com.bestinet.urp`
- **Base package**: `com.bestinet.urp.<artifactid>`
- **Application description**: From CLAUDE.md description
- **Modules**: From PRD.md module headings + model/MODEL.md
- **Database**: Auto-determined (see above)
- **Authentication**: Auto-determined (see above)
- **Scheduling**: Auto-determined (see above)
- **Messaging**: Auto-determined (see above)
- **Database name/credentials**: From ENVIRONMENT.md (root-level file with local environment credentials)
**Auto-derived from CLAUDE.md (Port Allocation table):**
- **Server port**: Look up the application's port from the `Port Allocation` table in the `Custom Applications` section of `CLAUDE.md`. Do NOT hardcode a default — the port MUST match the allocated port for this application.
**Optional (use sensible defaults if not found in context):**
- **API version prefix**: Default `/api/v1`
- **Log level**: Default `INFO` for application, `WARN` for frameworks
## Generating the Specification
Once inputs are gathered from context files and optional components are determined,
generate the specification as a **multi-file output split by module**. Read the spec
template at `references/spec-template.md` for the exact structure and content of each
section. The template is the authoritative guide — follow it closely.
The specification is split into two categories:
1. **Root `SPECIFICATION.md`** — Contains the Table of Contents, shared infrastructure,
and application-level sections that apply across all modules.
2. **Per-module `<module-name>/SPEC.md`** — Each module gets its own folder with
a self-contained specification file covering that module's complete blueprint.
This split enables a coding agent to:
- First, scaffold the shared infrastructure from `SPECIFICATION.md`
- Then, implement each module independently by picking up its `<module>/SPEC.md`
**Important:** The generated spec must use **real module data** from the context files,
not generic placeholders. Specifically:
- **Modules** must use the actual module names from PRD.md and MODEL.md
(e.g., `jobDemand`, `candidateRegistration`, `employer` — not `module1`, `module2`)
- **Entity fields** must match the actual fields defined in the module model
files (e.g., `model/job-demand/model.md`), not placeholder `fieldOne`/`fieldTwo`
- **Service interfaces** must expose methods matching the actual user stories (e.g., if
a story says "search job demands by country", the service needs `searchByCountry()`)
- **REST endpoints** must map to the actual user stories (e.g., if a user story says
"view details of a job demand", there must be a `GET /api/v1/job-demands/{id}` endpoint)
- **Request/Response DTOs** must match what the user stories and module model define
- **Version tags**: Every user story ID, NFR ID, constraint ID in the traceability section
must include its version tag (e.g., `USHC00228 [v1.0.3]`).
- **Removed / Replaced items**: The traceability section must include a "Removed / Replaced"
subsection listing any deprecated items from previous versions.
### Output Structure
```
<app_folder>/context/specification/
├── SPECIFICATION.md <- TOC + shared/application-level specs
├── job-demand/
│ └── SPEC.md <- Module blueprint for Job Demand
├── candidate-registration/
│ └── SPEC.md <- Module blueprint for Candidate Registration
├── ... <- One folder per module from PRD.md
```
### What Goes in `SPECIFICATION.md` (Root)
The root file contains the TOC and all shared/application-level sections. These are the
sections that a coding agent implements **first** before any module work:
#### 1. Project Overview
Project metadata, application description, technology stack summary, the complete
list of API consumers/roles, and the **Module Index** —
a table listing every module with a link to its `<module>/SPEC.md` file.
#### 2. Maven Configuration
Complete `pom.xml` structure with all dependencies (core + selected conditional),
plugin configurations (MapStruct annotation processor, Spring Boot Maven plugin),
and property management.
#### 3. Application Configuration *(conditional content varies)*
A single `application.yml` (no profile-specific files like `application-dev.yml` or
`application-prod.yml`) covering database connection (MongoDB URI or JDBC datasource
depending on selection), auth settings (Keycloak Resource Server JWT validation if
selected, or self-issued JWT if selected), scheduling config (if selected), and logging
configuration. **All environment-sensitive values (ports, hostnames, credentials, URIs)
MUST use Spring's `${ENV_VAR:default}` syntax** to allow externalization via environment
variables while keeping sensible defaults for local development. Do NOT use Spring
profiles or profile-specific YAML files — environment differences are handled entirely
through environment variables (e.g., via `.env` file locally or system environment
variables in deployment).
#### 3a. Application-Specific Configuration (`app:` namespace)
All application-owned configuration — any config specific to THIS application, as
opposed to the Spring/Java ecosystem — MUST live under the top-level `app:` key in
`application.yml`. NEVER place application-specific keys under Spring framework
namespaces (`spring.*`, `server.*`, `management.*`, `logging.*`, `springdoc.*`) —
those are reserved for framework configuration.
**Grouping rule.** Organise the `app:` tree by module:
- **Cross-cutting values** (version, shared feature flags, shared timeouts, CORS,
shared security settings, shared messaging infrastructure, shared object-storage
settings) sit directly under `app.*` with no module prefix.
- **Per-module values** are grouped under `app.<module-kebab-case>.*`, one block
per module that needs runtime config. A module with a single config value still
gets its own block — do not flatten.
- **NEVER place module-specific keys at the YAML root** (e.g., top-level
`notification:`, `batch-job:`, `audit-trail:`). They MUST be nested under `app:`.
**Naming rule.** YAML keys use **kebab-case** (`from-address`, `retry-limit`,
`max-retry`). Spring Boot's relaxed binding maps them to camelCase Java fields
automatically. Do NOT use camelCase or snake_case in YAML.
**Binding rule.** For every `app.*` subtree (cross-cutting OR per-module), bind once
via `@ConfigurationProperties` on a **record** in the corresponding module's `config`
subpackage — or, for cross-cutting values, in the application-level `config`
subpackage. **Do NOT** inject individual values via `@Value("${app....}")` scattered
across beans. Bind once at the module boundary and inject the typed record.
**Environment-override rule.** Every `app.*` leaf value MUST use Spring's
`${ENV_VAR:default}` syntax so it can be overridden per environment without editing
YAML. Every referenced `${ENV_VAR}` MUST appear in the `.env` file generated in
section 3b.
**Example structure:**
```yaml
app:
# Cross-cutting (no module prefix)
version: ${APP_VERSION:1.0.0}
cors:
allowed-origins: ${APP_CORS_ALLOWED_ORIGINS:http://localhost:3000}
security:
public-paths:
- /actuator/health
- /api/v1/info
# Per-module blocks — one per module with runtime config
notification:
email:
from-address: ${NOTIFICATION_FROM_ADDRESS:noreply@example.com}
retry-limit: ${NOTIFICATION_RETRY_LIMIT:3}
cleanup:
retention-days: ${NOTIFICATION_RETENTION_DAYS:30}
batch-job:
cleanup:
retention-days: ${BATCH_JOB_RETENTION_DAYS:90}
audit-trail:
cleanup:
retention-days: ${AUDIT_TRAIL_RETENTION_DAYS:365}
```
**Example cross-cutting record (`app.*`):**
```java
@ConfigurationProperties(prefix = "app")
public record AppProperties(String version, Cors cors, Security security) {
public record Cors(List<String> allowedOrigins) {}
public record Security(List<String> publicPaths) {}
}
```
**Example per-module record (`app.<module>.*`):**
```java
@ConfigurationProperties(prefix = "app.notification")
public record NotificationProperties(
Email email,
Cleanup cleanup
) {
public record Email(String fromAddress, int retryLimit) {}
public record Cleanup(int retentionDays) {}
}
```
Enable binding at the application root with `@ConfigurationPropertiesScan` on the
main application class, or register each record individually via
`@EnableConfigurationProperties` on a `@Configuration` class in the owning module.
**Mandatory cross-cutting values:**
| Key | Purpose | Binding |
|-----|---------|---------|
| `app.version` | Current application version; must match `pom.xml` `<version>` | `AppProperties.version()` |
Additional cross-cutting keys may be added as the application grows, but
`app.version` is always present.
**`app.version` specifics.** The `.env` file must include `APP_VERSION={version}`
with the actual version value. The `pom.xml` `<version>` element MUST also be set to
the same version value (e.g., `1.0.3`). When multiple versions were provided during
skill invocation, use the highest one. The REST API MUST expose the application
version in:
1. **A health/info endpoint** (e.g., `GET /api/v1/info` or Spring Actuator
`/actuator/info`) returning `{"version": "1.0.3", ...}`. Inject `AppProperties`
into the controller and read the version via `appProperties.version()`.
2. **Every API response envelope** — if the API uses a standard response wrapper,
include a `version` field (e.g., `{"version": "1.0.3", "data": {...}}`).
#### 3b. `.env` File Generation from ENVIRONMENT.md
Generate a `.env` file at the project root by reading `ENVIRONMENT.md` from the project root.
The `.env` file maps ENVIRONMENT.md credential and platform values to the environment variable
names referenced in `application.yml`. The spec must define the complete `.env` content
with actual values from ENVIRONMENT.md.
**Process:**
1. Read `ENVIRONMENT.md` from the project root
2. Extract credential values from `ENVIRONMENT.md` (`# Supporting 3rd Party Applications`
for database hosts, ports, usernames, passwords, plus Keycloak/RabbitMQ); read toolchain
paths (JDK, Maven) from `DEVTOOL.md`
3. Map each value to the corresponding `${ENV_VAR}` name used in `application.yml`
4. Generate the `.env` file with `KEY=value` pairs
**Example `.env` output (derived from ENVIRONMENT.md):**
```properties
# Database
DB_HOST=localhost
DB_PORT=3306
DB_NAME=hub_supp
DB_USERNAME=root
DB_PASSWORD=B3st1n3t@2025
# Authentication (Keycloak)
KEYCLOAK_HOST=http://localhost:8180
KEYCLOAK_REALM=urp
KEYCLOAK_CLIENT_ID=hub-middleware-api
# Messaging (RabbitMQ)
RABBITMQ_HOST=localhost
RABBITMQ_PORT=5672
RABBITMQ_USERNAME=guest
RABBITMQ_PASSWORD=guest
# Server
SERVER_PORT=<port from CLAUDE.md Port Allocation table>
# Platform
JAVA_HOME=C:\Users\rashidee.rashid.BESTINET\.jdks\azul-21.0.9
MAVEN_HOME=C:\Users\rashidee.rashid.BESTINET\apache-maven-3.9.12
```
**Rules:**
- Only include variables that are actually referenced in `application.yml`
- Use actual values from ENVIRONMENT.md — never use placeholders or `TODO`
- If ENVIRONMENT.md does not exist or a value is not found, use sensible defaults for local
development (e.g., `localhost`, default ports)
- The `.env` file is gitignored (already covered in `.gitignore`)
#### 4. `.gitignore`
Generate a `.gitignore` file at the project root that excludes all generated, downloaded,
and environment-specific files from version control.
#### 5. Package Structure
The complete directory tree rooted at the base package. The structure follows
Domain-Driven Design with Spring Modulith conventions, adapted for REST API
with `controller` subpackages (not `page`/`fragment`). Use actual module names.
Read `references/modulith-patterns.md` for the detailed module layout and inter-module
communication rules.
#### 6. Security Configuration *(conditional — include only if Auth != none)*
**If Auth = Keycloak (Resource Server):** OAuth2 Resource Server setup with JWT validation.
`SecurityFilterChain` with `oauth2ResourceServer(jwt -> ...)`. Keycloak JWT decoder
configuration. Role extraction from JWT claims (`realm_access`, `resource_access`).
Stateless session policy. CORS configuration. Read `references/security-patterns.md`
for the full security architecture.
**If Auth = JWT (self-issued):** Spring Security with custom JWT token provider.
`SecurityFilterChain` with `JwtAuthenticationFilter`. `JwtTokenProvider` for token
generation and validation. Stateless session policy. CORS configuration.
#### 7. REST API Conventions
Standardized REST API patterns including:
- URI naming conventions (plural nouns, kebab-case)
- API versioning strategy (`/api/v1/...` path prefix)
- Request/Response DTO patterns (Java records with Bean Validation)
- Standardized error response envelope (`ApiError` record)
- HTTP status code usage guidelines
- Pagination response structure (Spring Data `Page` serialization)
- HATEOAS considerations (optional, note when applicable)
Read `references/restapi-patterns.md` for the complete REST API patterns.
#### 8. Error Handling & Exceptions
Global `@RestControllerAdvice` exception handler returning standardized JSON error
responses. Base `ApiException` with status/code/message. `ResourceNotFoundException`,
`ValidationException`, `ConflictException` hierarchy. Consistent `ApiError` envelope
across all error responses.
#### 9. Pagination & Filtering Support
Standardized pagination using Spring Data `Pageable`. Sorting support via query
parameters. Dynamic filtering using Spring Data Specifications (JPA) or Query DSL
(MongoDB). Default page size, maximum page size configuration.
#### 10. Data Access *(conditional content varies)*
**If Database = MongoDB:** MongoDB repositories per module with Spring Data MongoRepository.
DTO mapping via MapStruct. All list endpoints paginated. Use actual collection names.
**If Database = PostgreSQL/MySQL:** JPA repositories per module with Spring Data
JpaRepository. JPA entities with `@Entity`/`@Table` annotations extending `BaseEntity`.
`BaseEntity` uses `@UuidGenerator(style = UuidGenerator.Style.TIME)` with
`@Column(columnDefinition = "CHAR(36)")` and `private String id`. Flyway migration scripts.
DTO mapping via MapStruct. All list endpoints paginated. Use actual table names.
**MySQL UUID rule:** All UUID primary keys and foreign keys use `CHAR(36)` in DDL.
**If Database = none:** In-memory data structures or stubs.
#### 11. API Documentation (SpringDoc OpenAPI)
SpringDoc OpenAPI configuration for auto-generating Swagger UI. Controller annotations
(`@Tag`, `@Operation`, `@ApiResponse`). Configuration in `application.yml`.
#### 12. Logging Strategy
SLF4J with Logback configuration, correlation ID filter (`X-Correlation-Id` header),
MDC context filter, per-module log levels.
#### 13. Scheduling and Batch Processing *(conditional — include only if Scheduling = yes)*
Quartz scheduler configuration with job store matching the selected database.
Read `references/batch-patterns.md` for the full scaffolding spec.
#### 14. Event-Driven Architecture
Spring Modulith application events for inter-module communication. Read
`references/modulith-patterns.md` for details.
#### 15. Messaging (RabbitMQ Pub/Sub) *(conditional — include only if Messaging = yes)*
Standalone RabbitMQ publisher/consumer services for inter-system communication.
Read `references/messaging-patterns.md` for the full messaging architecture.
#### 16. MapStruct Usage
Per-module MapStruct mapper conventions and mapping flow patterns.
#### 17. Testing Strategy
Overview of testing approach — unit tests (service layer with Mockito), integration tests
(controller layer with `@WebMvcTest` and MockMvc), security test utilities
(JWT mocking if Keycloak, or `@WithMockUser` if JWT), Spring Modulith module verification.
#### 18. Caching Strategy *(optional — include if applicable)*
HTTP caching headers (`Cache-Control`, `ETag`). Application-level caching with
Spring Cache and Caffeine. Cache eviction strategies.
#### 19. Idempotency *(optional — include if applicable)*
`Idempotency-Key` header pattern for mutating operations. Duplicate detection
and response replay.
#### 20. Reporting (JasperReports JRDesign API) *(conditional — include only if Reporting = yes)*
JasperReports infrastructure with fully programmatic report layout via JRDesign API — no
`.jrxml` XML templates. Report layouts are built entirely in Java code using `JasperDesign`,
`JRDesignBand`, `JRDesignStaticText`, `JRDesignTextField`, and `JRDesignField` classes.
Includes `ReportDefinition` interface with `buildDesign()` method for modules to implement,
`ReportDesignHelper` utility with static builders for common patterns (A4 portrait/landscape,
column headers, detail bands, page footers), `ReportService` orchestrating compile → fill →
export via `JRBeanCollectionDataSource`, `ReportRegistry` for auto-discovering and persisting
report definitions at startup, REST controller with report list, details, and generation
endpoints (`GET /api/v1/reports`, `POST /api/v1/reports/{id}/generate`), multi-format export
(PDF via OpenPDF, XLSX via Apache POI, CSV). Modules register reports by creating
`@Component` classes implementing `ReportDefinition` — each report builds its layout
programmatically and calls module services to produce DTOs (never repositories directly),
preserving Spring Modulith module boundaries. Read `references/reporting-patterns.md` for
the full reporting architecture.
### What Goes in Each `<module>/SPEC.md` (Per-Module)
For EACH module from PRD.md and MODEL.md, create a folder named after the
module (kebab-case, e.g., `job-demand/`) and generate a `SPEC.md` inside it.
Each module `SPEC.md` is a **self-contained** blueprint that a coding agent can pick up
and implement independently (after the shared infrastructure is in place). It must include:
- **Header** with module name and a back-reference to the root `SPECIFICATION.md`
- **Traceability**: User story IDs, NFR IDs, constraint IDs, table/collection names
- **Service interface** with methods derived from user stories
- **Request DTOs** with Bean Validation annotations matching module model fields
- **Response DTOs** as Java records matching module model fields
- **Exception class** for module-specific errors
- **Entity/Document class** with fields from `model/<module>/model.md` and
`model/<module>/schemas.json`
- **Repository** with query methods matching user stories' data access patterns
- **MapStruct mapper** with mappings matching actual field names
- **Service implementation** with full CRUD logic
- **REST controller** with endpoints matching user stories (`@RestController`)
- **Complete code samples** for every component — continuous and copy-pasteable
**Separating REST API Layer from Messaging/Async Pipeline:**
When a module has BOTH user-facing endpoints (user stories) AND async processing NFRs
(e.g., RabbitMQ message consumption, message validation, ACK publishing, forwarding),
the SPEC.md MUST clearly separate these into distinct sections:
1. **REST API sections** — service methods for CRUD operations (search, getById, create,
update, delete), REST controllers, request/response DTOs. These are driven by user
stories (USHCxxxxx).
2. **Messaging Pipeline sections** — message consumer (`@RabbitListener`), message
validator, ACK publisher, forward publisher, queue configuration, domain events,
`processIncomingMessage()` service method. These are driven by NFRs (NFRHCxxxx).
> **MQ listener placement (mandatory).** Every `@RabbitListener` class generated for a
> module MUST be placed inside that module's `internal/` package
> (`{{base}}.{{module}}.internal`), package-private, alongside the controller. Shared
> messaging infrastructure (`RabbitMQMessagingConfig`, `RabbitMQPublisher`,
> `MessageConverterConfig`, cross-module event/command DTOs) lives in
> `shared/messaging/`, but that package must contain **no** `@RabbitListener`
> classes. See `references/messaging-patterns.md` § "Consumer Service (module-internal)"
> for the canonical pattern.
See `references/spec-template.md` for the exact template structure.
## Changelog Append
After all specification files are successfully generated, append an entry to `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):
1. Read `<app_folder>/CHANGELOG.md`. If it does not exist, create it with:
```markdown
# Changelog
- This file tracks all skill executions by version for this application.
- The highest version recorded here is the current application version.
- Skills MUST NOT execute for a version lower than the highest version in this file.
---
```
2. Search for a `## {version}` heading matching the current version.
3. If the section **exists**: append a new row to its table.
4. If the section **does not exist**: insert a new section after the `---` below the context header and before any existing `## vX.Y.Z` section (newest-first ordering), with a new table header and the first row.
5. Row format: `| {YYYY-MM-DD} | {application_name} | specgen-spring-jpa-restapi | {module or "All"} | Generated Spring Boot REST API technical specification |`
6. **Never modify or delete existing rows.**
## Output Format
The generated specification is a **folder of files**, not a single document:
```
<app_folder>/context/specification/
├── SPECIFICATION.md <- Root: TOC + shared/application-level specs
├── <module-1>/
│ └── SPEC.md <- Module blueprint (self-contained)
├── <module-2>/
│ └── SPEC.md
├── <module-N>/
│ └── SPEC.md
```
- **Root folder**: `<app_folder>/context/specification/`
- **Root file**: `SPECIFICATION.md`
- **Module folders**: One folder per module from PRD.md, named in kebab-case
- **Module files**: Each `SPEC.md` is self-contained with full code samples
**Sample code is mandatory.** Every component described in any spec file must include a
complete, self-explanatory code sample inside a fenced code block (Java, YAML, or JSON
as appropriate). The sample code must be continuous (not fragments stitched with "// ..."
gaps) and usable as a direct reference by a coding agent or developer.
## Constraints
These constraints are non-negotiable. Every code sample in the generated spec must
follow them. If any constraint is violated, the spec is incorrect.
### Universal Constraints (Always Apply)
**Do NOT use Lombok's `@Data` annotation — anywhere.** Use `@Getter` and `@Setter`
explicitly on every class that needs accessors. `@Data` generates `equals()`, `hashCode()`,
and `toString()` which cause problems with persistent entities, lazy-loaded
collections, and circular references. The spec must use `@Getter @Setter` consistently.
**Do NOT use field injection.** Every Spring-managed bean must use constructor injection.
Use Lombok's `@RequiredArgsConstructor` with `private final` fields. Never use `@Autowired`
on fields. This applies to services, controllers, configurations, filters, and any other
Spring component.
**Use Java records for DTOs.** All request and response DTOs should be Java records
(immutable, auto-generated `equals`/`hashCode`/`toString`). Records with Bean Validation
annotations for request DTOs.
**Use MapStruct for all object mapping.** Define MapStruct mappers per module with
`@Mapper(componentModel = "spring")`. Avoid handwritten mapping beyond simple passthroughs.
**Never expose JPA entities or MongoDB documents directly in API responses.** Always
map to response DTOs via MapStruct.
**All data listings must be paginated.** Every endpoint that returns a list must accept
`Pageable` parameters and return `Page<T>`. Never return unbounded lists.
**Use real module data from context files.** The spec must use actual field names,
collection/table names, module names, and user stories from the context files.
**REST API URI conventions:**
- Use plural nouns for resource names (e.g., `/api/v1/job-demands`, NOT `/api/v1/job-demand`)
- Use kebab-case for multi-word resources (e.g., `/api/v1/job-demands`, NOT `/api/v1/jobDemands`)
- Use `{id}` path variable for single resource access (e.g., `/api/v1/job-demands/{id}`)
- Maximum 2 levels of nesting (e.g., `/api/v1/employers/{id}/contacts`)
- Non-CRUD actions use sub-resource verbs (e.g., `POST /api/v1/orders/{id}/cancel`)
**Return correct HTTP status codes:**
- `200 OK` for successful retrieval and updates
- `201 Created` with `Location` header for resource creation
- `204 No Content` for successful deletion
- `400 Bad Request` for validation errors
- `401 Unauthorized` for missing/invalid credentials
- `403 Forbidden` for insufficient permissions
- `404 Not Found` for non-existent resources
- `409 Conflict` for state conflicts
### Conditional Constraints
**If Auth = Keycloak (Resource Server):**
- **Use OAuth2 Resource Server (not OAuth2 Client).** The application validates JWT tokens
in the `Authorization: Bearer` header. Stateless — no HTTP session.
- **Do NOT manage users and roles in the application.** Keycloak owns user/role management.
The application only reads roles from JWT claims to enforce access control.
**If Auth = JWT (self-issued):**
- The application manages its own JWT token generation and validation.
- Stateless session policy. Custom `JwtAuthenticationFilter` extracts and validates tokens.
**If Scheduling = yes and Database = MongoDB:**
- **Use `io.fluidsonic.mirror` for Quartz MongoDB job store.**
**If Scheduling = yes and Database = PostgreSQL/MySQL:**
- Use the built-in Quartz JDBC job store with the selected relational database.
**If Messaging = yes:**
- Queue and exchange names for pub/sub messaging (`app.*`) must not collide with batch
partition queues (`batch.partition.*`). Use distinct prefixes for each concern.
## Principles Embedded in the Spec
These principles should be woven into every section of the spec rather than listed
separately.
### Always-Applicable Principles
- RESTful API design with standardized conventions
- JSON request/response with Jackson serialization
- Bean Validation at controller boundary (`@Valid`)
- Standardized error response envelope
- Event-driven inter-module communication via Spring Modulith events
- Domain-driven package structure (one module per bounded context)
- Separation of concerns (controller -> service -> repository)
- Constructor injection everywhere (`@RequiredArgsConstructor` + `private final`)
- `@Getter @Setter` instead of `@Data` on all entity/document classes
- Java records for all DTOs
- Single `application.yml` with environment variables for all environment-specific values (no profile-specific YAML files)
- Custom exception hierarchy with global error handling via `@RestControllerAdvice`
- Structured logging with correlation IDs
- OpenAPI documentation via SpringDoc
- Pagination on all list endpoints
### Conditional Principles
- **If Auth = Keycloak:** OAuth2 Resource Server with JWT validation for all
authentication and authorization (stateless). No user/role management — external IdP only.
- **If Auth = JWT:** Custom JWT token provider with stateless authentication.
- **If Auth = none:** No security filter chain. All endpoints are publicly accessible.
No comments yet. Be the first to comment!
