agents

Fixes English grammar, punctuation, and spelling errors in the prose of source-code comments and documentation — KDoc/Javadoc, Protobuf, TSDoc/JSDoc, Go doc comments, other comments, and Markdown/AsciiDoc. Applies the shared error catalog in `.agents/guidelines/english-style.md`: a fix lands only when no leave-alone guard matches, and an ambiguous case is reported rather than edited. Touches *project-owned* prose only — never code tokens, string literals, or machine-read comment directives. Runs in three modes chosen by the caller: the default scans files changed on the current branch; `all` sweeps every project-owned file, module by module; a path argument scopes the sweep to one directory. Stateless — no memory sentinel. Reports every change grouped by catalog topic so recurring error classes surface for review. Use once per repo with `all` after a fresh `config` pull, then on each branch to catch new occurrences, or against a named module.

Runs the pre-PR checklist for this repo: applies the version gate only when the repository has a root `version.gradle.kts`, runs a scope-dependent build/check command per `.agents/guidelines/running-builds.md` (proto → `clean build`; code/deps → `build`; doc-only `.kt`/`.java` edit → `dokkaGenerate`; Markdown-only → no build; no documented command → skipped), and running `dokkaGenerate` for any `.kt`/`.java` source change (alongside `build` for code edits, alone for KDoc/Javadoc-only edits) so unresolved KDoc/Javadoc links fail locally instead of in CI's Dokka run, and invokes the relevant reviewers (`kotlin-engineer`, `spine-code-review`, `review-docs`, `dependency-audit`, `check-links`) against the branch diff. On success, writes the `pre-pr.ok` sentinel into the repository's git directory so the `gh pr create` hook can verify the checklist ran for the current HEAD. Use before opening a PR, or when CI rejected a branch and a fast local repro is wanted.

Converts Java code to idiomatic Kotlin, including its API comments from Javadoc to KDoc. Use when asked to migrate Java files, classes, methods, nullability semantics, or common Java patterns into Kotlin while preserving behavior.

Writes, edits, and restructures user-facing and developer-facing documentation. Use when asked to create/update docs such as `README.md`, `docs/**`, and other Markdown documentation, including keeping docs navigation data in sync; when drafting tutorials, guides, troubleshooting pages, or migration notes; and when improving inline API documentation (KDoc) and examples.

Reviews documentation changes — doc comments inside sources (KDoc/Javadoc, Protobuf, TSDoc/JSDoc, Go) and Markdown docs (`README.md`, `docs/**`, `.agents/**`) — against Spine documentation conventions, including the English grammar, punctuation, and spelling catalog. Use when a diff touches doc comments or Markdown, before opening a doc-affecting PR, or when asked for a documentation review. Read-only; does not run builds.

Updates source file copyright headers from the IntelliJ IDEA copyright profile, replacing `today.year` with the current year. Automatically applies to changed source files when source files are modified in a change set. In repositories that consume the shared `config` submodule, files distributed by `config` (such as `buildSrc/`) are skipped — their headers are owned by `config`, not by the consumer's copyright profile.

Ensures `version.gradle.kts` is bumped above the base ref — at most once per branch, barring the sanctioned re-bumps below — per the Spine SDK versioning policy. This skill is idempotent: it stops without committing when the branch is already ahead of base. For the routine "make sure the branch is bumped" check use the `version-bumped` guard, which calls this skill only on a miss. Invoke this skill directly to perform the actual bump, or to re-bump only for a sanctioned reason — a published-version collision, or reclassification to a breaking PR (see "Sanctioned re-bumps"). Covers the idempotency gate, locating the published version value, choosing the increment, migrating deprecated `by extra(...)` declarations to `extra.set(...)`, committing the bump, rebuilding reports, and resolving version conflicts.

Verifies the current branch has bumped `version.gradle.kts` strictly above the base ref; runs the `bump-version` skill to auto-recover if not. Composable: other modifying skills (`dependency-update`, `bump-gradle`, `java-to-kotlin`, `move-files`) call this as their final step so a `./gradlew build` or `publishToMavenLocal` can never overwrite a previously published Maven Local artifact that integration tests in consumer repos depend on.

