grpc

gRPC — Protocol Buffers & Service Development

Activate When

• User invokes /godmode:grpc
• User says "build a gRPC service", "design proto"
• User says "add streaming", "bidirectional stream"
• User says "set up gRPC-web"
• Plan identifies gRPC or inter-service communication

Workflow

Step 1: Discovery & Context

# Detect existing proto files and tools
find . -name "*.proto" -not -path "*/node_modules/*" \
  2>/dev/null | head -20

# Check for buf configuration
ls buf.yaml buf.gen.yaml 2>/dev/null

# Check gRPC dependencies
grep -r "grpc\|tonic\|grpc-go\|grpcio" \
  go.mod Cargo.toml package.json pyproject.toml \
  2>/dev/null

GRPC DISCOVERY:
  Language: <Go|Rust|Java|Python|TypeScript>
  Framework: <tonic|grpc-go|grpc-java|grpc-node>
  Proto version: proto3
  Consumers: <internal|mobile|browser via gRPC-web>
  Patterns: <unary|server-stream|client-stream|bidi>

IF no buf.yaml: create one (not raw protoc)
IF no protos: scaffold from API requirements
IF browser clients: add gRPC-web or Connect

Step 2: Proto File Design

service <Entity>Service {
  rpc Get<Entity>(Get<Entity>Request)
    returns (<Entity>) {}
  rpc List<Entities>(List<Entities>Request)
    returns (List<Entities>Response) {}
  rpc Create<Entity>(Create<Entity>Request)
    returns (<Entity>) {}
  rpc Watch<Entities>(Watch<Entities>Request)
    returns (stream <Entity>Event) {}
}

PROTO RULES:
  1. proto3 syntax always
  2. Package = company.domain.v1
  3. Enum zero value = UNSPECIFIED
  4. Field numbers are permanent — never reuse
  5. FieldMask for partial updates
  6. Request/Response per RPC (never share)
  7. Idempotency key on create/update
  8. google.protobuf.Timestamp for time
  9. Reserve removed field numbers/names
  10. Keep messages < 100 fields

FILE LAYOUT:
  protos/<company>/<domain>/v1/
    <service>.proto, resources.proto,
    enums.proto, events.proto

Step 3: Code Generation Pipeline

# Lint protos
buf lint

# Check for breaking changes
buf breaking --against '.git#branch=main'

# Generate code
buf generate