x-review-grpc
Validates gRPC service definitions, proto3 conventions, implementation patterns, and operational readiness.
- License 许可
- MIT
- 最近更新
- 2026-10-27
- Stars
- ★ 0
- Forks
- 1
01 前言 Front Matter
- name
- x-review-grpc
- description
- Validates gRPC service definitions, proto3 conventions, implementation patterns, and operational readiness.
- allowed-tools
- Read, Grep, Glob, Bash
- argument-hint
- [service-name or proto-file]
- user-invocable
- true
- requires-capabilities
- []
02 资源文件 1
- 参考文档README.md1.3 KB
03 SKILL.md 正文
Global Output Policy
- Language: English ONLY.
- Tone: Technical, Direct, and Concise.
- Efficiency: Remove all conversational fillers and greetings to save tokens.
Skill: gRPC Service Review
Purpose
Review gRPC service definitions, implementation patterns, and operational readiness for compliance with proto3 conventions, error handling standards, and observability requirements.
Activation Condition
Include this skill when the project uses gRPC protocol (interfaces contains type: grpc).
Triggers
/x-review-grpc TransactionService-- review a specific service/x-review-grpc proto/transaction.proto-- review a specific proto file/x-review-grpc-- review all gRPC services and proto files
Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
target |
String | No | (all) | Service name or proto file path |
Knowledge Pack References
| Pack | Files | Purpose |
|---|---|---|
| protocols | skills/protocols/references/grpc-conventions.md |
Proto3 style guide, naming, streaming patterns, error codes, health checks |
Prerequisites
- Proto files (
*.proto) exist in the codebase - gRPC framework dependency is configured
- gRPC code generation plugin is configured in build tool
Workflow
Step 1 — Discover Proto Files
Scan for *.proto in project:
- List all proto files with their package declarations
- Identify service definitions and message types
Step 2 — Discover Service Implementations
Scan for classes implementing generated stubs:
- Identify server-side service implementations
- Identify client-side stub usage
Step 3 — Validate Proto File Conventions
Check each proto file:
- Package naming follows reverse domain with version suffix
- Service, message, and field naming conventions
- Enum design with UNSPECIFIED=0
- Versioning and compatibility rules
Step 4 — Validate Implementation Patterns
Check server and client code:
- Deadline/timeout propagation
- Error model usage
- Health checks and graceful shutdown
- Interceptor usage for cross-cutting concerns
Step 5 — Validate Operational Readiness
Check observability:
- OpenTelemetry trace propagation
- Metrics per method
- Structured logging
- Sensitive data exclusion
Step 6 — Generate Report
Summarize findings as checklist:
- List compliant items
- List violations with file paths and line numbers
- Suggest fixes for each violation
Proto3 Style Checklist (12 points)
Package & Naming (1-4)
- Package follows reverse domain convention with version suffix (
com.company.service.v1) - Service names are PascalCase and end with
Service(TransactionService) - Message names are PascalCase (
CreateTransactionRequest,TransactionResponse) - Field names are snake_case (
transaction_id,created_at)
Message Design (5-10)
- Every enum has
UNSPECIFIED = 0as first value (proto3 default value safety) - Request/Response messages are method-specific (no generic
Requestreuse) oneofused for mutually exclusive fields (not separate booleans)repeatedfields have bounded size expectations documented in commentsgoogle.protobuf.Timestampused for datetime (not string or int64)google.protobuf.FieldMaskused for partial updates
Versioning & Compatibility (11-12)
- Breaking changes go in new package version (
v1->v2), never modify existing - Deprecated fields use
reservedstatement (field number AND name)
Implementation Checklist (12 points)
Server-Side (13-18)
- Deadline/timeout propagation: server reads deadline from context, propagates to downstream calls
- Error model uses
google.rpc.Statuswith details (not plainStatusRuntimeExceptionwithout context) - Server reflection enabled for development/staging (disabled in production if security requires)
- Health check protocol implemented (
grpc.health.v1.Health) - Graceful shutdown drains in-flight RPCs before terminating
- Interceptors used for cross-cutting concerns (auth, logging, tracing, metrics)
Client-Side (19-22)
- Deadlines always set on client calls (never unlimited timeout)
- Retry policy configured with exponential backoff
- Channel management: reuse channels, don't create per-call
- Client-side load balancing configured (round-robin or pick-first)
Streaming (23-24)
- Server streaming: flow control implemented (backpressure)
- Bidirectional streaming: error handling covers both directions independently
Observability Checklist (4 points)
- gRPC interceptor for OpenTelemetry trace propagation (W3C context)
- Metrics:
grpc.server.duration,grpc.server.request.count,grpc.server.response.countper method - Structured logging includes: method name, status code, duration, trace_id
- No sensitive data in metadata, logs, or traces
Output Format
## gRPC Review — [Service/Change Description]
### Proto Compliance: HIGH / MEDIUM / LOW
### Implementation Quality: HIGH / MEDIUM / LOW
### Proto Findings
1. [Finding with file, line, issue, fix]
### Implementation Findings
1. [Finding with file, line, issue, fix]
### Breaking Changes
- [Any backward-incompatible changes identified]
### Checklist Results
[Items that passed / failed / not applicable]
### Verdict: APPROVE / REQUEST CHANGES
Error Handling
| Scenario | Action |
|---|---|
| No proto files found | Report INFO: no gRPC definitions discovered |
| Enum missing UNSPECIFIED=0 | REQUEST CHANGES with proto3 convention reference |
| Breaking change in existing version | REQUEST CHANGES with versioning guidance |
Rules
- REQUEST CHANGES if enum missing UNSPECIFIED=0
- REQUEST CHANGES if breaking change in existing proto version
- REQUEST CHANGES if no deadline set on client calls
- REQUEST CHANGES if sensitive data in metadata or logs
- Verify all new proto messages have field documentation comments
04 同仓库更多 Skills
x-parallel-eval
Detects and classifies file-collision risks between work units (tasks, stories, or epic phases) before parallel execution. Reads ## File Footprint blocks produced by x-task-plan / x-story-plan, applies the parallelism-heuristics knowledge pack (hard / regen / soft categories + hotspot overrides), and emits a collision matrix + serialization recommendation in Markdown (default) or JSON.
parallelism-heuristics
Canonical catalog of file-collision heuristics for parallel task, story, and epic execution. Defines the File Footprint block format, the three Conflict Categories (hard / regen / soft), a hotspot list of high-contention paths, and the degrade-with-warning policy. Consumed by x-task-plan, x-story-plan, x-epic-map, x-parallel-eval, and x-dev-*-implement.
x-watch-pr-ci
Polls a PR's CI checks and Copilot review status, blocking until checks complete or timeout. Returns one of 8 stable exit codes (SUCCESS=0, CI_PENDING_PROCEED=10, CI_FAILED=20, TIMEOUT=30, PR_ALREADY_MERGED=40, NO_CI_CONFIGURED=50, PR_CLOSED=60, PR_NOT_FOUND=70). Writes a versioned state-file for session resume.
x-validate-docs
Documentation freshness gate: validates 6 dimensions (readme, api-specs, grpc-proto, adr, skill-docs, system-architecture) against code changes in a PR. Stack-aware — only validates targets declared/auto-detected from ProjectConfig.documentation.targets. Returns exit non-zero on staleness; produces structured report.
x-update-system-architecture
Incrementally updates docs/architecture/system.md after an epic completes. Appends new entries to the Decision Log (§11) using x-internal-write-report --append (dedup by ## ID: marker) and surgically inserts component/integration changes into sections 1-10 via Edit. Idempotent: re-running with the same epic produces a byte-identical system.md.
x-update-architecture
Incrementally updates the service architecture document with changes from architecture plans. Adds new components, integrations, flows, and ADR references without rewriting existing content. Use after implementation to keep architecture documentation current.