use-buf

name	use-buf
description	Configure, inspect, update, validate, and troubleshoot Buf workspaces and modules. Use when working with buf.yaml, buf.lock, buf.gen.yaml or domain-specific Buf generation templates; managing BSR dependencies; formatting, linting, generating, detecting breaking Protobuf changes; locating dependency schemas; or diagnosing missing types and generation failures.

Use Buf

Use the Buf CLI as the source of truth for Protobuf compilation, dependency resolution, linting, breaking-change detection, and code generation.

Inspect Before Changing

1. Read repository instructions.
2. Search the repository root and likely API directories for buf.yaml, buf.lock, buf.gen.yaml, and buf.gen.<domain>.yaml files.
3. Inspect the configuration version, module paths, dependency declarations, lint policy, breaking policy, inputs, plugin pins, output paths, and existing generation scripts.
4. Run buf --version and check repository/CI tool pins before using features from a newer configuration schema.
5. Diagnose configuration or dependency problems before changing .proto files to work around them.

Use one default buf.gen.yaml. Introduce buf.gen.<domain>.yaml only when generation products genuinely require isolated plugin sets, inputs, or outputs. Pass non-default templates explicitly with buf generate --template <file>.

Keep Configuration Responsibilities Clear

• Use buf.yaml for workspaces/modules, BSR dependencies, lint rules, breaking rules, policies, and Buf check plugins.
• Use buf.gen.yaml or buf.gen.<domain>.yaml for protoc-gen-* code-generation plugins, inputs, output directories, options, and managed mode.
• Use buf.lock as generated dependency resolution state. Do not edit it manually.
• Keep configuration in the repository root or the established API workspace directory unless repository structure requires otherwise.

Read references/configuration.md before adding modules, dependencies, check plugins, generation templates, or output paths.

Manage Dependencies Deliberately

• Prefer BSR modules for maintained dependencies, including Google APIs, well-known types, Protovalidate, and grpc-gateway annotations.
• Add or remove dependencies in buf.yaml, then run buf dep update and inspect the buf.lock diff.
• Use buf dep graph --format json to identify the resolved dependency chain.
• Use buf dep prune only after confirming an import is genuinely unused.
• When a type appears missing, inspect configuration and the lockfile, run buf dep update, then run buf build or buf generate to obtain the compiler's concrete import/type error.
• Never hardcode an operating system's Buf cache location. Export the pinned module with buf export when source inspection is required.

Required Validation

After changing first-party Protobuf or Buf configuration, MUST run:

buf lint
buf generate
buf breaking --against '.git#branch=main'

Also run buf format --diff or the repository's format check and all language-specific tests/type checks for generated outputs.

Do not skip the breaking check merely because a break is intentional. Run it, capture the violations, and report that the change is an approved experimental/unreleased break. If the repository does not have a main branch, report that exact baseline failure and resolve the intended integration baseline rather than silently omitting compatibility validation.

Diagnose in Dependency Order

1. Confirm the current directory and discovered buf.yaml.
2. Confirm module paths and import paths.
3. Confirm dependencies and buf.lock with buf dep graph.
4. Compile with buf build.
5. Lint with buf lint.
6. Generate with the selected template.
7. Inspect plugin stderr, output collisions, and generated diffs.
8. Run the breaking check against main.

Use $use-buf-plugins for remote/local plugin selection, offline generation, rate limits, or plugin wrappers. Read references/commands-and-troubleshooting.md for precise inspection commands and failure handling.