adsa-cli 0.1.0

package/templates/briefs/examples-check.md

@@ -0,0 +1,37 @@
+# Fix: compile the guide examples in CI
+
+**Dimension:** Docs freshness · **Size:** M · **Repo:** {{name}} · **Stack:** {{stack}}
+
+Every code block in the guides is a promise. Compile them and find out which ones
+the system no longer keeps.
+
+## What to build
+
+A script that extracts every TypeScript or TSX block from `{{guidesDir}}` and type
+checks it against the **built** package, then fails with file and line numbers.
+
+1. Extract fenced blocks tagged `tsx`, `ts`, `jsx` or `js`.
+2. Most blocks are fragments with no imports. Build a per-file import registry:
+   collect the imports from that guide's own Import section and prepend them to
+   every fragment in the same file. This is what makes wrong props detectable.
+3. Unknown identifiers that are clearly out of scope become `declare const X: any`
+   so the check stays about props and imports, not about the surrounding app.
+4. Allow an explicit escape hatch — a comment above the block with a reason — and
+   print how many blocks are skipped so the number cannot creep up quietly.
+5. Report as `path:line — message`, and exit non-zero on the first failure.
+
+## Expect to find
+
+Real bugs, not formatting: icons that no longer exist, compound APIs that were
+never implemented, required props missing from examples, imports pointing at the
+wrong subpath. In our own run this flagged 13 guides out of 59 on the first pass.
+
+## Verify the check itself
+
+Break one example on purpose — rename a prop to something that cannot exist — and
+confirm the script fails with the right line. A check that never fails is not a check.
+
+## Done when
+
+- Every block compiles or is explicitly skipped with a stated reason.
+- CI runs it on every pull request.

package/templates/briefs/patterns-doc.md

@@ -0,0 +1,32 @@
+# Fix: page-level patterns
+
+**Dimension:** Patterns · **Size:** L · **Repo:** {{name}}
+
+Components tell an agent what exists. Patterns tell it what to build. Without them
+every agent re-invents page structure, and no two screens come out the same.
+
+## Where the content comes from
+
+Do not invent patterns. Take four or five real pages that already exist in the
+product — the ones that repeat — and describe what they actually are. A list page,
+a settings form, a detail view, an empty state, a wizard. If the design lives in
+Figma, read the real frames rather than imagining the layout.
+
+## What each pattern needs
+
+- **When to use it**, in one sentence, phrased the way someone would ask for it.
+- **Skeleton**: the component tree, with the actual imports from this system.
+- **States**: loading, empty, error, permission denied. This is the half agents skip.
+- **Traps**: the mistakes people make on this pattern in this system.
+- **What it is not**: the neighbouring pattern it gets confused with.
+
+## How it should load
+
+Not always in context. One file per pattern with a one-line description an agent
+matches against the task, and the body pulled in only when it matches. Always-loaded
+patterns eat the context window that the component guides need.
+
+## Done when
+
+- Four or five patterns exist, each with skeleton, states and traps.
+- Each one names the real components it uses, and those imports compile.

package/templates/briefs/prop-tables.md

@@ -0,0 +1,41 @@
+# Fix: generate prop tables from types
+
+**Dimension:** Docs freshness · **Size:** M · **Repo:** {{name}} · **Stack:** {{stack}}
+
+A hand-written prop table is a copy of the truth, and copies rot. Generate it.
+
+## What to build
+
+A script that reads the built type declarations and rewrites the prop table inside
+each guide, between markers, leaving everything else in the file untouched.
+
+1. Build the package first, then read the emitted `.d.ts` files — not the source.
+   The published types are what a consumer sees, and they are not always identical
+   to the source.
+2. For each documented component, resolve its props type and emit a table with
+   name, type, required, default and description.
+3. Write it into the guide between `<!-- props:start -->` and `<!-- props:end -->`.
+   Create the block if it is missing. Never touch text outside the markers.
+4. Preserve hand-written Default and Description cells across regeneration: read
+   the existing table first and carry those two columns over by prop name.
+5. Add the script to CI so it runs, then fails if the working tree changed.
+
+Guides live in `{{guidesDir}}`. Components: `{{sourceDir}}`.
+
+## Traps that cost us time
+
+- Sort union members. TypeScript returns them in internal order, which differs
+  between machines, so an unsorted table makes CI fail on somebody else's laptop.
+- Inherited props from a headless library ({{headless}}) are real props consumers
+  pass. Either list them in a separate "Inherited" table with the source interface
+  named, or state clearly that they are not covered. Do not silently drop them.
+- Generic props whose type is a type parameter need the base constraint resolved,
+  otherwise you print `T` instead of the twelve literal values.
+- Run the formatter after generating, as a separate commit, and check the exit code
+  explicitly. A piped command hides a non-zero exit.
+
+## Done when
+
+- `{{pkgRun}} <your script>` rewrites every table with no manual step.
+- CI fails when a table is stale.
+- Re-running twice produces no diff.

package/templates/ci/adsa.yml

@@ -0,0 +1,19 @@
+name: Agent readiness
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  score:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      # Fails when the score drops below the committed one, so documentation debt
+      # cannot land quietly alongside a feature.
+      - name: Score agent readiness
+        run: npx --yes adsa-cli@latest audit --gate

