spring-boot4-skill 1.1.0 → 1.3.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# 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.3.0] - 2026-02-21
+
+### Added
+
+- **Skill:** spring-boot-4.md: new section 12 (Rate limiting — Bucket4j, time-window vs @ConcurrencyLimit) and section 13 (Resources & performance — HikariCP/R2DBC pools, Actuator pool metrics, Caffeine cache, performance tuning summary).
+- **Skill:** SKILL.md Reference Files "Load when" extended for rate limiting, connection pools, resource metrics, caching, performance tuning; Quick decision mermaid node for "Rate limit / resources / performance?".
+- **Skill:** spring-framework-7.md Resilience section: note linking to spring-boot-4.md for time-window rate limiting.
+- **README:** Skill reference table: spring-boot-4.md description now includes rate limiting, connection pools, caching, performance.
+
+[1.3.0]: https://github.com/AyrtonAldayr/agent-skill-java-spring-framework/compare/v1.2.0...v1.3.0
+
+## [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) · **v1.1.0**
+> By [AyrtonAldayr](https://github.com/AyrtonAldayr) · **v1.3.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
 
 ```
@@ -112,8 +134,9 @@ 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: native, virtual threads, testing (Testcontainers), reactive stack |
+| `skills/java-spring-framework/references/spring-boot-4.md` | Boot 4: native, virtual threads, testing (Testcontainers), reactive stack, rate limiting, connection pools, caching, performance |
 | `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 |
@@ -151,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,

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.1.0",
+  "version": "1.3.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

@@ -40,6 +40,10 @@ flowchart TD
     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]
+    A --> O{Rate limit / resources / performance?}
+    O -->|Yes| P[spring-boot-4.md]
 ```
 
 ## Mandatory Workflow
@@ -77,8 +81,9 @@ Load these as needed — do not load all at once:
 | Topic | File | Load when |
 |---|---|---|
 | 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 Boot 4 features | `references/spring-boot-4.md` | Boot auto-config, Actuator, native images, testing, virtual threads, rate limiting, connection pools, resource metrics, caching, performance tuning |
 | 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

@@ -16,6 +16,8 @@
 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)
+12. [Rate Limiting](#12-rate-limiting)
+13. [Resources & Performance](#13-resources--performance)
 
 ---
 
@@ -201,6 +203,31 @@ management:
 
 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
@@ -421,3 +448,153 @@ Use `Netty` as the default server (Boot chooses it when `spring-boot-starter-web
 ### 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.
