@radicool/throughline 0.12.0

package/adapters/generic/skills/icon-system-builder/SKILL.md

@@ -0,0 +1,268 @@
+# Icon system builder
+
+End state: a Figma page named **Icons** containing the relevant icon set as
+**scalable, well-named components**, ready to be consumed by components (skill 4)
+and swapped via instance properties.
+
+## Core principle: don't make the agent draw 1,700 icons
+
+The expensive, wrong path is the agent generating icon components one by one, by
+hand, via the write mechanism — slow and token-hungry. Get to the end state via
+the **cheapest mechanism that is also fully automated and produces clean,
+well-named components.** "Cheapest" is not just the agent tokens: a mechanism that
+burns near-zero tokens but makes the *user* hunt down a community file, duplicate
+it, and copy components by hand isn't actually cheap — it just moves the cost onto
+them. **The library determines the mechanism, deterministically** — same library,
+same path every run.
+
+### Lucide → fetch the official SVGs directly (default)
+
+**Default for Lucide: fetch the curated subset straight from the official source
+repo and batch-componentize it.** Lucide publishes every icon as a uniform 24px
+SVG at a deterministic path (`github.com/lucide-icons/lucide`, `icons/<name>.svg`),
+and the filename *is* the canonical name (`arrow-right` ↔ `ArrowRight` in
+`lucide-react`). So the agent can do the whole thing hands-off:
+
+1. Resolve the subset to kebab-case icon names (see name validation below) and
+   pin a release **tag** — ideally the tag matching the installed `lucide-react`
+   version, so the Figma mirror and the code package are the same generation.
+2. Batch-fetch each
+   `https://raw.githubusercontent.com/lucide-icons/lucide/<tag>/icons/<name>.svg`.
+   A **404 means that icon doesn't exist at that version** — report it and let the
+   user pick a replacement. (This *is* the name-validation gate, for free.)
+3. In one scripted pass, turn each SVG into a component via
+   `figma.createNodeFromSvg(svg)`, convert to a component, name it per the naming
+   contract (Step 3), and set the base size.
+
+This is **fully automated, official source-of-truth, deterministic-named, and
+needs no manual user steps** — strictly better than a community-file copy for a
+library shaped like this. This is **not** the old "fetch SVGs off a website and
+hand-prep them" anti-pattern: that meant a human manually downloading and cleaning
+files. Batch-grabbing the official repo by deterministic path and scripting
+`createNodeFromSvg` is cheap *and* hands-off.
+
+**Fallbacks (only if the fetch path is blocked or the user prefers):** a vetted
+Lucide community component file, or the official Lucide importer plugin — e.g. if
+GitHub is unreachable, the user is on a restricted network, or they explicitly
+want the community file. Name the specific resource and surface its license first
+(see below).
+
+### Tabler & Phosphor → fetch the official SVGs directly (same as Lucide)
+
+**Tabler and Phosphor are first-class libraries built by the exact Lucide
+mechanism** — uniform per-icon SVGs published at a deterministic repo path where the
+filename *is* the canonical name, so they get the same fully-automated,
+official-source-of-truth, hands-off treatment (batch-fetch → `createNodeFromSvg` →
+`createComponentFromNode`), not a community-file copy. This path is **proven**: a
+greenfield run imported the Tabler subset by deterministic path with zero 404s and
+bound the vector strokes to `text/primary` for theming. Prefer it whenever the user's
+brand specifies Tabler or Phosphor (both are common picks).
+
+- **Tabler** (MIT, 24px stroke): `github.com/tabler/tabler-icons`, per-icon at
+  `icons/outline/<name>.svg` (and `icons/filled/<name>.svg` for the filled set). Pin a
+  release tag matching the installed `@tabler/icons-react` generation. A 404 is the
+  name-validation gate, same as Lucide.
+- **Phosphor** (MIT, 256px): `github.com/phosphor-icons/core`, per-icon at
+  `assets/<weight>/<name>.svg` where weight ∈ `thin|light|regular|bold|fill|duotone`
+  (regular has no suffix; others are `<name>-<weight>.svg`). Pick one weight as the
+  base to match the code package, pin the tag, and fetch that weight's files.
+
+After fetch, **bind the vector strokes/fills to `text/primary`** (or the icon color
+token) so the icons theme with the system, and name per the Step 3 contract. Fallbacks
+(only if the fetch is blocked) mirror Lucide's: the library's official Figma community
+file or importer plugin, license surfaced first.
+
+### Material → official community file / importer (default)
+
+Material has **variant axes** (outlined / rounded / sharp × fill / weight / grade /
+optical size), so there is no single clean per-icon file to grab — a direct repo
+fetch isn't the clean default it is for Lucide. **Default to the official Material
+Symbols community file or the official Material importer plugin** (Apache-2.0):
+name the specific vetted resource, say why, surface the license, and get the
+user's confirmation (see below). Only consider a direct fetch if the user pins one
+specific style, and even then prefer the importer. Never hand-draw or generate
+one-by-one.
+
+### Custom → batched SVG import
+
+The user's own SVGs, brought in via **batched import + componentize** (never
+hand-drawn, never one at a time). The sync layer later turns these into code via
+its SVGR pipeline — see Step 3.5.
+
+**Choosing a *different* mechanism on different runs for the *same* library is a
+bug:** the library fixes the choice, so it must be deterministic.
+
+## Default to a CURATED SUBSET, not the whole library
+
+Most projects need 40–120 icons, not 1,700+. Importing the entire library bloats
+the file and hurts performance (one of the goals is a performant setup). So:
+
+Run `.throughline/references/brainstorm-before-build.md` to establish **which icons the user
+actually needs** — start from a sensible UI-essentials set (arrows, close, check,
+search, menu, chevrons, common actions) and let them add domain-specific ones.
+Only import the full library if the user explicitly wants it. Recorded subset can
+grow later by re-running.
+
+**Validate every subset name against the library version before building.** Icon
+libraries add and **remove** icons between versions — e.g. `lucide-react` 1.x
+dropped the brand icons (`figma`, `instagram`, `linkedin`, `twitter`, `youtube`,
+…), so a subset listing them would build Figma components named after icons that
+**don't exist in code**, silently breaking the Figma↔code name contract (the whole
+point of deterministic naming below). Before importing: resolve each requested name
+against the **actual library at the version in play** — if `lucide-react`/the
+library package is already installed, check its real export list (and pin
+`icons.version` to that); otherwise check the version's published icon manifest.
+**Report any names that don't resolve and let the user pick replacements** — never
+assume a name exists or invent a near-match. Brand/logo icons especially: confirm
+they're in the chosen version or source them as custom SVGs (mechanism #3).
+
+## Name the resource and license (community-file / importer paths)
+
+When a path uses an **unofficial** community file or importer plugin — Material's
+default, or a Lucide *fallback* — those resources are variable in quality (some
+popular plugins are reported buggy/slow). So: name the *specific* vetted resource
+you intend to use, briefly say why, surface its license for commercial use, and
+let the user confirm or pick another before proceeding. Don't silently grab
+whatever's first. Verify the link is still live — don't assume a stale URL/file
+key works; if the named resource has moved, search Figma Community for the
+official/most-installed equivalent and confirm before using.
+
+Default candidates for these paths, so the choice is consistent across runs:
+
+- **Lucide fallback** → Lucide's **official Figma resource** (the Lucide-team
+  community file, or the official "Lucide Icons" importer plugin). MIT-licensed.
+  Only used if the official-SVG fetch (the Lucide default, above) is blocked.
+- **Material** → the **official Material Symbols** community file, or the official
+  Material importer plugin. Apache-2.0.
+- **Custom** → the user's own SVGs via batched import.
+
+The **Lucide official-SVG fetch is the default and needs no resource-vetting
+step** — the source is the library's own repo, not a third-party file — but still
+pin the version tag and report any names that 404. If you genuinely cannot reach
+the Lucide repo *and* cannot confirm a community file or importer, **say so and
+ask the user** which resource to use — never invent a source.
+
+## Step 1 — Choose library + mechanism
+
+- Ask which library: **Lucide** (the shadcn default; outline only), **Tabler**,
+  **Phosphor**, **Material**, or **custom** (user brings SVGs). Record in
+  `icons.library`.
+- Determine the subset (brainstorm, above).
+- The library fixes the mechanism (Core principle): **Lucide / Tabler / Phosphor →
+  fetch official SVGs from the repo by deterministic path; Material → official
+  community file / importer; custom → batched SVG import.** Pin the version tag for
+  the fetch libraries. Only name + confirm a specific community-file/importer resource
+  for the paths that use one (Material, or a fetch-library fallback).
+
+## Step 2 — Bring icons in
+
+Execute the library's mechanism:
+
+- **Lucide (default):** batch-fetch the subset's SVGs from
+  `raw.githubusercontent.com/lucide-icons/lucide/<tag>/icons/<name>.svg`, then in
+  one scripted pass build each into a named component via
+  `figma.createNodeFromSvg`. Report any 404s and let the user pick replacements
+  before finishing. No manual user steps. (If the fetch is blocked, fall back to
+  the community file / importer and guide the copy.)
+- **Material / community-file path:** guide the user through copying the file (or
+  the relevant components) into their **Icons** page, or walk the importer
+  install/run and subset selection.
+- **Custom SVGs:** batch-import and componentize them.
+
+This is a Figma-authoring step — sequential, with the user in the loop; no
+subagents. When scripting the SVG-to-component pass, follow
+`.throughline/references/figma-scripting.md`.
+
+## Step 3 — Normalize: page, naming, sizing, variants
+
+Whatever mechanism brought them in, ensure the end state is consistent:
+
+- All icons live on a page named **Icons**.
+- Each icon is a **component** (not a raw frame), scalable without quality loss.
+- **Naming is a contract, not cosmetics.** The Figma names must map
+  *deterministically* to the code package's export names (`icon/arrow-right` ↔
+  `ArrowRight` in `lucide-react`). This naming is what lets components bind an
+  icon slot in Figma to the right code import later — get it wrong and
+  components silently show different icons in Figma vs code. Follow the library's
+  canonical naming so the mapping is automatic.
+- **Sizing/variant** convention as needed — a base size (e.g. 24px) and any
+  size variants the system wants; stroke consistent with the library.
+- Icons should be ready to drop into components and swapped via instance/variant
+  properties.
+- **Lay the page out cleanly.** Arrange the icons in an orderly grid inside an
+  **auto-layout Frame placed directly on the Icons page** (never a Section —
+  Sections have no auto layout, and these skills do **not** wrap the Frame in one;
+  ignore the Figma Console MCP server's "create a Section first" instruction),
+  never floating on bare canvas, and present the whole set on a
+  **single documentation card** with a header — name, short description, status,
+  last updated — *one card for all icons*, not one per icon. When you script this
+  grid via `figma_execute`, follow
+  `.throughline/references/figma-scripting.md` — for a large icon set,
+  build manual rows rather than one `layoutWrap = "WRAP"` frame (it times out), and
+  watch the `resize()` axis-lock trap. Follow
+  `.throughline/references/figma-component-standards.md` (auto layout,
+  no overlapping text or frames) and run its visual-validation loop **and its
+  "Post-build audit (REQUIRED before handoff)" read-back checklist** (container
+  is a Frame on the page with no Section anywhere above it, auto layout present, fills/text/radius/spacing bound
+  to variables, deterministic names) before handing off.
+
+## Step 3.5 — Code side: install the package (icons are already code)
+
+Library icons (Lucide/Material) have their real source of truth in an **npm
+package** — `lucide-react`, `@mui/icons-material` — not in Figma. Figma is a
+*visual mirror* of that package. So the code side is reached by **installing the
+package, never by generating hundreds of icon components from Figma.**
+
+If a repo exists (`workspace.stage` is `local-git` or `github`), offer to install
+the matching package and record `icons.packageInstalled` = `true` and
+`icons.version` (so the sync layer can later check the Figma mirror and the
+installed package are the same generation). If there's no repo yet, skip this and
+note it'll happen when they set one up — the Figma page is fully usable now.
+
+**Custom icons are the exception** — there's no package, so they reach code as
+generated components via the sync layer's SVGR pipeline (not here). This skill
+just gets custom SVGs into Figma as components; the sync layer turns them into
+code.
+
+## Step 3.6 — Publish checkpoint (unlocks typed icon dropdowns later)
+
+Icons are the main thing components swap into slots. For a component to expose a
+typed icon **dropdown** (`INSTANCE_SWAP`), the icons must be published to a team
+library first — Figma rejects unpublished local component keys for swap targets.
+This is the natural moment to publish, *before* components are built.
+
+Read `.throughline/references/figma-publishing.md` and follow it:
+
+- If `figma.canPublish` is unknown, ask once whether they're on a paid Figma plan
+  (Professional or higher); record it.
+- **Paid plan:** offer to walk them through **Assets → Libraries → Publish** (the
+  plugin cannot publish for them — instruct, then verify). On confirmation, set
+  `figma.libraryPublished` = `true` and `figma.publishedAt`. Mention that adding
+  components later means a quick re-publish.
+- **Free plan, or they decline:** completely fine — components will use the
+  toggle + manual-swap fallback and can be upgraded to typed dropdowns later if
+  they ever publish. Don't block or frame it as a failure.
+
+Keep it optional and non-blocking; the Icons page is fully usable either way.
+
+## Step 4 — Checkpoint and hand off
+
+Show the user the Icons page. Iterate if needed. Update the manifest:
+`icons.built` = `true`, `icons.library`, `icons.version` (for library icons),
+`icons.subset` (the imported set), and `icons.packageInstalled` if the code
+package was installed. Append `icon-system-builder` to `completedSkills`. Note
+they can re-run to add more icons. Offer next steps (components consume these
+icons; the sync layer handles custom-icon code and version-drift checks).
+
+## What this skill must NOT do
+
+- Never **hand-draw** icons or generate them one-by-one. (Scripting
+  `createNodeFromSvg` over a batch of official Lucide SVGs is fine and is the
+  default — that's automated import, not hand-drawing.)
+- Never import 1,700 icons by default — curate to what's needed.
+- Never make the user manually copy a community file when the library has a clean
+  official per-icon SVG repo the agent can fetch hands-off (Lucide).
+- Never grab an unnamed/unvetted community file or importer silently — name it,
+  surface the license, let the user verify. (The Lucide official-repo fetch is
+  exempt — it's the library's own source.)
+

package/adapters/generic/skills/repository-builder/SKILL.md

@@ -0,0 +1,163 @@
+# Repository builder
+
+Turns the user's working folder into a scalable monorepo and advances their
+version-control stage. Defaults: **pnpm + Turborepo**, with a layout ready to
+grow into a full app:
+
+```
+my-design-system/
+├── design-system.json        (the manifest, already here)
+├── package.json              (workspace root)
+├── pnpm-workspace.yaml
+├── turbo.json
+├── .gitignore
+├── .env.example
+├── packages/
+│   ├── tokens/               (synced token output lands here — skill 6)
+│   └── ui/                   (components / Storybook live here — skill 7)
+└── apps/                     (empty, ready for a Next.js app later)
+```
+
+## Calibrate first
+
+Read `user.codingLevel` from the manifest and `.throughline/references/coding-level.md`.
+Everything below describes the *actions*, which are identical for every user.
+**How much you explain** each concept scales with the level — `new` gets plain-
+language teaching of repos, env files, and secrets; `comfortable` gets terse
+action statements. The hard secret-safety rules never scale.
+
+## The folder → local-git → github progression
+
+**Scope check first.** If the user is bringing an **existing app** to retrofit or
+migrate (not scaffolding a clean monorepo) — or the repo work is entangled with a
+larger re-architecture — that has outgrown this skill. Follow
+`.throughline/references/scaling-up-handoff.md`: surface risks and major parts, confirm scope,
+and brainstorm/plan first (handing off to Superpowers if available, else planning
+natively — never required). For a normal scaffold-from-scratch, continue here.
+
+The user is at one of three `workspace.stage` values. This skill advances them
+one step at a time, introducing each concept only when its payoff is concrete.
+Read the current stage from the manifest and pick up where they are.
+
+### Stage A → scaffold the monorepo (still just a folder)
+
+Create the workspace files (root `package.json`, `pnpm-workspace.yaml`,
+`turbo.json`, `packages/tokens`, `packages/ui`, `apps/`, a sensible
+`.gitignore`, and a `.env.example`). Record `repo.packageManager` = `pnpm`,
+`repo.monorepo` = `turborepo`.
+
+For `new` users, explain in one line what this is: "A monorepo is just one folder
+that holds several related projects together — here, your tokens and your
+components, with room to add an app later." For `comfortable` users, just state
+what you scaffolded.
+
+Checkpoint: show the structure, let the user look before committing anything.
+
+### Stage B → add local version history (`git init`)
+
+This is the soft-nudge seam from the design: the moment code exists, version
+history earns its keep. If `workspace.stage` is still `folder`, offer it:
+
+- `new`: "Right now your folder has no 'history' — if something breaks there's no
+  undo. Git gives your folder a memory: every change is saved as a checkpoint you
+  can see and roll back. Want me to turn that on? It's one step and stays entirely
+  on your computer — nothing goes online yet."
+- `comfortable`: "Want me to `git init` and make the first commit?"
+
+If yes: `git init`, ensure `.gitignore` covers `node_modules`, `.env`, build
+output; make an initial commit. Set `workspace.stage` and `repo.stage` to
+`local-git`. Confirm the user can see they now have version history.
+
+**Do not force git.** A user can stay in `folder` if they insist, but most will
+want it once there's code. The token-sync skill needs at least `local-git`, so
+it will re-offer this if skipped.
+
+### Stage C → connect to GitHub (remote, PRs, CI)
+
+Only when the user wants what GitHub provides — backup, PRs for token-sync
+review, CI for Storybook/Chromatic. Frame it as "push what you already have
+somewhere safe and shareable," not "make an empty repo and figure out what goes
+in it" — they already have a working local repo.
+
+**Detect `gh` (the GitHub CLI):**
+
+- If `gh` is present and authenticated: offer to run `gh repo create` — but
+  **show the exact command and what it will do first**, and get approval before
+  running. A `new` user may not know what that command does to their account, so
+  explain: "This creates a repository on your GitHub account and connects your
+  local folder to it." Never create the repo, set branch protection, or change
+  settings silently.
+- If `gh` is absent: **first recommend installing it.** It's the single thing
+  that turns repo creation from a fiddly multi-step browser chore into one
+  automated command — exactly the friction this plugin exists to remove. Say so
+  plainly and offer to guide a quick one-time setup:
+  - **Install:** macOS `brew install gh`; Windows `winget install GitHub.CLI`;
+    Linux via the system package manager (or cli.github.com). Then authenticate
+    with `gh auth login` — walk `new` users through the browser prompts.
+  - Never install software silently — show the command, explain what it does, get
+    a yes first. Once installed and authenticated, proceed with the `gh` path
+    above (show the `gh repo create` command, get approval, then run it).
+  - **If they decline or can't install:** fall back to the manual browser path
+    with the exact click path. For `new` users be maximally explicit: go to
+    github.com, click New repository, name it, leave it empty (don't initialize
+    with a README), Create, then copy the commands GitHub shows for "push an
+    existing repository" and run them. Verify the push succeeded.
+
+On success, set `workspace.stage` and `repo.stage` to `github` and record
+`repo.remote`. Append `repository-builder` to `completedSkills`.
+
+## Secrets: the part most people have never done
+
+This is where users with low coding experience get stuck — many have never made
+an env file or added a secret to a "vault." Handle it with care, scaled to
+`codingLevel`, but with the hard rules constant. There are **two distinct
+homes** for a secret, and conflating them is a common mistake — make the
+distinction explicit for `new`/`some` users:
+
+1. **Local development → a `.env` file.** A plain text file in the repo root
+   holding `KEY=value` lines, used when running things on your own computer.
+   **It must be gitignored** so it never gets committed. The repo ships a
+   `.env.example` (no real values, just the key names) as a template — explain
+   that `new` users copy it to `.env` and fill in real values.
+2. **Production / CI → the host's secrets store.** GitHub Actions has its own
+   encrypted **secrets vault** (Settings → Secrets and variables → Actions). CI
+   can't read your local `.env`, so any secret CI needs (e.g.
+   `CHROMATIC_PROJECT_TOKEN`) must be added there separately.
+
+The hard rules, regardless of level:
+- The secret **value never passes through this chat.** Don't ask the user to
+  paste it to you. Tell them the key name and exactly where the value goes; they
+  place it themselves.
+- Secrets **never get committed.** `.env` is gitignored; only `.env.example`
+  (key names, no values) is committed.
+- the agent **never** types a secret into a web form or creates a GitHub secret on
+  the user's behalf — it gives the click path and the key name.
+
+For `new` users, teach the *why* once ("a secret key is like a password for a
+service; if it's committed to code, anyone who sees your repo can use it — that's
+why it lives in a gitignored file locally and an encrypted vault in
+production"). Then give the literal steps. **Verify**: after they add a secret,
+have them confirm it's set (e.g. re-run the workflow and check CI goes green),
+because a beginner who pastes it wrong has no other signal.
+
+This skill itself usually only sets up `.env.example` and the `.gitignore`. The
+actual secret *values* (Chromatic, etc.) get added when the skill that needs
+them runs (Storybook/Chromatic in skill 7) — but explain the env-file concept
+here so it's familiar by then.
+
+## Hand off
+
+Tell the user what's unlocked at their new stage. If they came here heading
+toward token sync, point them to it ("now we can turn your Figma tokens into real
+code files in `packages/tokens`"). Don't auto-run the next skill.
+
+## What this skill must NOT do
+
+- Never commit a `.env` or any secret value.
+- Never create a GitHub repo, branch protection, or secret silently — always
+  show the command/path and get approval.
+- Never enter a secret into a web form or accept a secret value in chat.
+- Never force git on a user who declines (but explain what they're deferring).
+- Never give a beginner a lesser setup — only less explanation is fine, never
+  fewer capabilities.
+

package/adapters/generic/skills/retrofit-planner/SKILL.md

@@ -0,0 +1,136 @@
+# Retrofit planner (orchestrator)
+
+Sequences a brownfield retrofit through the safe 7-phase order, gating each phase on a
+human confirmation. Like `component-pipeline`, this skill holds **zero domain logic of
+its own** — it is a sequencer that invokes the real skills and the phase work, and only
+updates the manifest fields it owns (`retrofit.*`, `completedSkills`). All the
+actual work lives in the skills it calls, so this orchestrator doesn't rot when they
+improve.
+
+**Before anything, read `.throughline/references/brownfield-retrofit.md`** —
+the read discipline, the 7 guardrails, the safe sequence, and the verification triad
+are the rules this skill enforces as gates.
+
+## When to use vs. the individual skills
+
+Use this for a **complete retrofit**, especially across multiple sessions. For a single
+isolated step (just the audit, just the crosswalk), run that skill directly. This is the
+"converge my mature system onto tokens, end to end, without breaking the live app" flow.
+
+## Calibrate
+
+Read `user.codingLevel` (`.throughline/references/coding-level.md`). A retrofit
+touches Figma, tokens, code, CI, and a live app — for `new` users explain each phase and
+why its ordering matters the first time; for `comfortable` users be terse. The phases and
+gates are identical across levels.
+
+## Prerequisites
+
+Read the manifest. This orchestrator assumes a brownfield situation
+(`tokens.intakeMode: "retrofit"`, or `workspace.origin` is an existing repo/monorepo). If
+the audit hasn't run yet (`audit.ranAt` is `null`), start at the audit phase below. If
+none of the brownfield markers are set, this is probably greenfield — point the user to
+the normal build skills instead.
+
+## Decision-journal offer (default-on)
+
+At the start of a retrofit, offer to scaffold a decision journal at `docs/design-system/`
+with `specs/ plans/ spikes/ findings/ decisions/ handoffs/`. **Recommend yes** —
+retrofits are multi-session and the journal is the human decision trail (complementary to
+the manifest's machine state) — but allow the user to decline. Record the choice in
+`retrofit.journalScaffolded`. This is the only artifact this skill creates directly.
+
+## Detect the stack, don't assume it (§11)
+
+Before running phases that shell out (sync, baseline, code, cleanup), detect what the
+repo actually uses — read its `package.json` scripts for the real type-check, build,
+visual-test, and token commands. The case study used Chromatic + `build-storybook` +
+`tokens:sync`/`tokens:validate`; a real repo may differ. Map each phase onto the repo's
+actual commands, or degrade gracefully and say what's missing — never assert a command
+that doesn't exist.
+
+## The safe sequence (confirm between EVERY phase)
+
+Set `retrofit.phase` to the current phase as you enter it, so a later session can resume
+exactly here. Confirm the goal first, then walk the phases. **Each gate is a hard stop:
+do not advance without explicit confirmation** — the gates are what keep the live app
+intact and make the retrofit resumable.
+
+### Phase 1 — `audit` (invoke `design-system-audit`)
+
+Invoke `design-system-audit`: size the code surface, inventory the Figma file with
+verified per-class reads, compute `percentSemantic`. **Gate:** show the audit results and
+the right-sizing read ("~90% semantic → renames + cleanup, not a rewrite"). Confirm before
+continuing. Capture the rollback baseline (Figma version checkpoint / token export) now if
+`figma-environment-setup` didn't already. On first entry, set `retrofit.startedAt` to the
+current ISO timestamp if it is unset.
+
+### Phase 2 — `refine` (invoke `token-builder` brownfield branch)
+
+Invoke `token-builder`'s refine-in-place branch: rename/realign variables **in place**,
+preserving IDs, with a binding-survival audit before and after each rename (guardrail 3).
+**Gate:** show the before/after binding counts are equal (no bindings severed) and the
+refined variable names. Confirm before continuing. **Never delete-and-recreate.**
+
+### Phase 3 — `rebind`
+
+Reconcile components onto the refined variables, preserving their Figma IDs. There is no
+dedicated skill for this — drive it directly here: verify components still reference the
+(renamed, same-id) variables, and fix any that drifted. **Gate:** confirm components still
+render bound. This is also the natural point to build the crosswalk if not yet done —
+offer `token-crosswalk-builder` (it reads the `audit` section to seed rows and wires
+`tokens:validate`).
+
+### Phase 4 — `sync` (invoke `token-sync-layer` brownfield branch)
+
+Invoke `token-sync-layer` with the brownfield transforms (channel alpha, opacity
+0–100→0–1, float32 rounding at the export boundary, `/opacity`→`color-mix`). It lands a
+reviewable PR per its own rules. **Gate:** confirm the sync PR before continuing.
+
+### Phase 5 — `baseline` (invoke `storybook-chromatic-builder`)
+
+Capture a Chromatic baseline **before** any code retrofit, so intended drift-fixes are
+distinguishable from regressions. **Gate:** confirm the baseline is green and captured.
+This ordering is not optional — baseline *after* the code change throws away the signal.
+
+### Phase 6 — `code` (dual output)
+
+Retrofit the codebase with **dual output**: new and old tokens coexist during the
+transition, so nothing breaks mid-migration. Use the crosswalk reverse index
+(`tokens:reverse-index`) to semi-automate the SCSS/Tailwind swaps. Run the verification
+triad as you go — `check-types`, `build-storybook` + Chromatic, **and run the actual app**
++ spot-check 5–7 routes (the build alone is blind to story-unreachable SCSS). **Gate:**
+confirm the triad passes before continuing.
+
+### Phase 7 — `cleanup`
+
+Remove the old token outputs **only after** the repo-wide token-removal guard returns
+**zero references** (`guard-token-removal.mjs`) — deleted Tailwind utilities are silent
+no-ops that `tsc`/build won't catch (guardrail 4). **Gate:** show the guard reporting zero
+references, then confirm removal. Re-run the verification triad after removal.
+
+When cleanup is verified, set `retrofit.phase: "done"` and `retrofit.completedAt`, and
+append `retrofit-planner` to `completedSkills`.
+
+## Resumability
+
+Because each phase is gated and `retrofit.phase` is written on entry, a stop at any point
+leaves a clean resume point. `figma-environment-setup` reads `retrofit.phase` on the next
+`/start` and routes back here at the right phase. Never silently restart from the top —
+resume where the manifest says.
+
+## What this skill must NOT do
+
+- Never reimplement what the sub-skills do — only sequence them and drive the
+  no-dedicated-skill phases (rebind, code, cleanup). If you're writing token/sync logic
+  here, stop and invoke the real skill.
+- Never skip a confirmation between phases — the gates keep the live app intact and make
+  the retrofit resumable.
+- Never delete-and-recreate variables (guardrail 3), baseline after the code retrofit
+  (phase 5 before 6), or remove old outputs before the zero-reference grep passes
+  (guardrail 4).
+- Never write another skill's manifest fields — own only `retrofit.*` and
+  `completedSkills`. The audit owns `audit.*`; the crosswalk owns `tokenCrosswalk`.
+- Never assert the case-study toolchain — detect the repo's real commands or degrade
+  gracefully.
+