package/templates/mcp/mcp.json

@@ -0,0 +1,8 @@
+{
+    "mcpServers": {
+        "adsa": {
+            "command": "npx",
+            "args": ["--yes", "adsa-cli@latest", "mcp"]
+        }
+    }
+}

package/templates/tokens.android.md.tmpl

@@ -0,0 +1,32 @@
+# Design tokens
+
+Tables, not prose. An agent copies from a table and guesses from a paragraph.
+
+## Colour
+
+| Token | XML resource / Compose symbol | Use for |
+| :-- | :-- | :-- |
+| `brand_primary` | `colors.xml` → `MaterialTheme.colorScheme.primary` | The main call-to-action colour |
+| _add the rest of your semantic tokens_ | | |
+
+## Spacing
+
+| Token | Value | Use for |
+| :-- | :-- | :-- |
+| `space_2` | 8dp | Gap inside a control |
+| _add your scale_ | | |
+
+## Motion
+
+| Token | Value | Use for |
+| :-- | :-- | :-- |
+| `duration_fast` | 100ms | Ripple, colour changes |
+| `duration_base` | 200ms | Toggles, small reveals |
+| `duration_slow` | 300ms | Sheets, screen transitions |
+
+## Rules
+
+- Product code uses `MaterialTheme.colorScheme` / the theme's typography and shape
+  roles, never a hardcoded `Color(0xFF...)` or a raw hex value in layout XML.
+- A value that is not in these tables is a gap: add it to `colors.xml`/`Theme.kt`
+  and this file in the same change, or ask — do not inline it.

package/templates/tokens.md.tmpl

@@ -0,0 +1,31 @@
+# Design tokens
+
+Tables, not prose. An agent copies from a table and guesses from a paragraph.
+
+## Colour
+
+| Token | Class | Use for |
+| :-- | :-- | :-- |
+| `--color-bg-primary` | `bg-primary` | Default page and card background |
+| _add the rest of your semantic tokens_ | | |
+
+## Spacing
+
+| Token | Value | Use for |
+| :-- | :-- | :-- |
+| `--spacing-2` | 8px | Gap inside a control |
+| _add your scale_ | | |
+
+## Motion
+
+| Token | Value | Use for |
+| :-- | :-- | :-- |
+| `--duration-fast` | 100ms | Hover, focus ring, colour changes |
+| `--duration-base` | 200ms | Toggles, small reveals, tooltips |
+| `--duration-slow` | 300ms | Drawers, modals, layout shifts |
+| `--ease-standard` | `cubic-bezier(0.2, 0, 0, 1)` | Anything entering or moving |
+
+## Rules
+
+- Product code uses the token classes, never the raw palette.
+- A value that is not in these tables is a gap: add it here or ask, do not inline it.

package/templates/tokens.native.md.tmpl

@@ -0,0 +1,32 @@
+# Design tokens
+
+Tables, not prose. An agent copies from a table and guesses from a paragraph.
+
+## Colour
+
+| Token | Value (theme key or class) | Use for |
+| :-- | :-- | :-- |
+| `color.bg.primary` | `theme.colors.bgPrimary` | Default screen and card background |
+| _add the rest of your semantic tokens_ | | |
+
+## Spacing
+
+| Token | Value | Use for |
+| :-- | :-- | :-- |
+| `space.2` | 8 | Gap inside a control |
+| _add your scale_ | | |
+
+## Motion
+
+| Token | Value | Use for |
+| :-- | :-- | :-- |
+| `duration.fast` | 100ms | Press feedback, colour changes |
+| `duration.base` | 200ms | Toggles, small reveals |
+| `duration.slow` | 300ms | Sheets, screen transitions |
+
+## Rules
+
+- Product code uses the theme's token values, never a raw color literal in
+  `StyleSheet.create` and never a raw palette class if the theme is exposed through
+  NativeWind.
+- A value that is not in these tables is a gap: add it here or ask, do not inline it.

package/templates/tokens.swift.md.tmpl

@@ -0,0 +1,32 @@
+# Design tokens
+
+Tables, not prose. An agent copies from a table and guesses from a paragraph.
+
+## Colour
+
+| Token | Swift symbol / asset | Use for |
+| :-- | :-- | :-- |
+| `accentPrimary` | `Color("AccentPrimary")` (asset catalog) | The main call-to-action colour |
+| _add the rest of your semantic tokens_ | | |
+
+## Typography
+
+| Token | Swift symbol | Use for |
+| :-- | :-- | :-- |
+| `title` | `.font(.title)` / a custom `ShapeStyle` | Screen titles |
+| _add your scale_ | | |
+
+## Motion
+
+| Token | Value | Use for |
+| :-- | :-- | :-- |
+| `durationFast` | 0.1s | Press feedback, colour changes |
+| `durationBase` | 0.2s | Toggles, small reveals |
+| `durationSlow` | 0.3s | Sheets, navigation transitions |
+
+## Rules
+
+- Product code uses the named colours and text styles this system ships, never a
+  raw `Color(red:green:blue:)` literal or a hardcoded hex string.
+- A value that is not in these tables is a gap: add it to the asset catalog and
+  this file in the same change, or ask — do not inline it.