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.

Where it runs. Partition the spec files by their lint directory, and run steps 1–4 once per partition, in that directory. A spec's lint directory is the nearest directory at or above it, up to its repository's git top level (git -C "<the spec's directory>" rev-parse --show-toplevel), that holds a Spectral ruleset of its own — .spectral.yaml, .spectral.yml or .spectral.json — or a package.json that declares @stoplight/spectral-cli. A spec with no such ancestor belongs to its repository's top-level partition, linted from the top level itself; a spec in no repository has no top level to bound the walk, so the walk stops at the spec's own directory, and the spec is linted from there, with any other spec in that directory. A monorepo package that keeps its own ruleset or its own Spectral CLI is linted from that package, specs from two such packages are each linted from their own package, and a repository that keeps them at its top level from there, as it is when you are started in it. Your Bash tool starts every call in the session's directory, which need not be the spec's repository, and a cd does not persist between calls — while npx --no-install resolves the CLI from the directory it runs in, and from any other finds none, or the wrong one — so run each probe and each lint below as one subshell, (builtin cd "<the partition's directory>" >/dev/null && …), inside a single Bash call, naming the partition's specs by absolute path — builtin cd, its output discarded, since your Bash tool's shell carries the user's shell functions and aliases, and a cd of theirs would otherwise run in its place and could print into what you read. Merge what the partitions report into one set of findings, each keyed by its spec file.