api-guideline-reviewer

API Guideline Review

Review OpenAPI specification files for compliance with REST API and IAM permission-naming guidelines.

The review runs in three passes. Pass 0 is a deterministic Spectral lint; Passes 1 and 2 are the LLM review, scoped to what a linter cannot express. Pass 0 is best-effort: with no Spectral CLI on the machine the run proceeds exactly as it did before Spectral existed, and says so.

Before Starting

Load every guideline file listed below before reviewing — never skip one of these. All paths relative to ${CLAUDE_PLUGIN_ROOT}:

REST API Guidelines (references/api-guidelines/rest-api-guidelines/):

• Introduction.md — RFC 2119 keywords (MUST/SHOULD/MAY)
• General Structure.md — API types, URL mapping
• OpenAPI.md — Required template elements, version consistency
• API Versioning.md — Semantic versioning, deprecation
• Authentication.md — OAuth2 client credentials only
• Standard Methods.md — CRUD operations, HTTP methods
• Custom Methods.md — Custom method definitions
• Conventions.md — Naming conventions, HTTP response codes
• Common Datatypes.md — Field naming for timestamps, timezones, etc.
• Common Schemas.md — Error envelopes, modification info
• Design Patterns.md — Pagination, filtering, bulk operations
• Filtering And Sorting.md — Query parameters
• Swagger Documentation.md — Documentation completeness, mandatory error responses

Permission Guidelines (references/api-guidelines/permission-guidelines/):

• Introduction.md — IAM permission format {service}:{resource}:{action}
• General Mapping.md — URL-to-IAM mapping rules

Template: references/api-guidelines/template/openapi-template.yaml Spectral ruleset: references/api-guidelines/spectral/ruleset.yaml

Review Workflow

Pass 0: Deterministic lint (Spectral)

Run this before Pass 1. It is the only pass that produces machine-checked findings, and its findings are authoritative for the rules it covers.

1 — Resolve a CLI. Try each in order and stop at the first that exits 0: