Forge — Edit Component

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

Change an existing component so it matches the design system, self-documents back into the brain, and ships as a reviewable PR into the base branch from forge.config.json git.prBase (defaults to main). Closed loop: code change → brain section regenerated → PR. The brain can't drift because the same action that edits the code rewrites its section.

When this triggers

The user wants to change a component that already exists in the library. If the component is not in the brain (and not in source), stop — offer create-component instead. Never invent a component or props.

Inputs to confirm (ask at most one question)

1. Which component and what change, concretely — prop name, type, default, behavior.
2. Repo location (path to the local clone) if not already known.
3. Backwards-compatibility — breaking change acceptable, or must the default preserve current behavior? Default to non-breaking.

Workflow

1. Locate and load

• Confirm the component exists: find its ## <Name> section in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/DESIGN-SYSTEM.md. If absent, stop (see above).
• In the repo, read the component file (src/components/<Name>/<Name>.tsx), its co-located <Name>.css, and its *.stories.* / *.test.* if present. Stories show the prop surface you must not break; tests show behavior to preserve.
• Load the rules, in priority order: the rules in forge.config.json + the standard at ${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/component-standard.md (the enforceable spec — naming, prop API, sizes, a11y, deprecation policy), then .../conventions.md, then .../standing-guidance.md. Standing guidance overrides defaults; the standard overrides the component when they disagree.
• Bring the component toward the standard while you're in it. If it violates a rule (wrong size scale, wrong axis/prop name, wrong semantic color value, raw hex), fix it non-breaking per the deprecation policy: add the correct name/prop, keep the old one as a @deprecated alias. Never rename in place.
• Close prop gaps (non-breaking, additive). Check the component against §2.1/§2.2 of the standard. Add missing baseline/type props with safe defaults (e.g. add loading/disabled/size to a button, error/required to an input, controlled open/onOpenChange to a disclosure). Make onClick/onChange pass the native event if they currently drop it (additive second-arg or widened signature).
• Fix dead props & type bugs you encounter (unused interface props, documented-but- absent props, required-but-defaulted unions).
• Fix the required ARIA for the type (§4.1) — add aria-live to alerts, a real focus trap to overlays, roles/keyboard to menus/tabs/sliders, aria-label to icon buttons.
• Migrate tokens opportunistically — switch any raw --slate-*/--gray-*/hex text to canonical --text-*, and raw px to --space-*/--radius-*/--font-size-*.
• Read Foundations + Conventions in the brain so token names are exact.

2. Make the change, in the library's own style

• Match existing patterns in the file: prop ordering, forwardRef, how variants are typed (string-literal unions, never enums), how class names are composed (the project's clsx-style helper, never ad-hoc template strings), how tokens are referenced. Read before you write.
• Bias to dynamic, prop-driven design. To change styling/behavior, add a typed prop with a default that preserves current behavior (e.g. padding?: 'small' | 'medium' | 'large' defaulting to today's value) rather than hardcoding a new value.
• Reference design tokens by canonical name from the brain's Foundations; never introduce raw hex/px when a token exists.
• Keep it backwards-compatible unless the user explicitly accepted a break.
• Update *.stories.* to demonstrate the new prop; add/adjust a test if behavior changed. A new prop without a story is incomplete.

3. Regenerate the brain section (self-improvement — do not skip)

Rebuild this component's section from the changed source:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/_shared/scripts/sync_design_system.py" \
  --repo <repo-path> --component <Name> \
  --brain "<repo-path>/DESIGN-SYSTEM.md"

It re-extracts props/types/defaults (via react-docgen-typescript when Node is present, regex fallback otherwise), pulls tokens referenced, regrabs the Usage snippet from stories, and rewrites the ## <Name> section in place. Props read from real source become verified (the _(inferred)_ tag is dropped). Read its JSON output and confirm the section now reflects your change.

The canonical brain lives in the library repo root (<repo-path>/DESIGN-SYSTEM.md) and is committed in the same PR as the code. The plugin's ${CLAUDE_PLUGIN_ROOT}/skills/_shared/DESIGN-SYSTEM.md stays in sync via the consuming workflow — always target the repo brain on writes. Tokens for any follow-on rebuild_brain.py --brain "<repo-path>/DESIGN-SYSTEM.md" come from <repo-path>/forge.config.json repo.tokensCss (passed as --tokens-css).

4. Capture corrections as durable guidance

If the user corrects a convention ("ghost buttons never get a shadow", "default variant is secondary"), append a generalized, scoped rule:

python3 "${CLAUDE_PLUGIN_ROOT}/skills/_shared/scripts/record_guidance.py" \
  --rule "Button-like components: default variant is 'secondary', never 'primary'." \
  --scope components \
  --store "${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/standing-guidance.md"

Chat is forgotten; the store is read on every future run. This is how the same mistake stops recurring.

5. Open the PR (into the configured base branch)

bash "${CLAUDE_PLUGIN_ROOT}/skills/_shared/scripts/open_pr.sh" \
  --repo <repo-path> --component <Name> --action edit \
  --summary "Add loading prop to <ComponentName>" \
  --paths "src/components/<Name>/<Name>.tsx src/components/<Name>/<Name>.css DESIGN-SYSTEM.md"

Always pass --paths with exactly the files you changed — open_pr.sh stages only those, so no stray working-tree file (a local .env, secrets, WIP) is swept into the PR. Use --no-push to commit without pushing.

Creates branch forge/edit/<name>-<slug>, commits code + regenerated brain section + any guidance in one commit, pushes, and runs gh pr create --base <git.prBase from forge.config.json, defaults to main> with a templated body (what changed, tokens touched, review checklist). If gh is absent it prints the exact push + PR commands and the branch name.

After the PR opens, offer to run design:accessibility-review and design:design-critique against the diff as automated reviewers.

Output to the user

Report concisely: component changed, the new/changed prop signature, that the brain section was regenerated (verified vs inferred), and the PR link (or branch + command if gh was unavailable). Don't paste the whole diff — link the PR.

Guardrails

• Never edit a component absent from the library — offer create-component.
• Never break an existing prop's contract without explicit confirmation.
• Never write raw color/spacing when a token exists.
• Always regenerate the brain section in the same commit as the code — they ship together or not at all.
• Respect the team rule ("keep components unmodified — discuss with the design system team"): every change goes through a PR into the configured base branch (forge.config.json git.prBase, defaults to main) for review.