jentic-api-scorecard

Improve OpenAPI documents for AI-readiness by fixing issues and enriching content based on Jentic API AI-Readiness Framework (JAIRF) scoring. Use when you need to raise an API's quality score, fix diagnostics, or add missing descriptions/summaries/examples — whether directly requested ('improve my API', 'fix OpenAPI issues', 'make my API more AI-ready') or as part of a broader workflow (post-audit remediation, pre-release quality gate, automated spec enhancement). Produces an improved spec and an OpenAPI Overlay (the reusable, non-breaking delta).

Review a pull request authored by someone other than the current GitHub user, applying the team's diplomatic review-comments tone. Use when the PR author's GitHub login differs from the current user's `gh api user` login. For own PRs, use the built-in /review directly. Detects authorship automatically and refuses on self-authored PRs.

Bootstrap the SDD constitution (specs/mission.md, specs/tech-stack.md, specs/roadmap.md) from current repository evidence. Refuses by default if any of the three files already exists — overwriting requires explicit confirmation via AskUserQuestion. Loads the constitution templates, runs parallel Explore subagents over the code trees that exist (e.g. `docker/`, `packages/`), `docs/`, and top-level config to ground claims in evidence, synthesizes findings, then issues a single grouped AskUserQuestion call (Mission / Tech Stack / Roadmap) before writing the three files. Edits files in place and stops — committing, branching, and opening a PR are user actions.

Distil per-spec retrospectives into specs/lessons.md so future spec authoring absorbs the learning. Reads specs/*/retrospective.md, groups recurring patterns, surfaces candidate lessons and tech-stack.md promotion candidates via AskUserQuestion, writes confirmed additions to specs/lessons.md, then invokes /review against the pending change before stopping.

Implement an existing feature spec end-to-end — pick an unprocessed feature spec (one whose `## Phase N — ...` heading in `specs/roadmap.md` does not yet carry the `✅` lifecycle marker), cut a feature branch, walk `plan.md` task groups in order with one primary atomic Conventional-Commits commit per group (plus optional small fix-up commits during verification or pre-push review), run `plan.md`'s Verify group plus every check in `validation.md`, then run a pre-push review pairing the built-in `/review` skill with three parallel deep-review subagents (spec-adherence, code-quality, risk-and-robustness) before pushing and opening the PR. The spec is read-only during implementation; if it is wrong or incomplete, the skill stops and surfaces the gap rather than patching the spec mid-flight. Reports implementation, review, and verification results at the end. When `$ARGUMENTS` is empty, enumerates unprocessed specs via AskUserQuestion.

Append a new active phase to specs/roadmap.md. Parses existing phases (active and ✅-completed) to compute the next stable phase number per the lifecycle rule, grounds the proposal against specs/mission.md and specs/tech-stack.md, groups structured questions (goal, dependencies, priority) via AskUserQuestion, then collects a freeform bullet list for the phase body. Edits specs/roadmap.md in place, then invokes the built-in /review skill against the pending change before stopping — committing, pushing, and opening a PR are left to the user. Does not create a feature spec; that is /sdd-new-spec's job.

Scaffold a feature spec for a roadmap phase and open it as a PR for human review. Reads specs/roadmap.md, lets the user pick a phase (or accepts one as argument), runs preflight checks, cuts a feature branch, writes specs/YYYY-MM-DD-<slug>/ (requirements.md, plan.md, validation.md — grounded in specs/mission.md and specs/tech-stack.md), commits, pushes, and opens a PR. Makes zero code changes — the PR is for review of the spec itself; implementation follows in a separate PR once the spec is approved. Groups clarifying questions (one per output file) via AskUserQuestion before any disk write.

Use the @jentic/api-scorecard-cli to score an OpenAPI document against the Jentic API AI Readiness Framework (JAIRF). Use this skill whenever the user wants to score, grade, lint, or assess the AI-readiness / agent-readiness / quality of an OpenAPI (Swagger) spec — by local file or URL — or asks how to run the jentic-api-scorecard CLI, wire it into CI, produce a JSON or HTML scorecard, enable LLM-backed analysis, or interpret its score, dimensions, signals, or exit codes.