spring-boot4-skill 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.2.0] - 2026-02-21
+
+### Added
+
+- **Docs:** CHANGELOG.md (Keep a Changelog); README "What you get" example tree, expanded Contributing, npm version badge.
+- **CLI:** Project `description` in wizard and in generated Application.java, build.gradle.kts, pom.xml; friendly error messages (EEXIST, EACCES); "Minimal (API only)" option in wizard.
+- **Skill:** New reference `spring-messaging.md` (Kafka, @KafkaListener, producer/consumer); SKILL.md Quick decision node for Messaging/Kafka; Health groups (readiness/liveness) in spring-boot-4.md; BOM sync note in build-templates.md.
+- **Quality:** Jest config and unit tests for templates and buildContext; `scripts/smoke-cli.sh` and `npm run smoke`; `buildContext` exported for tests.
+
+### Changed
+
+- **CLI:** Generator context includes `description` default; success message already showed absolute path.
+
+[1.2.0]: https://github.com/AyrtonAldayr/agent-skill-java-spring-framework/compare/v1.1.0...v1.2.0
+
+## [1.1.0] - 2026-02-21
+
+### Added
+
+- **Skill:** New reference `spring-security-7.md` — OAuth2 Resource Server, JWT, method security (`@PreAuthorize`), CORS.
+- **Skill:** New reference `troubleshooting-migration.md` — common errors (javax/jakarta, RestTemplate, JSpecify, native), Boot 3→4 migration checklist.
+- **Skill:** "When NOT to use this skill" section and Quick decision (mermaid) in SKILL.md.
+- **Skill:** Spring Boot 4 reference: Testcontainers subsection, secure Actuator exposure, Reactive stack (R2DBC + WebFlux), redirect to spring-security-7.md for OAuth2/JWT.
+- **Skill:** Spring Modulith reference: "Common pitfalls" subsection.
+- **Skill:** Spring Framework 7: note for reactive apps (WebFlux + R2DBC) with link to spring-boot-4.md.
+- **README:** Install options for skill via `npx skills add` and `claude skills install`; skill reference table updated.
+
+### Changed
+
+- **Skill:** Reference table in SKILL.md now includes Spring Security 7 and Troubleshooting & migration; triggers listed in body.
+
+## [1.0.0] - 2026-02-21
+
+### Added
+
+- **CLI:** Interactive wizard for project name, package, build tool (Gradle KTS / Maven), Java version (25/21/17), Spring Boot version, database (PostgreSQL, MySQL, MongoDB, H2, None), features (Actuator, Security, Validation, Modulith, Native, WebFlux, Docker Compose), and Java preview features.
+- **CLI:** Non-interactive mode (`--no-interactive`) and Maven option (`--maven`).
+- **Templates:** Gradle Kotlin DSL and Maven POM with Spring Boot 4.0.3 BOM; Application.java with JSpecify `@NullMarked`, application.yaml with virtual threads and OTEL, ApplicationTests, optional compose.yaml and Modulith skeleton.
+- **Skill:** Core SKILL.md with mandatory workflow (Analyze → Implement → Optimize → Document), Core Principles table, and reference files (spring-framework-7, spring-boot-4, spring-modulith, build-templates).
+- **npm:** Package `spring-boot4-skill` publishable with `npx spring-boot4-skill`.
+
+[1.1.0]: https://github.com/AyrtonAldayr/agent-skill-java-spring-framework/compare/v1.0.0...v1.1.0
+[1.0.0]: https://github.com/AyrtonAldayr/agent-skill-java-spring-framework/releases/tag/v1.0.0

package/README.md

@@ -1,7 +1,9 @@
 # Spring Boot 4 · Java 25 · Spring Framework 7
 
