@radicool/throughline 0.12.0 → 0.13.0

package/README.md

@@ -154,7 +154,7 @@ For the technically curious — how the machine actually runs.
 
 **Modes, within Figma's limits.** Light/Dark lives on the semantic collections; brand variants live on the primitive palette. Splitting the two axes across two collections keeps each one under Figma's 4-modes-per-collection cap on the Professional plan while still resolving correctly (`bg/default` → `{gray/50}` → the active brand's gray).
 
-**Model routing.** Setup runs on **Haiku** automatically to keep first-run costs low. Everyday work runs on whatever model your session is set to — **Sonnet** is a sensible default. For the heaviest authoring (large token systems, intricate variant matrices), **Opus** gives the best results: `/model opus`, then back to `/model sonnet`. Nothing forces an expensive model on you.
+**Model routing.** ThroughLine routes work by *cognition, not guesswork* — the expensive thinking on the best model, the mechanical doing on a cheap one. Setup runs on **Haiku** automatically to keep first-run costs low. Inside a skill, the deciding — a token architecture, a variant matrix, a slot contract — is planned once on the strongest tier, while the long mechanical part — placing Figma nodes, transcribing component code, running SVGR — runs on a cheap tier and self-verifies. You get the best model where it matters and a cheap one where it doesn't, without micromanaging it. The recommended mapping is **Haiku → Sonnet → Opus** for the `fast < balanced < deep` tiers, but nothing is hardcoded — the ladder resolves against whatever models your install actually has, and on hosts without subagents skills degrade cleanly to a single model. You can still steer the session yourself (`/model opus` for the heaviest authoring, back to `/model sonnet` after); nothing forces an expensive model on you.
 
 ## Who it's for
 

package/adapters/codex/prompts/component-builder.md

@@ -88,8 +88,23 @@ of the primitive→semantic token seam:
    slot the atoms.
 
 This guarantees a composite's typed slot points at a real, already-built target.
-Build bottom-up; checkpoint after each component (sequential — this is Figma
-authoring, no subagents).
+Build bottom-up in dependency order.
+
+**Execution model — sequential subagents with model routing.** If your host
+supports subagent dispatch, plan the whole set once with one **architect**
+dispatch (deep tier) — it reads existing Figma state and emits a
+transcription-grade spec in stable identifiers — then build **each component**
+with one **figma-executor** dispatch (fast→balanced), strictly sequentially:
+preflight `figma_get_status` and never run two Figma-touching subagents at once
+(the single bridge is concurrency-1). Each executor builds into a `WIP:` frame
+and finalizes by build-verify-then-replace (see
+`.throughline/references/figma-scripting.md`); gate each finished
+component with a **reviewer** visual pass. Route per
+`.throughline/references/agent-routing.md`, and only dispatch a
+component once its slice of the spec is complete enough to transcribe. **Keep the
+human checkpoint between components** — subagents run continuously within a
+component, but you pause for the human between them. If your host has no subagent
+dispatch, build and verify each component inline, sequentially, as before.
 
 ## Step 3 — Build each component, bound to tokens/styles
 

package/adapters/codex/prompts/icon-system-builder.md

@@ -169,8 +169,16 @@ Execute the library's mechanism:
   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
+**Execution model — sequential Figma-lane subagent with model routing.** If your
+host supports subagent dispatch, run the bring-in + componentize pass as a
+**`figma-executor`** dispatch (balanced tier): preflight `figma_get_status`,
+never run two Figma-touching subagents at once (the single bridge is
+concurrency-1), build into a `WIP:` frame and finalize by build-verify-then-
+replace with the read-back audit in Step 3. The subset + naming contract were
+already settled with the user in Step 1, so no separate architect dispatch is
+needed here. Route per `.throughline/references/agent-routing.md`. If
+your host has no subagent dispatch, script the SVG-to-component pass inline,
+sequentially, with the user in the loop. Either way, follow
 `.throughline/references/figma-scripting.md`.
 
 ## Step 3 — Normalize: page, naming, sizing, variants

package/adapters/codex/prompts/storybook-chromatic-builder.md

@@ -67,13 +67,19 @@ Match the deterministic naming so `Button` (Figma) ↔ `Button` (code).
 
 ## Step 3 — Generate stories (subagent-driven, parallel)
 
-Story generation is independent and verifiable per component, so use the
-**subagent-driven model** (code-gen skills parallelize; this is the opposite of
-the sequential Figma-authoring skills): dispatch one subagent per component to
-write its stories — a story per meaningful variant, controls wired to props,
-slot props demonstrated. Each subagent verifies its work (the story builds and
-renders). Two-stage review (does it match the component spec; is it quality
-code) before combining.
+Story generation is independent and verifiable per component, so it
+parallelizes — one worker per component, unlike the concurrency-1 Figma lane.
+
+**Execution model — parallel subagents with model routing.** If your host
+supports subagent dispatch, dispatch **one `code-executor` per component** (fast
+tier) to write its stories — a story per meaningful variant, controls wired to
+props, slot props demonstrated — each verifying its own work (the story builds
+and renders); then a **`reviewer`** (balanced) two-stage pass (does it match the
+component spec; is it quality code) before combining. Route per
+`.throughline/references/agent-routing.md`, and only dispatch a
+component once its story spec is complete enough to transcribe. If your host has
+no subagent dispatch, generate and verify each component's stories inline
+instead.
 
 **Controls must actually drive the component (args-through render).** A `render`
 that ignores its args silently breaks the Controls panel — the toggle writes to

package/adapters/codex/prompts/token-builder.md

@@ -51,6 +51,22 @@ and why large `WRAP` grids time out. For a simple verification read, prefer the
 dedicated `figma_get_variables` tool (it handles dynamic-page correctly and
 resolves aliases with `resolveAliases: true`) over a hand-written script.
 
+**Execution model — sequential architect → figma-executor with model routing.**
+If your host supports subagent dispatch, plan the token architecture once with
+one **architect** dispatch (deep tier) — it reads existing Figma state and emits
+a transcription-grade spec in stable identifiers (collection/variable *names*,
+never nodeIds) — then build the variables with **figma-executor** dispatches
+(balanced tier), strictly sequentially: preflight `figma_get_status` and never
+run two Figma-touching subagents at once (the single bridge is concurrency-1).
+Each executor finalizes by build-verify-then-replace with a programmatic
+read-back (`figma_get_variables`, not a screenshot); gate the result with a
+**reviewer** pass. **Keep the human checkpoint between tiers** (the PAUSE in
+Steps 2–4) — subagents run continuously within a tier, but you pause for the
+human between them. Route per
+`.throughline/references/agent-routing.md`; never parallelize Figma
+work. If your host has no subagent dispatch, build and verify each tier inline,
+sequentially, as the steps below describe.
+
 ## Step 1 — Brainstorm the structure (before building anything)
 
 Run the protocol in `.throughline/references/brainstorm-before-build.md`. **First establish

package/adapters/codex/prompts/token-sheet-builder.md

@@ -33,6 +33,20 @@ swatch/type grids — exactly the layouts that hit the two worst traps: the
 single-call `layoutWrap = "WRAP"` timeout on big grids (build manual rows or split
 across calls instead). Also run the single-bridge-instance preflight before writing.
 
+**Execution model — sequential architect → figma-executor with model routing.**
+If your host supports subagent dispatch, plan the sheet layout once with one
+**architect** dispatch (deep tier) — a lighter plan than token-builder's, since
+the tokens already exist; it emits a stable-identifier layout spec (which
+collections/sections, how much per-token detail) — then build the page with
+**figma-executor** dispatches (balanced tier), strictly sequentially: preflight
+`figma_get_status`, concurrency-1, `WIP:` frame + build-verify-then-replace with
+a programmatic read-back (spot-check that the swatches resolved to their bound
+variables via `figma_get_variables`, not just a screenshot), gated by a
+**reviewer** visual pass. Route per
+`.throughline/references/agent-routing.md`; never parallelize Figma
+work. If your host has no subagent dispatch, build and verify the page inline,
+sequentially, as the steps below describe.
+
 ## Step 1 — Brainstorm the layout (lightly)
 
 Run `.throughline/references/brainstorm-before-build.md`, but keep it light — this is a
@@ -141,7 +155,7 @@ refresh the "Last updated" date instead of creating a second Cover.)
 ## Step 3 — Checkpoint
 
 Show the user the Foundations page and the Cover page. Sequential review (this is
-a Figma-authoring skill — no subagents). Iterate on layout/styling if they want
+a Figma-authoring skill). Iterate on layout/styling if they want
 changes. Then update the manifest: `sheets.built` = `true`, append
 `token-sheet-builder` to `completedSkills`.
 

