api-guideline-reviewer

Review OpenAPI specification files for compliance with REST API and IAM permission-naming guidelines: $ARGUMENTS

--rules <path> (optional) — an organization's own API rule directory, layered over the bundled baseline. Set it aside from $ARGUMENTS before resolving the spec files, and pass it to the agent as rules_path. Absent, the agent resolves an overlay itself from <repo-root>/.dev-workflows/api-guidelines/ then $API_GUIDELINES_PATH, falling back to the bundled baseline — silently where a candidate is absent or unreadable, and with a rules_overlay_skipped: line naming any candidate that is a readable directory holding no .md file of its own, since an overlay is flat and one whose rules sit in subdirectories would otherwise be lost without a word. The executable half has its own precedence: a repo's own Spectral ruleset — .spectral.yaml, .spectral.yml or .spectral.json — wins over the bundled one, which organizations are expected to extend rather than edit.

If $ARGUMENTS is empty, ask the user which OpenAPI spec file(s) to review.

Dispatch the review to the api-guideline-reviewer subagent:

→ Agent (subagent_type: "guideline-reviewers:api-guideline-reviewer"):

"Review the following OpenAPI spec file(s) against the guidelines: $ARGUMENTS"

Surface the subagent's verdict to the user.

Deterministic lint

Before its LLM review passes, the subagent runs a Spectral lint of the spec files — once per directory it lints from, the nearest one holding their Spectral ruleset or a package.json declaring the CLI, or else their repository's top level — for specs in no repository, their own directory — each run over the specs that share it — against the ruleset bundled with this plugin at references/api-guidelines/spectral/ruleset.yaml — forty rules that make the machine-checkable half of the guidelines executable, on top of spectral:oas (recommended). Where a .spectral.yaml, .spectral.yml or .spectral.json sits at or above the spec — the nearest one, up to its repository's top level, or, for a spec in no repository, one in the spec's own directory, where the search stops — that file is used instead, passed to Spectral by its absolute path, on the assumption that an organization extends the bundled ruleset rather than editing it in place.

Two things follow, and both belong to the subagent — this command neither runs the linter nor post-processes its output:

• A missing Spectral CLI is not a failure. The subagent probes spectral on PATH, then npx --no-install @stoplight/spectral-cli. If neither answers from a directory, its lint is skipped silently, the review of its specs proceeds exactly as it does without it, and the skip is recorded as lint_source: none in the verdict. Nothing is installed, nothing is prompted, and the run never fails on the linter's absence.
• Findings are merged, not duplicated. Spectral's findings are authoritative for the rules it covers; the LLM passes cover what Spectral cannot express — cross-field version agreement, allOf property redefinition, error-envelope conformance, semantic naming quality, resource modelling and documentation adequacy, and whether an IAM scope is correct rather than merely well-formed.

Surface the lint_source line — one per lint directory where the specs span more than one — with the rest of the verdict, so the reader can tell which half of the review was machine-checked.