Validates the Hugo documentation site under `docs/` or `site/` for broken links. Builds the site, starts the Hugo server locally, runs Lychee against the rendered HTML using the repo's `lychee.toml`, and reports any broken URLs grouped by source Markdown page. Use locally before pushing changes that touch `docs/**` or `site/**`, when CI's `Check Links` job fails, or whenever the user asks to "check doc links". If no Hugo site exists under `docs/` or `site/`, report the check as not applicable instead of failing. Read-only with respect to the project sources. Does **not** cover Javadoc/KDoc (out of scope for this skill).

Guide a user through collaboratively co-authoring a structured document — a proposal, technical spec, decision doc, README, design doc, or similar — in three stages: gathering context, drafting and refining each section, then reader-testing the result against a fresh, context-free agent to catch blind spots before others read it. Use when the user wants to write such a document through an interactive, section-by-section workflow. For directly writing or restructuring existing docs without the interview loop, use the writer skill.

Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.

The Spine SDK authority on writing a JVM test in Kotlin, for both Kotlin and Java production code. New tests are Kotlin — JUnit 5 structure, Kotest assertions, `internal` `Spec`-suffixed classes, and the matching `testlib` base class — with one sanctioned exception: an `XJavaSpec` that verifies a Kotlin class works from Java across the compatibility bridge. Use when adding or restructuring any JVM test: a fresh suite, more cases, a Kotlin suite beside an existing Java test, an integration `XIgTest`, or a Java-bridge spec. `raise-coverage` delegates its test-writing conventions here; `kotlin-engineer` remains the baseline for the Kotlin inside each test body.

Reviews Kotlin, Java, and build changes in this repo against repo-specific Spine rules: the AGENTS.md code-review filter, safety rules, testing policy, and the version gate. Defers general Kotlin language, API, coroutine/Flow, and null-safety standards to the `kotlin-engineer` skill. Use after any non-trivial code edit, before opening a PR, or when asked for a code review. Read-only; does not run builds.

Encodes the project's Kotlin 2.x implementation policy and the pitfalls that recur in review. Use whenever writing, modifying, refactoring, or explaining Kotlin code, especially coroutines, Flow, null-safety, Java interop, Gradle Kotlin DSL, and public API design.

Walks every dependency declaration under `buildSrc/src/main/kotlin/io/spine/dependency/`, discovers the latest accepted version of each artifact from the URL hinted in its file (or from Maven metadata if no URL is present), and update the `version` constant in place. Also refresh the build script's own dependencies declared in `buildSrc/build.gradle.kts` (Gradle plugins and `buildSrc` libraries), respecting their pin rationale and "keep in sync with `io.spine.dependency.*`" comments. External dependency scopes accept only released versions; the `local` scope also accepts snapshots and pre-releases published from sibling Spine repos. Use when asked to refresh dependency versions, bump libraries, run a dependency audit, or "see what's stale".

Raises JVM test coverage for a Gradle module or source path. Outside read-only `--triage`, first ensures the repo is on Kover — auto-migrating from vanilla JaCoCo, or installing Kover when absent (routine cases run without asking; manual-review surfaces are flagged). Then localizes uncovered lines and branches from Kover's JaCoCo-format XML report and generates policy-compliant unit tests: stubs not mocks, written in Kotlin with Kotest assertions even when the code under test is Java, class names suffixed `Spec`. Proposes a test-case list and waits for approval before writing any test (pass `--yes` to skip), then re-runs the report to confirm the gap closed. Use when asked to add missing tests, close coverage gaps, or raise a module's coverage.

Resolves the on-disk location of a Maven artifact's source code, so it can be inspected directly instead of running `unzip` against JARs in the Gradle cache. Use when inspecting a library's API or implementation — definitions of public types, method signatures, KDoc, internal helpers, etc.

Updates 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.

Audits changes to dependency declarations under `buildSrc/src/main/kotlin/io/spine/dependency/` — catches accidental version downgrades, BOM mismatches, missing deprecation markers when artifacts are renamed or removed, copyright drift, and convention drift. Use whenever a diff touches that directory, or when asked to "audit this dependency bump". Read-only; does not run builds.

Reviews Gradle-related changes in this repo against Spine SDK conventions and the upstream Gradle best-practices guides ingested under `practices/`. Three scopes: (1) `buildSrc/` in the `config` repository only; (2) Gradle build files in any project; (3) production code of Gradle plugins exposed by Spine SDK tools. Use after any non-trivial change to build logic, before opening a PR, or when asked for a Gradle review. Read-only; does not run builds.

Moves or renames any files/directories in a repo: preserves history, updates all references and build metadata, verifies no stale paths remain.