package/adapters/codex/prompts/token-sync-layer.md

@@ -139,13 +139,18 @@ register the platform, transform group, format, and `outputReferences`
 flattens). Web adapters emit `:root`/`.dark` (or `[data-theme]`); the shadcn
 adapter also emits a Tailwind preset.
 
-**Execution model — subagent-driven for multiple platforms.** When more than one
-platform is targeted, generating each platform's output is independent and
-verifiable, so dispatch **one subagent per adapter**: each produces its
+**Execution model — subagent dispatch with model routing.** Generating each
+platform's output is independent and verifiable. If your host supports subagent
+dispatch, dispatch **one `code-executor` per adapter** — each produces its
 platform's files and verifies them (the config builds, the expected files
-appear, references resolve correctly for web / flatten for native). Review each
-before combining. For a single platform, run inline. (See the selective-
-subagent decision: code-gen skills parallelize; Figma-authoring skills don't.)
+appear, references resolve for web / flatten for native) — then a **`reviewer`**
+to check each before combining. Choose each subagent's model from its role tier
+per `.throughline/references/agent-routing.md` (`code-executor` → fast,
+`reviewer` → balanced), and only dispatch once each adapter's spec is complete
+enough to transcribe. If your host has no subagent dispatch, generate and verify
+each adapter inline instead. For a single platform, run inline either way. This
+is a code-gen stage, so these subagents may run in parallel — unlike Figma
+authoring, which is always sequential.
 
 ## Step 4 — Build and place outputs
 
