| 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
