super-protobuf

Files (39)

• SKILL.md
• Makefile.example · assets/
• buf.gen.go-connect.yaml · assets/
• buf.gen.go.yaml · assets/
• buf.gen.java.yaml · assets/
• buf.gen.python.yaml · assets/
• buf.gen.ts.yaml · assets/
• buf.gen.yaml · assets/
• buf.lock · assets/
• buf.yaml · assets/
• book.proto · assets/proto/example/v1/
• book_service.proto · assets/proto/example/v1/
• README.md · references/
• buf-workflow.md · references/core/
• compatibility.md · references/core/
• design.md · references/core/
• evolution.md · references/core/
• migration.md · references/core/
• protoc-toolchain.md · references/core/
• protovalidate.md · references/core/
• quick-reference.md · references/core/
• research-synthesis.md · references/core/
• review-checklist.md · references/core/
• security.md · references/core/
• style.md · references/core/
• troubleshooting.md · references/core/
• design.md · references/modes/
• generate.md · references/modes/
• lint-breaking.md · references/modes/
• review-compat.md · references/modes/
• README.md · references/tech/
• connect-vs-grpc.md · references/tech/
• csharp.md · references/tech/
• elixir.md · references/tech/
• go.md · references/tech/
• README.md · templates/
• buf.yaml · templates/
• resource.proto · templates/
• service.proto · templates/

SKILL.md (first lines)

# Super protobuf

One router for proto3 schemas, the **buf** toolchain, Connect/gRPC services, and compatibility review. Language-agnostic core; language tracks are optional and short.

**Merged scope:** formerly `protobuf`. Index: [references/README.md](references/README.md). Research: [research-synthesis.md](references/core/research-synthesis.md).

## Principles

1. **Match the repo first.** Copy existing package layout, field order, validation, and comments. If none exist, use this skill's defaults.
2. **Buf is the default toolchain.** `buf format -w && buf lint`, then `buf breaking --against '.git#branch=main'` when the schema already shipped. EasyP is a buf-compatible alternative, not a second source of truth.
3. **Protovalidate on production fields.** The `.proto` file is the contract for structure and constraints.
4. **Evolve additively.** New fields, enum values, and RPCs stay in `v1`. Breaking changes get a new package version. Never reuse field or enum numbers.
5. **Treat gRPC as an API.** Authz on every method, including "internal" services that just became reachable. Do not leak `.proto` files or descriptors. Do not run or document attacks.

## Step 0: detect the job

Do this first; do not announce it. If the request already names a mode, go there.

| If the user is doing this | Mode | Load |
|---|---|---|
| New messages, RPCs, package layout, AIP-style resources | **design** | [modes/design.md](references/modes/design.md), [design.md](references/core/design.md) |
| `buf.yaml` / `buf.gen.yaml`, generate stubs, Connect vs gRPC | **generate** | [modes/generate.md](references/modes/generate.md), [buf-workflow.md](references/core/buf-workflow.md) |
| Review a proto diff, mixed-version deploys, wire vs JSON vs storage | **review-compat** | [modes/review-compat.md](references/modes/review-compat.md), [compatibility.md](references/core/compatibility.md) |
| `buf lint` / `buf breaking`, naming, EasyP as alternative | **lint-breaking** | [modes/lint-breaking.md](references/modes/lint-breaking.md), [style.md](references/core/style.md) |
| Auth on gRPC, reflection, grpc-web, leaked schemas | **harden** | [security.md](references/core/security.md) |
| Go plugins, opaque API | **language: Go** | [go.md](references/tech/go.md) |
| Elixir / protobuf-elixir | **language: Elixir** | [elixir.md](references/tech/elixir.md) |
| C# / grpc-dotnet | **language: C#** | [csharp.md](references/tech/csharp.md) |
| Connect vs gRPC choice | **rpc stack** | [connect-vs-grpc.md](references/tech/connect-vs-grpc.md) |

Stack index: [references/tech/README.md](references/tech/README.md). Depth: [evolution.md](references/core/evolution.md), [protovalidate.md](references/core/protovalidate.md), [review-checklist.md](references/core/review-checklist.md), [quick-reference.md](references/core/quick-reference.md), [troubleshooting.md](references/core/troubleshooting.md), [migration.md](references/core/migration.md), [protoc-toolchain.md](references/core/protoc-toolchain.md).

## Default pipeline

1. Detect the job (table above).
2. **Design** the messages and RPCs. Copy [templates/](templates/README.md) or [assets/proto/example/v1/](assets/proto/example/v1/).
3. **Generate** with the project's `buf.gen.yaml` (templates in [assets/](assets/)).
4. **Verify:** `buf format -w && buf lint`. If the schema shipped, `buf breaking --against '.git#branch=main'`.
5. **Review-compat** when consumers, storage, or mixed versions exist.

Check the Makefile or `package.json` first—many repos wrap these as `make lint` / `make generate`.

## Contribute

Keep this router lean. Do not paste language samples or extra checklists here.

- **Language track:** add `references/tech/<lang>.md` (one screen), one row in `references/tech/README.md`, and one row in the Step 0 table.
- **Template:** add a file under `templates/` or `assets/` and mention its basename in [templates/README.md](templates/README.md).
- **Core topic:** add `references/core/<topic>.md` and one table row here. Prefer extending an existing file.

## Old skill name

| Old | Use |
|---|---|
| `protobuf` | This skill (`super-protobuf`) |

## Related skills

- `super-elixir`: the service is Elixir.
- `super-nodejs`: the service is Node and uses Connect or gRPC.
- `super-architecture`: decide service boundaries before you design the schema.
- `verify`: show buf lint and breaking output before you claim compatibility.
- `create-bruno-collection`: add runnable gRPC examples as a Bruno collection.

## Done when

- The matching mode ran; only needed references were opened.
- `buf format -w && buf lint` (or the project's wrap) succeeded; breaking check ran when the schema already shipped.
- Production fields have protovalidate constraints; reserved numbers cover removals.
- gRPC exposure was treated as an API (authz, no schema leak) when that was in scope.

From pahlevikun/levistack, MIT.

More from pahlevikun/levistack