@@ -169,7 +174,9 @@ icons (`icons.built` true):
 - **Custom icons** — these the repo owns, so generate them: export the custom
   SVGs from Figma, optimize, and componentize via SVGR into `packages/ui` (or a
   dedicated icons package). This is real code generation and rides the same
-  PR-review and subagent model as token output.
+  **`code-executor` (fast) + `reviewer` (balanced)** routing and PR-review as
+  token output (SVGR transforms are the textbook mechanical op the fast tier is
+  for) — see the Step 4 execution model.
 
 ## Step 5 — Full regeneration + rename detection (the safety net)
 

package/adapters/cursor/.cursor/rules/component-builder.mdc

@@ -92,8 +92,23 @@ of the primitive→semantic token seam:
    slot the atoms.
 
 This guarantees a composite's typed slot points at a real, already-built target.
-Build bottom-up; checkpoint after each component (sequential — this is Figma
-authoring, no subagents).
+Build bottom-up in dependency order.
+
+**Execution model — sequential subagents with model routing.** If your host
+supports subagent dispatch, plan the whole set once with one **architect**
+dispatch (deep tier) — it reads existing Figma state and emits a
+transcription-grade spec in stable identifiers — then build **each component**
+with one **figma-executor** dispatch (fast→balanced), strictly sequentially:
+preflight `figma_get_status` and never run two Figma-touching subagents at once
+(the single bridge is concurrency-1). Each executor builds into a `WIP:` frame
+and finalizes by build-verify-then-replace (see
+`.throughline/references/figma-scripting.md`); gate each finished
+component with a **reviewer** visual pass. Route per
+`.throughline/references/agent-routing.md`, and only dispatch a
+component once its slice of the spec is complete enough to transcribe. **Keep the
+human checkpoint between components** — subagents run continuously within a
+component, but you pause for the human between them. If your host has no subagent
+dispatch, build and verify each component inline, sequentially, as before.
 
 ## Step 3 — Build each component, bound to tokens/styles
 

package/adapters/cursor/.cursor/rules/icon-system-builder.mdc

@@ -173,8 +173,16 @@ Execute the library's mechanism:
   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
+**Execution model — sequential Figma-lane subagent with model routing.** If your
+host supports subagent dispatch, run the bring-in + componentize pass as a
+**`figma-executor`** dispatch (balanced tier): preflight `figma_get_status`,
+never run two Figma-touching subagents at once (the single bridge is
+concurrency-1), build into a `WIP:` frame and finalize by build-verify-then-
+replace with the read-back audit in Step 3. The subset + naming contract were
+already settled with the user in Step 1, so no separate architect dispatch is
+needed here. Route per `.throughline/references/agent-routing.md`. If
+your host has no subagent dispatch, script the SVG-to-component pass inline,
+sequentially, with the user in the loop. Either way, follow
 `.throughline/references/figma-scripting.md`.
 
 ## Step 3 — Normalize: page, naming, sizing, variants

package/adapters/cursor/.cursor/rules/storybook-chromatic-builder.mdc

@@ -71,13 +71,19 @@ Match the deterministic naming so `Button` (Figma) ↔ `Button` (code).
 
 ## Step 3 — Generate stories (subagent-driven, parallel)
 
-Story generation is independent and verifiable per component, so use the
-**subagent-driven model** (code-gen skills parallelize; this is the opposite of
-the sequential Figma-authoring skills): dispatch one subagent per component to
-write its stories — a story per meaningful variant, controls wired to props,
-slot props demonstrated. Each subagent verifies its work (the story builds and
-renders). Two-stage review (does it match the component spec; is it quality
-code) before combining.
+Story generation is independent and verifiable per component, so it
+parallelizes — one worker per component, unlike the concurrency-1 Figma lane.
+
+**Execution model — parallel subagents with model routing.** If your host
+supports subagent dispatch, dispatch **one `code-executor` per component** (fast
+tier) to write its stories — a story per meaningful variant, controls wired to
+props, slot props demonstrated — each verifying its own work (the story builds
+and renders); then a **`reviewer`** (balanced) two-stage pass (does it match the
+component spec; is it quality code) before combining. Route per
+`.throughline/references/agent-routing.md`, and only dispatch a
+component once its story spec is complete enough to transcribe. If your host has
+no subagent dispatch, generate and verify each component's stories inline
+instead.
 
 **Controls must actually drive the component (args-through render).** A `render`
 that ignores its args silently breaks the Controls panel — the toggle writes to

package/adapters/cursor/.cursor/rules/token-builder.mdc

@@ -55,6 +55,22 @@ and why large `WRAP` grids time out. For a simple verification read, prefer the
 dedicated `figma_get_variables` tool (it handles dynamic-page correctly and
 resolves aliases with `resolveAliases: true`) over a hand-written script.
 
