SpineEventEngine

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.

Validate 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". Read-only with respect to the project sources. Does **not** cover Javadoc/KDoc (out of scope for this skill).

Run the pre-PR checklist for this repo: apply the version gate only when the repository has a root `version.gradle.kts`, run a scope-dependent build/check command per `.agents/running-builds.md` (docs-only → `dokka`; code/deps → `build`; proto → `clean build`; no documented command → skipped), and invoke the relevant reviewers (`kotlin-review`, `review-docs`, `dependency-audit`, `check-links`) against the branch diff. On success, write a sentinel file at `.git/pre-pr.ok` 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 you want a fast local repro.

Resolve the on-disk location of a Maven artifact's source code, so you can `Grep`/`Read` it directly instead of running `unzip` against JARs in the Gradle cache. Use this whenever you need to inspect a library's API or implementation — definitions of public types, method signatures, KDoc, internal helpers, etc.

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

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

Walk every dependency declaration under `buildSrc/src/main/kotlin/io/spine/dependency/`, discover 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. 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".

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.

Chords build and release-engineering policy. Use for root and codegen/plugins Gradle build logic, buildSrc dependency coordinates, publishing wiring, version increments, generated `pom.xml`/`dependencies.md` reports, and the config submodule relationship.

Chords CI/CD workflow guidance. Use for authoring or reviewing GitHub Actions workflows under `.github/workflows`: Ubuntu/Windows builds, license-report and version-increment guards, Gradle wrapper validation, and artifact publishing.

Reviews Chords implementation changes for correctness, regressions, public API breaks, missing tests, and cross-module contract breaks. Use to review component, codegen, or build diffs. Read-only unless explicitly asked to run checks.

Chords code generation policy. Use for the ProtoData codegen plugins project, the codegen runtime library, generated MessageField/MessageOneof/MessageDef contracts, codegen correctness tests, and Protobuf declarations with Kotlin extensions in proto-values.

Chords UI component implementation policy. Use for the class-based component model, application shell, input components, layouts, message forms, validation display, dropdown/table/entity components, and server-connected components across the core, proto, and client modules.

Reviews Chords documentation changes: KDoc comments, README.md files, .agents/project.md, AGENTS.md, skills, command examples, and architecture or module maps. Read-only unless explicitly asked to run checks.

Writes, edits, and restructures Chords documentation. Use when asked to create or update README.md files, .agents/project.md, AGENTS.md, skills, KDoc comments, or inline explanatory comments. Verifies claims against current code, tests, workflows, and build files.

Routes Chords implementation work to the area-specific engineering skill. Use for mixed component/codegen/build changes or when the owning area is unclear; otherwise prefer the narrowest specialist skill directly.

Encodes the embed-code-go Go implementation policy and recurring pitfalls. Use whenever writing, modifying, refactoring, debugging, or reviewing Go code in this repository, especially CLI/config parsing, parser state transitions, embedding behavior, fragmentation, filesystem handling, error reporting, package APIs, formatting, vetting, and build verification.

The embed-code-go authority on writing and reviewing Go tests. Use when adding, restructuring, or reviewing tests for Go production code, parser behavior, embedding flows, fragmentation, CLI/config validation, fixtures, malformed inputs, regression coverage, focused go test commands, or full suite verification. go-engineer remains the baseline for Go inside test helper code.

Writes, edits, and restructures embed-code-go documentation. Use when asked to create or update README.md, showcase guides, PROJECT.md, AGENTS.md, skills, Markdown fixtures, contributor notes, examples, command snippets, Go doc comments, or inline explanatory comments. Verifies claims against current Go code, tests, fixtures, and project flows.

Reviews documentation changes in embed-code-go: Go doc comments, inline comments, README.md, showcase guides, PROJECT.md, AGENTS.md, skills, Markdown fixtures, and user-facing examples. Use when a diff touches prose, documentation comments, embedding syntax docs, command examples, architecture/package maps, or agent instructions. Read-only; does not run builds unless explicitly asked.

Validate 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". Read-only with respect to the project sources. Does **not** cover Javadoc/KDoc (out of scope for this skill).

Run the pre-PR checklist for this repo: apply the version gate only when the repository has a root `version.gradle.kts`, run the configured build/check command per `.agents/running-builds.md`, and invoke the configured reviewers (`kotlin-review`, `review-docs`, `dependency-audit`, `check-links`) against the branch diff. On success, write a sentinel file at `.git/pre-pr.ok` 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 you want a fast local repro.

Write, edit, and restructure user-facing and developer-facing documentation. Use when asked to create/update docs such as `README.md`, `docs/**`, and other Markdown documentation; when drafting tutorials, guides, troubleshooting pages, or migration notes; and when improving inline API documentation (KDoc) and examples.