+
+---
+
+## 12. Rate Limiting
+
+**Concurrency vs time-based:** For **limiting concurrent calls per method**, use Spring 7’s built-in `@ConcurrencyLimit(maxConcurrentCalls = N)` — see `references/spring-framework-7.md` (Resilience Annotations). For **rate limiting by time window** (e.g. 100 requests per minute per IP or per user), use an in-app filter/interceptor with a token-bucket implementation or a gateway.
+
+### Time-based rate limit (in application)
+
+Use **Bucket4j** (token bucket) with a key per client (e.g. IP or authenticated user). Apply it in a `Filter` or `HandlerInterceptor` and return `429 Too Many Requests` when the bucket is exhausted.
+
+**Dependency:**
+
+```kotlin
+// build.gradle.kts
+implementation("com.bucket4j:bucket4j-core:8.10.1")
+```
+
+**Example: filter keyed by IP**
+
+```java
+import io.github.bucket4j.Bandwidth;
+import io.github.bucket4j.Bucket;
+import io.github.bucket4j.Refill;
+import jakarta.servlet.FilterChain;
+import jakarta.servlet.ServletException;
+import jakarta.servlet.http.HttpServletRequest;
+import jakarta.servlet.http.HttpServletResponse;
+import org.springframework.core.annotation.Order;
+import org.springframework.stereotype.Component;
+import org.springframework.web.filter.OncePerRequestFilter;
+
+import java.io.IOException;
+import java.time.Duration;
+import java.util.Map;
+import java.util.concurrent.ConcurrentHashMap;
+
+@Component
+@Order(1)
+public class RateLimitFilter extends OncePerRequestFilter {
+
+    private final Map<String, Bucket> buckets = new ConcurrentHashMap<>();
+    private static final int CAPACITY = 100;
+    private static final Duration REFILL_DURATION = Duration.ofMinutes(1);
+
+    @Override
+    protected void doFilterInternal(HttpServletRequest request, HttpServletResponse response,
+                                    FilterChain filterChain) throws ServletException, IOException {
+        String key = clientKey(request); // e.g. request.getRemoteAddr() or principal name
+        Bucket bucket = buckets.computeIfAbsent(key, k -> newBucket());
+        if (bucket.tryConsume(1)) {
+            filterChain.doFilter(request, response);
+        } else {
+            response.setStatus(HttpServletResponse.SC_TOO_MANY_REQUESTS);
+            response.getWriter().write("Rate limit exceeded");
+        }
+    }
+
+    private static String clientKey(HttpServletRequest request) {
+        return request.getRemoteAddr();
+    }
+
+    private static Bucket newBucket() {
+        Bandwidth limit = Bandwidth.classic(CAPACITY, Refill.greedy(CAPACITY, REFILL_DURATION));
+        return Bucket.builder().addLimit(limit).build();
+    }
+}
+```
+
+For **per-user** limits, use a key derived from `SecurityContextHolder.getContext().getAuthentication()` (e.g. principal name) and exempt unauthenticated or health endpoints from the filter if needed.
+
+**When to use which:** Use `@ConcurrencyLimit` to cap concurrent executions of a specific method. Use a filter with Bucket4j (or similar) for API-level limits per time window (per IP or per user). If traffic is fronted by **Spring Cloud Gateway**, rate limiting can also be implemented at the edge; that is outside the scope of this reference.
+
+---
+
+## 13. Resources & Performance
+
+### Connection pools (HikariCP, R2DBC)
+
+**HikariCP (blocking JDBC)** — Spring Boot configures it by default. Tune in `application.yaml`:
+
+```yaml
+spring:
+  datasource:
+    hikari:
+      maximum-pool-size: 20
+      minimum-idle: 5
+      connection-timeout: 30000
+      idle-timeout: 600000
+      max-lifetime: 1800000
+```
+
+See [Spring Boot Data Access](https://docs.spring.io/spring-boot/docs/current/reference/html/data.html#data.sql.datasource.hikari) for all options.
+
+**R2DBC** — For reactive apps, configure the connection pool similarly (e.g. `spring.r2dbc.pool.*`). DB health is included in health groups (section 4); use readiness to avoid sending traffic to instances that cannot get a connection.
+
+### Metrics for resources
+
+Actuator exposes **HikariCP** metrics (e.g. `hikaricp.connections.active`, `hikaricp.connections.idle`, `hikaricp.connections.pending`). Use these in Prometheus/Grafana to size pools and alert on exhaustion. R2DBC pool metrics follow a similar pattern when the reactive stack is used.
+
+### Caching
+
+Use **Spring Cache** with **Caffeine** for in-process caching. Reduces repeated work and database load.
+
+**Dependencies:**
+
+```kotlin
+// build.gradle.kts
+implementation("org.springframework.boot:spring-boot-starter-cache")
+implementation("com.github.ben-manes.caffeine:caffeine")
+```
+
+**Enable and configure:**
+
+```java
+@SpringBootApplication
+@EnableCaching
+public class Application { ... }
+```
+
+```yaml
+# application.yaml
+spring:
+  cache:
+    cache-names: products,users
+    caffeine:
+      spec: maximumSize=1000,expireAfterWrite=300s
+```
+
+**Usage:**
+
+```java
+@Service
+public class ProductService {
+
+    @Cacheable(cacheNames = "products", key = "#id")
+    public Product findById(Long id) {
+        return productRepository.findById(id).orElseThrow();
+    }
+}
+```
+
+Use short TTLs or size limits to avoid stale or unbounded caches.
+
+### Performance tuning (summary)
+
+- **Virtual threads** (section 6): Enable for high concurrency with blocking I/O; no need to size a large thread pool.
+- **Pool sizing:** Set HikariCP (or R2DBC pool) size based on observed metrics (connections in use, pending); avoid over-provisioning.
+- **N+1:** Avoid N+1 queries in JPA (e.g. `@EntityGraph`, fetch joins, or DTO projections) so a single request does not open many statements.
+- **Observability:** Use Actuator/Prometheus and traces (section 4) to find bottlenecks (slow endpoints, DB, or external calls) and tune accordingly. No JVM-level tuning (heap, GC) is covered here.

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

@@ -92,6 +92,8 @@ public class PaymentService {
 }
 ```
 
+For **time-window rate limiting** (e.g. requests per minute per IP or user), see `references/spring-boot-4.md` (Rate limiting).
+
 ---
 
 ## 4. Programmatic Bean Registration

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/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)