+**Execution model — sequential architect → figma-executor with model routing.**
+If your host supports subagent dispatch, plan the token architecture once with
+one **architect** dispatch (deep tier) — it reads existing Figma state and emits
+a transcription-grade spec in stable identifiers (collection/variable *names*,
+never nodeIds) — then build the variables with **figma-executor** dispatches
+(balanced tier), strictly sequentially: preflight `figma_get_status` and never
+run two Figma-touching subagents at once (the single bridge is concurrency-1).
+Each executor finalizes by build-verify-then-replace with a programmatic
+read-back (`figma_get_variables`, not a screenshot); gate the result with a
+**reviewer** pass. **Keep the human checkpoint between tiers** (the PAUSE in
+Steps 2–4) — subagents run continuously within a tier, but you pause for the
+human between them. Route per
+`.throughline/references/agent-routing.md`; never parallelize Figma
+work. If your host has no subagent dispatch, build and verify each tier inline,
+sequentially, as the steps below describe.
+
 ## Step 1 — Brainstorm the structure (before building anything)
 
 Run the protocol in `.throughline/references/brainstorm-before-build.md`. **First establish

package/adapters/cursor/.cursor/rules/token-sheet-builder.mdc

@@ -37,6 +37,20 @@ swatch/type grids — exactly the layouts that hit the two worst traps: the
 single-call `layoutWrap = "WRAP"` timeout on big grids (build manual rows or split
 across calls instead). Also run the single-bridge-instance preflight before writing.
 
+**Execution model — sequential architect → figma-executor with model routing.**
+If your host supports subagent dispatch, plan the sheet layout once with one
+**architect** dispatch (deep tier) — a lighter plan than token-builder's, since
+the tokens already exist; it emits a stable-identifier layout spec (which
+collections/sections, how much per-token detail) — then build the page with
+**figma-executor** dispatches (balanced tier), strictly sequentially: preflight
+`figma_get_status`, concurrency-1, `WIP:` frame + build-verify-then-replace with
+a programmatic read-back (spot-check that the swatches resolved to their bound
+variables via `figma_get_variables`, not just a screenshot), gated by a
+**reviewer** visual pass. Route per
+`.throughline/references/agent-routing.md`; never parallelize Figma
+work. If your host has no subagent dispatch, build and verify the page inline,
+sequentially, as the steps below describe.
+
 ## Step 1 — Brainstorm the layout (lightly)
 
 Run `.throughline/references/brainstorm-before-build.md`, but keep it light — this is a
@@ -145,7 +159,7 @@ refresh the "Last updated" date instead of creating a second Cover.)
 ## Step 3 — Checkpoint
 
 Show the user the Foundations page and the Cover page. Sequential review (this is
-a Figma-authoring skill — no subagents). Iterate on layout/styling if they want
+a Figma-authoring skill). Iterate on layout/styling if they want
 changes. Then update the manifest: `sheets.built` = `true`, append
 `token-sheet-builder` to `completedSkills`.
 

package/adapters/cursor/.cursor/rules/token-sync-layer.mdc

@@ -143,13 +143,18 @@ register the platform, transform group, format, and `outputReferences`
 flattens). Web adapters emit `:root`/`.dark` (or `[data-theme]`); the shadcn
 adapter also emits a Tailwind preset.
 
-**Execution model — subagent-driven for multiple platforms.** When more than one
-platform is targeted, generating each platform's output is independent and
-verifiable, so dispatch **one subagent per adapter**: each produces its
+**Execution model — subagent dispatch with model routing.** Generating each
+platform's output is independent and verifiable. If your host supports subagent
+dispatch, dispatch **one `code-executor` per adapter** — each produces its
 platform's files and verifies them (the config builds, the expected files
-appear, references resolve correctly for web / flatten for native). Review each
-before combining. For a single platform, run inline. (See the selective-
-subagent decision: code-gen skills parallelize; Figma-authoring skills don't.)
+appear, references resolve for web / flatten for native) — then a **`reviewer`**
+to check each before combining. Choose each subagent's model from its role tier
+per `.throughline/references/agent-routing.md` (`code-executor` → fast,
+`reviewer` → balanced), and only dispatch once each adapter's spec is complete
+enough to transcribe. If your host has no subagent dispatch, generate and verify
+each adapter inline instead. For a single platform, run inline either way. This
+is a code-gen stage, so these subagents may run in parallel — unlike Figma
+authoring, which is always sequential.
 
 ## Step 4 — Build and place outputs
 
@@ -173,7 +178,9 @@ icons (`icons.built` true):
 - **Custom icons** — these the repo owns, so generate them: export the custom
   SVGs from Figma, optimize, and componentize via SVGR into `packages/ui` (or a
   dedicated icons package). This is real code generation and rides the same
-  PR-review and subagent model as token output.
+  **`code-executor` (fast) + `reviewer` (balanced)** routing and PR-review as
+  token output (SVGR transforms are the textbook mechanical op the fast tier is
+  for) — see the Step 4 execution model.
 
 ## Step 5 — Full regeneration + rename detection (the safety net)
 

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

