Add initial AI-agents configuration

.agents/project.md

@@ -0,0 +1,141 @@
+# Project
+
+This document gives agents and contributors the Chords project overview, module
+map, architecture notes, documentation ownership, and CI notes. For agent
+operating policy, read [`AGENTS.md`](../AGENTS.md).
+
+## Overview
+
+**Chords** is a suite of open-source Kotlin/JVM libraries for desktop UI
+development with the Compose Multiplatform toolkit. The libraries introduce a
+class-based component model on top of Compose, domain-specific input components
+that operate on Protobuf messages, and server connectivity based on the Spine
+Event Engine framework. The libraries are currently at an experimental stage.
+
+The main concerns are:
+
+- A class-based UI component model and application shell on top of Compose
+  (`core`).
+- Input components, message forms, and validation for Protobuf-based domain
+  models (`proto`).
+- Supplementary Protobuf messages and Kotlin extensions (`proto-values`).
+- Server connectivity, command posting, and entity subscriptions via Spine
+  Event Engine (`client`).
+- Code generation that enriches Protobuf message APIs with `MessageField`,
+  `MessageOneof`, and `MessageDef` implementations (`codegen/*`).
+
+Artifacts are published as `io.spine.chords:spine-chords-<module>` to the Spine
+snapshots repository (`https://europe-maven.pkg.dev/spine-event-engine/snapshots`)
+and GitHub Packages.
+
+## Project Map
+
+- `settings.gradle.kts`: root Gradle module registry (`core`, `runtime`,
+  `proto-values`, `proto`, `client`, `codegen-tests`).
+- `build.gradle.kts`: root Gradle configuration for group/version, the Chords
+  codegen Gradle plugin wiring, publishing, license reports, and Jacoco.
+- `version.gradle.kts`: the single `chordsVersion` for all Chords libraries;
+  must be incremented in every PR.
+- `buildSrc/`: dependency coordinates, repository helpers, and shared Gradle
+  convention plugins for the root project.
+- `quality/detekt-config.yml`: Detekt rules for the repository.
+- `config/`: Git submodule shared across Spine repositories with build scripts
+  and CI helpers; owned by `SpineEventEngine/config`, do not edit here.
+- `core/`: application shell, class-based `Component` model, input component
+  base classes, layouts, and primitive UI components.
+- `proto/`: Protobuf-aware UI components — `MessageForm`, field editors, oneof
+  support, and validation display for Protobuf domain models.
+- `proto-values/`: supplementary Protobuf message declarations (e.g., money
+  types) with Kotlin extensions; uses Chords code generation.
+- `client/`: server connectivity components — application shell client
+  extensions, command posting, entity subscriptions, and entity-backed
+  components such as `EntityChooser`.
+- `codegen/runtime/` (Gradle path `:runtime`): the runtime library required by
+  `proto` and `client` to use generated `MessageField`/`MessageOneof`/
+  `MessageDef` implementations.
+- `codegen/tests/` (Gradle path `:codegen-tests`): tests that check the
+  correctness of code generation; uses Chords code generation.
+- `codegen/plugins/`: **separate Gradle project** with ProtoData plugins that
+  generate Kotlin extensions for Protobuf messages. Requires JDK 17,
+  Gradle 9.4.x, and Kotlin 2.3.20, unlike the root project (JDK 11,
+  Gradle 6.9.4, Kotlin 1.8.20). Applied to consuming projects through the
+  [Chords Gradle plugin](https://github.com/SpineEventEngine/Chords-Gradle-plugin).
+- `pom.xml`, `dependencies.md`: generated dependency/license reports; must be
+  regenerated (not hand-edited) when the version or dependencies change.
+- `.github/workflows/`: CI for Ubuntu/Windows builds, license-report and
+  version-increment guards, Gradle wrapper validation, and publishing.
+
+Gradle group: `io.spine.chords`. Artifact prefix: `spine-chords-`. Preserve
+package roots such as `io.spine.chords` and `io.spine.money` where already
+present.
+
+## Architecture Notes
+
+The `core` module defines the class-based component model. Components extend
+`io.spine.chords.core.Component` (or `InputComponent` for value-editing
+components), render in `content()`, and perform pre-composition state updates
+in `beforeComposeContent()`. Components are configured declaratively with
+`Props`-style configuration lambdas and are instantiated per usage site via
+companion-object `invoke` operators. State that must trigger recomposition is
+held in `mutableStateOf`-backed properties.
+
+The `proto` module builds `MessageForm` and related editors on top of `core`,
+using generated `MessageField`/`MessageOneof`/`MessageDef` metadata from the
+codegen runtime to bind form fields to Protobuf message fields with validation.
+
+The `client` module connects components to a Spine Event Engine server through
+the application shell's `app.client` API (reading, observing, and posting
+commands). Components such as `EntityChooser` read and observe entity states.
+
+Code generation flow: the `codegen/plugins` project builds ProtoData plugins;
+the root build's `publishCodegenPluginsToMavenLocal` task publishes them to
+Maven local; the `io.spine.chords` Gradle plugin then applies them to the
+modules listed in `modulesWithChordsCodegen` (`proto-values`, `codegen-tests`)
+inside a generated codegen workspace. This chain is wired automatically into
+the root build; touching it usually means `build.gradle.kts` or
+`buildSrc` work.
+
+The versions of the toolchain are intentionally conservative to match consumer
+projects (Spine 1.9.x ecosystem). Do not casually bump Kotlin, Compose, Gradle,
+or Spine versions; such upgrades are dedicated tasks with wide impact.
+
+## Documentation Ownership
+
+- `README.md`: project entry point — library list, supported environment,
+  consumption instructions, and development setup.
+- `AGENTS.md`: repository operating policy for agents.
+- `.agents/project.md`: project map, architecture notes, documentation
+  ownership, and CI notes.
+- `core/README.md`: application shell, component model, and core components.
+- `proto/README.md`: Protobuf-aware components and message forms.
+- `proto-values/README.md`: supplementary Protobuf messages and extensions.
+- `client/README.md`: server connectivity facilities.
+- `codegen/runtime/README.md`: codegen runtime ownership.
+- `codegen/plugins/README.md`: ProtoData plugin project — requirements,
+  workspace resources, and module layout.
+- `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`: standard contribution policy.
+
+Keep usage instructions in the nearest library README. Keep architecture,
+module ownership, and CI notes in this file. Keep agent policy in `AGENTS.md`.
+API-level documentation belongs in KDoc on the public declarations.
+
+## CI
+
+This repository is configured with these GitHub workflows:
+
+- `Build under Ubuntu` (`.github/workflows/build-on-ubuntu.yml`): runs on every
+  push, sets up JDK 11, and runs `./gradlew build --stacktrace`.
+- `Build under Windows` (`.github/workflows/build-on-windows.yml`): runs on
+  pull requests and builds with `gradlew.bat build --stacktrace --no-daemon`.
+- `Ensure license reports updated` (`.github/workflows/ensure-reports-updated.yml`):
+  runs on pull requests and fails when `dependencies.md` / `pom.xml` (or
+  `version.gradle.kts`) were not updated in the changeset.
+- `Check version increment` (`.github/workflows/increment-guard.yml`): runs
+  `./gradlew checkVersionIncrement` to enforce that `chordsVersion` grows.
+- `Validate Gradle Wrapper` (`.github/workflows/gradle-wrapper-validation.yml`):
+  validates wrapper JAR integrity.
+- `Publish` (`.github/workflows/publish.yml`): runs on pushes to `master`,
+  decrypts publishing credentials from `.github/keys/*.gpg`, and publishes
+  artifacts to the configured Maven repositories.
+
+Publishing credentials and their rotation are human-owned.

