| name | codegen-engineer |
| description | 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.
|
Codegen Engineering
When to Use
Use this skill for code generation and Protobuf model work:
- ProtoData plugins under
codegen/plugins/ (a separate Gradle project).
- The codegen runtime under
codegen/runtime/ (Gradle path :runtime):
MessageField, MessageOneof, MessageDef, and related runtime types.
- Codegen correctness tests under
codegen/tests/ (Gradle path
:codegen-tests).
- Protobuf declarations and Kotlin extensions in
proto-values.
- The codegen wiring in the root build (
modulesWithChordsCodegen,
publishCodegenPluginsToMavenLocal, the io.spine.chords Gradle plugin
configuration).
For components that merely consume generated metadata, prefer
.agents/skills/component-engineer/SKILL.md. For build-only concerns, use
.agents/skills/build-engineer/SKILL.md.
Policy
codegen/plugins targets JDK 17, Gradle 9.4.x, and Kotlin 2.3.20; the rest
of the repository targets JDK 11, Gradle 6.9.4, and Kotlin 1.8.20. Never mix
the two toolchains in one command or assume APIs from one are available in
the other.- The generated-code contract is consumed by
proto and client and by
external projects: changes to MessageField/MessageOneof/MessageDef
shapes are public API changes on both the generator and runtime sides and
must stay in sync.
- For Protobuf schema changes in
proto-values: never delete or renumber
existing fields, reserve retired field numbers and names, and keep package
names consistent with the existing spine/chords/proto/value/** structure
under proto-values/src/main/proto/.
- Keep
codegen/plugins/src/main/resources/codegen-workspace resources
consistent with the build logic that copies buildSrc and wrapper files
into them; that workspace is what the Chords Gradle plugin unpacks in
consumer projects.
- Do not manually edit generated outputs (
generated/, _out/); change the
generator and regenerate instead.
- Cover generator behavior changes with tests in
codegen/tests, which
exercise generation end-to-end against test Protobuf definitions.
Verification
Codegen plugin changes (from codegen/plugins/, JDK 17):
./gradlew build
./gradlew publishToMavenLocal
Runtime and end-to-end verification (from the repository root, JDK 11):
./gradlew :runtime:test
./gradlew :codegen-tests:test
./gradlew :proto-values:test
./gradlew clean build
The root build republishes codegen plugins to Maven local automatically before
generating; a stale local plugin usually means the codegen/plugins build was
not rerun.