@@ -88,8 +88,23 @@ of the primitive→semantic token seam:
    slot the atoms.
 
 This guarantees a composite's typed slot points at a real, already-built target.
-Build bottom-up; checkpoint after each component (sequential — this is Figma
-authoring, no subagents).
+Build bottom-up in dependency order.
+
+**Execution model — sequential subagents with model routing.** If your host
+supports subagent dispatch, plan the whole set once with one **architect**
+dispatch (deep tier) — it reads existing Figma state and emits a
+transcription-grade spec in stable identifiers — then build **each component**
+with one **figma-executor** dispatch (fast→balanced), strictly sequentially:
+preflight `figma_get_status` and never run two Figma-touching subagents at once
+(the single bridge is concurrency-1). Each executor builds into a `WIP:` frame
+and finalizes by build-verify-then-replace (see
+`.throughline/references/figma-scripting.md`); gate each finished
+component with a **reviewer** visual pass. Route per
+`.throughline/references/agent-routing.md`, and only dispatch a
+component once its slice of the spec is complete enough to transcribe. **Keep the
+human checkpoint between components** — subagents run continuously within a
+component, but you pause for the human between them. If your host has no subagent
+dispatch, build and verify each component inline, sequentially, as before.
 
 ## Step 3 — Build each component, bound to tokens/styles
 

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

@@ -169,8 +169,16 @@ Execute the library's mechanism:
   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
+**Execution model — sequential Figma-lane subagent with model routing.** If your
+host supports subagent dispatch, run the bring-in + componentize pass as a
+**`figma-executor`** dispatch (balanced tier): preflight `figma_get_status`,
+never run two Figma-touching subagents at once (the single bridge is
+concurrency-1), build into a `WIP:` frame and finalize by build-verify-then-
+replace with the read-back audit in Step 3. The subset + naming contract were
+already settled with the user in Step 1, so no separate architect dispatch is
+needed here. Route per `.throughline/references/agent-routing.md`. If
+your host has no subagent dispatch, script the SVG-to-component pass inline,
+sequentially, with the user in the loop. Either way, follow
 `.throughline/references/figma-scripting.md`.
 
 ## Step 3 — Normalize: page, naming, sizing, variants

package/adapters/generic/skills/storybook-chromatic-builder/SKILL.md

@@ -67,13 +67,19 @@ Match the deterministic naming so `Button` (Figma) ↔ `Button` (code).
 
 ## Step 3 — Generate stories (subagent-driven, parallel)
 
-Story generation is independent and verifiable per component, so use the
-**subagent-driven model** (code-gen skills parallelize; this is the opposite of
-the sequential Figma-authoring skills): dispatch one subagent per component to
-write its stories — a story per meaningful variant, controls wired to props,
-slot props demonstrated. Each subagent verifies its work (the story builds and
-renders). Two-stage review (does it match the component spec; is it quality
-code) before combining.
+Story generation is independent and verifiable per component, so it
+parallelizes — one worker per component, unlike the concurrency-1 Figma lane.
+
+**Execution model — parallel subagents with model routing.** If your host
+supports subagent dispatch, dispatch **one `code-executor` per component** (fast
+tier) to write its stories — a story per meaningful variant, controls wired to
+props, slot props demonstrated — each verifying its own work (the story builds
+and renders); then a **`reviewer`** (balanced) two-stage pass (does it match the
+component spec; is it quality code) before combining. Route per
+`.throughline/references/agent-routing.md`, and only dispatch a
+component once its story spec is complete enough to transcribe. If your host has
+no subagent dispatch, generate and verify each component's stories inline
+instead.
 
 **Controls must actually drive the component (args-through render).** A `render`
 that ignores its args silently breaks the Controls panel — the toggle writes to

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

@@ -51,6 +51,22 @@ and why large `WRAP` grids time out. For a simple verification read, prefer the
 dedicated `figma_get_variables` tool (it handles dynamic-page correctly and
 resolves aliases with `resolveAliases: true`) over a hand-written script.
 
+**Execution model — sequential architect → figma-executor with model routing.**
+If your host supports subagent dispatch, plan the token architecture once with
+one **architect** dispatch (deep tier) — it reads existing Figma state and emits
+a transcription-grade spec in stable identifiers (collection/variable *names*,
+never nodeIds) — then build the variables with **figma-executor** dispatches
+(balanced tier), strictly sequentially: preflight `figma_get_status` and never
+run two Figma-touching subagents at once (the single bridge is concurrency-1).
+Each executor finalizes by build-verify-then-replace with a programmatic
+read-back (`figma_get_variables`, not a screenshot); gate the result with a
+**reviewer** pass. **Keep the human checkpoint between tiers** (the PAUSE in
+Steps 2–4) — subagents run continuously within a tier, but you pause for the
+human between them. Route per
+`.throughline/references/agent-routing.md`; never parallelize Figma
+work. If your host has no subagent dispatch, build and verify each tier inline,
+sequentially, as the steps below describe.
+
 ## Step 1 — Brainstorm the structure (before building anything)
 
 Run the protocol in `.throughline/references/brainstorm-before-build.md`. **First establish

