adsa-cli 0.1.0

package/lib/score.mjs

@@ -0,0 +1,197 @@
+/**
+ * Turns facts into a score. Every dimension returns the evidence it used, so the
+ * number is arguable: a maintainer who disagrees can point at the line that produced it.
+ */
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+
+const here = dirname(fileURLToPath(import.meta.url));
+export const RUBRIC = JSON.parse(readFileSync(join(here, "..", "rubric", "rubric.json"), "utf8"));
+
+const pct = (n) => `${Math.round(n * 100)}%`;
+
+/** What "accessibility documentation" means in the vocabulary of each platform. */
+const A11Y_LABEL = {
+    web: "keyboard or accessibility",
+    "react-native": "VoiceOver/TalkBack or accessibility",
+    swift: "VoiceOver/Dynamic Type",
+    android: "TalkBack/content description",
+};
+
+const SCORERS = {
+    "agent-instructions"(f) {
+        const files = f.agentFiles.filter((a) => a.lines > 3);
+        const main = files.find((a) => a.mentionsPackage) || files[0];
+        if (!main) return { score: 1, evidence: ["No AGENTS.md, CLAUDE.md or equivalent in the repository."] };
+        const ev = [`${main.file}, ${main.lines} lines.`];
+        if (!main.mentionsPackage) {
+            ev.push(`It never mentions ${f.name}, so an agent gets no design-system rules from it.`);
+            return { score: 1, evidence: ev };
+        }
+        const parts = [
+            ["an import rule", main.hasImportRule],
+            ["a lookup command", main.hasLookupCommand],
+            ["token rules", main.hasTokenRule],
+            ["a list of what is forbidden", main.hasForbidden],
+            ["a check to run before finishing", main.hasFinishCheck],
+        ];
+        const present = parts.filter(([, ok]) => ok).map(([label]) => label);
+        const absent = parts.filter(([, ok]) => !ok).map(([label]) => label);
+        ev.push(`Contains ${present.join(", ") || "none of the expected rules"}.`);
+        if (absent.length) ev.push(`Missing ${absent.join(", ")}.`);
+        return { score: absent.length === 0 ? 5 : present.length >= 2 ? 3 : 1, evidence: ev };
+    },
+
+    "machine-surface"(f) {
+        const m = f.machine;
+        const ev = [];
+        if (m.mcpInPackage) ev.push(`An MCP server ships inside the package (bin: ${m.binNames.join(", ")}).`);
+        if (m.declaredServers.length) ev.push(`${m.mcpConfigs.join(", ")} registers ${m.declaredServers.join(", ")}.`);
+        if (m.cliShipped && !m.mcpInPackage) ev.push(`A CLI ships with the package (bin: ${m.binNames.join(", ")}).`);
+        if (m.llmsTxt.length) ev.push(`${m.llmsTxt.join(", ")} present.`);
+        if (m.skills.length) ev.push(`${m.skills.length} agent skill${m.skills.length === 1 ? "" : "s"} published.`);
+        if (m.storybookMcp) ev.push("@storybook/addon-mcp is installed, which answers from a running Storybook in this repo only.");
+        if (!ev.length) ev.push("No MCP server, no docs CLI, no llms.txt, no published skills: an agent has to read files.");
+        const score = m.mcpInPackage || m.declaredServers.length ? 5 : m.cliShipped || m.llmsTxt.length || m.skills.length || m.storybookMcp ? 3 : 1;
+        return { score, evidence: ev };
+    },
+
+    "docs-coverage"(f) {
+        const c = f.coverage;
+        if (!c.total) return { score: 1, evidence: ["No importable components detected — check `source` in adsa.config.json."] };
+        const gate = f.verification.docChecks || f.verification.scoreGate;
+        const ev = [`${c.documented} of ${c.total} importable components have a guide (${pct(c.ratio)}).`];
+        if (f.icons) ev.push(`${f.icons} icon or logo exports were set aside; nobody writes a guide per icon.`);
+        if (c.missing.length) ev.push(`Undocumented, first few: ${c.missing.slice(0, 8).join(", ")}.`);
+        ev.push(gate ? "CI runs a documentation check." : "Nothing in CI stops a new export from shipping without a guide.");
+        const score = c.ratio >= 0.9 && gate ? 5 : c.ratio >= 0.7 ? 3 : 1;
+        return { score, evidence: ev };
+    },
+
+    "docs-freshness"(f) {
+        const s = f.freshness;
+        const ev = [`${f.guides.length} guides, ${s.blocks} code blocks, ${s.guidesWithPropTable} with a prop table.`];
+        if (s.guidesGenerated) ev.push(`${s.guidesGenerated} guides carry a generated marker.`);
+        else ev.push("No guide is marked as generated, so every table is hand-maintained.");
+        if (s.unknownCount) ev.push(`${s.unknownCount} imports in the guides name symbols this repo does not export, e.g. ${s.unknownImports.slice(0, 3).map((u) => `${u.name} in ${u.guide}`).join("; ")}.`);
+        else ev.push("Every symbol imported in the guides exists in the source.");
+        ev.push(s.compiledInCi ? "CI checks the guides against the code." : "Nothing compares the guides to the code.");
+        let score = s.compiledInCi && s.guidesGenerated ? 5 : s.guidesGenerated || s.guidesWithPropTable ? 3 : 1;
+        if (s.unknownCount > 5) score = 1;
+        else if (s.unknownCount > 0) score = Math.min(score, 3);
+        return { score, evidence: ev };
+    },
+
+    tokens(f) {
+        const t = f.tokens;
+        const ev = [];
+        ev.push(t.docs.length ? `Token documentation: ${t.docs.slice(0, 4).join(", ")}.` : "No token documentation found in the guides.");
+        const source = t.source;
+        if (!t.docs.length && source && source.count) {
+            const noun = source.count === 1 ? "named token" : "named tokens";
+            ev.push(`${source.count} ${noun} defined in ${source.kind} (${source.files.slice(0, 2).join(", ")}), e.g. ${source.names.slice(0, 3).join(", ")} — real, but nothing in prose describes when to use which.`);
+        }
+        ev.push(`${t.motion ? "Motion documented" : "No motion documentation"}; ${t.spacing ? "spacing documented" : "no spacing documentation"}.`);
+        if (t.rawPaletteCount) ev.push(`${t.rawPaletteCount} raw palette classes in guide examples, e.g. ${t.rawPalette.slice(0, 3).map((h) => h.value).join(", ")}.`);
+        if (t.hexCount) ev.push(`${t.hexCount} raw hex values in guide examples.`);
+        const hasNamedTokens = t.docs.length > 0 || Boolean(source && source.count);
+        let score = t.docs.length && t.motion && t.spacing ? 5 : hasNamedTokens ? 3 : 1;
+        if (t.rawPaletteCount > 0) score = Math.min(score, 3);
+        return { score, evidence: ev };
+    },
+
+    patterns(f) {
+        const p = f.patterns;
+        const ev = [];
+        if (p.files.length) ev.push(`Pattern-level docs: ${p.files.slice(0, 4).join(", ")}.`);
+        if (p.mapFound) ev.push("A task-to-component table exists in the guides.");
+        if (!p.files.length && !p.mapFound) ev.push("Components only. Nothing describes how a page is assembled.");
+        if (p.files.length && !p.rich) ev.push("The pattern docs do not cover states or traps, so an agent still guesses the empty and error cases.");
+        return { score: p.rich ? 5 : p.files.length || p.mapFound ? 3 : 1, evidence: ev };
+    },
+
+    a11y(f) {
+        const a = f.a11y;
+        const label = A11Y_LABEL[a.platform] || A11Y_LABEL.web;
+        const ev = [`${a.withSection} of ${a.total} guides carry a ${label} section (${pct(a.ratio)}).`];
+        if (a.generated) ev.push("At least some of those sections are generated rather than hand-written.");
+        ev.push(a.automation ? "Accessibility checks run in CI." : "No automated accessibility check found.");
+        if (a.baseline.length) ev.push(`A known-violations baseline exists: ${a.baseline.join(", ")}.`);
+        return { score: a.ratio >= 0.9 && (a.generated || a.automation) ? 5 : a.ratio >= 0.3 ? 3 : 1, evidence: ev };
+    },
+
+    verification(f) {
+        const v = f.verification;
+        const ev = [`${v.testFiles} test files, ${v.storyFiles} stories.`];
+        const bits = [v.testScript && "test", v.typecheckScript && "typecheck", v.lintScript && "lint"].filter(Boolean);
+        ev.push(bits.length ? `Scripts: ${bits.join(", ")}.` : "No test, typecheck or lint script.");
+        if (v.workflows.length) ev.push(`CI: ${v.workflows.join(", ")}.`);
+        else ev.push("No CI workflow found, so nothing runs on a pull request.");
+        if (v.storyTests) ev.push("Stories are rendered and tested in CI.");
+        if (v.axe) ev.push("Accessibility assertions run as part of that.");
+        if (v.scoreGate) ev.push("The agent-readiness score itself is gated in CI.");
+        const strong = (v.storyTests && v.axe) || (v.testScript && v.docChecks && v.workflows.length);
+        return { score: strong ? 5 : v.testScript || v.lintScript || v.workflows.length ? 3 : 1, evidence: ev };
+    },
+
+    "gap-handling"(f) {
+        const g = f.gaps;
+        const ev = [];
+        ev.push(g.file ? `A list of known absences exists: ${g.file}.` : "Nothing lists what the system deliberately does not have.");
+        ev.push(g.stopAndAsk ? "The agent instructions tell the agent to stop and ask instead of inventing." : "No stop-and-ask rule, so an unlisted gap gets filled silently.");
+        ev.push(g.reportCommand ? `A gap can be reported with \`${g.reportCommand}\`.` : "No way for an agent to report a new gap where the next agent will read it.");
+        const score = g.file && g.stopAndAsk && g.reportCommand ? 5 : g.file || g.stopAndAsk ? 3 : 1;
+        return { score, evidence: ev };
+    },
+};
+
+/** @returns {{ total:number, max:number, dimensions:Array }} */
+export function score(facts, config = {}) {
+    const skip = new Set(config.skip || []);
+    const dimensions = RUBRIC.dimensions.map((dim) => {
+        if (skip.has(dim.id)) {
+            return { id: dim.id, title: dim.title, score: null, max: 5, skipped: true, evidence: ["Skipped by configuration."], fixes: [] };
+        }
+        const result = SCORERS[dim.id](facts);
+        return {
+            id: dim.id,
+            title: dim.title,
+            question: dim.question,
+            why: dim.why,
+            score: result.score,
+            max: 5,
+            level: dim.levels[String(result.score)],
+            next: result.score < 5 ? dim.levels[String(result.score === 1 ? 3 : 5)] : null,
+            evidence: result.evidence,
+            fixes: result.score < 5 ? dim.fixes : [],
+        };
+    });
+    const scored = dimensions.filter((d) => !d.skipped);
+    return {
+        total: scored.reduce((n, d) => n + d.score, 0),
+        max: scored.length * 5,
+        dimensions,
+    };
+}
+
+/** The machine-readable artifact: committed to the repo so the next run can compare. */
+export function scoreFile(facts, scored) {
+    return {
+        tool: "adsa",
+        rubric: RUBRIC.version,
+        generatedAt: new Date().toISOString(),
+        target: { name: facts.name, version: facts.version },
+        total: scored.total,
+        max: scored.max,
+        dimensions: Object.fromEntries(scored.dimensions.map((d) => [d.id, d.score])),
+        summary: {
+            components: facts.coverage.total,
+            documented: facts.coverage.documented,
+            guides: facts.guides.length,
+            codeBlocks: facts.freshness.blocks,
+            unknownImports: facts.freshness.unknownCount,
+            guidesWithA11y: facts.a11y.withSection,
+        },
+    };
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+    "name": "adsa-cli",
+    "version": "0.1.0",
+    "description": "Score a design system on how well coding agents can use it, then fix what is missing.",
+    "type": "module",
+    "bin": {
+        "adsa": "bin/adsa.mjs"
+    },
+    "files": [
+        "bin",
+        "lib",
+        "rubric",
+        "templates",
+        "skills"
+    ],
+    "engines": {
+        "node": ">=20"
+    },
+    "scripts": {
+        "test": "node --test test/*.test.mjs",
+        "audit:self": "node bin/adsa.mjs audit example/design-system"
+    },
+    "keywords": [
+        "design-system",
+        "agents",
+        "ai",
+        "documentation",
+        "audit",
+        "mcp"
+    ],
+    "license": "MIT",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/nrmk13/ADSA.git"
+    },
+    "homepage": "https://adsa.space",
+    "bugs": {
+        "url": "https://github.com/nrmk13/ADSA/issues"
+    },
+    "author": "Nazar Melnyk"
+}