.agents/skills/README.md

@@ -0,0 +1,51 @@
+# Skills
+
+This index is a quick orientation aid. Each skill's frontmatter remains the
+routing source of truth.
+
+- `engineer`: routing skill for mixed or unclear implementation work.
+- `component-engineer`: class-based Compose UI components across `core`,
+  `proto`, and `client` — the component model, input components, message
+  forms, and server-connected components.
+- `codegen-engineer`: ProtoData codegen plugins, the codegen runtime,
+  generated `MessageField`/`MessageOneof`/`MessageDef` contracts, and
+  Protobuf declarations in `proto-values`.
+- `build-engineer`: root and `codegen/plugins` Gradle builds, `buildSrc`
+  dependency coordinates, publishing wiring, version policy, and generated
+  report regeneration.
+- `security-reviewer`: publishing credentials, GitHub Actions secrets,
+  dependency provenance, agent prompt/configuration safety, and accidental
+  secret exposure review.
+- `ci-engineer`: GitHub Actions workflow authoring and review for build,
+  guard, validation, and publishing pipelines.
+- `code-reviewer`: implementation review for component, codegen, and build
+  changes.
+- `tester`: test authoring and verification strategy for all modules,
+  including codegen correctness tests.
+- `docs-writer`: documentation authoring, editing, restructuring, and claim
+  checks.
+- `docs-reviewer`: documentation review for prose, examples, and comments.
+
+## Skill Directory Layout
+
+Each skill lives in its own directory:
+
+```
+.agents/skills/<skill-name>/
+  SKILL.md              — frontmatter (name, description) + policy body
+  agents/openai.yaml    — UI metadata for the OpenAI-based agent interface
+```
+
+`openai.yaml` fields:
+- `display_name`: label shown in the UI
+- `short_description`: hint shown in the UI
+- `default_prompt`: starter prompt shown by the interface when the skill is invoked
+
+The `name` in `SKILL.md` frontmatter must match the directory name.
+
+## Invocation
+
+Skills are invoked via `$<skill-name>` in supported agent interfaces (for
+example, `$component-engineer`). Supported runtimes read the corresponding
+`SKILL.md` as the skill's durable instructions; `openai.yaml` carries only UI
+metadata, not policy.

