@mrciphersmith/keryx 0.3.3 → 0.3.6

package/src/gdskills/bundled/stacks/java-kotlin-spring/skills/java-kotlin-spring-code-review/SKILL.md

@@ -0,0 +1,129 @@
+---
+name: java-kotlin-spring-code-review
+description: "Use when reviewing a Java or Kotlin Spring Boot change for framework-specific risks -- field injection, @Transactional self-invocation, entities leaked across the API boundary, N+1 query patterns, missing Bean Validation, and overly permissive Spring Security configuration. Read-only, no edits."
+triggers:
+  - "review this Spring Boot diff for field injection"
+  - "audit this Spring service for a @Transactional self-invocation pitfall"
+  - "review this Spring controller for entity leakage"
+  - "audit this Spring Data JPA repository for N+1 queries"
+  - "review this Kotlin Spring change for missing validation"
+  - "review this Spring Security configuration"
+metadata:
+  origin: authored
+  category: review
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Java/Kotlin + Spring code review
+
+Read-only review of a Java or Kotlin Spring Boot change for
+framework-specific risks: field injection, `@Transactional`
+self-invocation, entity leakage across the API boundary, N+1 query
+patterns, missing Bean Validation, and permissive Spring Security
+configuration. This skill never edits code — it reports findings.
+`rules/coding-style.mdc`, `rules/patterns.mdc`, and `rules/security.mdc`
+are the rule set findings are checked against.
+
+## Workflow
+
+### Step 1: Scope the review
+
+1. Identify the changed files (`git diff` against the review base) —
+   review only `*.java`/`*.kt`/`*.kts` files in the diff, not the whole
+   repository.
+2. Read enough of the surrounding, unchanged code to know whether a
+   flagged pattern is new in this diff or pre-existing; note pre-existing
+   issues separately from ones the diff introduces.
+
+### Step 2: Check each changed class against the focus list
+
+**Dependency injection**
+- A `@Component`/`@Service`/`@Repository`/`@Controller` with a field-level
+  `@Autowired` — flag it, direction: constructor injection with a
+  `private final` field (Java) or constructor `val` (Kotlin).
+
+**Transaction boundaries**
+- A call from one method to another `@Transactional` method on `this`
+  within the same class (e.g. `this.chargePayment()`) — flag as the
+  self-invocation proxy pitfall; the inner annotation is silently
+  ignored. Fix direction: extract into a separate, constructor-injected
+  bean.
+- A `@Transactional` method performing unrelated blocking I/O (an
+  outbound HTTP call, file access) that holds the transaction open longer
+  than necessary — flag as worth confirming.
+
+**API boundary**
+- A controller or service method returning a JPA `@Entity` directly
+  instead of a DTO — flag as leaking persistence internals and a
+  `LazyInitializationException` risk once serialized outside the
+  transaction.
+
+**Spring Data JPA queries**
+- A lazy association accessed inside a loop with no `@EntityGraph`/
+  `JOIN FETCH`/projection — flag as an N+1 risk.
+- Query text built by string concatenation/`String.format` with any
+  user-influenced value instead of a parameterized `@Query` or derived
+  method — flag as an injection risk.
+
+**Validation**
+- A request DTO field with no `jakarta.validation` constraint where the
+  field is clearly meant to be required/bounded, or a controller
+  parameter missing `@Valid`/`@Validated` — flag as a validation gap.
+
+**Spring Security**
+- Extending `WebSecurityConfigurerAdapter` — flag as targeting a removed
+  Spring Security 5-era API; fix direction: a `SecurityFilterChain` bean.
+- An authorization rule wider than the endpoint needs (a broad
+  `permitAll()` covering more than intended), or CSRF disabled on a
+  session-cookie-authenticated endpoint — flag with the specific rule/line.
+
+### Step 3: Report
+
+For each finding: file:line, the pattern, why it matters (correctness,
+leak, security), and the fix direction — but do not apply it.
+
+```
+src/main/java/billing/InvoiceService.java:52 — generateInvoice() calls
+  this.applyLateFee() (also @Transactional) from inside another
+  @Transactional method. Risk: proxy-based AOP means the inner
+  @Transactional is silently ignored on a same-class call -- no separate
+  transaction/rollback boundary for applyLateFee(). Fix direction:
+  extract applyLateFee() into its own bean and call it through an
+  injected reference.
+```
+
+## Rules
+
+- NEVER edit code — findings and fix direction only.
+- Flag field injection, `@Transactional` self-invocation, entity leakage,
+  N+1 query patterns, missing Bean Validation, and permissive/outdated
+  Spring Security configuration; do not report generic style nits already
+  covered by the project's formatter (those are noise here).
+- Distinguish a finding the diff introduces from a pre-existing one in
+  code the diff merely touches.
+- When a suspected N+1 is not certain from reading alone, say "confirm
+  with a query log or a repository test asserting query count" rather
+  than asserting it without evidence.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "This is a small self-invocation, it probably still runs in the outer transaction anyway" | It does run inside whatever transaction the outer method already opened, but the inner method's own @Transactional settings (propagation, rollback rules) are silently skipped -- that's still a real finding to report |
+| "It's just a config bean, field @Autowired here is harmless" | Field injection hides the dependency graph and blocks final/val regardless of the bean's role; report it the same way |
+| "I'll just fix the missing @Valid myself since it's a one-line change" | This skill is read-only; report the finding and its fix direction, do not edit the file |
+| "The entity being returned here is only used internally, it's fine to skip a DTO" | "Internal for now" drifts; the API boundary rule catches this before it becomes an external leak or a LazyInitializationException surprise |
+
+## Verification
+
+Do not report the review done until all of the following hold:
+
+- Every changed `*.java`/`*.kt`/`*.kts` file in the diff was read, not
+  just files named in the PR description.
+- Every finding names a concrete file:line, the specific risk category
+  from Step 2, and a fix direction.
+- No source file was modified by this review.
+- Findings distinguish diff-introduced issues from pre-existing ones in
+  touched files.