package/rubric/rubric.json

@@ -0,0 +1,115 @@
+{
+    "version": "1.0",
+    "max": 45,
+    "scale": [1, 3, 5],
+    "dimensions": [
+        {
+            "id": "agent-instructions",
+            "title": "Agent instructions",
+            "question": "When an agent opens this repo, does anything tell it how to use the system?",
+            "why": "An agent with no instructions falls back on habits from other libraries: shadcn imports, raw Tailwind palette classes, a local components/ui folder.",
+            "levels": {
+                "1": "No AGENTS.md or CLAUDE.md, or one that never mentions the design system.",
+                "3": "A file exists and names the package, but reads like a README: prose, no rules an agent can follow.",
+                "5": "Short and imperative: how to look a component up, how to import, which token classes are required, what is forbidden, what to run before finishing."
+            },
+            "fixes": ["agents-md"]
+        },
+        {
+            "id": "machine-surface",
+            "title": "Machine surface",
+            "question": "Can an agent query the system, or must it read files and guess?",
+            "why": "Reading .d.ts files burns context and teaches the agent the type, not the rule. A queryable surface answers the question the agent actually has.",
+            "levels": {
+                "1": "Nothing. Docs are a website or markdown a human reads.",
+                "3": "One machine-readable entry point: llms.txt, a docs CLI, or published skills.",
+                "5": "An MCP server or CLI that ships inside the package and answers from the installed version, so answers match the version the project has."
+            },
+            "fixes": ["mcp-config"]
+        },
+        {
+            "id": "docs-coverage",
+            "title": "Docs coverage",
+            "question": "Does every component a consumer can import have a guide?",
+            "why": "A component with no guide is a component the agent will either skip or reinvent, and undocumented exports are where invented APIs come from.",
+            "levels": {
+                "1": "Under half of the exported components have a guide.",
+                "3": "Most have one, and nothing stops a new component from shipping without one.",
+                "5": "Effectively all of them, and CI fails when a new export arrives without a guide."
+            },
+            "fixes": ["coverage-gate"]
+        },
+        {
+            "id": "docs-freshness",
+            "title": "Docs freshness",
+            "question": "If a guide drifts from the code, does anything notice?",
+            "why": "Docs written next to the code look fine until something checks them. Guides that can only fail silently always drift.",
+            "levels": {
+                "1": "Guides are hand-written prose; nothing compares them to the code.",
+                "3": "Prop tables or examples are generated, but regenerating is a manual step somebody has to remember.",
+                "5": "CI regenerates the generated parts and compiles every code block in the guides against the built package. A guide that lies turns the build red."
+            },
+            "fixes": ["prop-tables", "examples-check"]
+        },
+        {
+            "id": "tokens",
+            "title": "Tokens",
+            "question": "Are colour, spacing, radius and motion documented as named decisions?",
+            "why": "Without a token table the agent hardcodes hex values and raw palette classes, and every screen drifts a little further from the system.",
+            "levels": {
+                "1": "No token documentation; guides show raw hex or raw palette classes.",
+                "3": "Tokens exist and are documented, but examples still mix in raw values.",
+                "5": "Semantic tokens documented as tables, raw palette usage forbidden by lint, and motion and spacing covered as well as colour."
+            },
+            "fixes": ["tokens-doc"]
+        },
+        {
+            "id": "patterns",
+            "title": "Patterns",
+            "question": "Is there anything above component level — how a real page is assembled?",
+            "why": "Components tell an agent what exists. Patterns tell it what to build. Without them each agent re-invents page structure from scratch.",
+            "levels": {
+                "1": "Components only. Nothing describes a page.",
+                "3": "A pattern-to-component map: for this task, reach for these parts.",
+                "5": "Page-level patterns with skeleton, states and traps, loaded on demand rather than always in context."
+            },
+            "fixes": ["patterns-doc"]
+        },
+        {
+            "id": "a11y",
+            "title": "Accessibility documentation",
+            "question": "Do the guides say how a component behaves for assistive technology — keys or gestures, focus, role and name?",
+            "why": "An agent cannot infer that behaviour from a prop table alone. On the web it ships a div that looks like a menu and answers to nothing; on mobile it ships a touchable with no accessible name and no role, silent to VoiceOver and TalkBack alike.",
+            "levels": {
+                "1": "Accessibility is not mentioned in the guides.",
+                "3": "Some guides mention it, written by hand and unevenly.",
+                "5": "Every guide carries the full interaction contract for its platform — keys or gestures, focus or touch-target behaviour, role and naming requirements — generated from the primitives the component is built on."
+            },
+            "fixes": ["a11y-docs"]
+        },
+        {
+            "id": "verification",
+            "title": "Verification",
+            "question": "Can an agent check its own work before calling it done?",
+            "why": "Speed is not the problem. An agent that cannot verify produces confident output nobody can audit.",
+            "levels": {
+                "1": "Types only, or nothing. A human is the first check.",
+                "3": "Unit tests and lint, run by hand.",
+                "5": "Every story rendered and checked for accessibility in CI, with a baseline that can only shrink, and one documented command an agent runs before finishing."
+            },
+            "fixes": ["ci-workflow"]
+        },
+        {
+            "id": "gap-handling",
+            "title": "Gap handling",
+            "question": "What happens when the system genuinely does not have the thing?",
+            "why": "An agent cannot tell 'this does not exist' from 'I have not found it yet', so it invents a component and moves on. More documentation cannot fix an absence.",
+            "levels": {
+                "1": "Nothing. The agent fills the gap silently with the nearest thing it knows.",
+                "3": "A written list of known absences and what to use instead.",
+                "5": "The list, plus an explicit stop-and-ask rule in the agent instructions, plus a way to report a new gap that lands where the next agent reads."
+            },
+            "fixes": ["gaps-file"]
+        }
+    ]
+}

