Forge — Delete Component

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

Removing a component is breaking by nature — anything importing it breaks. So this skill defaults to deprecation, and only hard-deletes when the user explicitly accepts the break after seeing who uses it. Either way the brain is updated and the change ships as a PR into the base branch from forge.config.json git.prBase (defaults to main).

When this triggers

The user wants a component gone. First confirm it exists: find its section in ${CLAUDE_PLUGIN_ROOT}/skills/_shared/DESIGN-SYSTEM.md and its source dir in the repo. If it isn't there, say so and stop.

Step 0 — Usage check (always, before anything)

Find everyone who depends on it:

grep -rn "<Name>\b" "<repo>/src" --include=*.tsx --include=*.ts \
  | grep -v "<Name>/<Name>"        # exclude its own files
grep -n "<Name>\b" "<repo>/src/index.ts" "<repo>"/src/index*.ts

Report the count and the call sites. Read the standard's deprecation policy: ${CLAUDE_PLUGIN_ROOT}/skills/_shared/references/component-standard.md §7–8.

Step 1 — Decide: deprecate (default) or hard-delete

• Deprecate (default, non-breaking): the right move whenever there are usages, or whenever the user hasn't explicitly asked to break things.
• Hard-delete: only if the user explicitly confirms removal AND (it has no internal usages, or they accept fixing them). Hard delete = a major-version change per §8.

If unsure, deprecate and tell the user how to escalate to a full removal later.

Path A — Deprecate (non-breaking)

1. Mark the component /** @deprecated <reason / replacement> */ on its export.
2. Keep it exported from the barrel. Don't touch its files otherwise.
3. In the brain, add a > **Deprecated:** <reason> line under the component's ## <Name> heading (regenerate via the edit path, or hand-add the line).
4. PR (see Step 3) with --action deprecate.

Path B — Hard-delete (breaking, confirmed)

1. Remove its export(s) from the package barrel (src/index.ts / index*.ts).
2. Delete its source dir src/components/<Name>/ (tsx + css + stories + test).
3. Fix any internal call sites found in Step 0 (or the build will fail — verify).
4. Remove its brain section:

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

   The canonical brain is <repo>/DESIGN-SYSTEM.md (committed in this PR); the plugin's ${CLAUDE_PLUGIN_ROOT}/skills/_shared/DESIGN-SYSTEM.md stays in sync via the consuming workflow — never target it on writes. Tokens for any follow-on rebuild_brain.py --brain "<repo>/DESIGN-SYSTEM.md" come from <repo>/forge.config.json repo.tokensCss (passed as --tokens-css). Also remove its row from the Component index table near the top of the brain.
5. PR with --action delete.

Step 2 — Verify the build

Before opening the PR, confirm the repo still builds and type-checks (a hard delete that misses a call site will fail CI):

cd <repo> && npm run build && npx tsc --noEmit

Don't open a PR that doesn't build.

Step 3 — Open the PR (into the configured base branch)

bash "${CLAUDE_PLUGIN_ROOT}/skills/_shared/scripts/open_pr.sh" \
  --repo <repo> --component <Name> --action <deprecate|delete> \
  --summary "Deprecate <Name>" \
  --paths "src/components/<Name>/ src/index.ts DESIGN-SYSTEM.md"

Branch forge/<action>/<name>-<slug>, single commit (code + brain update), PR into the base branch from forge.config.json git.prBase (defaults to main). The PR body lists the usage-check result so reviewers see the blast radius.

Output to the user

Report: which path was taken (deprecate vs delete), how many usages were found and where, what the brain change was, build/type-check result, and the PR link (or branch + command). For a hard delete, restate that it's a breaking, major-version change.

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

Guardrails

• Never hard-delete without an explicit confirmation and a usage check first.
• Default to deprecation whenever usages exist or intent is ambiguous.
• Never open a PR that doesn't build/type-check.
• Brain (section + index row) updates in the same commit as the code.
• Hard delete = breaking → call it out as a major-version change.