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:

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

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.

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:

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).

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.

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 for local development, testing, and release instructions.