package/adapters/generic/skills/token-sheet-builder/SKILL.md

@@ -33,6 +33,20 @@ swatch/type grids — exactly the layouts that hit the two worst traps: the
 single-call `layoutWrap = "WRAP"` timeout on big grids (build manual rows or split
 across calls instead). Also run the single-bridge-instance preflight before writing.
 
+**Execution model — sequential architect → figma-executor with model routing.**
+If your host supports subagent dispatch, plan the sheet layout once with one
+**architect** dispatch (deep tier) — a lighter plan than token-builder's, since
+the tokens already exist; it emits a stable-identifier layout spec (which
+collections/sections, how much per-token detail) — then build the page with
+**figma-executor** dispatches (balanced tier), strictly sequentially: preflight
+`figma_get_status`, concurrency-1, `WIP:` frame + build-verify-then-replace with
+a programmatic read-back (spot-check that the swatches resolved to their bound
+variables via `figma_get_variables`, not just a screenshot), gated by a
+**reviewer** visual pass. Route per
+`.throughline/references/agent-routing.md`; never parallelize Figma
+work. If your host has no subagent dispatch, build and verify the page inline,
+sequentially, as the steps below describe.
+
 ## Step 1 — Brainstorm the layout (lightly)
 
 Run `.throughline/references/brainstorm-before-build.md`, but keep it light — this is a
@@ -141,7 +155,7 @@ refresh the "Last updated" date instead of creating a second Cover.)
 ## Step 3 — Checkpoint
 
 Show the user the Foundations page and the Cover page. Sequential review (this is
-a Figma-authoring skill — no subagents). Iterate on layout/styling if they want
+a Figma-authoring skill). Iterate on layout/styling if they want
 changes. Then update the manifest: `sheets.built` = `true`, append
 `token-sheet-builder` to `completedSkills`.
 

package/adapters/generic/skills/token-sync-layer/SKILL.md

@@ -139,13 +139,18 @@ register the platform, transform group, format, and `outputReferences`
 flattens). Web adapters emit `:root`/`.dark` (or `[data-theme]`); the shadcn
 adapter also emits a Tailwind preset.
 
-**Execution model — subagent-driven for multiple platforms.** When more than one
-platform is targeted, generating each platform's output is independent and
-verifiable, so dispatch **one subagent per adapter**: each produces its
+**Execution model — subagent dispatch with model routing.** Generating each
+platform's output is independent and verifiable. If your host supports subagent
+dispatch, dispatch **one `code-executor` per adapter** — each produces its
 platform's files and verifies them (the config builds, the expected files
-appear, references resolve correctly for web / flatten for native). Review each
-before combining. For a single platform, run inline. (See the selective-
-subagent decision: code-gen skills parallelize; Figma-authoring skills don't.)
+appear, references resolve for web / flatten for native) — then a **`reviewer`**
+to check each before combining. Choose each subagent's model from its role tier
+per `.throughline/references/agent-routing.md` (`code-executor` → fast,
+`reviewer` → balanced), and only dispatch once each adapter's spec is complete
+enough to transcribe. If your host has no subagent dispatch, generate and verify
+each adapter inline instead. For a single platform, run inline either way. This
+is a code-gen stage, so these subagents may run in parallel — unlike Figma
+authoring, which is always sequential.
 
 ## Step 4 — Build and place outputs
 
@@ -169,7 +174,9 @@ icons (`icons.built` true):
 - **Custom icons** — these the repo owns, so generate them: export the custom
   SVGs from Figma, optimize, and componentize via SVGR into `packages/ui` (or a
   dedicated icons package). This is real code generation and rides the same
