@planview/pvds-skills 0.0.1

package/README.md

@@ -0,0 +1,156 @@
+# PVDS Agent Skills & Knowledge Base
+
+Skills and reference knowledge for building with the Planview Design System (PVDS).
+
+## 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:
+
+```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.
+
+Either path installs the skills into your project's `.claude/skills/` directory (or your home directory if you install globally).
+
+## 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.                   |
+
+## CLI reference
+
+```bash
+pnpm dlx @planview/pvds-skills init      # one-time setup + install skill markdown
+pnpm dlx @planview/pvds-skills upgrade   # refresh skill markdown; bump config version
+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 --help
+```
+
+For npm / yarn / bun projects, substitute the equivalent runner:
+
+| PM   | Run                                 |
+| ---- | ----------------------------------- |
+| pnpm | `pnpm dlx @planview/pvds-skills …`  |
+| npm  | `npx --yes @planview/pvds-skills …` |
+| 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.
+
+### `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.
+
+```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 --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:
+
+```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
+```
+
+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).
+
+```bash
+pnpm dlx @planview/pvds-skills versions
+pnpm dlx @planview/pvds-skills versions --format=json
+```
+
+### `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.
+
+### 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.
+
+## Usage
+
+### Building with PVDS
+
+Invoke the builder skill when you need help creating UI with PVDS:
+
+```
+/pvds-builder I need a grid with editable cells and drag-and-drop
+```
+
+### Reviewing PVDS code
+
+Invoke the review skill to check your PVDS usage:
+
+You can ask for a review of a specific PR:
+
+```
+/pvds-peer-review can you please review PR #123
+```
+
+Or ask for a general review of your current branch:
+
+```
+/pvds-peer-review can you please review the current changes in my branch? The intent with the changes are....
+```
+
+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....
+```
+
+## Knowledge Base Coverage
+
+| Package                  | Status                                                       |
+| ------------------------ | ------------------------------------------------------------ |
+| `@planview/pv-grid`      | Available (API reference, 27 recipes, gotchas, architecture) |
+| `@planview/pv-uikit`     | Available (API reference, 15 recipes, gotchas, architecture) |
+| `@planview/pv-utilities` | Available (API reference, 13 recipes, gotchas, architecture) |
+| `@planview/pv-tokens`    | Available (API reference, gotchas)                           |
+| `@planview/pv-toolbar`   | Available (API reference, 15 recipes, gotchas, architecture) |
+| `@planview/pv-icons`     | Available (API reference, gotchas)                           |
+| `@planview/pv-details`   | Available (API reference, 12 recipes, gotchas, architecture) |
+| `@planview/pv-filter`    | Available (API reference, 14 recipes, gotchas, architecture) |
+| `@planview/pv-gantt`     | Available (API reference, 17 recipes, gotchas, architecture) |
+| `@planview/pv-form`      | Available (API reference, 19 recipes, gotchas, architecture) |
+| `@planview/pv-widget`    | Available (API reference, 17 recipes, gotchas, architecture) |
+
+Cross-cutting guides available: accessibility, coding style, theming & tokens, i18n, testing, performance.
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local development, testing, and release instructions.