Forge — Audit Library

Prerequisite: forge.config.json exists at the repo root (run forge init once).

Measure every component against the rules in forge.config.json + the standard at ${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/component-standard.md and emit a prioritized fix list. This is the bridge between the standard (the rule) and edit-component (the fix): audit tells you what and in what order; edit-component does each one.

What it checks

Naming truth comes from the standard's §10 migration map, so the audit can never disagree with the standard about correct names.

Brain-level (always run):

• Naming — symbol renamed per the standard's migration map
• Props verified vs inferred/partial in the brain
• Semantic color values match the standard's vocabulary
• Size scale matches the standard's scale
• Visual/color axes match the standard's prop names

Source-level (only with --repo):

• a11y (ARIA / keyboard / :focus-visible)
• no raw hex/px where a token exists
• files present (tsx + css + stories + test)
• barrel export of symbol + type

Workflow

1. Run the scorer

python3 "${CLAUDE_PLUGIN_ROOT}/skills/_shared/scripts/audit_components.py" \
  --brain    "${CLAUDE_PLUGIN_ROOT}/skills/_shared/DESIGN-SYSTEM.md" \
  --standard "${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/component-standard.md" \
  --repo <repo-path-if-available> \
  --report <out>/audit-report.md

Without --repo, source checks are listed as deferred — that's expected before the repo is connected.

2. Read the output

The script prints JSON (components, clean count, fix_items, ranked queue) and writes a markdown report with a per-component fix table sorted by score (higher = more to fix). Summarize for the user: how many components, how many clean, the top offenders, and the fix-type breakdown (how many renames, how many unverified, etc.).

3. Turn the queue into work

Each queue item maps to one edit-component run — non-breaking, per the standard's deprecation policy. Recommend an order:

1. Verify props (props_unverified) — cheapest, pure accuracy; often just sync_design_system.py --all against the connected repo.
2. Color/size/axis fixes — small, mechanical, alias the old value.
3. Renames — highest effort (alias + barrel + deprecate); batch by category.

Offer to kick off the top item via edit-component, or to run the whole queue in priority order if the repo is connected.

Guardrails

• Audit is advisory — it flags, it doesn't change code. Fixes go through edit-component (PR into the base branch from forge.config.json git.prBase, defaults to main).
• Naming flags come from the migration map; if a flag looks wrong, fix the map in component-standard.md, don't special-case the audit.
• Re-run after each batch of fixes — the fix queue should shrink toward zero, and props_unverified should drop as the brain is regenerated from real source.