Add TemplateString and Placeholder

.agents/_TOC.md

@@ -13,4 +13,4 @@
 11. [Advanced safety rules](advanced-safety-rules.md)
 12. [Refactoring guidelines](refactoring-guidelines.md)
 13. [Common tasks](common-tasks.md)
-14. [Java to Kotlin conversion](java-kotlin-conversion.md)
+14. [Java to Kotlin conversion](skills/java-to-kotlin/SKILL.md)

.agents/quick-reference-card.md

@@ -3,7 +3,6 @@
 ```
 🔑 Key Information:
 - Kotlin/Java project with CQRS architecture
-- Use ChatGPT for documentation, Codex for code generation, GPT-4o for complex analysis
 - Follow coding guidelines in Spine Event Engine docs
 - Always include tests with code changes
 - Version bump required for all PRs

.agents/skills/bump-gradle/SKILL.md

@@ -0,0 +1,117 @@
+---
+name: bump-gradle
+description: >
+  Update the Gradle wrapper version used by this repository. Use when asked to
+  upgrade Gradle, bump the Gradle wrapper, move the project to the latest
+  Gradle release from the official release notes, run the Gradle build, and
+  commit Gradle wrapper and dependency report changes separately.
+---
+
+# Bump Gradle
+
+Use the official Gradle release notes as the source of truth for both the
+latest version and the wrapper update command:
+
+https://docs.gradle.org/current/release-notes.html#upgrade-instructions
+
+Always check that page at task time. Do not rely on remembered Gradle versions.
+
+## Checklist
+
+1. Work from the target repository root.
+
+   Confirm `./gradlew` and `gradle/wrapper/gradle-wrapper.properties` exist
+   before changing anything. Inspect `git status --short` and preserve unrelated
+   user changes. If Gradle wrapper files are already modified, inspect the diff
+   and continue only when those edits are part of the same requested Gradle
+   bump; otherwise ask before overwriting or staging them.
+
+2. Read the latest Gradle version from the release notes.
+
+   Open the Upgrade instructions section at the URL above. Use the version in
+   the release heading and the wrapper command shown there. They should agree;
+   if they do not, stop and report the mismatch.
+
+3. Run the wrapper update command.
+
+   Substitute the version from the release notes:
+
+   ```bash
+   ./gradlew wrapper --gradle-version=GRADLE_VERSION && ./gradlew wrapper
+   ```
+
+   For example, if the release notes say Gradle `9.5.1`, run:
+
+   ```bash
+   ./gradlew wrapper --gradle-version=9.5.1 && ./gradlew wrapper
+   ```
+
+4. Run the build.
+
+   ```bash
+   ./gradlew clean build
+   ```
+
+   If the wrapper update or build fails, do not commit partial changes. Report
+   the failing command and the relevant error output.
+
+5. Commit only Gradle-related files.
+
+   Inspect `git status --short` and `git diff --name-only`. Stage only files
+   created or updated by the Gradle wrapper bump, normally:
+
+   ```text
+   gradle/wrapper/gradle-wrapper.properties
+   gradle/wrapper/gradle-wrapper.jar
+   gradlew
+   gradlew.bat
+   ```
+
+   Include other Gradle-owned files only when they are directly required by the
+   wrapper update and are clearly part of the same change. Do not stage
+   dependency reports or unrelated build output in this commit.
+
+   Commit with the exact subject, replacing `GRADLE_VERSION`:
+
+   ```text
+   Bump Gradle -> `GRADLE_VERSION`
+   ```
+
+   Example:
+
+   ```bash
+   git commit -m 'Bump Gradle -> `9.5.1`'
+   ```
+
+   If no Gradle-related files changed, do not create an empty commit; report
+   that the wrapper was already current after verification.
+
+6. Commit dependency reports separately when the build updates them.
+
+   Stage only generated dependency report files. In repositories using this
+   config, the usual paths are:
+
+   ```text
+   docs/dependencies/pom.xml
+   docs/dependencies/dependencies.md
+   ```
+
+   Include other changed files only when they are clearly generated dependency
+   reports from the build. Commit them separately with:
+
+   ```text
+   Update dependency reports
+   ```
+
+7. Verify the final branch state.
+
+   Confirm the recent commit subjects and make sure no owned Gradle bump or
+   dependency report changes remain unstaged:
+
+   ```bash
+   git log --format=%s -2
+   git status --short
+   ```
+
+   Leave unrelated pre-existing user changes alone and mention them separately
+   in the final response.

.agents/skills/bump-gradle/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Bump Gradle"
+  short_description: "Update the Gradle wrapper safely"
+  default_prompt: "Use $bump-gradle to update this repository to the latest Gradle wrapper version from the official release notes, build, and split Gradle/report commits."

.agents/skills/bump-version/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: bump-version
+description: >
+  Bump the project version in `version.gradle.kts` following the Spine SDK
+  versioning policy. Use when starting a new branch, before opening a PR, or
+  when CI rejects a branch for a missing/insufficient version increment. Covers
+  locating the published version value, choosing the increment, committing the
+  bump, rebuilding reports, and resolving version conflicts.
+---
+
+# Bump the project version
+
+The authoritative policy is [Spine SDK Versioning][version-policy]. In this
+skill's target repository, CI runs the `Version Guard` workflow, which invokes
+`checkVersionIncrement` through `IncrementGuard`. The task fails if the current
+project version already exists in the Maven repository. It does not compare git
+branches or inspect commit subjects; the checks below are agent-side guardrails.
+
+## Checklist
+
+1. Work from the target repository root.
+
+   Confirm `version.gradle.kts` exists before editing. If it is absent, stop and
+   report that this skill does not apply to the current checkout.
+
+   Inspect `git status --short` before changing files. Preserve unrelated user
+   changes and stage only the version/report files this workflow owns.
+
+2. Locate `version.gradle.kts` and update the value that feeds
+   `versionToPublish`.
+
+   The published version may be a literal:
+
+   ```kotlin
+   val versionToPublish: String by extra("2.0.0-SNAPSHOT.182")
+   ```
+
+   Or it may come from another variable:
+
+   ```kotlin
+   val compilerVersion: String by extra("2.0.0-SNAPSHOT.043")
+   val versionToPublish by extra(compilerVersion)
+   ```
+
+   In the second case, update the source value (`compilerVersion` here), not
+   only the `versionToPublish` alias.
+
+3. Choose the increment.
+
+   For the normal snapshot-line PR, increment the trailing snapshot number by
+   one: `2.0.0-SNAPSHOT.182` -> `2.0.0-SNAPSHOT.183`. Preserve existing
+   zero-padding: `2.0.0-SNAPSHOT.009` -> `2.0.0-SNAPSHOT.010`.
+
+   For a breaking snapshot-line PR, advance to the next multiple of 10 that is
+   strictly greater than the current value: `.187` -> `.190`, and `.180` ->
+   `.190`.
+
+   For release-line work, follow the [policy][version-policy]: urgent fixes bump `PATCH`;
+   feature work or significant fixes bump `MINOR` and reset `PATCH` to `0`.
+
+4. Commit only the `version.gradle.kts` change with this subject:
+
+   ```text
+   Bump version -> `2.0.0-SNAPSHOT.183`
+   ```
+
+   Use the actual new version in the subject. Do not include unrelated files in
+   this commit.
+
+5. Run the build to verify the bump and regenerate reports:
+
+   ```bash
+   ./gradlew clean build
+   ```
+
+   Repos using this config commonly finalize `generatePom` and
+   `mergeAllLicenseReports` after `build`, which updates
+   `docs/dependencies/pom.xml` and `docs/dependencies/dependencies.md` when
+   those reports are configured.
+
+6. If `docs/dependencies/pom.xml` or `docs/dependencies/dependencies.md` changed,
+   commit those generated files separately:
+
+   ```text
+   Update dependency reports
+   ```
+
+   If the PR has the `License Reports` workflow, make sure the branch modifies
+   `docs/dependencies/pom.xml` and `docs/dependencies/dependencies.md`.
+
+7. Validate the branch state.
+
+   ```bash
+   BASE=master
+   git fetch --quiet origin "$BASE"
+   RANGE="$(git merge-base HEAD origin/$BASE)..HEAD"
+   git log --format=%s "$RANGE" | grep '^Bump version ->'
+   git diff --name-only "$RANGE" -- version.gradle.kts | grep '^version.gradle.kts$'
+   ```
+
+   Use the actual merge target for `BASE` when it is not `master`.
+   Also confirm `git status --short` has no uncommitted changes created by the
+   version bump or report regeneration.
+
+## Conflict Rule
+
+When merging a base branch into a feature branch:
+
+- If the base branch version is lower, keep the feature branch version.
+- If the base branch version is greater than or equal to the feature branch
+  version, set the feature branch version to `base + 1`, or apply the breaking
+  change rounding rule.
+
+Do not require a completely clean worktree if unrelated user changes are
+present. Instead, make sure no uncommitted changes were created by the version
+bump or report regeneration.
+
+[version-policy]: https://github.com/SpineEventEngine/documentation/wiki/Versioning

.agents/skills/bump-version/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Bump Version"
+  short_description: "Bump Spine project versions safely"
+  default_prompt: "Use $bump-version to bump the project version in version.gradle.kts, commit the version change, rebuild dependency reports, and verify the branch."

.agents/java-kotlin-conversion.md → .agents/skills/java-to-kotlin/SKILL.md

@@ -1,3 +1,11 @@
+---
+name: java-to-kotlin
+description: >
+  Convert Java code to Kotlin, including Java API comments from Javadoc to KDoc.
+  Use when asked to migrate Java files, classes, methods, nullability semantics,
+  or common Java patterns into idiomatic Kotlin while preserving behavior.
+---
+
 # 🪄 Converting Java code to Kotlin
 
 * Java code API comments are Javadoc format.

.agents/skills/java-to-kotlin/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Java to Kotlin"
+  short_description: "Convert Java code to idiomatic Kotlin"
+  default_prompt: "Use $java-to-kotlin to convert Java code to Kotlin while preserving behavior, nullability, and API documentation wording."

.agents/skills/move-files/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: move-files
+description: >
+  Move or rename any files/directories in a repo: preserve history, update all
+  references and build metadata, verify no stale paths remain.
+---
+
+# Move Files
+
+## Workflow
+
+1. Preflight.
+   - Run `git status --short`.
+   - Map each `source -> destination`.
+   - Classify scope: simple same-module moves stay targeted; package, module, or
+     cross-module moves need broader inspection.
+   - Ask before ambiguous mappings, destination conflicts, or unclear semantic
+     package/module changes.
+
+2. Search before moving.
+   - Search all old identifiers: paths, names, resource refs, doc links.
+   - For Gradle/module/source-set moves, check `settings.gradle.kts`,
+     `build.gradle.kts`, and `buildSrc`.
+   - For Kotlin/Java, update package declarations only when package intent
+     changes.
+
+3. Move safely.
+   - Prefer `git mv` for tracked files in the repo.
+   - Use filesystem moves only for untracked/generated/out-of-git files.
+   - Create parent directories first.
+   - For case-only renames, move through a temporary name.
+
+4. Repair references.
+   - Update all references: imports, build metadata, docs, resources, and scripts.
+   - Start search scope narrow: affected directory, then module, then repo-wide.
+   - Prefer precise edits; avoid broad replacements on generic names.
+
+5. Verify.
+   - Re-run targeted searches for old tokens.
+   - Run `git status --short` and confirm the delta matches the move.
+   - Run focused validation for moved files, or state what could not run.
+
+## Repo Notes
+
+Follow `.agents/project-structure-expectations.md` for module/source-set/test moves.
+
+## Report
+
+Return: `Moved[]`, `UpdatedRefs[]`, `Verification[]`, `Risks[]`.

.agents/skills/move-files/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Move Files"
+  short_description: "Move files safely across a repo"
+  default_prompt: "Use $move-files to relocate files or directories in this repository while preserving history, updating references, and verifying the result."

.agents/skills/update-copyright/SKILL.md

@@ -0,0 +1,16 @@
+---
+name: update-copyright
+description: >
+  Update source file copyright headers from the IntelliJ IDEA copyright profile,
+  replacing `today.year` with the current year.
+  Automatically apply when source files are modified in a change set.
+---
+
+# Copyright Update
+
+**Command:** `python3 .agents/skills/update-copyright/scripts/update_copyright.py`
+
+1. Scope: explicit files/dirs from the user, or all tracked source files if none given.
+2. No explicit paths → run with `--dry-run` first, then without.
+3. Relay stdout (notice source, file count, changed paths) to the user.
+4. Never add a copyright header to a file that does not already have one.

.agents/skills/update-copyright/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Copyright Update"
+  short_description: "Refresh source copyright headers"
+  default_prompt: "Use $update-copyright to refresh source file copyright headers from the IntelliJ IDEA copyright profile in this repository."