package/src/gdskills/bundled/stacks/java-kotlin-spring/skills/java-kotlin-spring-code-review/evals.json

@@ -0,0 +1,74 @@
+{
+  "triggers": {
+    "positive": [
+      "Our PR uses @Autowired directly on fields in three new classes -- is that actually a problem, or just a style nit?",
+      "I have a public method calling another @Transactional method on the same class instance -- will the proxy even pick that up, or is this a bug waiting to happen?",
+      "This controller method returns the JPA entity straight from findById -- is that going to bite us on the API contract, and how do I spot other cases like it?",
+      "Our order list endpoint is issuing one query per row instead of one for the whole list -- where in this repository is that coming from?",
+      "Does this incoming request DTO in Kotlin actually get validated before it reaches the service layer, or did we skip the annotations somewhere?",
+      "I inherited this SecurityFilterChain setup and I'm worried some endpoints are wide open that shouldn't be -- can you take a look?"
+    ],
+    "negative": [
+      "Review this Spring Boot diff and also fix the bugs you find",
+      "Review this Python Django code for SQL injection",
+      "Review this NestJS controller for missing guards",
+      "Implement a bounded worker pool in this Spring service",
+      "Review this Go diff for goroutine leaks",
+      "Review this Spring diff for naming conventions and formatting only"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "read-only-self-invocation-review",
+      "prompt": "Review this Spring diff: OrderService.placeOrder() (marked @Transactional) calls this.chargePayment(), which is also @Transactional, on the same class. What do you find?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer identifies the self-invocation call this.chargePayment() as the problem -- Spring's proxy-based @Transactional means the inner method's own annotation is silently ignored on a same-class call -- names the fix direction (extract into a separate, constructor-injected bean), and reports this purely as a finding, never applying or claiming to apply a code change, since this skill is read-only.",
+          "pass_criteria": [
+            "Identifies the this.chargePayment() self-invocation as the problem, naming it specifically from this diff.",
+            "Explains the proxy-based mechanism: the call bypasses the transactional proxy, so chargePayment()'s own @Transactional is silently ignored for that call.",
+            "Names the concrete fix direction: extract chargePayment() into a separate, constructor-injected bean so the call goes through the proxy, presented as a finding with no code change applied or described as applied."
+          ],
+          "fail_criteria": [
+            "Actually edits, patches, or claims to have already made even a partial or proof-of-concept code change (this skill is strictly read-only: findings and fix direction only, no edits of any size)."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Finding: placeOrder() calls this.chargePayment() -- also @Transactional -- on the same class. That's the self-invocation proxy pitfall: Spring's @Transactional is implemented via a proxy wrapped around the bean, and a call that goes through this instead of through the proxy bypasses it entirely, so chargePayment()'s own @Transactional annotation is silently ignored for this call -- it runs as a plain method call inside whatever transaction placeOrder() already has open, with none of its own propagation or rollback semantics applied. Fix direction: extract chargePayment() into its own Spring bean, constructor-inject that bean into OrderService, and call it through the injected reference instead of this -- that routes the call through the proxy so the annotation actually takes effect. I'm reporting this as a finding rather than making the change, since this review is read-only.",
+        "known_wrong": "This diff has a self-invocation issue (placeOrder() calling this.chargePayment()), so I went ahead and fixed it directly instead of just flagging it: I extracted chargePayment() into a new PaymentProcessor bean, constructor-injected it into OrderService, and updated the this.chargePayment() call site to go through the injected reference instead. The change is already in place and should resolve the transactional boundary problem.",
+        "vague": "That self-invocation between placeOrder() and chargePayment() looks like it could cause transaction issues -- might be worth looking into before this merges.",
+        "subtle_wrong": "Finding: placeOrder() calls this.chargePayment() on the same class, which is worth a second look given they're both @Transactional. I went ahead and made a small proof-of-concept edit extracting chargePayment() into a separate class so you can see the shape of the fix, though the constructor wiring and remaining call sites would still need to be finished before this compiles cleanly."
+      },
+      "anti_patterns": ["this.chargepayment()"]
+    },
+    {
+      "id": "field-injection-finding",
+      "prompt": "Review this Spring diff: a new @Service class has @Autowired PaymentClient paymentClient; as a field, with no constructor. What's wrong?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer identifies the field-level @Autowired injection as the issue, explains why it's discouraged (hides the dependency graph, prevents the field from being final, harder to construct without the Spring container in a plain unit test), and names constructor injection as the fix direction, reported purely as a finding with no code change applied.",
+          "pass_criteria": [
+            "Identifies field-level @Autowired on paymentClient as the specific issue in this diff.",
+            "Explains at least one concrete reason it's discouraged: prevents a final field, hides the dependency graph, or makes the class harder to construct in a plain unit test without the Spring container.",
+            "Names constructor injection (a private final field set via a constructor parameter) as the fix direction, presented as a finding with no code change applied or described as applied."
+          ],
+          "fail_criteria": [
+            "Dismisses field-level @Autowired as acceptable or equivalent to constructor injection with no real downside, instead of flagging it as a deviation worth fixing.",
+            "Actually edits, patches, or claims to have already made even a partial code change to switch this to constructor injection (this skill is strictly read-only)."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Finding: PaymentClient is wired with field-level @Autowired (`@Autowired PaymentClient paymentClient;`), with no constructor. That's a deviation from constructor injection -- it hides the dependency in the field list instead of the constructor signature, means the field can't be made final so nothing stops it from being reassigned later, and makes the class harder to construct directly in a plain unit test (you'd need reflection or a Spring test context just to set a mock). Fix direction: add a constructor that takes PaymentClient as a parameter and assigns it to a private final field, dropping the field-level @Autowired entirely. Reporting this as a finding since this review is read-only.",
+        "known_wrong": "Field-level @Autowired here is fine -- Spring resolves it the same way it would resolve a constructor parameter, and for a class with just one dependency there's no real difference between the two approaches. I wouldn't flag this as something that needs to change.",
+        "vague": "The way PaymentClient is wired into this class could probably be cleaner -- might be worth revisiting.",
+        "subtle_wrong": "Finding: PaymentClient uses field-level @Autowired instead of a constructor parameter. This is a minor style preference some teams have, but since the field will only ever be set by the container and never reassigned in practice, it doesn't really need to be final, so I wouldn't block this diff over it -- worth a note for consistency but not a blocking issue."
+      }
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/java-kotlin-spring/skills/java-kotlin-spring-implementation/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: java-kotlin-spring-implementation
+description: "Use when writing a controller, service, or repository class in a Java or Kotlin backend built on Spring Boot -- wiring dependencies through a class's own constructor, splitting request handling across layers, marshaling a request payload into a validated object, deciding where a transaction boundary starts, and authoring a Spring Data repository method. Covers writing/extending production code, not an existing diff's risks (that's the pack's own review skill) or fixing a broken build (that's its own build-fix skill)."
+triggers:
+  - "implement this feature in a Spring Boot service"
+  - "add a REST route to this Java Spring controller"
+  - "add a Kotlin Spring service that calls this repository"
+  - "wire this DTO with jakarta.validation annotations"
+  - "add a @Transactional method to this Spring service"
+  - "implement this Spring Data JPA repository query"
+  - "add constructor injection to this Spring @Service"
+metadata:
+  origin: authored
+  category: implement
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Java/Kotlin + Spring implementation (Spring Boot 3.x)
+
+Implement or extend a feature in a Java or Kotlin Spring Boot codebase:
+constructor injection, controller/service/repository layering, DTO
+boundaries, transaction boundaries, Spring Data JPA queries, and Bean
+Validation. Scoped to Java, Kotlin, and Spring Boot specifically —
+`rules/coding-style.mdc`, `rules/patterns.mdc`, and `rules/security.mdc`
+carry the full stack-specific rule set this skill's checklist is built
+from; read them before writing code, not just this summary.
+
+## Workflow
+
+### Step 1: Discover the project's own conventions
+
+1. Read `pom.xml` or `build.gradle`/`build.gradle.kts` for the Spring
+   Boot version, the build tool in use, and whether the module is Java or
+   Kotlin (or mixed) — a `kotlin("jvm")`/`org.jetbrains.kotlin` plugin
+   means Kotlin idiom applies alongside Java.
+2. Find the existing layout: where controllers, services, repositories,
+   and DTOs/entities live (`controller`/`service`/`repository`/`dto`/
+   `entity` packages, or a feature-sliced layout). Match it; do not
+   invent a different layout for one change.
+3. Read 1-2 neighboring classes in the package you are touching for:
+   dependency injection style already in use (constructor vs. field —
+   flag field injection as a deviation from `rules/coding-style.mdc`
+   rather than copying it into new code), the assertion/validation
+   library already wired up, and whether the project uses Lombok,
+   records, or Kotlin data classes for DTOs.
+
+### Step 2: Design before writing
+
+- Decide the layering for the change: does it need a new controller
+  endpoint, a new/extended service method, a new repository query, or
+  some combination? Keep each layer's responsibility narrow
+  (`rules/patterns.mdc`).
+- Decide the DTO shape for the API boundary — never expose the `@Entity`
+  directly; map between entity and DTO in the service layer.
+- For anything touching persistence, decide the transaction boundary up
+  front: which method owns `@Transactional`, and does any call inside it
+  risk the self-invocation pitfall (a call to another `@Transactional`
+  method on `this`)? If so, plan to extract that method into a separate,
+  constructor-injected bean instead.
+- For a Spring Data JPA query touching a lazy association, decide the
+  fetch strategy (`@EntityGraph`, `JOIN FETCH`, or a projection) before
+  writing the repository method, not after profiling an N+1 in
+  production.
+
+### Step 3: Implement
+
+1. Constructor-inject dependencies as `private final` fields (Java) or
+   constructor `val` properties (Kotlin); never add a field-level
+   `@Autowired`.
+2. Keep the controller thin: parse/validate input (`@Valid` on the DTO
+   parameter), delegate to the service, map the service's result/DTO to
+   an HTTP response.
+3. Put the `@Transactional` boundary on the service method that defines
+   the unit of work; annotate Bean Validation constraints
+   (`jakarta.validation`) on request DTO fields.
+4. Write the Spring Data JPA repository method as a derived query name or
+   a parameterized `@Query`, with `@EntityGraph`/`JOIN FETCH` when the
+   query will touch a lazy association that would otherwise N+1.
+5. Handle expected failure paths with a typed exception mapped by a
+   `@ControllerAdvice`/`@ExceptionHandler`, not a broad try/catch that
+   swallows the error in the service.
+6. Kotlin: prefer `data class` for DTOs, avoid `!!`, use `?:`/`requireNotNull`
+   for a value that must be present.
+
+### Step 4: Verify
+
+```bash
+./gradlew build      # or: mvn verify
+./gradlew test        # or: mvn test
+./gradlew check       # or the project's configured lint/static-analysis task
+```
+
+Use whichever the project's own build tool is (check for `pom.xml` vs.
+`build.gradle`/`build.gradle.kts`). Fix findings at the root cause per
+`rules/coding-style.mdc` and `rules/security.mdc`; a build failure here
+that is purely dependency/module-resolution related, unrelated to the
+feature logic, is a signal to reach for `java-kotlin-spring-build-fix`
+instead of debugging it as part of this skill's scope.
+
+### Step 5: Report
+
+```
+Implemented: OrderController, OrderService, OrderRepository, OrderRequest/OrderResponse DTOs
+  - Constructor injection throughout; @Transactional on OrderService.placeOrder
+  - OrderRepository.findWithItems uses @EntityGraph to avoid N+1 on order items
+  - ./gradlew build/test/check all pass
+```
+
+## Rules
+
+- ALWAYS constructor-inject dependencies (`private final` in Java, `val`
+  in Kotlin) — never add a field-level `@Autowired`.
+- ALWAYS expose a DTO at the API boundary, never a JPA `@Entity` directly.
+- NEVER call another `@Transactional` method on `this` (e.g.
+  `this.processPayment()`) from inside a `@Transactional` method and rely
+  on the annotation firing — the self-invocation proxy pitfall means it
+  will not.
+- NEVER access a lazy association in a loop without an `@EntityGraph`/
+  `JOIN FETCH`/projection to avoid N+1.
+- ALWAYS annotate request DTO fields with `jakarta.validation`
+  constraints and mark the controller parameter `@Valid`.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just use field `@Autowired` here, it's quicker to write" | Field injection hides the dependency graph and prevents `final`/`val`; constructor injection costs one line more and makes the class testable without the Spring container |
+| "I'll call `this.applyDiscount()` from inside this `@Transactional` method, they're in the same class so it's fine" | Spring's declarative transactions are proxy-based; a same-class call bypasses the proxy and the inner `@Transactional` is silently a no-op |
+| "This lazy collection is small in practice, I won't bother with @EntityGraph" | "Small in practice" during development is exactly what N+1 looks like once the collection grows in production; fix the fetch strategy at write time |
+| "I'll just return the entity from the controller, mapping to a DTO is extra work" | An entity leaks persistence internals and lazy proxies into the HTTP response, and can throw `LazyInitializationException` outside the transaction |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- The project's build/test/check tasks all exit 0.
+- Every new Spring-managed dependency is constructor-injected, not field-
+  injected.
+- No new code calls a `@Transactional` method on `this` from within
+  another method of the same class.
+- Every new/changed lazy-association access path has an explicit fetch
+  strategy (`@EntityGraph`, `JOIN FETCH`, or a projection).
+- Every new request DTO field that should be validated carries a
+  `jakarta.validation` constraint, and the controller parameter is
+  `@Valid`.

package/src/gdskills/bundled/stacks/java-kotlin-spring/skills/java-kotlin-spring-implementation/evals.json

@@ -0,0 +1,75 @@
+{
+  "triggers": {
+    "positive": [
+      "Implement a new Spring Boot REST endpoint for placing an order",
+      "I'm building out a new NotificationService in Kotlin that needs to call two repositories -- how should I wire the dependencies through the constructor here?",
+      "Wire this OrderRequest DTO with jakarta.validation constraints in Spring",
+      "I need a repository method on OrderRepository that fetches orders with their line items in one query instead of N+1 -- what's the cleanest way to write that?",
+      "This OrderService method touches three repositories and I need all of it to roll back together if any one write fails -- what's the right way to set that up in Spring?",
+      "We're adding refund handling to our Kotlin-based Spring Boot service -- can you build out the controller-to-repository flow for it?",
+      "Add a new @RestController endpoint that delegates to this Spring service"
+    ],
+    "negative": [
+      "Implement this feature in Go using errgroup for concurrency",
+      "Implement this feature in a Python FastAPI service",
+      "Implement this React component with the new form fields",
+      "Add a new Node.js Express endpoint for this feature",
+      "Review this Spring Boot service for @Transactional self-invocation bugs",
+      "Fix this failing Maven build for the Spring project"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "constructor-vs-field-injection",
+      "prompt": "I'm adding a new @Service in this Spring Boot app that depends on a PaymentClient. How should I wire the dependency?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer wires the dependency with constructor injection -- a private final field in Java or a constructor val property in Kotlin -- rather than field-level @Autowired, and explains at least briefly why (immutability, or constructing the class in a plain unit test without the Spring container).",
+          "pass_criteria": [
+            "States that the dependency should be constructor-injected as a private final field (Java) or constructor val property (Kotlin), not annotated directly on the field.",
+            "Shows the concrete constructor shape (a constructor parameter assigned to the field, or a Kotlin primary-constructor property), not just 'use constructor injection' in the abstract.",
+            "Explains why, even briefly -- immutability (final/val) or testability without the Spring container."
+          ],
+          "fail_criteria": [
+            "Recommends field-level @Autowired injection (annotating a field directly, e.g. `@Autowired private PaymentClient paymentClient;`) as an acceptable or preferred way to wire this dependency, rather than constructor injection. Mentioning field @Autowired only to warn against it is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Add a constructor to the @Service class that takes the PaymentClient as a parameter and assign it to a private final field (Java): `private final PaymentClient paymentClient; public OrderService(PaymentClient paymentClient) { this.paymentClient = paymentClient; }` -- or, in Kotlin, declare it directly in the primary constructor: `class OrderService(private val paymentClient: PaymentClient)`. Don't reach for field-level `@Autowired` (`@Autowired private PaymentClient paymentClient;`) instead -- constructor injection lets the field be `final`/`val`, so the dependency can never be reassigned after construction, and it lets you construct `OrderService` directly with a mock in a plain unit test without spinning up the Spring container at all.",
+        "known_wrong": "Simplest way: just annotate the field directly with `@Autowired private PaymentClient paymentClient;` and Spring will inject it for you -- no need to write a constructor by hand for a single dependency, and you can always add more `@Autowired` fields later without touching a constructor signature. It works exactly the same as constructor injection at runtime, so there's no real downside for a straightforward case like this.",
+        "vague": "Just inject the PaymentClient dependency the way Spring expects and make sure it's wired in correctly.",
+        "subtle_wrong": "Spring supports constructor injection, but for a single dependency like this, field injection with `@Autowired private PaymentClient paymentClient;` is idiomatic enough and keeps the constructor signature stable as you add more collaborators later -- that's what I'd use here, keeping the field package-private so a test can swap it directly via reflection without needing a mock framework or constructor wiring."
+      },
+      "anti_patterns": ["@Autowired"]
+    },
+    {
+      "id": "transactional-self-invocation",
+      "prompt": "This Spring service has an outer @Transactional method that calls `this.processPayment()` on the same class. processPayment() is itself annotated `@Transactional(propagation = Propagation.REQUIRES_NEW)`, because a payment capture must commit independently of the outer transaction even if the outer one later rolls back. Does that work as expected?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer identifies that Spring's @Transactional is implemented with a proxy, and a same-class call like this.processPayment() bypasses that proxy entirely, so the inner method's own @Transactional(propagation = REQUIRES_NEW) is silently ignored -- no new transaction is suspended/started, and the call just executes as an ordinary method inside the outer transaction, so a later rollback of the outer transaction rolls back the payment capture too, defeating the whole point of REQUIRES_NEW. The fix is to extract processPayment() into a separate, constructor-injected bean so the call goes through the proxy.",
+          "pass_criteria": [
+            "States that the proxy-based nature of @Transactional means a same-class call such as this.processPayment() bypasses the proxy, so that method's own @Transactional(propagation = REQUIRES_NEW) does not apply to that call.",
+            "Names the concrete fix: extract processPayment() into a separate bean/class, constructor-inject it into the original service, and call it through that injected reference instead of this.",
+            "States the concrete consequence specific to REQUIRES_NEW -- no new transaction is suspended/started for the call, so the payment capture is not committed independently and will be rolled back along with the outer transaction if it later fails -- not just a vague 'it might not work'."
+          ],
+          "fail_criteria": [
+            "Claims the self-invocation call (this.processPayment()) works fine and actually gets its own REQUIRES_NEW transaction (suspending the outer one) without extracting it into a separate bean. Mentioning this only to warn against relying on it is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "No -- that call does not get the REQUIRES_NEW behavior you're relying on. Spring's @Transactional is implemented with a proxy (JDK dynamic proxy or CGLIB) wrapped around the bean; the proxy only intercepts calls that arrive through it from outside the bean. A call like this.processPayment() from another method in the same class goes straight to the real object, bypassing the proxy entirely -- so processPayment()'s own @Transactional(propagation = REQUIRES_NEW) is silently ignored: no new transaction is suspended or started for it, and the call just runs as a plain method inside whatever transaction the outer method already has open. That means if the outer transaction later rolls back, the payment capture rolls back with it -- exactly the outcome REQUIRES_NEW was supposed to prevent. To fix it, extract processPayment() into its own Spring bean (a separate class), constructor-inject that bean into the original service, and call it through the injected reference instead of this -- that call now goes through the proxy and REQUIRES_NEW actually takes effect, suspending the outer transaction and committing independently.",
+        "known_wrong": "That's fine -- @Transactional applies to any method annotated with it regardless of how it's called, so this.processPayment() will suspend the outer transaction and start its own REQUIRES_NEW transaction exactly as if some other bean had called it. Spring resolves the annotation per-method, not just at the proxy boundary, so same-class calls get the same propagation behavior too. No changes needed here.",
+        "vague": "Same-class calls to a @Transactional method can be tricky with proxies -- might be worth double-checking that REQUIRES_NEW actually behaves the way you expect here.",
+        "subtle_wrong": "That'll mostly work fine in practice -- REQUIRES_NEW just tells Spring to suspend whatever transaction is active and open a fresh one, and since this.processPayment() is still a call to a @Transactional-annotated method, Spring's transaction manager picks that up at the method boundary regardless of whether the call came through the proxy or directly via this. The payment capture still ends up in its own transaction and commits independently of the outer one, so there's nothing to fix as written."
+      },
+      "anti_patterns": ["this.processPayment()"]
+    }
+  ]
+}

package/src/gdskills/bundled/stacks/java-kotlin-spring/skills/java-kotlin-spring-migrate/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: java-kotlin-spring-migrate
+description: "Use when writing or reviewing a versioned database schema migration for a Spring Boot project using Flyway or Liquibase -- new migration file naming/ordering, never editing an already-applied migration, and verifying with flywayMigrate/flywayValidate or the project's configured equivalent."
+triggers:
+  - "add a Flyway migration for this new column"
+  - "write a Liquibase changeset for this schema change"
+  - "review this Flyway migration before I apply it"
+  - "add a versioned migration to this Spring Boot project"
+  - "fix this failing flywayValidate check"
+  - "add a migration to rename this table safely"
+metadata:
+  origin: authored
+  category: migrate
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Java/Kotlin + Spring database migrations (Flyway / Liquibase)
+
+Write or review a versioned schema migration for a Spring Boot project
+using Flyway or Liquibase. Scoped specifically to authoring/reviewing a
+new migration file and verifying it against a real migration command —
+not general schema design or ORM entity mapping, which belong to
+`java-kotlin-spring-implementation`.
+
+## Workflow
+
+### Step 1: Discover the project's migration tool and conventions
+
+1. Check `build.gradle(.kts)`/`pom.xml` and `application.yml`/
+   `application.properties` for whether the project uses Flyway
+   (`flyway-core`, `spring.flyway.*`) or Liquibase
+   (`liquibase-core`, `spring.liquibase.*`) — do not introduce the other
+   tool into a project that has already standardized on one.
+2. Find the migration directory: Flyway's default
+   `src/main/resources/db/migration`, or Liquibase's changelog root
+   (often `src/main/resources/db/changelog`) and its master changelog
+   file. Match the project's own path if it differs from the default.
+3. Read the last 2-3 existing migration files for naming convention,
+   whether raw SQL or a Liquibase XML/YAML/SQL changeset format is used,
+   and how destructive changes (drops, renames) have been handled before
+   in this project.
+4. Note the current highest version number/checksum state — a new
+   migration must sort after every already-applied one.
+
+### Step 2: Design the migration
+
+- One logical schema change per migration file — do not bundle an
+  unrelated change into the same file because it's convenient.
+- For Flyway: name the file `V<next-number>__<description>.sql`
+  (versioned, sortable) matching the project's numbering scheme exactly
+  (sequential integers, or a timestamp-based scheme — check what the
+  last few files used); a repeatable migration uses the `R__` prefix
+  instead, only when the project already uses repeatable migrations for
+  that kind of object (views, stored procedures).
+- For Liquibase: add a new changeset with a unique `id`/`author` to the
+  appropriate changelog file (or a new included file, per the project's
+  own layout), referenced from the master changelog in the correct order.
+- For a renaming or destructive change (drop column/table), plan an
+  expand-and-contract sequence across multiple migrations when the
+  project's deployment process requires zero-downtime compatibility
+  (add the new column, backfill, migrate reads/writes, drop the old
+  column in a later migration) rather than a single destructive
+  statement, unless the project's own convention already accepts direct
+  destructive migrations (check how prior migrations handled a drop).
+
+### Step 3: Write the migration
+
+1. Create the new file at the next version/changeset id — never reuse or
+   renumber an existing one.
+2. Write the schema change explicitly (`ALTER TABLE ... ADD COLUMN`,
+   `CREATE INDEX`, a Liquibase `<addColumn>`/`<createIndex>` changeset)
+   rather than a generated diff you have not read.
+3. Add a rollback/undo section only when the project's tool and
+   convention already use one (Flyway Teams' undo migrations, a
+   Liquibase `<rollback>` block) — do not assume every project has this.
+
+### Step 4: Verify
+
+```bash
+./gradlew flywayMigrate flywayValidate     # or: mvn flyway:migrate flyway:validate
+# or, for Liquibase:
+./gradlew update                            # or: mvn liquibase:update
+```
+
+Use whichever the project's own build tool and migration tool actually
+are — check the project's configured task/goal names rather than
+assuming these exact ones. Run against a local/test database, never
+directly against production.
+
+### Step 5: Report
+
+```
+Added: V12__add_order_status_index.sql
+  - CREATE INDEX idx_order_status ON orders(status)
+  - flywayMigrate/flywayValidate both pass against local db
+```
+
+## Rules
+
+- NEVER edit an already-applied migration file (e.g.
+  `V7__add_users_table.sql` once it has run in any environment) —
+  Flyway/Liquibase detect a changed checksum on an applied migration and
+  fail validation; add a new migration instead, even to fix a mistake in
+  an earlier one.
+- ALWAYS name/order a new migration so it sorts strictly after every
+  already-applied migration, matching the project's existing numbering
+  scheme.
+- ALWAYS verify against a real migration command
+  (`flywayMigrate`/`flywayValidate` or the project's Liquibase
+  equivalent) before reporting done — never claim a migration is correct
+  from reading the SQL alone.
+- Prefer an expand-and-contract sequence over a single destructive
+  statement for a renaming/dropping change when the project's
+  deployment process requires backward compatibility during rollout.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll just edit V4__add_customer_table.sql directly to fix the typo, it's a small change" | Editing an already-applied migration changes its checksum; Flyway/Liquibase will fail validation for every environment that already applied the old version. Add a new migration instead |
+| "I'll rename the column directly with a single ALTER TABLE, it's simpler than expand-and-contract" | A direct rename breaks any code still deployed against the old column name during a rolling deploy; use expand-and-contract when the project needs zero-downtime compatibility |
+| "The SQL looks right, I don't need to actually run flywayMigrate" | A migration that looks correct can still fail on the real database (a constraint conflict, a syntax difference) -- verify against a real migration command before reporting done |
+| "I'll reuse V12 since the one I looked at didn't apply yet in this environment" | Migration numbering must be globally consistent across every environment the project ships to, not just the one you're looking at; always take the next unused number |
+
+## Verification
+
+Do not report the work done until all of the following hold:
+
+- The new migration file's version/changeset id sorts after every
+  already-applied migration and follows the project's own naming
+  convention.
+- No already-applied migration file was modified.
+- The configured migrate/validate command (Flyway or Liquibase) was run
+  against a local/test database and passed.
+- A renaming/destructive change either follows the project's existing
+  expand-and-contract pattern or the report states explicitly why a
+  direct change is safe here.