agentready-design-cli

Score a design system against the Agent-Ready Design rubric in one command.

Quick start

Deterministic + paste-into-agent (zero config)

npx agentready-design-cli ./path/to/your/design-system

Walks the repo, scores everything that can be scored without a model, and writes a paste-ready prompt for the rest:

✓ ./agent-ready-report.json
✓ ./agent-ready-report.md
✓ ./agent-ready-prompt.md      ← paste this into your agent

Tier 1 — Human-ready, AI-hostile  ·  floor 2/4  ·  retrieval 1/4  ·  median 2.0/4

Fully auto-scored (hosted API, no agent needed)

npx agentready-design-cli ./your-ds --remote

Same as above, but also calls the hosted scoring endpoint (Claude Haiku) to fill in the judgment-required rows. You don't need an API key — the endpoint is hosted by the project. Privacy notes below.

Flags

--format markdown|json|both   default both
--out <dir>                   default = target path
--target <name>               friendly name in the report header
--merge <existing.json>       only re-run pending criteria from a prior run
--remote                      auto-fill pending rows via the hosted scoring API
--api <url>                   override the API endpoint (default agentreadydesign.com)
--no-prompt                   skip writing agent-ready-prompt.md
--help

What gets scored

| | | |---|---| | Deterministic checks (no model needed) | tokens dir, DTCG format, AGENTS.md, llms.txt, component manifest, layout primitives, raw <button>/<input> in components, hex literals in component CSS, Storybook config, Chromatic/Percy, axe, semver, … | | Judgment-required (filled by --remote or paste-prompt) | prop-naming consistency, anti-pattern docs, composition rules, doc structure, hand-curation of AGENTS.md, drift detection, eval suite, trust levels, governance |

See CRITERIA.md for the full split.

Privacy — what --remote sends

When you pass --remote, the CLI sends a curated sample (up to ~60 KB) of your repo to https://agentreadydesign.com/api/score. Files included:

• package.json, README.md, tsconfig.json
• AGENTS.md, .builder/AGENTS.md, CLAUDE.md, .cursorrules, .windsurfrules, .clinerules
• llms.txt, llms-full.txt
• custom-elements.json, registry.json, Storybook main config
• Token files under tokens/, src/tokens/, packages/tokens/
• Up to 5 component files from each of components/, src/components/, packages/ui/src/
• Up to 3 files each from patterns/ and recipes/

Hard caps: ≤40 files, ≤4 KB per file, ≤60 KB total. Files matching .env*, *.key, *.pem, etc. are never matched by the included glob patterns.

The endpoint forwards your sample to Anthropic Claude Haiku for scoring and returns only the deltas. No content is logged or retained. Source: site/netlify/functions/score.ts.

If you'd rather not send anything: omit --remote. The default flow writes a paste-ready prompt locally and your AI tool reads your repo directly.

Programmatic use

import { runAssessment, renderMarkdown } from "agentready-design-cli";

const report = await runAssessment({ target: "./packages/ui" });
console.log(renderMarkdown(report));

License

MIT.