agentready-design-cli 0.1.0

package/CRITERIA.md

@@ -0,0 +1,57 @@
+# What `agentready-design-cli` can and cannot score on its own
+
+The Agent-Ready Design rubric has 31 criteria. Some are deterministically checkable from the repo (file existence, package.json fields, AST/grep scans). Some require judgment — "is this `AGENTS.md` actually hand-curated?" — and the CLI marks those `status: "pending"` so an agent (or human) can complete the report.
+
+## Split
+
+| Criterion | Title (short) | Deterministic? | What the CLI checks |
+|---|---|---|---|
+| 1.1 | Tokens exist as exported, versioned source files | ✅ | Looks for `tokens/`, `*.tokens.json`, DTCG `$value`/`$type`, Style Dictionary config. |
+| 1.2 | Semantic tokens on top of primitives | ⏸ requires-agent | Naming taxonomy needs semantic interpretation. |
+| 1.3 | Tokens closed and enumerable | ⏸ requires-agent | Existence is detectable; "exhaustive, no hidden tokens" needs reading. |
+| 1.4 | Token usage enforced | 🟡 partial | Detects stylelint/eslint config + scans component CSS for hex literals. |
+| 2.1 | Machine-readable component manifest | ✅ | Checks `package.json#customElements`, `custom-elements.json`, Storybook/docgen output, TS-enumerated variants. |
+| 2.2 | Prop naming consistent | ⏸ requires-agent | Cross-component naming consistency needs a semantic pass. |
+| 2.3 | Composition rules explicit | ⏸ requires-agent | Compound-component rules live in prose/manifest semantics. |
+| 2.4 | Anti-patterns documented per component | ⏸ requires-agent | Counts of "Don't" examples per component require reading docs. |
+| 2.5 | A11y metadata travels with component | ⏸ requires-agent | Distinguishing structured field vs. prose needs reading. |
+| 3.1 | Single canonical docs site | ⏸ requires-agent | Detecting Confluence/Notion/Figma duplication needs external knowledge. |
+| 3.2 | Stable predictable doc structure | ⏸ requires-agent | Front-matter consistency check is doable but doc-engine-specific; deferred. |
+| 3.3 | ≥3 examples + anti-pattern per component | ⏸ requires-agent | Counting examples per component needs reading. |
+| 3.4 | `llms.txt` published | ✅ | Checks `/llms.txt`, `/llms-full.txt`, and common docs subdirs. |
+| 4.1 | Layout primitives exist | ✅ | Looks for `Stack`/`Inline`/`Grid`/`Box`/`Container`/`Flex` component files. |
+| 4.2 | Responsive conventions uniform | ⏸ requires-agent | Pattern uniformity needs cross-file comparison. |
+| 4.3 | Patterns/recipes layer | ✅ | Checks for `patterns/`, `recipes/`, `src/patterns`, `src/recipes`. |
+| 5.1 | `AGENTS.md` / `CLAUDE.md` hand-curated | 🟡 partial | Detects existence + flags suspiciously short or "auto-generated" content. "Hand-curated" semantics need an agent. |
+| 5.2 | MCP server or registry endpoint | 🟡 partial | Detects MCP-related deps, `.storybook/main.*` MCP addon, `registry.json`, `mcp-server/`. |
+| 5.3 | Always-on foundational rules | 🟡 partial | Detects `.cursorrules`, `.windsurfrules`, `.clinerules`, etc. Content quality needs an agent. |
+| 5.4 | Stable component identifiers | 🟡 partial | Checks `package.json#exports` map presence. |
+| 6.1 | Single install mechanism | ✅ | Looks for non-private npm name, `registry.json`, monorepo workspaces. |
+| 6.2 | Machine-readable deprecations | ⏸ requires-agent | Requires inspecting manifest contents for `deprecated: true`. |
+| 6.3 | Version pinning communicated | 🟡 partial | Checks semver in `package.json` + version mention in AGENTS.md. |
+| 7.1 | Stories / interaction tests | ✅ | Counts `*.stories.*` and `*.test.*` files, checks for `.storybook/`. |
+| 7.2 | Visual regression | ✅ | Detects Chromatic, Percy, Loki, Lost Pixel, Playwright in deps. |
+| 7.3 | A11y automation | ✅ | Detects axe-core, jest-axe, `@storybook/addon-a11y`. |
+| 7.4 | Internal consistency | ✅ | Scans component sources for raw `<button>/<input>` and component CSS for hex literals. |
+| 8.1 | Eval suite | 🟡 partial | Detects `evals/` directory; quality assessment requires an agent. |
+| 8.2 | Trust levels defined | ⏸ requires-agent | Policy lives in AGENTS.md prose + CI config. |
+| 8.3 | Drift detection | ⏸ requires-agent | Requires inspecting CI workflows. |
+| 8.4 | Agent-PR attribution | ⏸ requires-agent | Requires inspecting `CODEOWNERS`, `labeler.yml`, branch protections. |
+
+Legend:
+
+- ✅ **Deterministic.** The CLI scores 0–4 directly.
+- 🟡 **Partial.** The CLI assigns a starting score (often 0–2) based on detectable signals; an agent should raise (or lower) it.
+- ⏸ **Requires agent.** The CLI emits `status: "pending", pending: "requires-agent"`. Report stays complete; downstream prompt/skill fills it in.
+
+## How to extend
+
+Each check is a function `(ctx: CheckContext) => Promise<CheckResult>` in `src/checks/category-N-*.ts`. To add or upgrade a check:
+
+1. Open the relevant `category-N-*.ts` file.
+2. Implement or improve the check. Use `ctx.glob`, `ctx.readFile`, `ctx.exists` — they are cached.
+3. Return `{ score, rationale, evidence, suggestion }`. If you can't decide, return `{ score: null, status: "pending", pending: "requires-agent", rationale: ... }`.
+4. Update the table above.
+5. Add a test under `test/`.
+
+When in doubt, prefer `pending` over a confident wrong number. The whole point of this rubric is to expose imbalances, not paper over them.

