axone-proto-specification - SKILL.md Agent Skill

name: axone-proto-specification description: Design and evolve protobuf APIs for this repository. Use when creating or changing files under proto/, or when shaping the Go implementation that follows from a proto contract. Focuses on API specification first, with repo-specific conventions plus Cosmos SDK, gRPC, and protobuf compatibility rules. compatibility: Requires go, make, docker, and local access to the repository. Read reference files in this skill when changing wire-visible schemas.

Axone Proto Specification

Use this skill when changing protobuf schemas or designing module APIs that will be expressed in proto/.

This skill is about specification first. In this repo, the .proto contract is the source of truth; generated code, gateway routes, docs, and most implementation structure follow from it.

Read order

Read repo conventions.
Read external guidance if the change affects fields, service shape, compatibility, or error semantics.
Then design the schema before editing code.

Design rules

Start from the domain model and invariants, not from the current keeper or handler code.
Treat every field number, field name, service name, and HTTP path as part of a long-lived public contract.
Preserve the local convention of the touched module unless you are intentionally migrating the whole module. Do not normalize logic and mint styles accidentally.
Prefer small, explicit RPCs with dedicated request and response messages.
Use Cosmos-specific annotations only when they express real semantics such as signer identity, safe queries, or scalar meaning.
Design pagination, field presence, and reserved slots deliberately. Do not leave them to later cleanup.
Write comments as part of the spec, not as afterthoughts. In this repo, comments are linted and flow into generated docs.

What to change first

Edit proto/<module>/<version>/*.proto
Keep module docs aligned through proto/<module>/docs.yaml when the user-facing description changes
Let generation produce Go code and markdown docs
Then adapt the Go implementation to the contract rather than mutating the contract to match incidental implementation details

Compatibility rules

Never reuse a field number.
When removing a field, reserve both its number and name.
Do not change wire-visible meaning casually: type, cardinality, field meaning, enum behavior, and path semantics all matter.
If a field needs presence semantics, decide that explicitly before choosing the representation.
If an RPC is side-effect free, keep it query-shaped and mark it accordingly.
If an RPC mutates state or is authority-gated, express signer and authority semantics explicitly in the schema.

Validation

Run make proto
If you changed Go implementation too, run make lint-go and make test-go
Inspect generated diffs instead of trusting generation blindly

Output expectation

When using this skill, the agent should be able to explain:

why the schema shape fits the module domain
why the chosen field numbers and names are safe to evolve
why the annotations and HTTP mapping match Cosmos and gRPC semantics
what generated and implementation files must change downstream