Working with agents

The repository is designed to be legible to coding agents. CLAUDE.md / AGENTS.md at the root explain the modes and the gate; skills in .claude/skills/ do the recurring jobs.

Skills

Skill	Audience	What it does
/setup-project	project owners	New project from the template on a fresh machine: install, name the site, choose the internal-site gate (deploy/audience.json), create the private repo and secrets, explain the first deploy — nobody installs wrangler or logs into Cloudflare
/new-report	authors	Scaffolds content/reports/<slug>/v1.0.mdx (public) or content/internal/<slug>/v1.0.mdx (internal, D11) from templates/new-report, asks title/type/authors/audience
/new-analysis	authors	Scaffolds an analysis cell (components/analyses/<topic>/) wired to a bundle, plus a report stub
/new-bundle	authors, data	Creates a bundle directory and computes the manifest (bytes, sha256)
/new-tool	engineers	Scaffolds a /tools/<name> page-app from templates/new-tool
/validate	everyone	Runs pnpm check and pnpm test, explains failures in plain language
/publish	authors	Branch → commit → push → PR with a sign-in-protected preview link; never merges, never pushes to main. Merging deploys both the public and the internal site

What makes agents reliable here

A small opinionated vocabulary (not the whole of PatternFly), a live catalogue at /design/* to copy from, PatternFly’s own docs pinned in node_modules, and one gate — pnpm check — named as the definition of done.

PatternFly documentation for agents

• Local, pinned: node_modules/@patternfly/react-core/src/components/<Name>/examples/*.md|tsx (pnpm pf:example <Name>), .d.ts props, react-icons (pnpm icons find).
• MCP: claude mcp add patternfly-mcp -- npx -y @patternfly/patternfly-mcp@latest — design guidelines, accessibility notes and JSON prop schemas for React components (it fetches patternfly-org and patternfly-react).
• Plugins: the PatternFly plugin marketplace moved to rh-uxd/ai-helpers; pf-css-token-check is worth enabling.

Guardrails

• ESLint no-restricted-imports: only allowlisted PatternFly components; banned stylesheets never import
• scripts/check-classes.mjs: no raw pf-v6-c-* classes, no palette tokens / hex / !important / sub-12 px text; scripts/pf-barrel.mjs --check: the PatternFly entry map matches the allowlist
• scripts/check-classes.mjs: no raw pf-v6-c-* classes in the site
• astro check + tsc, axe on every surface, VR on Linux CI
• Frontmatter validated by zod at build; unknown bundle ids fail the build