package/README.md

@@ -0,0 +1,51 @@
+# agentready-design-cli
+
+Deterministic checks for the [Agent-Ready Design rubric](https://github.com/hgillispie/Agent-Ready-Design). Walks a design-system repo and scores everything that can be scored without an LLM. Emits Markdown + JSON in the [shared report format](../../schema/).
+
+## Usage
+
+```bash
+npx agentready-design-cli ./path/to/your/design-system
+```
+
+Writes `agent-ready-report.md` and `agent-ready-report.json` next to the target. Anything that requires judgment is emitted as `status: "pending"` — the report stays complete.
+
+### 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
+--help
+```
+
+### Output
+
+A Markdown heatmap with a `0`–`4` cell per criterion (and `?` for pending), and a JSON file conforming to [`schema/report.schema.json`](../../schema/report.schema.json).
+
+```
+Tier 1 — Human-ready, AI-hostile  ·  floor 2/4  ·  retrieval 1/4  ·  median 2.0/4
+12 criteria require an agent. Paste prompts/self-assessment.md to complete the report.
+```
+
+## What it checks
+
+Roughly half the rubric is deterministically checkable; the rest is `pending: requires-agent`. See [`CRITERIA.md`](./CRITERIA.md) for the full split.
+
+## Programmatic use
+
+```ts
+import { runAssessment, renderMarkdown } from "agentready-design-cli";
+
+const report = await runAssessment({ target: "./packages/ui" });
+console.log(renderMarkdown(report));
+```
+
+## Pair it with the prompt
+
+After running the CLI, paste [`prompts/self-assessment.md`](https://github.com/hgillispie/Agent-Ready-Design/blob/main/prompts/self-assessment.md) into your agent. It will detect `agent-ready-report.json` at the repo root and fill in only the `pending` rows, marking `producer.kind: "merged"` in the output.
+
+## License
+
+MIT.