package/skills/ds-audit/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: ds-audit
+description: Audit a design system for how well coding agents can use it. Use when someone asks to check whether a design system is agent-ready, why an agent keeps producing wrong UI with their component library, or asks for a design system audit, readiness score or agent-readiness report.
+---
+
+# Agent-readiness audit
+
+You are auditing a design system for one question: **can a coding agent build a
+correct page with it, without a human correcting the result?**
+
+The tool does the counting. You do the judgement, the experiment, and the writing.
+
+The tool audits React/web, React Native, Swift/SwiftUI/UIKit and Kotlin/Jetpack
+Compose, detected from real evidence in the repo (`package.json` dependencies,
+`Package.swift`/`.xcodeproj`, a Gradle build next to `.kt` files) — check
+`facts.platform` in `adsa audit --json` if you are unsure which one it picked, and
+say which platform you audited when you write it up. A dimension that genuinely
+does not apply on that platform is skipped, not scored down — the "keyboard"
+question becomes "VoiceOver/Dynamic Type" on Swift and "TalkBack/content
+description" on Android rather than failing either for lacking a keyboard.
+
+## Phase 0 — Intake
+
+Ask these in **one message**, numbered, then wait. Do not ask anything the repo can
+answer — the stack, the framework, the component count and the guide layout are all
+detected. If someone says "just go", take the defaults and say which you took.
+
+1. Where is the design system? A local path or a GitHub URL.
+2. Is there a project that already uses it — a real product repo? (This is what
+   makes the experiment possible; without it the audit is static only.)
+3. Which coding agent does your team use — Claude Code, Cursor, Copilot, other?
+   (Decides where instructions and MCP config get written.)
+4. Is there a Figma library, and is Code Connect set up? A link if you have one.
+5. Anything the system deliberately does not have, that you already know about?
+
+> **From Nazar, who built this:** if you work with Figma, use the figma-console
+> bridge rather than a screenshot or a static export. It reads the real component —
+> sizes, paddings, tokens, variants — so parity checks are against node data instead
+> of your impression of the design. Say so if the user has Figma but no bridge: an
+> audit that guesses at design parity is worth less than one that skips it honestly.
+
+If there is no Figma library, skip the design-parity discussion entirely rather than
+scoring it badly. A dimension that does not apply is skipped, never failed.
+
+## Phase 1 — Run the tool
+
+```bash
+npx adsa-cli audit <path>            # score, report, .adsa/score.json
+npx adsa-cli audit <path> --json     # the same, machine-readable
+```
+
+Read `.adsa/report.md` and the evidence under every dimension. The score is a
+starting point, not the finding.
+
+## Phase 2 — Read what the numbers cannot see
+
+Open five or six guides yourself, including the biggest and the oldest. Look for:
+
+- Rules stated as prose an agent cannot act on ("use sparingly", "be consistent").
+- Examples that would not compile: props that no longer exist, invented compound
+  APIs, imports from the wrong subpath.
+- The gap between what the guide says and what the type declares.
+- Six files the agent must read before it can write one line — context it does not have.
+- Anything that assumes the reader will ask a colleague.
+
+## Phase 3 — The experiment (only with a consumer project)
+
+This is the finding people believe. Everything else is opinion.
+
+```bash
+npx adsa-cli eval init                          # writes the task
+# hand the task to a fresh agent session, let it build
+npx adsa-cli eval score <project> --system <ds> # measure what came out
+```
+
+Record: components invented, imports from the system, forbidden packages, raw
+palette classes, time to a working page. Invented components are the headline
+number — an agent cannot tell "this does not exist" from "I have not found it yet",
+so every invention is a gap the system never declared.
+
+## Phase 4 — Compare
+
+Say where the system stands against systems that have done this work, by trait, not
+by vibe. The ones worth checking, and what each is known for:
+
+| System | What to look at |
+| :-- | :-- |
+| [Astryx](https://astryx.atmeta.com) (Meta) | CLI-first: `templates`, `blocks`, docs answered by command, API designed for generated code |
+| [Untitled UI](https://www.untitledui.com) | MCP inside the CLI, llms.txt, docs written for both readers |
+| [Serendie](https://serendie.design) | Skills shipped as a Claude Code plugin, generated from the guides |
+| [SmartHR](https://smarthr.design) | Over a hundred skills, generated rather than hand-written |
+| [Board UI](https://boardui.com) | Docs CLI, machine-readable component manifest |
+| [shadcn/ui](https://ui.shadcn.com) | Registry as a distribution format; components arrive as source |
+| [Radix](https://www.radix-ui.com) / [React Aria](https://react-spectrum.adobe.com/react-aria/) | Behaviour and keyboard contracts documented per primitive |
+| [Material](https://m3.material.io) / [Fluent](https://fluent2.microsoft.design) | Pattern and page-level documentation above component level |
+
+Name the two or three traits the audited system is missing, and which of these
+already ship them. Do not rank systems overall; rank traits.
+
+## Phase 5 — Write it up
+
+The tool has already written `.adsa/report.html`. Extend it, or write your own, but
+keep these:
+
+- The score out of 45 with the per-dimension breakdown and the evidence.
+- Findings in severity order, each with the file and line that proves it.
+- The to-do list, cheapest first, each item with its `adsa fix` command.
+- The experiment result if you ran one, including what the agent invented.
+
+Then say what to do first, in one sentence, and stop. Do not pad.
+
+## Phase 6 — Fix
+
+```bash
+npx adsa-cli fix --list        # what is automatic and what is a brief
+npx adsa-cli fix agents-md     # writes files
+npx adsa-cli fix prop-tables   # writes a task brief for you to execute
+```
+
+Briefs are specifications, not suggestions: read the whole brief, follow the traps
+section, and verify the check fails when you break something on purpose. A check
+that never fails is not a check.
+
+After the fixes: `npx adsa-cli audit` again. The delta is the deliverable.
+
+## Rules
+
+- Never invent a finding. Every claim names a file, a line or a command output.
+- Report a dimension you could not assess as not assessed. Do not guess a number.
+- Quote the repository, not your memory of similar repositories.
+- The score belongs to a version. Say which one you audited.
+
+---
+
+*From one designer to designers with love <3*

package/templates/AGENTS.android.md.tmpl

@@ -0,0 +1,22 @@
+<!-- adsa:start -->
+## Design system: {{name}}{{version}} ({{stack}})
+
+This project uses {{name}}. Before writing any UI:
+
+- Find the composable first: {{lookup}}. Do not read the compiled AAR and do not
+  reach for bare Material defaults or a copied composable from Stack Overflow —
+  this system has its own names.
+- Import per composable: `{{importExample}}`. {{importRule}}
+- Colour and typography come from the system's theme. {{paletteExample}} are not
+  allowed in product code — use the theme's color roles from `colors.xml`/`Theme.kt`
+  or `MaterialTheme.colorScheme`.
+- Icons come only from the system's icon set. No second icon library, no local
+  re-implementation of a composable that already exists.
+- Every clickable composable needs a `contentDescription` (via `Modifier.semantics`
+  or the component's own label parameter) and, where it is not obvious from the
+  content, a `Role`. A minimum touch target of 48dp per Material guidance.
+- **If the composable you need does not exist, stop and ask.** Do not invent a
+  wrapper, do not approximate it with a bare `Text`/`Box`, and do not silently pick
+  the nearest thing. Known absences and what to use instead are listed in {{gapsFile}}.
+- Before you call the work done: {{finishCheck}}.
+<!-- adsa:end -->

package/templates/AGENTS.md.tmpl

@@ -0,0 +1,17 @@
+<!-- adsa:start -->
+## Design system: {{name}}{{version}}
+
+This project uses {{name}}. Before writing any UI:
+
+- Find the component first: {{lookup}}. Do not read `node_modules` types and do not
+  reach for habits from shadcn, MUI or Radix — this system has its own names.
+- Import per component: `{{importExample}}`. {{importRule}}
+- Colour, spacing, radius and typography come from the system's tokens. Raw palette
+  classes ({{paletteExample}}) and raw hex values are not allowed in product code.
+- Icons come only from the system's icon set. No second icon library, no local
+  `components/ui` folder, no copied component source.
+- **If the component you need does not exist, stop and ask.** Do not invent a
+  wrapper, do not approximate it with a div, and do not silently pick the nearest
+  thing. Known absences and what to use instead are listed in {{gapsFile}}.
+- Before you call the work done: {{finishCheck}}.
+<!-- adsa:end -->

package/templates/AGENTS.react-native.md.tmpl

@@ -0,0 +1,21 @@
+<!-- adsa:start -->
+## Design system: {{name}}{{version}} ({{stack}})
+
+This project uses {{name}}. Before writing any UI:
+
+- Find the component first: {{lookup}}. Do not read `node_modules` types and do not
+  reach for React Native Elements, NativeBase or a copy-pasted community snippet —
+  this system has its own names.
+- Import per component: `{{importExample}}`. {{importRule}}
+- Colour, spacing, radius and motion come from the system's tokens. {{paletteExample}}
+  are not allowed in product code — use the theme instead.
+- Icons come only from the system's icon set. No second icon library, no local
+  `components/ui` folder, no copied component source.
+- Every `Pressable`, `TouchableOpacity` or custom control needs `accessibilityRole`
+  and an `accessibilityLabel` (or `accessibilityLabelledBy`). A touchable with
+  neither answers to nothing on VoiceOver or TalkBack.
+- **If the component you need does not exist, stop and ask.** Do not invent a
+  wrapper, do not approximate it with a bare `View`, and do not silently pick the
+  nearest thing. Known absences and what to use instead are listed in {{gapsFile}}.
+- Before you call the work done: {{finishCheck}}.
+<!-- adsa:end -->

package/templates/AGENTS.swift.md.tmpl

@@ -0,0 +1,23 @@
+<!-- adsa:start -->
+## Design system: {{name}}{{version}} ({{stack}})
+
+This project uses {{name}}. Before writing any UI:
+
+- Find the view first: {{lookup}}. Do not read the compiled module's generated
+  interface and do not reach for UIKit boilerplate, a different design system, or
+  Apple's default control styles — this system has its own names.
+- Import the module: `{{importExample}}`. {{importRule}}
+- Colour and typography come from the system's tokens. {{paletteExample}} are not
+  allowed in product code — use the named colors and `ShapeStyle`s the system ships,
+  from its asset catalog or token file.
+- Icons come only from the system's asset catalog. No second icon set, no copied
+  view source, no local re-implementation of a view that already exists.
+- Every control needs an accessible name and role: `.accessibilityLabel(...)`,
+  `.accessibilityAddTraits(...)`, and Dynamic Type support (`.font(.body)` style
+  fonts, not fixed point sizes). A view with none of these answers to nothing on
+  VoiceOver.
+- **If the view you need does not exist, stop and ask.** Do not invent a wrapper,
+  do not approximate it with a raw `Text`/`Button`, and do not silently pick the
+  nearest thing. Known absences and what to use instead are listed in {{gapsFile}}.
+- Before you call the work done: {{finishCheck}}.
+<!-- adsa:end -->

package/templates/GAPS.md.tmpl

@@ -0,0 +1,17 @@
+# What this system does not have
+
+An agent cannot tell "this does not exist" from "I have not found it yet", so it
+invents a component and moves on. This file is the difference between those two.
+
+Keep it short and current. Every row is a decision, not a backlog item.
+
+| What is missing | Use instead | Why / status |
+| :-- | :-- | :-- |
+| _example:_ Date range picker | Two `DatePicker` fields with a shared label | Planned, no owner yet |
+| _example:_ Toast / snackbar | The host application's notification layer | Deliberate: lives outside the system |
+
+## Reporting a new gap
+
+If you hit something that is not in this list and not in the system, add a row
+here in the same change. Do not put it only in a ticket or a chat message: the next
+agent reads this file, not your inbox.

package/templates/briefs/a11y-docs.md

@@ -0,0 +1,35 @@
+# Fix: keyboard and accessibility sections in every guide
+
+**Dimension:** Accessibility documentation · **Size:** M · **Repo:** {{name}} · **Stack:** {{stack}}
+
+An agent cannot infer keyboard behaviour from a prop table, so it ships a div that
+looks like a menu and answers to nothing. Write the behaviour down — generated, so
+it stays true.
+
+## What to build
+
+1. Map each component to the primitive it is built on ({{headless}}). If the system
+   is built on a headless library, the primitive already defines keys, focus
+   behaviour and roles: read that mapping from the component's own inherited
+   interfaces rather than guessing per component.
+2. Write a table per primitive: keys and what they do, focus behaviour, the ARIA
+   role, and whether an accessible name is required.
+3. Generate a `### Keyboard & accessibility` section into every guide between
+   markers. Components that are genuinely not interactive get one honest line
+   saying so — silence reads as an omission.
+4. Keep a hand-written `### Notes` subsection that survives regeneration, for the
+   things the primitive does not capture.
+5. Where the mapping is uncertain, print a confidence marker instead of inventing
+   a key list.
+
+## Traps
+
+- One primitive interface is often shared by two very different components. Check
+  the pairs before trusting the mapping.
+- Components that pick props instead of extending an interface will not be detected
+  automatically; keep a small explicit override list.
+
+## Done when
+
+- Every guide has the section, generated from the map.
+- The generator is idempotent and runs in CI.

package/templates/briefs/coverage-gate.md

@@ -0,0 +1,23 @@
+# Fix: fail CI on an undocumented export
+
+**Dimension:** Docs coverage · **Size:** S · **Repo:** {{name}}
+
+Coverage that nothing enforces goes down with every release. One gate keeps it.
+
+## What to build
+
+A check that lists what a consumer can import and asserts each has a guide in
+`{{guidesDir}}`. Package `exports` subpaths are the reliable source of that list;
+fall back to exported component symbols if the package ships one entry point.
+
+1. Set aside icon and logo sets — nobody writes a guide per icon — and print how
+   many were set aside so the number is not a surprise.
+2. Allow an explicit allowlist file for exports that genuinely need no guide
+   (sub-parts documented inside a parent guide), with a reason per entry.
+3. Fail with the list of undocumented exports, not just a count.
+4. Wire it into the same CI job as the other documentation checks.
+
+## Done when
+
+- A new exported component with no guide turns the build red.
+- The allowlist is short and every entry has a reason.