protobuf-design

# Protocol Buffers Design Skill

## When to Use This Skill

Use this skill when:

- **Designing gRPC services** - Protocol Buffers (proto3) for typed service contracts
- **Schema definition** - Messages, enums, services, streaming patterns
- **Implementing in C#** - gRPC with ASP.NET Core
- **Schema evolution** - Backward/forward compatibility, versioning

## MANDATORY: Documentation-First Approach

Before creating protobuf definitions:

1. **Invoke `docs-management` skill** for API contract patterns
2. **Verify proto3 syntax** via MCP servers (context7 for latest spec)
3. **Base all guidance on Google's Protocol Buffers documentation**

## Why Protocol Buffers?

| Benefit | Description |
|---------|-------------|
| **Efficient** | Binary format, 3-10x smaller than JSON |
| **Typed** | Strong typing with code generation |
| **Versioned** | Built-in backward/forward compatibility |
| **Cross-Language** | Supports C#, Java, Python, Go, etc. |
| **gRPC Integration** | Native service definition for gRPC |

## Proto3 Structure Overview

```protobuf
syntax = "proto3";

package ecommerce.orders.v1;

option csharp_namespace = "ECommerce.Orders.V1";

import "google/protobuf/timestamp.proto";

service OrderService {
  rpc GetOrder(GetOrderRequest) returns (Order);
  rpc ListOrders(ListOrdersRequest) returns (ListOrdersResponse);
  rpc WatchStatus(WatchRequest) returns (stream StatusUpdate);
}

enum OrderStatus {
  ORDER_STATUS_UNSPECIFIED = 0;
  ORDER_STATUS_DRAFT = 1;
  ORDER_STATUS_SUBMITTED = 2;
}

message Order {
  string id = 1;
  string customer_id = 2;
  OrderStatus status = 3;
  google.protobuf.Timestamp created_at = 4;
}
```

**For complete template**: See [proto-syntax.md](references/proto-syntax.md)

## Quick Reference

### gRPC RPC Types

| Pattern | Syntax | Use Case |
|---------|--------|----------|
| Unary | `rpc Get(Req) returns (Resp)` | Simple CRUD |
| Server Stream | `rpc List(Req) returns (stream Resp)` | Large results, updates |
| Client Stream | `rpc Upl