+[![npm version](https://img.shields.io/npm/v/spring-boot4-skill.svg)](https://www.npmjs.com/package/spring-boot4-skill)
+
 > **2026-standard** project scaffolder + Claude Code AI skill for Java / Spring development.
-> By [AyrtonAldayr](https://github.com/AyrtonAldayr)
+> By [AyrtonAldayr](https://github.com/AyrtonAldayr) · **v1.2.0**
 
 This repository provides two tools in one:
 
@@ -44,6 +46,26 @@ After answering a few prompts, you get a complete project with:
 - **`compose.yaml`** *(optional)* — Docker Compose for PostgreSQL 17, MongoDB 7, OTEL Collector
 - **Spring Modulith module skeleton** *(optional)*
 
+**Example output** (Gradle, default options):
+
+```
+my-service/
+├── build.gradle.kts
+├── settings.gradle.kts
+├── src/
+│   ├── main/
+│   │   ├── java/<package-path>/
+│   │   │   └── Application.java
+│   │   └── resources/
+│   │       └── application.yaml
+│   └── test/
+│       └── java/<package-path>/
+│           └── ApplicationTests.java
+└── compose.yaml          # if Docker Compose was selected
+```
+
+The generator prints the full path of the created project (e.g. `Project created at /path/to/my-service`).
+
 ### Wizard options
 
 ```
@@ -70,7 +92,26 @@ After answering a few prompts, you get a complete project with:
 
 Install the skill to get AI assistance aligned with Spring Boot 4 / Framework 7 standards.
 
-### Install from GitHub
+There are **two common ways** to install it, depending on which tool you use:
+
+### Option 1 — npx (Skills CLI, multi-agent)
+
+Uses the open [Skills CLI](https://github.com/vercel-labs/skills) (`npx skills`). Works with Claude Code, Cursor, Codex, and other agents that follow the same skill layout.
+
+```bash
+# Install the skill (prompts for which agent(s) to install to)
+npx skills add AyrtonAldayr/agent-skill-java-spring-framework --skill java-spring-framework
+
+# Install only for Claude Code
+npx skills add AyrtonAldayr/agent-skill-java-spring-framework --skill java-spring-framework -a claude-code
+
+# Install for Cursor
+npx skills add AyrtonAldayr/agent-skill-java-spring-framework --skill java-spring-framework -a cursor
+```
+
+### Option 2 — Claude Code official CLI
+
+If you use the `claude` CLI (Anthropic’s Claude Code), you can install directly from GitHub:
 
 ```bash
 claude skills install github:AyrtonAldayr/agent-skill-java-spring-framework
@@ -93,9 +134,12 @@ Once installed, Claude Code acts as a **Senior Spring Boot 4 architect**:
 | File | Contents |
 |---|---|
 | `skills/java-spring-framework/references/spring-framework-7.md` | All Spring 7 APIs with code examples |
-| `skills/java-spring-framework/references/spring-boot-4.md` | Boot 4 features: native, virtual threads, Security 7, testing |
-| `skills/java-spring-framework/references/spring-modulith.md` | Module structure, events, integration testing |
+| `skills/java-spring-framework/references/spring-boot-4.md` | Boot 4: native, virtual threads, testing (Testcontainers), reactive stack |
+| `skills/java-spring-framework/references/spring-security-7.md` | OAuth2 Resource Server, JWT, method security, CORS |
+| `skills/java-spring-framework/references/spring-messaging.md` | Kafka, event-driven, @KafkaListener, producer/consumer |
+| `skills/java-spring-framework/references/spring-modulith.md` | Module structure, events, integration testing, common pitfalls |
 | `skills/java-spring-framework/references/build-templates.md` | Complete Gradle KTS + Maven POM templates |
+| `skills/java-spring-framework/references/troubleshooting-migration.md` | Common errors (javax/jakarta, RestTemplate), Boot 3→4 checklist |
 
 ---
 
@@ -130,12 +174,17 @@ npx spring-boot4-skill
 
 ## Contributing
 
-PRs welcome. Please keep all generated code aligned with:
-
-- [Spring Boot 4.x docs](https://docs.spring.io/spring-boot/)
-- [Spring Framework 7.x docs](https://docs.spring.io/spring-framework/reference/)
-- [Spring Modulith docs](https://docs.spring.io/spring-modulith/reference/)
-- [JSpecify](https://jspecify.dev/)
+PRs welcome.
+
+1. **Clone and install:** `git clone <repo> && cd agent-skill-java-spring-framework && npm install`
+2. **Run CLI locally:** `node bin/create-spring-app.js [project-name]` or `node bin/create-spring-app.js my-test --no-interactive`
+3. **Tests:** `npm test` (unit tests); `npm run smoke` (CLI smoke test).
+4. **Skill changes:** Keep the structure under `skills/java-spring-framework/` (SKILL.md plus `references/*.md`). Load criteria in the Reference Files table should stay accurate.
+5. **Generated code** must align with:
+   - [Spring Boot 4.x docs](https://docs.spring.io/spring-boot/)
+   - [Spring Framework 7.x docs](https://docs.spring.io/spring-framework/reference/)
+   - [Spring Modulith docs](https://docs.spring.io/spring-modulith/reference/)
+   - [JSpecify](https://jspecify.dev/)
 
 ---
 

package/jest.config.cjs

@@ -0,0 +1,9 @@
+/** @type {import('jest').Config} */
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: ['**/*.test.js'],
+  transform: {},
+  moduleNameMapper: {
+    '^(\\.{1,2}/.*)\\.js$': '$1',
+  },
+};

package/lib/generator.js

@@ -15,11 +15,9 @@ const TEMPLATES_DIR = join(__dirname, '../templates');
 export async function generateProject(config) {
   const spinner = ora('Generating project…').start();
   const projectDir = resolve(process.cwd(), config.projectName);
+  const ctx = buildContext(config);
 
   try {
-    // Derive additional config values
-    const ctx = buildContext(config);
-
     // Create root project directory
     mkdirSync(projectDir, { recursive: true });
 
@@ -45,15 +43,21 @@ export async function generateProject(config) {
 
   } catch (err) {
     spinner.fail('Generation failed');
+    const msg = err.code === 'EEXIST'
+      ? `Directory already exists: ${projectDir}`
+      : err.code === 'EACCES'
+        ? `Permission denied writing to: ${projectDir}`
+        : err.message || String(err);
+    console.error(chalk.red(msg));
     throw err;
   }
 }
 
 // ---------------------------------------------------------------------------
-// Context builder
+// Context builder (exported for tests)
 // ---------------------------------------------------------------------------
 
-function buildContext(config) {
+export function buildContext(config) {
   const appName = toPascalCase(config.projectName);
   const packagePath = config.packageName.replace(/\./g, '/');
   const features = config.features || [];
@@ -76,6 +80,7 @@ function buildContext(config) {
 
   return {
     ...config,
+    description: config.description ?? 'Spring Boot 4 microservice',
     appName,
     packagePath,
     features,
@@ -179,9 +184,11 @@ ${chalk.bold('Next steps:')}
   ${chalk.cyan(cd)}
   ${chalk.cyan(run)}
 
-${chalk.bold('Install the AI coding skill:')}
+${chalk.bold('Install the AI coding skill (optional):')}
 
-  ${chalk.cyan(`claude skills install github:AyrtonAldayr/agent-skill-java-spring-framework`)}
+  ${chalk.cyan('npx skills add AyrtonAldayr/agent-skill-java-spring-framework --skill java-spring-framework')}
+  ${chalk.dim('or')}
+  ${chalk.cyan('claude skills install github:AyrtonAldayr/agent-skill-java-spring-framework')}
 
 ${chalk.dim('Docs: https://github.com/AyrtonAldayr/agent-skill-java-spring-framework')}
 `);

package/lib/generator.test.js

@@ -0,0 +1,82 @@
+/**
+ * Unit tests for the generator context builder (buildContext).
+ */
+
+import { buildContext } from './generator.js';
+
+describe('buildContext', () => {
+  it('includes projectName, packageName, appName, packagePath', () => {
+    const ctx = buildContext({
+      projectName: 'my-service',
+      packageName: 'com.acme',
+      database: 'none',
+      features: [],
+    });
+    expect(ctx.projectName).toBe('my-service');
+    expect(ctx.packageName).toBe('com.acme');
+    expect(ctx.appName).toBe('MyService');
+    expect(ctx.packagePath).toBe('com/acme');
+  });
+
+  it('sets hasJpa true for postgresql, mysql, h2', () => {
+    expect(buildContext({ projectName: 'x', packageName: 'c', database: 'postgresql', features: [] }).hasJpa).toBe(true);
+    expect(buildContext({ projectName: 'x', packageName: 'c', database: 'mysql', features: [] }).hasJpa).toBe(true);
+    expect(buildContext({ projectName: 'x', packageName: 'c', database: 'h2', features: [] }).hasJpa).toBe(true);
+    expect(buildContext({ projectName: 'x', packageName: 'c', database: 'none', features: [] }).hasJpa).toBe(false);
+  });
+
+  it('sets hasActuator, hasSecurity, hasValidation from features', () => {
+    const ctx = buildContext({
+      projectName: 'x',
+      packageName: 'c',
+      database: 'none',
+      features: ['actuator', 'validation'],
+    });
+    expect(ctx.hasActuator).toBe(true);
+    expect(ctx.hasSecurity).toBe(false);
+    expect(ctx.hasValidation).toBe(true);
+  });
+
+  it('sets hasModulith, hasNative, hasDockerCompose from features', () => {
+    const ctx = buildContext({
+      projectName: 'x',
+      packageName: 'c',
+      database: 'postgresql',
+      features: ['modulith', 'docker-compose'],
+    });
+    expect(ctx.hasModulith).toBe(true);
+    expect(ctx.hasNative).toBe(false);
+    expect(ctx.hasDockerCompose).toBe(true);
+  });
+
+  it('provides description default when missing', () => {
+    const ctx = buildContext({
+      projectName: 'x',
+      packageName: 'c',
+      database: 'none',
+      features: [],
+    });
+    expect(ctx.description).toBe('Spring Boot 4 microservice');
+  });
+
+  it('uses provided description when set', () => {
+    const ctx = buildContext({
+      projectName: 'x',
+      packageName: 'c',
+      description: 'My API',
+      database: 'none',
+      features: [],
+    });
+    expect(ctx.description).toBe('My API');
+  });
+
+  it('sets modulithDataDep for JPA when modulith and postgresql', () => {
+    const ctx = buildContext({
+      projectName: 'x',
+      packageName: 'c',
+      database: 'postgresql',
+      features: ['modulith'],
+    });
+    expect(ctx.modulithDataDep).toContain('modulith-starter-jpa');
+  });
+});

package/lib/prompts.js

@@ -7,6 +7,7 @@ import inquirer from 'inquirer';
 const DEFAULTS = {
   projectName: 'my-service',
   packageName: 'com.example',
+  description: 'Spring Boot 4 microservice',
   buildTool: 'gradle',
   javaVersion: '25',
   bootVersion: '4.0.3',
@@ -88,6 +89,12 @@ export async function runWizard(projectNameArg, options = {}) {
       ],
       default: 'postgresql',
     },
+    {
+      type: 'confirm',
+      name: 'minimal',
+      message: 'Minimal project (API only — no Actuator, Security, Validation)?',
+      default: false,
+    },
     {
       type: 'checkbox',
       name: 'features',
@@ -101,6 +108,7 @@ export async function runWizard(projectNameArg, options = {}) {
         { name: 'Spring WebFlux (Reactive)', value: 'webflux', checked: false },
         { name: 'Docker Compose support', value: 'docker-compose', checked: false },
       ],
+      when: (ans) => !ans.minimal,
     },
     {
       type: 'confirm',
@@ -111,5 +119,8 @@ export async function runWizard(projectNameArg, options = {}) {
     },
   ]);
 
+  if (answers.minimal) {
+    answers.features = [];
+  }
   return answers;
 }

package/lib/templates.test.js

@@ -0,0 +1,80 @@
+/**
+ * Unit tests for the template engine (renderTemplate, interpolate, #if, #each).
+ * Uses in-memory template strings; does not read from disk.
+ */
+
+import { readFileSync, writeFileSync, mkdtempSync, rmSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { renderTemplate } from './templates.js';
+
+describe('templates', () => {
+  let tempDir;
+
+  beforeEach(() => {
+    tempDir = mkdtempSync(join(tmpdir(), 'skill-tpl-'));
+  });
+
+  afterEach(() => {
+    rmSync(tempDir, { recursive: true });
+  });
+
+  function createTemplate(content) {
+    const path = join(tempDir, 'tpl.txt');
+    writeFileSync(path, content);
+    return path;
+  }
+
+  describe('interpolate', () => {
+    it('replaces {{key}} with context value', () => {
+      const path = createTemplate('Hello {{name}}');
+      expect(renderTemplate(path, { name: 'World' })).toBe('Hello World');
+    });
+
+    it('replaces multiple placeholders', () => {
+      const path = createTemplate('{{a}} and {{b}}');
+      expect(renderTemplate(path, { a: 'A', b: 'B' })).toBe('A and B');
+    });
+
+    it('replaces undefined/null with empty string', () => {
+      const path = createTemplate('x{{missing}}y');
+      expect(renderTemplate(path, {})).toBe('xy');
+    });
+  });
+
+  describe('{{#if}}', () => {
+    it('includes block when value is truthy', () => {
+      const path = createTemplate('{{#if ok}}yes{{/if}}');
+      expect(renderTemplate(path, { ok: true })).toBe('yes');
+    });
+
+    it('omits block when value is falsy', () => {
+      const path = createTemplate('{{#if ok}}yes{{/if}}');
+      expect(renderTemplate(path, { ok: false })).toBe('');
+    });
+
+    it('supports negation {{#if !key}}', () => {
+      const path = createTemplate('{{#if !hide}}show{{/if}}');
+      expect(renderTemplate(path, { hide: true })).toBe('');
+      expect(renderTemplate(path, { hide: false })).toBe('show');
+    });
+  });
+
+  describe('{{#each}}', () => {
+    it('iterates array and exposes {{item}}', () => {
+      const path = createTemplate('{{#each items}}({{item}}){{/each}}');
+      expect(renderTemplate(path, { items: ['a', 'b'] })).toBe('(a)(b)');
+    });
+
+    it('returns empty string when key is not an array', () => {
+      const path = createTemplate('{{#each items}}x{{/each}}');
+      expect(renderTemplate(path, { items: null })).toBe('');
+    });
+  });
+
+  it('combines if and interpolate', () => {
+    const path = createTemplate('{{name}}{{#if active}} (active){{/if}}');
+    expect(renderTemplate(path, { name: 'Foo', active: true })).toBe('Foo (active)');
+    expect(renderTemplate(path, { name: 'Bar', active: false })).toBe('Bar');
+  });
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spring-boot4-skill",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Interactive CLI scaffold for Java 25 / Spring Boot 4.x projects — with a bundled Claude Code skill for AI-assisted development.",
   "type": "module",
   "bin": {
@@ -8,7 +8,8 @@
   },
   "scripts": {
     "start": "node bin/create-spring-app.js",
-    "test": "node --experimental-vm-modules node_modules/.bin/jest"
+    "test": "node --experimental-vm-modules node_modules/.bin/jest",
+    "smoke": "bash scripts/smoke-cli.sh"
   },
   "keywords": [
     "spring-boot",
@@ -40,5 +41,8 @@
     "commander": "^12.1.0",
     "inquirer": "^10.1.5",
     "ora": "^8.1.0"
+  },
+  "devDependencies": {
+    "jest": "^29.7.0"
   }
 }

package/scripts/smoke-cli.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+# Smoke test: run CLI in non-interactive mode and verify key files exist.
+set -e
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+REPO_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+CLI="$REPO_ROOT/bin/create-spring-app.js"
+PROJECT_NAME="smoke-test-project"
+TMP_DIR=$(mktemp -d 2>/dev/null || mktemp -d -t 'skill-smoke')
+
+cd "$TMP_DIR"
+node "$CLI" "$PROJECT_NAME" --no-interactive
+
+PROJECT_DIR="$TMP_DIR/$PROJECT_NAME"
+if [ ! -d "$PROJECT_DIR" ]; then
+  echo "FAIL: Project directory not created: $PROJECT_DIR"
+  exit 1
+fi
+
+if [ ! -f "$PROJECT_DIR/build.gradle.kts" ]; then
+  echo "FAIL: build.gradle.kts not found"
+  exit 1
+fi
+
+if [ ! -f "$PROJECT_DIR/src/main/resources/application.yaml" ]; then
+  echo "FAIL: application.yaml not found"
+  exit 1
+fi
+
+# Default package is com.example; app name from "smoke-test-project" -> SmokeTestProject
+JAVA_FILE=$(find "$PROJECT_DIR/src/main/java" -name "*Application.java" 2>/dev/null | head -1)
+if [ -z "$JAVA_FILE" ] || [ ! -f "$JAVA_FILE" ]; then
+  echo "FAIL: Application main class not found under src/main/java"
+  exit 1
+fi
+
+echo "PASS: Smoke test — CLI generated project with build.gradle.kts, application.yaml, and Application class."
+rm -rf "$TMP_DIR"

package/skills/java-spring-framework/SKILL.md

@@ -16,6 +16,34 @@ description: >
 You are a Senior Java & Spring Boot 4 / Spring Framework 7 architect. All code must be
 idiomatic for **2026 standards**: Spring Boot 4.0.x, Spring Framework 7.0.x, Java 25, Jakarta EE 11.
 
+**Triggers:** REST APIs, microservices, JdbcClient/JPA 3.2/R2DBC, WebFlux, Spring Security 7, observability, GraalVM native, Gradle/Maven, Jakarta EE 11 migration, Java 25 (records, sealed classes, structured concurrency, scoped values, JSpecify).
+
+## When NOT to use this skill
+
+- Legacy Spring Boot 2.x or 3.x with no upgrade plan to Boot 4 / Framework 7.
+- Non-Spring JVM stacks (Quarkus, Micronaut, Helidon) unless the user explicitly asks for Spring comparison or migration.
+- Tasks that do not touch Java/Spring backend (e.g. only frontend, only infra/DevOps with no Spring code).
+- General Java questions with no Spring or framework context.
+
+## Quick decision (which reference to load first)
+
+```mermaid
+flowchart TD
+    A[User request] --> B{REST blocking or reactive?}
+    B -->|Blocking MVC + JDBC/JPA| C[spring-boot-4.md + spring-framework-7.md]
+    B -->|Reactive WebFlux + R2DBC| D[spring-boot-4.md Reactive section + spring-framework-7.md]
+    A --> E{Modular monolith?}
+    E -->|Yes| F[spring-modulith.md]
+    A --> G{Security / OAuth2 / JWT?}
+    G -->|Yes| H[spring-security-7.md]
+    A --> I{Scaffold / build / versions?}
+    I -->|Yes| J[build-templates.md]
+    A --> K{Migration or errors?}
+    K -->|Yes| L[troubleshooting-migration.md]
+    A --> M{Messaging / Kafka?}
+    M -->|Yes| N[spring-messaging.md]
+```
+
 ## Mandatory Workflow
 
 1. **Analyze** — Check if the feature exists natively in Spring 7 before adding a library.
@@ -52,5 +80,8 @@ Load these as needed — do not load all at once:
 |---|---|---|
 | Spring Framework 7 APIs | `references/spring-framework-7.md` | Framework-level features: versioning, resilience, JSpecify, SpEL, streaming |
 | Spring Boot 4 features | `references/spring-boot-4.md` | Boot auto-config, Actuator, native images, testing, virtual threads |
+| Spring Security 7 | `references/spring-security-7.md` | OAuth2 Resource Server, JWT, method security, CORS, authentication/authorization |
+| Messaging (Kafka) | `references/spring-messaging.md` | Kafka, event-driven, messaging, @KafkaListener, producer/consumer |
 | Spring Modulith | `references/spring-modulith.md` | Domain-driven module design, event-driven architecture |
 | Build templates | `references/build-templates.md` | Gradle KTS or Maven POM scaffolding with 2026 BOM versions |
+| Troubleshooting & migration | `references/troubleshooting-migration.md` | Migration from Boot 3, compile/runtime errors (javax/jakarta, RestTemplate, native, null-safety) |

package/skills/java-spring-framework/references/build-templates.md

@@ -276,6 +276,8 @@ dependencies {
 | Micrometer | 1.15.x |
 | io.spring.dependency-management | 1.1.7 |
 
+When updating BOM versions, keep the CLI templates under `templates/` and this reference in sync.
+
 ---
 
 ## 4. Spring Initializr CLI Quick Start

package/skills/java-spring-framework/references/spring-boot-4.md

@@ -15,6 +15,7 @@
 8. [Scoped Values (Java 25)](#8-scoped-values-java-25)
 9. [Docker Compose Support](#9-docker-compose-support)
 10. [Spring Security 7 Basics](#10-spring-security-7-basics)
+11. [Reactive Stack (R2DBC + WebFlux)](#11-reactive-stack-r2dbc--webflux)
 
 ---
 
@@ -126,19 +127,67 @@ class UserRepositoryTest {
 }
 ```
 
+### Testcontainers (integration tests)
+
+For full integration tests against a real database, use **Testcontainers**. Prefer this when testing repository logic, transactions, or schema; use `@MockBean` for unit/slice tests where the focus is the controller or service in isolation.
+
+```kotlin
+// build.gradle.kts
+testImplementation("org.springframework.boot:spring-boot-testcontainers")
+testImplementation("org.testcontainers:postgresql")
+testImplementation("org.testcontainers:junit-jupiter")
+```
+
+```java
+@SpringBootTest(webEnvironment = WebEnvironment.RANDOM_PORT)
+@Testcontainers
+class OrderRepositoryIntegrationTest {
+
+    @Container
+    static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:17")
+        .withDatabaseName("testdb").withUsername("test").withPassword("test");
+
+    @DynamicPropertySource
+    static void props(DynamicPropertyRegistry registry) {
+        registry.add("spring.datasource.url", postgres::getJdbcUrl);
+        registry.add("spring.datasource.username", postgres::getUsername);
+        registry.add("spring.datasource.password", postgres::getPassword);
+    }
+
+    @Autowired OrderRepository repository;
+
+    @Test
+    void shouldFindOrdersByUserId() {
+        // real DB; no mocks
+        List<Order> orders = repository.findByUserId("user-1");
+        assertThat(orders).isNotEmpty();
+    }
+}
+```
+
+**When to use @MockBean vs Testcontainers:** Use `@MockBean` in `@WebMvcTest` or `@DataJpaTest` when you want fast, isolated tests. Use Testcontainers when you need real DB/network behavior (transactions, constraints, SQL).
+
 ---
 
 ## 4. Actuator & Observability
 
 Spring Boot 4 ships first-class **Micrometer Tracing + OpenTelemetry** support.
 
+### Endpoint exposure (secure by default)
+
+Expose only what you need. In production, prefer `health` and `info` for public checks; restrict `metrics`, `prometheus`, and `traces` to an internal network or secure endpoint (e.g. via Spring Security).
+
 ```yaml
 # application.yaml
 management:
   endpoints:
     web:
       exposure:
-        include: health,info,metrics,prometheus,traces
+        include: health,info,metrics,prometheus,traces   # restrict in prod
+      base-path: /actuator
+  endpoint:
+    health:
+      show-details: when-authorized   # or "never" in prod
   tracing:
     sampling:
       probability: 1.0
@@ -150,13 +199,42 @@ management:
       endpoint: http://otel-collector:4318/v1/traces
 ```
 
+Protect actuator in Security 7: allow `health`/`info` for load balancers, require authentication for `metrics`/`prometheus`/`traces`. See `references/spring-security-7.md`.
+
+### Health groups (readiness / liveness)
+
+Customize health groups for Kubernetes or load balancers. Example: a custom "readiness" group that includes DB and a custom indicator:
+
+```yaml
+management:
+  endpoint:
+    health:
+      show-details: when-authorized
+  health:
+    livenessstate:
+      enabled: true
+    readinessstate:
+      enabled: true
+    db:
+      enabled: true
+    group:
+      readiness:
+        include: readinessState,db
+      liveness:
+        include: livenessState
+```
+
+Expose only the group endpoints (e.g. `/actuator/health/readiness`, `/actuator/health/liveness`) in Security 7 for k8s probes.
+
+### Dependencies (Micrometer + OTEL)
+
 ```kotlin
 // build.gradle.kts
 implementation("io.micrometer:micrometer-tracing-bridge-otel")
 implementation("io.opentelemetry:opentelemetry-exporter-otlp")
 ```
 
-Custom span:
+### Custom span (Tracer)
 
 ```java
 @Service
@@ -318,7 +396,7 @@ No manual connection properties needed — Boot auto-configures `DataSource` and
 
 ## 10. Spring Security 7 Basics
 
-Lambda DSL is the only supported style in Spring Security 7.
+Spring Security 7 uses **lambda DSL** only for `SecurityFilterChain` and related config. Minimal example:
 
 ```java
 @Configuration
@@ -332,10 +410,8 @@ public class SecurityConfig {
                 .requestMatchers("/api/public/**").permitAll()
                 .requestMatchers("/api/admin/**").hasRole("ADMIN")
                 .anyRequest().authenticated())
-            .oauth2ResourceServer(oauth2 -> oauth2
-                .jwt(jwt -> jwt.decoder(jwtDecoder())))
-            .sessionManagement(session -> session
-                .sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .oauth2ResourceServer(oauth2 -> oauth2.jwt(jwt -> jwt.decoder(jwtDecoder())))
+            .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
             .build();
     }
 
@@ -345,3 +421,28 @@ public class SecurityConfig {
     }
 }
 ```
+
+For **OAuth2 Resource Server (JWT)**, **method security (`@PreAuthorize`)**, and **CORS**, load `references/spring-security-7.md`.
+
+---
+
+## 11. Reactive Stack (R2DBC + WebFlux)
+
+Choose the reactive stack when you need non-blocking I/O end-to-end (high concurrency, streaming, or integration with reactive drivers). For typical CRUD APIs with blocking JDBC/JPA, prefer **Spring MVC + virtual threads** (section 6).
+
+### Dependencies
+
+```kotlin
+// build.gradle.kts — replace or add to starters
+implementation("org.springframework.boot:spring-boot-starter-webflux")
+implementation("org.springframework.boot:spring-boot-starter-data-r2dbc")
+runtimeOnly("org.postgresql:r2dbc-postgresql")
+```
+
+### Main application
+
+Use `Netty` as the default server (Boot chooses it when `spring-boot-starter-webflux` is on the classpath and `spring-boot-starter-web` is not).
+
+### R2DBC repositories and WebFlux controllers
+
+Define reactive repositories (`ReactiveCrudRepository`) and inject them into `@RestController` or handler functions. Use `ServerWebExchange`, `Mono`, and `Flux` for reactive types. For **RestClient** in a reactive app, use the reactive variant and streaming; see `references/spring-framework-7.md` (Streaming Support) for alignment with Spring 7 APIs.

package/skills/java-spring-framework/references/spring-framework-7.md

@@ -2,6 +2,8 @@
 
 **Version**: 7.0.5 (Stable) | **Java baseline**: 17 (25 recommended) | **Jakarta EE**: 11
 
+For **reactive applications (WebFlux + R2DBC)**, combine this reference with the **Reactive stack** section in `references/spring-boot-4.md`.
+
 ---
 
 ## Table of Contents

package/skills/java-spring-framework/references/spring-messaging.md

@@ -0,0 +1,132 @@
+# Spring Messaging (Kafka) — Boot 4
+
+**Spring Boot**: 4.0.x | **Spring Kafka**: aligned with Boot BOM | **Jakarta EE**: 11
+
+---
+
+## Table of Contents
+
+1. [Dependencies](#1-dependencies)
+2. [application.yaml](#2-applicationyaml)
+3. [Consumer — @KafkaListener](#3-consumer--kafkalistener)
+4. [Producer](#4-producer)
+5. [Records for payloads](#5-records-for-payloads)
+
+---
+
+## 1. Dependencies
+
+Spring Boot 4 BOM manages Spring Kafka. Add the starter:
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation("org.springframework.kafka:spring-kafka")
+    // or explicitly:
+    // implementation("org.springframework.boot:spring-boot-starter-web")  // or webflux
+    // implementation("org.springframework.kafka:spring-kafka")
+}
+```
+
+For JSON (de)serialization with Jackson 3 (Jakarta):
+
+```kotlin
+implementation("org.springframework.kafka:spring-kafka")
+// Jackson is provided by Boot; ensure jakarta.* for JSON
+```
+
+---
+
+## 2. application.yaml
+
+```yaml
+spring:
+  kafka:
+    bootstrap-servers: localhost:9092
+    consumer:
+      group-id: my-app
+      auto-offset-reset: earliest
+      key-deserializer: org.apache.kafka.common.serialization.StringDeserializer
+      value-deserializer: org.springframework.kafka.support.serializer.JsonDeserializer
+      properties:
+        spring.json.trusted.packages: "*"
+    producer:
+      key-serializer: org.apache.kafka.common.serialization.StringSerializer
+      value-serializer: org.springframework.kafka.support.serializer.JsonSerializer
+```
+
+---
+
+## 3. Consumer — @KafkaListener
+
+Use Records for message payloads where possible. Listen on a topic and process with Jakarta and JSpecify where applicable.
+
+```java
+import org.springframework.kafka.annotation.KafkaListener;
+import org.springframework.kafka.support.KafkaHeaders;
+import org.springframework.messaging.handler.annotation.Header;
+import org.springframework.messaging.handler.annotation.Payload;
+import org.springframework.stereotype.Component;
+
+@Component
+public class OrderEventsConsumer {
+
+    @KafkaListener(topics = "orders", groupId = "my-app")
+    public void onOrder(@Payload OrderEvent event,
+                        @Header(KafkaHeaders.RECEIVED_KEY) String key) {
+        // process event (OrderEvent as record)
+    }
+}
+```
+
+With batch consumption:
+
+```java
+@KafkaListener(topics = "orders", groupId = "my-app", containerFactory = "batchFactory")
+public void onOrders(@Payload List<OrderEvent> events) {
+    events.forEach(this::process);
+}
+```
+
+---
+
+## 4. Producer
+
+Inject `KafkaTemplate` and send records. Use `JsonSerializer` for value when configured in application.yaml.
+
+```java
+import org.springframework.kafka.core.KafkaTemplate;
+import org.springframework.stereotype.Service;
+
+@Service
+public class OrderEventsProducer {
+
+    private final KafkaTemplate<String, OrderEvent> kafkaTemplate;
+
+    public OrderEventsProducer(KafkaTemplate<String, OrderEvent> kafkaTemplate) {
+        this.kafkaTemplate = kafkaTemplate;
+    }
+
+    public void send(OrderEvent event) {
+        kafkaTemplate.send("orders", event.orderId(), event);
+    }
+}
+```
+
+For a simple `KafkaTemplate<String, Object>` with JSON, ensure your payload type is on the trusted packages list for the consumer’s `JsonDeserializer`.
+
+---
+
+## 5. Records for payloads
+
+Prefer Java records for event DTOs (Jackson 3 supports them):
+
+```java
+public record OrderEvent(String orderId, String productId, int quantity, java.time.Instant at) {}
+```
+
+Use `jakarta.*` and JSpecify nullability in shared libraries if you need strict null contracts; for internal events, records are often sufficient.
+
+---
+
+**Summary:** Use `spring-kafka` with Boot 4 BOM, configure bootstrap servers and (de)serializers in `application.yaml`, and use `@KafkaListener` for consumers and `KafkaTemplate` for producers. Prefer records for event payloads. For Spring Cloud Stream (bindings), see the Spring Cloud Stream docs; the same Kafka dependencies can be used with Stream if you add the appropriate starters.

package/skills/java-spring-framework/references/spring-modulith.md

@@ -13,6 +13,7 @@
 6. [Transactional Event Listeners](#6-transactional-event-listeners)
 7. [Module Integration Testing](#7-module-integration-testing)
 8. [Generating Documentation](#8-generating-documentation)
+9. [Common Pitfalls](#9-common-pitfalls)
 
 ---
 
@@ -218,3 +219,15 @@ void generateModuleDocumentation() throws Exception {
 ```
 
 Output lands in `target/spring-modulith-docs/` (Maven) or `build/spring-modulith-docs/` (Gradle).
+
+---
+
+## 9. Common Pitfalls
+
+| Pitfall | Remedy |
+|--------|--------|
+| **Circular module dependencies** | `ApplicationModules.of(...).verify()` fails. Break the cycle: introduce a shared module or move the coupling to events so no module depends on the other. |
+| **Exposing internal types in the module API** | Public classes in the module root (e.g. `OrderService`) must not return or accept types from `internal/`. Use DTOs or domain types in the public package only. |
+| **Forgetting the verification test in CI** | Add the module verification test (section 3) to your CI pipeline so boundary violations are caught on every commit. |
+| **Direct service calls across modules** | One module must not inject another module's service and call it directly. Use `ApplicationEventPublisher` and `@ApplicationModuleListener` (or transactional events) for cross-module communication. |
+| **Putting shared DTOs in one module's internal** | Types used in events or APIs consumed by several modules belong in a `shared/` (or similar) package, not in one module's `internal/`. |

package/skills/java-spring-framework/references/spring-security-7.md

@@ -0,0 +1,203 @@
+# Spring Security 7 — Reference (Boot 4)
+
+**Spring Boot**: 4.0.x | **Spring Security**: 7.0.x | **Jakarta EE**: 11
+
+---
+
+## Table of Contents
+
+1. [Dependencies](#1-dependencies)
+2. [OAuth2 Resource Server (JWT)](#2-oauth2-resource-server-jwt)
+3. [SecurityFilterChain (Lambda DSL)](#3-securityfilterchain-lambda-dsl)
+4. [Method Security (@PreAuthorize)](#4-method-security-preauthorize)
+5. [CORS](#5-cors)
+6. [application.yaml](#6-applicationyaml)
+
+---
+
+## 1. Dependencies
+
+Spring Boot 4 BOM brings Spring Security 7. Add only what you need:
+
+```kotlin
+// build.gradle.kts
+dependencies {
+    implementation("org.springframework.boot:spring-boot-starter-security")
+    implementation("org.springframework.boot:spring-boot-starter-oauth2-resource-server")  // JWT
+    implementation("org.springframework.boot:spring-boot-starter-oauth2-client")             // optional: OAuth2 login
+}
+```
+
+---
+
+## 2. OAuth2 Resource Server (JWT)
+
+Validate JWTs from an authorization server (e.g. OIDC issuer). Lambda DSL is the only supported style in Security 7.
+
+```java
+import org.springframework.context.annotation.Bean;
+import org.springframework.context.annotation.Configuration;
+import org.springframework.security.config.annotation.web.builders.HttpSecurity;
+import org.springframework.security.config.annotation.web.configuration.EnableWebSecurity;
+import org.springframework.security.oauth2.jwt.JwtDecoder;
+import org.springframework.security.oauth2.jwt.NimbusJwtDecoder;
+import org.springframework.security.web.SecurityFilterChain;
+import org.springframework.security.config.http.SessionCreationPolicy;
+
+@Configuration
+@EnableWebSecurity
+public class SecurityConfig {
+
+    @Bean
+    SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+        return http
+            .authorizeHttpRequests(auth -> auth
+                .requestMatchers("/api/public/**", "/actuator/health").permitAll()
+                .requestMatchers("/api/admin/**").hasRole("ADMIN")
+                .anyRequest().authenticated())
+            .oauth2ResourceServer(oauth2 -> oauth2
+                .jwt(jwt -> jwt.decoder(jwtDecoder())))
+            .sessionManagement(session -> session
+                .sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+            .csrf(csrf -> csrf.disable())   // typical for stateless API
+            .build();
+    }
+
+    @Bean
+    JwtDecoder jwtDecoder() {
+        return NimbusJwtDecoder.withJwkSetUri("https://auth.example.com/.well-known/jwks.json").build();
+    }
+}
+```
+
+With **issuer-uri** (Boot auto-configures `JwtDecoder`):
+
+```yaml
+# application.yaml
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: https://auth.example.com
+```
+
+Then omit the custom `JwtDecoder` bean; Boot provides it.
+
+---
+
+## 3. SecurityFilterChain (Lambda DSL)
+
+All security configuration uses the lambda style. Example: form login + API protected by JWT.
+
+```java
+import org.springframework.security.config.Customizer;
+
+@Bean
+SecurityFilterChain webFilterChain(HttpSecurity http) throws Exception {
+    return http
+        .securityMatcher("/api/**")
+        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
+        .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
+        .sessionManagement(s -> s.sessionCreationPolicy(SessionCreationPolicy.STATELESS))
+        .build();
+}
+```
+
+---
+
+## 4. Method Security (@PreAuthorize)
+
+Enable method security and use SpEL in annotations (Jakarta namespace).
+
+```java
+@Configuration
+@EnableMethodSecurity
+public class MethodSecurityConfig {}
+```
+
+```java
+import org.springframework.security.access.prepost.PreAuthorize;
+
+@Service
+public class OrderService {
+
+    @PreAuthorize("hasRole('ADMIN') or #userId == authentication.name")
+    public Order getOrder(String userId, String orderId) {
+        return orderRepository.findById(orderId).orElseThrow();
+    }
+
+    @PreAuthorize("hasAuthority('SCOPE_orders:write')")
+    public Order create(OrderRequest request) {
+        return orderRepository.save(map(request));
+    }
+}
+```
+
+Use `@PreAuthorize` / `@PostAuthorize` for read; `@PreFilter` / `@PostFilter` for filtering collections. All use Jakarta annotations in Spring Security 7.
+
+---
+
+## 5. CORS
+
+Configure CORS in the security pipeline or globally. Example: allow a frontend origin.
+
+```java
+import org.springframework.security.config.Customizer;
+import org.springframework.web.cors.CorsConfiguration;
+import org.springframework.web.cors.CorsConfigurationSource;
+import org.springframework.web.cors.UrlBasedCorsConfigurationSource;
+
+@Bean
+SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
+    return http
+        .cors(cors -> cors.configurationSource(corsConfigurationSource()))
+        .authorizeHttpRequests(auth -> auth.anyRequest().authenticated())
+        .oauth2ResourceServer(oauth2 -> oauth2.jwt(Customizer.withDefaults()))
+        .build();
+}
+
+@Bean
+CorsConfigurationSource corsConfigurationSource() {
+    CorsConfiguration config = new CorsConfiguration();
+    config.setAllowedOrigins(List.of("https://app.example.com"));
+    config.setAllowedMethods(List.of("GET", "POST", "PUT", "DELETE", "OPTIONS"));
+    config.setAllowedHeaders(List.of("*"));
+    config.setAllowCredentials(true);
+
+    UrlBasedCorsConfigurationSource source = new UrlBasedCorsConfigurationSource();
+    source.registerCorsConfiguration("/**", config);
+    return source;
+}
+```
+
+Or use `WebMvcConfigurer` for non-security CORS only; for APIs with credentials, the above is typical.
+
+---
+
+## 6. application.yaml
+
+Minimal Security 7 + OAuth2 RS settings:
+
+```yaml
+spring:
+  security:
+    oauth2:
+      resourceserver:
+        jwt:
+          issuer-uri: https://auth.example.com
+          jwk-set-uri: https://auth.example.com/.well-known/jwks.json  # if no issuer-uri
+
+# Optional: restrict actuator by profile
+management:
+  endpoints:
+    web:
+      exposure:
+        include: health,info,metrics
+```
+
+For **development only**, you can disable security (e.g. with a `SecurityFilterChain` that permits all when a profile is active). Never disable in production.
+
+---
+
+**Summary:** Use `SecurityFilterChain` with lambda DSL, OAuth2 Resource Server with JWT for APIs, `@EnableMethodSecurity` and `@PreAuthorize` for method-level rules, and configure CORS in the security pipeline when the API is consumed by a browser client.

package/skills/java-spring-framework/references/troubleshooting-migration.md

@@ -0,0 +1,119 @@
+# Troubleshooting & Migration — Spring Boot 4 / Framework 7
+
+Quick fixes for common errors and a short checklist for migrating from Boot 3 to Boot 4.
+
+---
+
+## Table of Contents
+
+1. [Common errors](#1-common-errors)
+2. [Boot 3 → 4 migration checklist](#2-boot-3--4-migration-checklist)
+
+---
+
+## 1. Common errors
+
+### javax vs jakarta
+
+**Symptom:** Compilation errors like `package javax.servlet does not exist`, `javax.persistence` not found, or similar for `javax.*`.
+
+**Cause:** Spring Boot 4 and Spring Framework 7 use **Jakarta EE 11**. All `javax.*` namespaces were replaced by `jakarta.*`.
+
+**Fix:**
+
+- Replace imports: `javax.servlet.*` → `jakarta.servlet.*`, `javax.persistence.*` → `jakarta.persistence.*`, `javax.validation.*` → `jakarta.validation.*`, etc.
+- Ensure dependencies use Jakarta. Spring Boot 4 BOM already brings Jakarta-based starters. Third-party libs must be Jakarta-compatible (e.g. Hibernate 7.x, Bean Validation 3.x, Servlet API 6.x).
+- Search the project for `javax.` and replace with `jakarta.` where applicable.
+
+---
+
+### RestTemplate not found or deprecated
+
+**Symptom:** `RestTemplate` cannot be resolved, or IDE/compiler warns it is deprecated.
+
+**Cause:** In Spring Framework 6+, `RestTemplate` is in maintenance mode. Spring 7 promotes `RestClient` for synchronous HTTP.
+
+**Fix:**
+
+- Add dependency (usually already present with `spring-boot-starter-web`): `RestClient` is in `spring-web`.
+- Replace usage:
+
+```java
+// Before
+RestTemplate rest = new RestTemplate();
+MyDto dto = rest.getForObject(url, MyDto.class);
+
+// After (Spring 7)
+RestClient rest = RestClient.create();
+MyDto dto = rest.get().uri(url).retrieve().body(MyDto.class);
+```
+
+For declarative clients, use `HttpServiceProxyFactory` + interface. See `references/spring-framework-7.md`.
+
+---
+
+### Null-safety: JSR-305 vs JSpecify
+
+**Symptom:** Warnings or errors about `@Nullable` / `@NonNull` (e.g. wrong package or conflicting annotations).
+
+**Cause:** Spring 7 aligns with **JSpecify** (`org.jspecify.annotations`). Legacy JSR-305 (`javax.annotation` or `org.checkerframework`) is not the standard for Spring 7.
+
+**Fix:**
+
+- Remove JSR-305 / Checker Framework null annotations from dependencies if possible.
+- Add JSpecify and use it consistently:
+
+```kotlin
+implementation("org.jspecify:jspecify:1.0.0")
+```
+
+```java
+import org.jspecify.annotations.Nullable;
+import org.jspecify.annotations.NonNull;
+import org.jspecify.annotations.NullMarked;
+```
+
+- Annotate packages or types with `@NullMarked` where you want strict null checking. Replace `javax.annotation.Nullable` with `org.jspecify.annotations.Nullable`, etc.
+
+---
+
+### Native image: reflection or classpath errors
+
+**Symptom:** GraalVM native build fails with "Class not found", "Reflection without registration", or similar.
+
+**Cause:** Native images need explicit metadata for reflection, resources, and dynamic proxies. Spring Boot AOT helps but not all code paths are covered.
+
+**Fix:**
+
+- Prefer **functional bean registration** instead of classpath scanning where possible. Use `ApplicationContextInitializer` or `BeanDefinitionRegistryPostProcessor` to register beans programmatically.
+- For DTOs or types used in JSON/serialization, register reflection:
+
+```java
+@RegisterReflectionForBinding({MyDto.class, OtherDto.class})
+@Configuration(proxyBeanMethods = false)
+public class NativeHintsConfig {}
+```
+
+- Add GraalVM reachability metadata for third-party libraries if needed (e.g. `native-image.properties` or library-specific hints). Check [GraalVM Native Image documentation](https://www.graalvm.org/latest/reference-manual/native-image/) and Spring Boot’s native support.
+- Ensure you are not loading classes only by name (e.g. `Class.forName`) without registering them for reflection.
+
+---
+
+## 2. Boot 3 → 4 migration checklist
+
+Use this as a short guide. For authoritative steps, refer to the official [Spring Boot 4 release notes](https://github.com/spring-projects/spring-boot/wiki/Spring-Boot-4.0-Release-Notes) and upgrade guides.
+
+| Step | Action |
+|------|--------|
+| **Java** | Use Java 17 minimum; **Java 21 or 25** recommended. |
+| **BOM** | Update parent or BOM to Spring Boot **4.0.x** (e.g. `4.0.3`). |
+| **javax → jakarta** | Replace all `javax.*` imports and dependencies with `jakarta.*` (servlet, persistence, validation, etc.). |
+| **Dependencies** | Align with Boot 4: Jackson **3.x**, JPA/Hibernate **3.2 / 7.x**, Bean Validation **3.1**, Spring Framework **7.0.x**. Remove or upgrade any lib that still depends on `javax.*` or old versions. |
+| **RestTemplate** | Migrate to **RestClient** (or WebClient for reactive). See `references/spring-framework-7.md`. |
+| **Null annotations** | Migrate to **JSpecify** (`org.jspecify`) if you use null-safety annotations. |
+| **Security** | Spring Security 7 uses **lambda DSL** only. Update `SecurityFilterChain` and related config to lambda style. See `references/spring-security-7.md`. |
+| **Optional: Virtual threads** | Enable with `spring.threads.virtual.enabled: true` in `application.yaml` for eligible workloads. |
+| **Optional: Java 25 features** | For Structured Concurrency or Scoped Values, enable `--enable-preview` in compile and run; use Boot 4 + Java 25. See `references/spring-boot-4.md`. |
+| **Tests** | Run full test suite; fix any failures due to API changes (e.g. `RestTestClient` instead of `TestRestTemplate` where applicable). Use **Testcontainers** for integration tests if needed. See `references/spring-boot-4.md` Testing section. |
+
+After migration, verify actuator endpoints, security rules, and database access. For deeper issues, load the appropriate reference file (e.g. `spring-security-7.md`, `spring-framework-7.md`, `spring-boot-4.md`) as indicated in the skill’s Reference Files table.

package/templates/gradle-kotlin/build.gradle.kts.template

@@ -9,6 +9,7 @@ plugins {
 
 group   = "{{packageName}}"
 version = "0.0.1-SNAPSHOT"
+description = "{{description}}"
 
 java {
     toolchain {

package/templates/gradle-kotlin/src/main/java/com/example/app/Application.java.template

@@ -5,9 +5,10 @@ import org.springframework.boot.SpringApplication;
 import org.springframework.boot.autoconfigure.SpringBootApplication;
 
 /**
- * {{appName}} — Spring Boot {{bootVersion}} / Java {{javaVersion}} / Jakarta EE 11
+ * {{appName}} — {{description}}
+ * Spring Boot {{bootVersion}} / Java {{javaVersion}} / Jakarta EE 11
  *
- * Generated by create-spring-boot4 ({{year}})
+ * Generated by spring-boot4-skill ({{year}})
  */
 @NullMarked
 @SpringBootApplication(proxyBeanMethods = false)