@planview/pvds-skills 0.0.1 → 0.0.5

package/README.md

@@ -4,25 +4,26 @@ Skills and reference knowledge for building with the Planview Design System (PVD
 
 ## Installation
 
-The recommended path is the `@planview/pvds-skills` CLI, which auto-detects your project's skills root, records a `.pvds-skills/config.json` marker, and installs all three skills in one step:
+The recommended path is the `@planview/pvds-skills` CLI, which auto-detects your project's skills root, records a `.pvds-skills/config.json` marker, and installs all four skills in one step:
 
 ```bash
 pnpm dlx @planview/pvds-skills init
 ```
 
-For npm / yarn / bun, substitute the equivalent runner (`npx --yes`, `yarn dlx`, `bunx`). The CLI is a zero-dependency ~100 KB tarball — no lockfile changes, no peer deps.
+For npm / yarn / bun, substitute the equivalent runner (`npx --yes`, `yarn dlx`, `bunx`). The CLI is a zero-dependency ~160 KB tarball — no lockfile changes, no peer deps.
 
-Either path installs the skills into your project's `.claude/skills/` directory (or your home directory if you install globally).
+Either path installs the skills into the skills directory of each coding agent you have installed (`.claude/skills/` for Claude Code, `.agents/skills/` for Codex, Cursor, and Copilot, and so on — or your home directory if you install globally). Use `--agent` to target specific agents; see [`--agent` (init)](#--agent-init).
 
 ## Available Skills
 
-| Skill              | Purpose                                                                                                                                         |
-| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `pvds-knowledge`   | Shared reference knowledge base — API docs, code recipes, gotchas, architecture guides. Not a standalone skill; other skills load data from it. |
-| `pvds-builder`     | Generate React code using PVDS packages correctly. Loads knowledge on demand to produce correct, performant, accessible code.                   |
-| `pvds-peer-review` | Expert-level peer review of code consuming PVDS packages. Checks coding style, accessibility, performance, theming, and more.                   |
+| Skill               | Purpose                                                                                                                                                                |
+| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `pvds-knowledge`    | Shared reference knowledge base — API docs, code recipes, gotchas, architecture guides. Not a standalone skill; other skills load data from it.                        |
+| `pvds-builder`      | Generate React code using PVDS packages correctly. Loads knowledge on demand to produce correct, performant, accessible code.                                          |
+| `pvds-peer-review`  | Expert-level peer review of code consuming PVDS packages. Checks coding style, accessibility, performance, theming, and more.                                          |
+| `pvds-test-builder` | Write tests for code consuming PVDS packages: sets up the PVDS test providers, queries by role, label and text, and tests your integration rather than PVDS internals. |
 
-## CLI reference
+## CLI
 
 ```bash
 pnpm dlx @planview/pvds-skills init      # one-time setup + install skill markdown
@@ -30,8 +31,9 @@ pnpm dlx @planview/pvds-skills upgrade   # refresh skill markdown; bump config v
 pnpm dlx @planview/pvds-skills check     # run all deterministic PVDS audits
 pnpm dlx @planview/pvds-skills doctor    # verify config + skills presence
 pnpm dlx @planview/pvds-skills versions  # compare bundled PVDS reference data vs. installed pv-* versions
-pnpm dlx @planview/pvds-skills props <Component>  # look up a component's own-declared props from the manifest
-pnpm dlx @planview/pvds-skills fix       # no-op (parked for future auto-fixable checks)
+pnpm dlx @planview/pvds-skills props <Component>  # look up components', hooks' or styling namespaces' APIs
+pnpm dlx @planview/pvds-skills components         # list the manifest's exports (filter by --package / --grep)
+pnpm dlx @planview/pvds-skills tokens             # list color, spacing and size tokens, or find which hold a value
 pnpm dlx @planview/pvds-skills --help
 ```
 
@@ -44,62 +46,40 @@ For npm / yarn / bun projects, substitute the equivalent runner:
 | yarn | `yarn dlx @planview/pvds-skills …`  |
 | bun  | `bunx @planview/pvds-skills …`      |
 
-The CLI auto-detects your project's package manager (via `packageManager` in `package.json`, then lockfile) and uses the matching runner for the downstream `skills add` invocation. Override with `--package-manager=<pnpm|npm|yarn|bun>` if detection is wrong.
+### Quick start
 
-### `check` — deterministic PVDS audits
-
-`check` walks the repo (skipping `node_modules`, `dist`, etc.) and runs a set of zero-heuristic checks against `@planview/pv-*` usage: version drift, subpath imports, orphan/undeclared dependencies (including `.less`/`.scss`/`.sass`/`.css` references), deprecated-export imports, hardcoded colors/spacing in CSS-in-JS, invalid enum prop literals, unknown/typo'd JSX props, and manifest-vs-installed version drift.
+Audit your code. `check` is deterministic and offline; it exits `1` on error-level findings (warnings don't block by default) and `2` when it couldn't run:
 
 ```bash
 pnpm dlx @planview/pvds-skills check
-pnpm dlx @planview/pvds-skills check --verbose                     # list every scanned file
-pnpm dlx @planview/pvds-skills check --only=hardcoded-colors,hardcoded-spacing
+pnpm dlx @planview/pvds-skills check --preset=self-review --changed   # only what you've touched
+pnpm dlx @planview/pvds-skills check --only=hardcoded-colors,unknown-props
+pnpm dlx @planview/pvds-skills check --fail-on=warning                # strict CI
 pnpm dlx @planview/pvds-skills check --format=json --output=./pvds-report.json
 ```
 
-Every run prints a scan summary per category so a "0 issues" result is trustworthy. Exit code is `1` when any error-level issue is found; suitable for CI. Output formats: `human` (default), `json`, `sarif`.
-
-By default `check` walks the entire directory tree. Scope it to a specific file set instead with:
+Look things up before writing code:
 
 ```bash
-pnpm dlx @planview/pvds-skills check --files=src/components/Button.tsx,src/components/Input.tsx
-pnpm dlx @planview/pvds-skills check --changed                     # uncommitted changes (tracked + untracked), vs HEAD
-pnpm dlx @planview/pvds-skills check --staged                      # staged files only (git diff --cached)
-pnpm dlx @planview/pvds-skills check --since=main                  # files changed since diverging from a ref
+pnpm dlx @planview/pvds-skills props Grid Toolbar             # a component's props
+pnpm dlx @planview/pvds-skills props ContentLayout.Left       # a composite's sub-component
+pnpm dlx @planview/pvds-skills components --grep=button       # what is it actually called?
+pnpm dlx @planview/pvds-skills tokens colors --grep=error     # color tokens by name
+pnpm dlx @planview/pvds-skills tokens --value '#d41616'       # which tokens hold this value?
 ```
 
-These are additive — combine `--files` with a git flag to union both sets. Scoping only applies to the per-file checks (`subpath-imports`, `deprecated-imports`, `hardcoded-colors`, `hardcoded-spacing`, `literal-size-props`, `unknown-props`, and the source side of `undeclared-imports`); `orphan-deps`, `versions`, and `manifest-drift` always need whole-repo visibility to be correct and ignore it.
-
-`--changed`, `--staged`, and `--since` shell out to the `git` binary (the only external process the CLI invokes) and require the target directory to be inside a git repository — `--files` has no such requirement.
-
-### `versions` — reference-data freshness
-
-The manifest baked into the CLI (deprecations, enum props, style-token hints) is generated once per release against one fixed version of each `@planview/pv-*` package — it does not track a consumer's installs over time. `versions` shows what the bundled manifest was generated against next to what's actually installed in your project, and flags major-version gaps. The same comparison runs as part of `check` under the `manifest-drift` category (warning-level, never blocks CI on its own).
+Choose which agents get the skills:
 
 ```bash
-pnpm dlx @planview/pvds-skills versions
-pnpm dlx @planview/pvds-skills versions --format=json
+pnpm dlx @planview/pvds-skills init                      # auto-detect installed agents
+pnpm dlx @planview/pvds-skills init --agent claude-code  # or name them; repeatable, '*' for all
 ```
 
-### `props` — component prop lookup
-
-Looks up a component's own-declared props (name, type, enum values, deprecation) directly from the bundled manifest — no source scanning, no network call beyond the initial `dlx` fetch. Intended for agents (or humans) that need an authoritative prop list before writing or reviewing code, without loading the full `api-reference.md`.
-
-```bash
-pnpm dlx @planview/pvds-skills props Grid
-pnpm dlx @planview/pvds-skills props Button --package=@planview/pv-uikit
-pnpm dlx @planview/pvds-skills props FilterPanel --format=json
-```
-
-Only _own-declared_ props are tracked (see Architecture below) — a component with zero own props (fully inherited from HTML/React) won't appear, and that's not an error. Standard HTML/React/ARIA attributes (`className`, `onClick`, `style`, `data-*`, `aria-*`, ...) are always valid regardless of manifest presence; every response repeats this caveat. Exit code is `1` when the component isn't found in the manifest.
-
-### `--yes` (init)
-
-`pvds-skills init` itself is non-interactive. `--yes` forwards `-y` to the downstream `skills add` command so it skips its own prompts. Use it in CI or headless runs.
+**[CLI-REFERENCE.md](CLI-REFERENCE.md)** has everything else: every command and flag, exit codes, JSON output shapes, the rule catalogue (each `ruleId`, its severity, and what it ignores), how `props` resolves a name, and the manifest schema.
 
 ### Architecture
 
-Single bundled ESM entry (`dist/cli.js`). Every dependency (currently just `citty`) is inlined at build time via tsup's `noExternal: /.*/`. No runtime deps, no peer deps, no post-install hooks. The consumer-facing manifest (deprecations, enum props, style-token reverse-lookups) is generated from the installed `@planview/pv-*` `.d.ts` files via `pnpm refresh-manifest` and bundled inline — no runtime dependency on those packages.
+Single bundled ESM entry (`dist/cli.js`). Every dependency (`citty` and `cross-spawn`) is inlined at build time via tsdown's `deps.alwaysBundle: /.*/`. No runtime deps, no peer deps, no post-install hooks. The consumer-facing manifest (deprecations, enum props, style-token reverse-lookups) is generated from the installed `@planview/pv-*` `.d.ts` files via `pnpm refresh-manifest` and bundled inline — no runtime dependency on those packages.
 
 ## Usage
 
@@ -133,6 +113,26 @@ Or ask for a review of commits not yet pushed to a PR:
 /pvds-peer-review can you please review the last three commits in my branch? The intent with the changes are....
 ```
 
+You can also do a quick, only mechanical review of your code by asking for a quick review. This will run the deterministic CLI checks and return the results to you.
+
+```
+/pvds-peer-review can you please do a quick review of the changes done in my branch?
+```
+
+### Testing PVDS code
+
+Invoke the test builder skill to write tests for code that uses PVDS components. It sets up the PVDS test providers, queries by accessible role, label and text, and covers how your code uses the components rather than what PVDS does internally:
+
+```
+/pvds-test-builder add tests for the filter panel: changing a filter should narrow the grid
+```
+
+Or point it at existing code:
+
+```
+/pvds-test-builder write tests for src/features/tasks/TaskDetails.tsx, including selecting a card and opening the details panel
+```
+
 ## Knowledge Base Coverage
 
 | Package                  | Status                                                       |