-  PR-review and subagent model as token output.
+  **`code-executor` (fast) + `reviewer` (balanced)** routing and PR-review as
+  token output (SVGR transforms are the textbook mechanical op the fast tier is
+  for) — see the Step 4 execution model.
 
 ## Step 5 — Full regeneration + rename detection (the safety net)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radicool/throughline",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "Build a complete design system end to end — author in Figma, sync tokens to code, generate Storybook. Usable from Claude Code, Cursor, Codex, or any AGENTS.md agent.",
   "type": "module",
   "bin": {

package/references/agent-routing.md

@@ -0,0 +1,70 @@
+# Agent routing — choosing a model per subagent
+
+**Claude-only.** This reference governs subagent dispatch, a Claude Code
+capability. Hosts without subagent dispatch (Codex, generic AGENTS.md) run the
+work inline on their single model and ignore this file.
+
+## Why route
+
+Do the *thinking* on the best model and the *doing* on a cheap one. Deciding a
+component's variant matrix, token architecture, or adapter strategy is reasoning
+— it earns the best model. Running the resulting spec — transcribing code,
+placing Figma nodes, emitting adapter output — is mechanical, and a cheap model
+does it well **once the plan is complete**.
+
+## The tier ladder
+
+Relative, never a hardcoded model name — installers have different plans, so we
+name a *capability tier* and resolve it against the models actually available.
+
+- `fast` — cheapest/fastest tier. Transcription-grade work from a complete spec.
+- `balanced` — mid tier. Judgment, integration, review scaled to risk.
+- `deep` — most capable tier available. Planning, architecture, hard reasoning.
+
+### Recommended mapping (Anthropic)
+
+| Tier | Recommended model |
+|---|---|
+| `fast` | Haiku |
+| `balanced` | Sonnet |
+| `deep` | Opus (or the most capable model you have) |
+
+**Override in one place:** edit this table for your plan. Everything downstream
+reads tiers, not model names.
+
+### Resolution + fallback
+
+At dispatch, resolve the role's tier to a concrete model **from the models you
+actually have**, then pass it explicitly (an omitted model inherits the session
+model — often the most expensive — which defeats routing). If a tier's model is
+unavailable, **collapse to the nearest lower tier you have**; `deep` always maps
+to the most capable model available. An installer with only one model degrades
+to that model everywhere — routing becomes a no-op, never a failure.
+
+## Roles → tiers
+
+| Agent | Tier | Concurrency | Role |
+|---|---|---|---|
+| `code-executor` | `fast` | parallel-safe | Transcribe code/adapter output from a complete spec; verify its own build. |
+| `reviewer` | `balanced` (scale to risk) | parallel-safe | Spec-compliance + quality gate; code-diff or Figma-visual mode. |
+| `architect` | `deep` | 1 | Plan a stage; read Figma read-only; emit a transcription-grade spec in stable identifiers (names, never nodeIds). |
+| `figma-executor` | `fast`→`balanced` (default **`balanced`** for a real component build; `fast` only for trivial mechanical ops) | **1 (bridge-locked)** | Resolve names→nodeIds at run time; build into a `WIP:` frame; verify via `COMPONENT_SET` read-back (not screenshot-only); finalize by build-verify-then-replace and reap `WIP:` debris. |
+
+## The spec-completeness gate
+
+Dispatch an executor on `fast` **only when the spec is transcription-grade** —
+complete enough that execution is copying, not deciding. Turn count beats token
+price: a cheap model on a vague task takes 2–3× the turns and costs more. If the
+spec is incomplete, run the work inline on the stronger model instead.
+
+## Escalation
+
+A `BLOCKED` executor is re-dispatched **one tier up**, never the same model
+unchanged. If still blocked at `deep`, escalate to the human.
+
+## Concurrency
+
+Code-gen roles are parallel-safe. Figma work is **not**: the figma-console
+bridge is a single live connection with global selection/current-page state, so
+the entire Figma surface is concurrency-1. Route Figma work through
+sequential subagents — model routing yes, parallelism never.

package/references/figma-component-standards.md

@@ -227,6 +227,30 @@ variant explosion), so **prefer them for composite components**.
   plain instance-swap property instead — slots are for freeform/repeating areas.)
 - **Single icon** (button leading icon) → instance-swap property, not a slot.
 
