write-protolisted

# Protobuf Writing Skill Proto definitions are the contract between gRPC producers and consumers: once published, they must evolve without breaking existing callers. Treat every field number and type as a durable commitment. **Before touching any proto file**, read it and all files it imports. Read `buf.yaml` and `buf.gen.yaml` — they control what gets generated and where. Read the corresponding generated Go file in `internal/handlers/protogen/` to see what callers currently depend on. --- ## Project Layout ``` internal/models/proto/ # Source .proto files (edit these) <entity>_<operation>.proto # One file per RPC — service + request/response messages <entity>.proto # Shared message/enum types (no service definition) internal/handlers/protogen/ # Generated Go stubs (never edit — always regenerated from scratch) <entity>_<operation>.pb.go # Message types <entity>_<operation>_grpc.pb.go # gRPC client/server interfaces ``` The entire `internal/handlers/protogen/` directory is **deleted and recreated** on every `pnpm generate:go` run. Never put hand-written code there. --- ## After Every Edit ``` pnpm format:proto # format .proto files + sync buf.lock pnpm lint:proto # validate against buf's STANDARD ruleset pnpm generate:go # wipe protogen/ and regenerate Go stubs + mocks pnpm format:go # goimports on the newly generated files pnpm lint:go # catch any issues in handler code using new types ``` **Every edit**