proto-change
This skill records repository policy for Claude. Use repoctl as the authority for graph,
ownership, affected analysis, task routing, and final hand-off verification, but keep repoctl out of
the inner coding loop unless the graph or boundaries are changing.
When this fires
- The user changes
.proto files, generated clients, API contracts, event schemas, or service
package ownership.
- A generated file appears in the diff and it is unclear whether it should be regenerated or left
untouched.
- A PR may break consumers of a foundation service or cross-language client.
Source of truth
The source contract lives under protos/ unless a project.yaml explicitly declares another proto
source root. Generated code is consumer-local output and should not be edited to change behavior.
Workflow
Find owners and consumers:
repoctl proto owners <package-or-path>
repoctl proto consumers <package-or-path>
If ownership is missing, update the owning project manifest before changing the contract.
Read the package context:
- package name and versioning convention,
- service and message consumers,
- generated language targets,
- backwards-compatibility rules in the owning project docs.
Edit source only:
Change protos/** or the manifest-declared source root. Do not patch generated/, gen/,
checked-in language clients, or build output as a substitute for changing the contract.
Preserve compatibility unless the user explicitly requests a breaking change:
- Add fields instead of renaming or reusing numbers.
- Reserve removed field numbers and names.
- Keep package names stable.
- Check JSON names and language-specific reserved words when adding public fields.
Run proto verification once at hand-off:
repoctl proto check --base origin/main --head HEAD
repoctl affected --base origin/main --head HEAD --tasks check,test
Run repoctl proto check at hand-off and run affected analysis once to select consumer
verification. Do not recompute affected after source-only proto fixes. If the repo has a
declared generation task, run it through repoctl run for affected consumers.
Review checklist
- Owner and consumer lists are included in the PR summary.
- Breaking changes are explicit, justified, and routed to consumers.
- Generated output is either absent from the diff or produced by the repo's generation task.
- Affected app/framework/foundation tasks cover every consumer repoctl reports.
Hand-off
State the package changed, owners, consumers, compatibility impact, generation status, and commands
run. If a consumer cannot be tested locally, name it as a residual risk.
1---2name: proto-change-23description: Change source proto contracts through owners and never edit generated code directly.4---56# proto-change78This skill records repository policy for Claude. Use repoctl as the authority for graph,9ownership, affected analysis, task routing, and final hand-off verification, but keep repoctl out of10the inner coding loop unless the graph or boundaries are changing.1112## When this fires1314- The user changes `.proto` files, generated clients, API contracts, event schemas, or service15 package ownership.16- A generated file appears in the diff and it is unclear whether it should be regenerated or left17 untouched.18- A PR may break consumers of a foundation service or cross-language client.1920## Source of truth2122The source contract lives under `protos/` unless a `project.yaml` explicitly declares another proto23source root. Generated code is consumer-local output and should not be edited to change behavior.2425## Workflow26271. **Find owners and consumers**:2829 ```bash30 repoctl proto owners <package-or-path>31 repoctl proto consumers <package-or-path>32 ```3334 If ownership is missing, update the owning project manifest before changing the contract.35362. **Read the package context**:3738 - package name and versioning convention,39 - service and message consumers,40 - generated language targets,41 - backwards-compatibility rules in the owning project docs.42433. **Edit source only**:4445 Change `protos/**` or the manifest-declared source root. Do not patch `generated/`, `gen/`,46 checked-in language clients, or build output as a substitute for changing the contract.47484. **Preserve compatibility unless the user explicitly requests a breaking change**:4950 - Add fields instead of renaming or reusing numbers.51 - Reserve removed field numbers and names.52 - Keep package names stable.53 - Check JSON names and language-specific reserved words when adding public fields.54555. **Run proto verification once at hand-off**:5657 ```bash58 repoctl proto check --base origin/main --head HEAD59 repoctl affected --base origin/main --head HEAD --tasks check,test60 ```6162 Run `repoctl proto check` at hand-off and run affected analysis once to select consumer63 verification. Do not recompute affected after source-only proto fixes. If the repo has a64 declared generation task, run it through `repoctl run` for affected consumers.6566## Review checklist6768- Owner and consumer lists are included in the PR summary.69- Breaking changes are explicit, justified, and routed to consumers.70- Generated output is either absent from the diff or produced by the repo's generation task.71- Affected app/framework/foundation tasks cover every consumer repoctl reports.7273## Hand-off7475State the package changed, owners, consumers, compatibility impact, generation status, and commands76run. If a consumer cannot be tested locally, name it as a residual risk.77
tyrchen