.agents/skills/build-engineer/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: build-engineer
+description: >
+  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.
+---
+
+# Build Engineering
+
+## When to Use
+
+Use this skill for build, dependency, and release-plumbing work:
+
+- Root `build.gradle.kts`, `settings.gradle.kts`, `version.gradle.kts`, and
+  `gradle.properties`.
+- `buildSrc/` dependency coordinates, repository helpers, and convention
+  plugins (`jvm-module`, publishing, reports).
+- The `codegen/plugins` Gradle project's own build logic and its
+  `codegen-workspace` resource packaging.
+- Publishing configuration: `spinePublishing`, artifact prefix, destination
+  repositories, and the `publishCodegenPlugins*` tasks.
+- Version policy and the generated `pom.xml` / `dependencies.md` reports.
+- Detekt configuration under `quality/`.
+
+For workflow YAML under `.github/workflows`, use
+`.agents/skills/ci-engineer/SKILL.md`.
+
+## Policy
+
+- Two toolchains coexist: the root project uses JDK 11 / Gradle 6.9.4 /
+  Kotlin 1.8.20; `codegen/plugins` uses JDK 17 / Gradle 9.4.x / Kotlin 2.3.20.
+  Keep build logic compatible with the owning toolchain.
+- Dependency coordinates belong in
+  `buildSrc/src/main/kotlin/io/spine/internal/dependency/`, one object per
+  library, following the existing pattern. Do not inline version strings into
+  module build files.
+- Do not auto-update external dependencies or toolchain versions outside
+  dedicated upgrade tasks; the pins match the Spine 1.9.x consumer ecosystem.
+- Every PR increments `chordsVersion` in `version.gradle.kts`
+  (`2.0.0-SNAPSHOT.<N>`); CI enforces this with `checkVersionIncrement`.
+- `pom.xml` and `dependencies.md` are generated by the build (PomGenerator and
+  LicenseReporter); regenerate them via `./gradlew build` rather than editing,
+  and include the regenerated files in version-bump changesets.
+- The `config/` submodule is owned by `SpineEventEngine/config`; do not edit
+  its contents here. If shared build logic must change, describe the upstream
+  change instead.
+- Do not run `publish` or `publishCodegenPlugins` against remote repositories;
+  publishing is CI-owned (pushes to `master`). Local verification uses
+  `publishToMavenLocal`.
+- Preserve the codegen wiring contract: `modulesWithChordsCodegen` lists the
+  modules that get the `io.spine.chords` Gradle plugin, and
+  `createCodegenWorkspace` depends on `publishCodegenPluginsToMavenLocal`.
+- Keep the Gradle plugin version (`io.spine.chords` in `build.gradle.kts` and
+  `Spine.kt` in `buildSrc`) consistent in both places when bumping it.
+
+## Verification
+
+Root build (repository root, JDK 11):
+
+```bash
+./gradlew clean build
+./gradlew publishToMavenLocal
+./gradlew checkVersionIncrement
+```
+
+Codegen plugins build (from `codegen/plugins/`, JDK 17):
+
+```bash
+./gradlew build
+./gradlew publishToMavenLocal
+```
+
+Run the `publishToMavenLocal` variant when plugin publication is part of the
+change, so root modules consume the rebuilt plugins.
+
+After version or dependency changes, confirm `pom.xml` and `dependencies.md`
+were regenerated and reflect the new version.