+### Rule: icons match the component's text color
+
+**A leading or trailing icon inside a text-bearing component ALWAYS takes the
+same color token as that component's adjacent text/label — in every variant,
+tone, and state.** Bind the icon to the *same* variable the label uses (e.g. a
+badge icon and its label both bind the tone's `fg`; a primary button's icon and
+label both bind `text/onEmphasis`). This is what prevents the mismatch failures:
+a white-text/black-icon control, an icon that stays one fixed color while the
+text changes per tone, or an icon that ignores the theme.
+
+Apply the color on the channel the icon actually draws with, and only that
+channel:
+
+- **Line / outline icons** (Lucide, Material Symbols outlined — most sets here)
+  draw with a **stroke and no fill.** Bind the color on the vectors' **stroke**
+  and leave the **fill empty.** Never bind a line icon's fill — a filled
+  outline path renders as a solid blob.
+- **Solid / filled glyphs** draw with a **fill.** Bind the color on the fill;
+  they have no meaningful stroke.
+
+Never hardcode an icon color, and never leave a fixed dark (or light) icon color
+across tones/states. Bind the override on the icon **instance's** vectors — never
+edit the shared `icon/*` source component, which would recolor every other usage.
+
 **Practical rules (from Figma's constraints):**
 - **Auto layout must be clean first.** Slots depend on a correct auto layout
   setup — a messy one makes everything shift. This is why auto-layout-on-

package/references/figma-scripting.md

@@ -38,6 +38,37 @@ This is the bridge-side application of the read-discipline principle (B4) in
 `${CLAUDE_PLUGIN_ROOT}/references/brownfield-retrofit.md`: don't assert "another
 instance is active" without confirming it's actually live.
 
+## Preflight: confirm the *active* file is your target (writes hit the active file)
+
+A connected bridge is **not** the same as the *right* file. `figma_execute` (and
+every write) targets whichever file is currently **active** in Figma Desktop — it
+takes no `fileUrl`/`fileKey` argument. So a green `figma_get_status` only proves a
+bridge exists; the active file can silently drift to a different open file between
+your preflight and your write (a user tabbing to another file, a `figma_navigate`
+from an earlier step, a plugin reload). Writing then lands in the wrong file —
+best case it errors with "collection/node not found"; worse case it mutates the
+wrong document.
+
+**So the preflight must assert the active file's *identity*, not just connection:**
+
+1. **Know your target `fileKey`** before writing (the one your architect read, or
+   the one the workflow is scoped to).
+2. **Read the active file and compare.** `figma_get_status` reports
+   `currentFileKey` / `currentFileName`; `figma_list_open_files` shows every
+   connected file and which is active. Confirm the active `fileKey` equals your
+   target before the first write **and** re-confirm after any step that could have
+   switched it.
+3. **If it drifted, navigate — don't just retry.** `figma_navigate` to the target
+   file URL, then re-read status to confirm the switch took, then write. A bare
+   re-run without navigating will hit the wrong file again.
+
+This is the file-level analogue of the live-instance discipline above: the
+instance preflight guards against *two* live bridges; this guards against the *one*
+live bridge pointing at the *wrong file*. (Observed live: a status probe reported
+the intended file connected, but by write time the active file had drifted to a
+different open document, and the build failed with "collection not found" until a
+`figma_navigate` corrected it.)
+
 ## Read discipline: never report "empty" without a verified read (B1/B2)
 
 Before reporting that a file has no variables, no text styles, or no effect styles,
@@ -276,3 +307,34 @@ const totalBindings = Object.values(tally).reduce((a, b) => a + b, 0);
 - **This is the number `design-system-audit` records** as
   `audit.figmaInventory.bindings`, and the before/after gate the `token-builder`
   brownfield branch runs around every rename.
+
+## Subagent authoring: named working frame + finalize protocol
+
+Figma writes are not git-committable, so a dead executor must never leave a
+corrupted live component. Any subagent authoring a component (`figma-executor`)
+uses **build-verify-then-replace**:
+
+1. **Always build into a distinct working frame** named `WIP: <ComponentName>` —
+   never edit the live component in place.
+2. **Verify the working frame green before touching anything real** — a
+   screenshot alone is **insufficient**: 10 tone-colored frames render
+   identically to 10 real variants, so a fast model can build plain frames and
+   self-report success. The gate is a **programmatic read-back** (`figma_execute`)
+   that asserts `node.type === 'COMPONENT_SET'` (never `'FRAME'`), the child count
+   matches the variant matrix with every child a `'COMPONENT'`,
+   `variantGroupProperties` names the expected axes, and a spot-check of ≥2
+   variants shows fills/strokes/radius bound to variables (not raw values) with
+   the expected `clipsContent`. A `figma_capture_screenshot` is a **secondary**
+   check (create → read-back → screenshot → iterate, max ~3), never the sole one.
+3. **Only then finalize:** remove/replace any existing same-named component,
+   rename the working frame's component set to the real `<ComponentName>`, **and
+   reap leftover artifacts** — search for and remove any stray `WIP:` frames or
+   orphaned fragments (from this or a prior failed run) so the file is left with
+   exactly one finalized component and zero `WIP:` debris.
+4. **On failure / `BLOCKED`:** leave the `WIP:` frame intact and named; the
+   existing real component is **never touched**. A resumed run finds the `WIP:`
+   frame by name and either continues or rebuilds it. A failure therefore leaves
+   an obvious, named, resumable artifact — not a half-built live component.
+
+Concurrency-1 still applies: the whole Figma surface serializes through the one
+bridge, so only one subagent runs this protocol at a time.

package/references/sync-adapters.md

@@ -139,3 +139,8 @@ each platform's output is independent and verifiable, which makes it a good fit
 for **parallel subagent generation** — one subagent per adapter, each producing
 and validating its platform's files, reviewed before the combined result is
 landed in a PR. See the token-sync skill for the execution model.
+
+Token-adapter generation parallelizes because each adapter writes independent
+files. Figma authoring does **not**: the single figma-console bridge is
+concurrency-1, so Figma work uses sequential subagents — model routing yes,
+parallel never (see `${CLAUDE_PLUGIN_ROOT}/references/agent-routing.md`).

package/scripts/install.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, copyFileSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, copyFileSync, realpathSync } from 'node:fs';
 import { join, dirname, relative, sep } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { rewritePluginRoot } from './adapters/translate.mjs';
@@ -129,7 +129,14 @@ export function install({ target, dir, pkgRoot = PKG_ROOT }) {
   return { target, dir, written, payload };
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+function isDirectInvocation() {
+  if (!process.argv[1]) return false;
+  let invoked = process.argv[1];
+  try { invoked = realpathSync(invoked); } catch { /* keep original */ }
+  return import.meta.url === pathToFileURL(invoked).href;
+}
+
+if (isDirectInvocation()) {
   const args = parseArgs(process.argv.slice(2));
   if (args.help) { console.log(USAGE); process.exit(0); }
   if (args.cmd !== 'init') { console.error(`✗ unknown command; expected "init"\n\n${USAGE}`); process.exit(1); }