.agents/skills/build-engineer/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "Build Engineer"
+  short_description: "Implement Chords Gradle, publishing, or version changes"
+  default_prompt: >
+    Use $build-engineer after reading AGENTS.md, README.md, and
+    .agents/project.md to implement a scoped Chords build or
+    release-plumbing change.

.agents/skills/ci-engineer/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: ci-engineer
+description: >
+  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.
+---
+
+# CI Engineering
+
+Use this skill for GitHub Actions workflow work under `.github/workflows/`.
+Publishing to Maven repositories happens automatically on `master`, but changes
+to the publishing pipeline and its credentials remain human-reviewed; this
+skill authors and reviews workflow definitions, it does not trigger them.
+
+## Scope
+
+- `.github/workflows/build-on-ubuntu.yml`: JDK 11 build on every push.
+- `.github/workflows/build-on-windows.yml`: Windows build on pull requests.
+- `.github/workflows/ensure-reports-updated.yml`: guard that `dependencies.md`
+  / `pom.xml` (or `version.gradle.kts`) changed in the PR, via
+  `config/scripts/ensure-reports-updated.sh`.
+- `.github/workflows/increment-guard.yml`: the `checkVersionIncrement` guard.
+- `.github/workflows/gradle-wrapper-validation.yml`: wrapper JAR integrity.
+- `.github/workflows/publish.yml`: publishing from `master`, including GPG
+  decryption of credentials from `.github/keys/`.
+- Workflow triggers, branch filters, job/step wiring, JDK setup, caching,
+  working directories, and secret references by name.
+
+For secret handling and supply-chain safety, also use
+`.agents/skills/security-reviewer/SKILL.md`. For the Gradle tasks the
+workflows invoke, use `.agents/skills/build-engineer/SKILL.md`.
+
+## Rules
+
+- Do not weaken the guards that gate merges: the version-increment check, the
+  license-report check, wrapper validation, and the build steps.
+- Preserve existing triggers, branch filters, JDK versions, and working
+  directories unless the task explicitly asks to change them. Note that the
+  repository checkout must initialize the `config` submodule where scripts
+  from it are used.
+- Reference secrets by name through `secrets.*`. Never inline secret values,
+  tokens, or credentials into a workflow.
+- Do not add steps that publish artifacts or rotate credentials as routine
+  changes. Describe the required human action instead.
+- Keep in mind the two-toolchain layout: root builds need JDK 11; any step
+  building `codegen/plugins` directly needs JDK 17 and runs from
+  `codegen/plugins/`.
+
+## Verification
+
+Workflows run in GitHub Actions, not locally. Verify changes by static review:
+
+- Confirm referenced Gradle tasks, module paths, scripts, and working
+  directories exist and match the owning `build.gradle.kts`, `config/scripts`,
+  and README files.
+- Confirm secret names, environment variables, branch filters, and job
+  dependencies match the intended trigger and the rest of the pipeline.
+- Confirm that jobs using scripts from the `config/` submodule configure
+  `actions/checkout` with submodule initialization.
+- Validate YAML structure and the versions of referenced actions.
+
+State clearly in the final response that full validation happens in CI.
+
+Follow the git-history and safety policy in `AGENTS.md`.

.agents/skills/ci-engineer/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "CI Engineer"
+  short_description: "Author or review Chords GitHub Actions workflows"
+  default_prompt: >
+    Use $ci-engineer after reading AGENTS.md and .agents/project.md to author
+    or review a scoped change to the GitHub Actions workflows of Chords.