orchestrix-skills 0.9.0 → 0.10.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrix-skills",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Capability-first AI development skill graph (Anthropic-native): plan → build with a warm-context orchestrator, contract-wired skills, and independent verification.",
   "author": "Orchestrix",
   "homepage": "https://orchestrix-mcp.youlidao.ai",

package/README.md

@@ -16,7 +16,7 @@ intent
   └─ orchestrate (root: warm context, wires skills by output→input, enforces gates)
        ├─ brainstorm ──(needs facts?)─→ research
        ├─ (existing repo?) ──→ map-codebase (brownfield entry: evidence-based map → registry)
-       ├─ (has UI?) ──→ design-system (once) → design-ui
+       ├─ (has UI?) ──→ design-directions (human picks a rendered direction) → design-system (once) → design-ui
        ├─ (arch decision?) ──→ design-architecture
        ├─ draft-story → implement → run-tests → review-code → commit
        │                              ↑ verify         ↑ design-review (UI only)
@@ -51,7 +51,7 @@ Re-running `install` refreshes the skills in place. It also writes a stamp at
 `<skills-dir>/.orchestrix-skills.json`:
 
 ```json
-{ "version": "0.8.0", "ide": "claude", "skills": ["brainstorm", "commit", "…"] }
+{ "version": "0.10.0", "ide": "claude", "skills": ["brainstorm", "commit", "…"] }
 ```
 
 Two things read it. The installer prunes skills a previous version placed that
@@ -88,7 +88,11 @@ The root skill is where the interesting engineering lives. Beyond wiring:
   even if it asked for a deferred one.
 - **Two rules are hard-wired** because output→input matching structurally cannot
   reach them: `smoke-test` is the acceptance floor for a runnable app the run
-  changed, and `design-system` precedes `design-ui`.
+  changed, and visual work runs direction → system → screens, with the human
+  approving rendered artboards at each gate rather than token files.
+- **Model tiers are declared, not guessed.** Each skill states
+  `requires.model: frontier | capable | cheap`; the adapter maps the tier to a
+  model, and the resolved model is recorded on every ledger step.
 
 ## Runtime adapters
 

package/adapters/claude/runtime.json

@@ -8,6 +8,12 @@
     "filesystem.write": "Write, Edit",
     "shell.execute": "Bash",
     "web.read": "WebSearch, WebFetch",
-    "agent.spawn": "Task"
+    "agent.spawn": "Task",
+    "design.canvas": "the bundled design skill (Claude Design canvas) + Artifact publish"
+  },
+  "models": {
+    "frontier": "fable",
+    "capable": "opus",
+    "cheap": "haiku"
   }
 }

package/adapters/codex/AGENTS.md

@@ -4,7 +4,8 @@
 - Use the skills installed under `.codex/skills/`; start end-to-end work with `orchestrate`.
 - Treat each skill's `metadata.contract` as Orchestrix workflow data. Codex skill selection still depends on `name` and `description`.
 - Resolve logical knowledge and work namespaces through `core-config.yaml`.
-- Map capability names in `metadata.requires.capabilities` to the tools available in the current Codex session.
+- Map capability names in `metadata.requires.capabilities` to the tools available in the current Codex session. `design.canvas` is not available: design skills write standalone HTML files, and you open them for the human at visual gates.
+- Map `metadata.requires.model` tiers to models the session can select (`frontier` = the most capable available). When a step cannot switch models, record the session model in its ledger `step` event.
 - When isolated agents are available, dispatch independent leaf skills concurrently and await them. Otherwise execute leaf skills sequentially in the current context, reading only their declared inputs before each step.
 - Independently run every objective verification command. Never accept an agent's success report as proof.
 - Keep runtime evidence at the fixed `.orchestrate/` path described by the `orchestrate` skill.

package/adapters/codex/runtime.json

@@ -8,6 +8,12 @@
     "filesystem.write": "runtime patch/edit tools",
     "shell.execute": "runtime shell tool",
     "web.read": "runtime web tools when enabled",
-    "agent.spawn": "optional collaboration tools; otherwise sequential fallback"
+    "agent.spawn": "optional collaboration tools; otherwise sequential fallback",
+    "design.canvas": "not available; design skills write standalone HTML files"
+  },
+  "models": {
+    "frontier": "the most capable model the session can select; else the session model, recorded in the ledger",
+    "capable": "the session default model",
+    "cheap": "the smallest model the session can select; else the session model"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrix-skills",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Capability-first AI development skill graph — Anthropic-native skills that run in any agent runtime.",
   "type": "module",
   "bin": {

package/project-scaffold/knowledge/taste/design-system.md

@@ -42,4 +42,5 @@ focus:
   visible_style: "" # the keyboard focus indicator every interactive element carries
 
 provenance: { source: design-system, added: "", approved_by: "" }
+# per token: extracted: <file> | extracted: <file>, snapped <before → after> | added
 ```

package/skills/README.md

@@ -18,6 +18,11 @@ Runtime-neutral capability requirements live under
 Adapters map those names to runtime tools. Runtime-specific tool names are not
 part of the orchestration contract.
 
+`metadata.requires.model` declares the model tier a skill needs —
+`frontier` (judgment: design, review, planning), `capable` (implementation),
+or `cheap` (mechanical). Adapters map tiers to models under `models` in
+`runtime.json`; the orchestrator states the resolved model on every dispatch.
+
 ### The contract (6 fields)
 
 | Field         | Meaning                                            |
@@ -54,7 +59,7 @@ are different gates; never merge them.
 intent
   └─ orchestrate (root: warm context, wires skills by output→input, enforces gates)
        ├─ brainstorm ──(needs facts?)─→ research
-       ├─ (has UI?) ──→ design-system (once) → design-ui
+       ├─ (has UI?) ──→ design-directions (human picks a rendered direction) → design-system (once) → design-ui
        ├─ (arch decision?) ──→ design-architecture
        └─ draft-story → implement → run-tests → review-code → commit
                                       ↑ verify         ↑ design-review (UI only)
@@ -71,6 +76,7 @@ Human gates are front-loaded (planning = direction) and at the very end
 | `orchestrate`         | root                     | inline (delivery)  |
 | `brainstorm`          | planning                 | inline (hard gate) |
 | `research`            | planning (optional)      | never              |
+| `design-directions`   | planning (UI, once)      | inline             |
 | `design-system`       | planning (UI, once)      | inline             |
 | `design-ui`           | planning (UI only)       | inline             |
 | `design-architecture` | planning (when needed)   | inline             |

package/skills/brainstorm/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [Read, Write, Grep, Glob]
 metadata:
   requires:
     capabilities: [filesystem.read, filesystem.write]
+    model: frontier
   contract:
     inputs: [intent, project_context]
     reads: [taste/*, architecture/*, registry/*]
@@ -75,6 +76,8 @@ origin: <stable short handle of this intent>
 ## Downstream — flags for the orchestrator:
 
 - needs UI design? yes/no (→ design-ui)
+- key screens (UI only): the 2–3 screens that carry the product, one line each
+  (→ design-directions renders these first)
 - needs an architecture decision? yes/no (→ design-architecture)
 - open question needing facts? yes/no (→ research)
 

package/skills/commit/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [Read, Bash]
 metadata:
   requires:
     capabilities: [filesystem.read, shell.execute]
+    model: cheap
   contract:
     inputs: [verified_changes, message_intent]
     reads: []

package/skills/deploy/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [Read, Bash]
 metadata:
   requires:
     capabilities: [filesystem.read, shell.execute]
+    model: capable
   contract:
     inputs: [accepted_deliverable, target]
     reads: [registry/deploy]

package/skills/design-architecture/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [Read, Write, Grep, Glob]
 metadata:
   requires:
     capabilities: [filesystem.read, filesystem.write]
+    model: frontier
   contract:
     inputs: [requirement, system_context]
     reads: [architecture/*, registry/api, registry/db]

package/skills/design-directions/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: design-directions
+description: Use when a product has a UI but no settled visual direction — renders 2–4 genuinely different low-fidelity directions of the key screens so the human picks one they can SEE, before any design system is written.
+license: MIT
+allowed-tools: [Read, Write, Bash, Grep, Glob, Skill]
+metadata:
+  requires:
+    capabilities: [filesystem.read, filesystem.write, shell.execute, "design.canvas?"]
+    model: frontier
+  contract:
+    inputs: [product_context, key_screens, "references?", "direction_feedback?"]
+    reads: [taste/brand, taste/design-system, registry/*]
+    outputs: [design_directions]
+    authority: "Write design assets under the specs namespace (default docs/specs/design/directions/). No source code, no production. Never publish or share externally — the orchestrator shows the artboards at the gate."
+    verify: "2–4 directions, each named by the axis it explores; every direction renders every key screen; every artboard passes the canvas check command (or is a standalone HTML file that opens from disk); directions.md gives every direction a motivation and a tradeoff."
+    accept:
+      when: "Always — the human picks a direction by looking at rendered screens, never by reading tokens."
+      timing: inline
+---
+
+# Design Directions
+
+Settle the visual direction with the human, not for them. People react to a
+rendered screen; they do not react to a typeface name or a hex value. So the
+first thing a human sees of a new product's look is 2–4 low-fidelity screens
+they can compare — and the direction they pick is what `design-system` then
+codifies.
+
+**Posture:** Senior product designer running a direction review. Breadth over
+polish. Every option gets an honest case; a set where only your favorite is
+argued for is a rigged vote.
+
+## Precondition — skip when the direction is already settled
+
+Do not explore what is already decided. Return `skipped` with a one-line
+reason when either holds:
+
+- `taste/design-system` is populated (a real system, not the unedited seed).
+- `registry/*` shows an existing UI in the repo. Its look is the direction;
+  `design-system` extracts it from source.
+
+## Inputs
+
+- `product_context` — the approved spec from `brainstorm` (goal, requirement,
+  constraints).
+- `key_screens` — the 2–3 screens that carry the product, from the spec's
+  `Downstream` section. If the spec lists none, derive them from the
+  requirement and name them at the top of `directions.md`. Never more than 3.
+- `references?` — products, brands, or assets the human named.
+- `direction_feedback?` — present on re-dispatch when the human rejected every
+  direction. Read it first; the new set must answer it.
+
+## Process
+
+1. **Read the signal.** `taste/brand`, references, and the product context.
+   What is the product for, and for whom? Which tone does the brief imply
+   (internal tool → utilitarian; consumer → expressive)?
+2. **Name 2–4 directions, each on a named axis.** An axis is a real choice:
+   density (dense vs airy), type personality (editorial serif vs geometric
+   sans vs mono), color stance (one accent on neutral vs tonal), tone (quiet
+   vs bold). Two directions that differ only in shade are one direction —
+   replace one.
+3. **Sketch every key screen in every direction, low-fi.** Structure,
+   hierarchy, a type pairing, one accent, real layout. Real copy where the
+   brief supplies it; a bracketed placeholder like `[price]` where it does
+   not. No filler sections, no emoji as icons, no fake device chrome. Low-fi
+   means decision fidelity, not deliverable fidelity — enough to choose, not
+   enough to ship.
+4. **Author the artboards.**
+   - With `design.canvas`: one artboard per direction × screen, named
+     `<Direction>-<Screen>.dc.html`, plus a `canvas.json` that lays each
+     direction out as one row. `Main.dc.html` is the leading candidate's
+     first screen. Follow the runtime's design skill for the file format and
+     run its check command; its output is the verify evidence.
+   - Without it: one standalone `<Direction>-<Screen>.html` per artboard,
+     self-contained (inline CSS, no external assets except Google Fonts), and
+     an `index.html` that links every file under its direction name. Each
+     must open from disk.
+5. **Write `directions.md`.** For each direction: name, the axis it explores,
+   the motivation (why it fits this product), and its main tradeoff (what it
+   costs). One paragraph each. End with the key screens list.
+
+## Anti-slop
+
+The canonical list lives in the `design-system` skill. A direction that lands
+on one of those defaults is allowed only as a stated, justified choice — and
+never as two of the 2–4.
+
+## Output: `specs/design/directions/`
+
+```
+directions.md                           # name, axis, motivation, tradeoff per direction
+canvas.json                             # with design.canvas only
+<Direction>-<Screen>.dc.html            # with design.canvas
+<Direction>-<Screen>.html + index.html  # without it
+```
+
+## Done
+
+Write the files, run the check, then stop (`accept: inline`). The
+orchestrator puts the rendered artboards in front of the human and records
+their pick as `chosen_direction`. Never pick for them. If they reject every
+direction, you are re-dispatched with `direction_feedback` — same skill, new
+set.

package/skills/design-review/SKILL.md

@@ -6,8 +6,9 @@ allowed-tools: [Read, Bash, Grep, Glob]
 metadata:
   requires:
     capabilities: [filesystem.read, shell.execute]
+    model: frontier
   contract:
-    inputs: [built_ui, ui_spec, "screenshots?"]
+    inputs: [built_ui, ui_spec, "ui_artboards?", "screenshots?"]
     reads: [taste/design-system, taste/brand]
     outputs: [design_review_report]
     authority: "Read-only on code. Start and stop the app locally to render it, and drive it via browser automation or HTTP. No edits, no commits, no deploy, no external spend."
@@ -42,6 +43,10 @@ clean one.
 - `built_ui` — the running app (a live URL, or a dev server this skill starts).
 - `ui_spec` — `specs/<slug>-ui.md` it must satisfy, including its declared
   **treatment** (`utility` / `product` / `editorial`).
+- `ui_artboards?` — the artboards the human approved at the `design-ui` gate
+  (`specs/design/<slug>/`). They are the visual bar for Verdict 3: a built
+  screen that departs from its approved artboard in hierarchy, spacing, or
+  treatment is a finding, at the same severity as a deviation from the system.
 - `screenshots?` — captures a prior `smoke-test` already took. Use them instead
   of relaunching the app for the same screen.
 - Read `taste/design-system` + `taste/brand` — the bar to calibrate against.

package/skills/design-system/SKILL.md

@@ -1,73 +1,105 @@
 ---
 name: design-system
-description: Use when a project has no design direction yet, or must (re)establish its aesthetic — produces the durable design system (aesthetic POV, type, color, space, motion) before any UI is designed.
+description: Use once a visual direction is chosen (or an existing UI must be codified) to write the durable design system — extracts tokens from what the human approved, completes what a sketch cannot show, and renders the system as a sheet for visual approval.
 license: MIT
-allowed-tools: [Read, Write, WebSearch, Grep, Glob]
+allowed-tools: [Read, Write, Bash, WebSearch, Grep, Glob, Skill]
 metadata:
   requires:
-    capabilities: [filesystem.read, filesystem.write, web.read]
+    capabilities: [filesystem.read, filesystem.write, shell.execute, web.read, "design.canvas?"]
+    model: frontier
   contract:
-    inputs: [product_context, "references?"]
-    reads: [taste/brand, taste/design-system]
-    outputs: [taste/design-system, taste/brand]
-    authority: "Author the durable design KB (taste/design-system, taste/brand). High-authority, audited (knowledge write). No source code, no production."
-    verify: "Specific, not generic: a named typeface, real type/space scales, named reference products, one memorable-thing. Covers type + color + theme + space + motion + focus. Every mode listed under theme.modes has a full palette. No AI-default tells (see anti-slop)."
+    inputs: [product_context, "chosen_direction?", "references?"]
+    reads: [taste/brand, taste/design-system, registry/*]
+    outputs: [taste/design-system, taste/brand, design_system_sheet]
+    authority: "Author the durable design KB (taste/design-system, taste/brand) and the system sheet under the specs namespace. High-authority, audited (knowledge write). No source code, no production."
+    verify: "Every token value traces to the chosen direction's artboard source or to existing UI source, or is marked added and appears on the system sheet; covers type + color + theme + space + motion + focus; every mode under theme.modes has a full palette; the sheet and re-rendered key screens pass the canvas check command; no AI-default tells (see anti-slop)."
     accept:
-      when: "Always — the aesthetic direction is foundational and brand-defining."
+      when: "Always — the human approves the rendered sheet and key screens, not the YAML."
       timing: inline
 ---
 
 # Design System
 
-Establish the project's durable visual direction — once — so every UI after it
-is consistent and unmistakably this product's. This is the source of taste the
-`design-ui` skill applies.
-
-**Posture:** You are a senior product designer with strong opinions about
-typography, color, space, and motion. You research, then propose ONE coherent
-system and explain why. Opinionated, not dogmatic. Zero tolerance for generic,
-AI-generated-looking interfaces.
-
-## The forcing question (do this first)
-
-Ask: **"What is the one thing someone should remember after seeing this product
-for the first time?"** One sentence — a feeling, a claim, a posture. Every
-decision below serves it. A system that tries to be memorable for everything is
-memorable for nothing.
-
-## Commit to a reference (this is what beats slop)
-
-AI defaults to the on-distribution average. Beat it by committing to a specific
-point of view BEFORE specifying anything:
-
-1. **Research the space.** What do the 2–3 best products here actually look like?
-2. **Name 2–3 concrete references** to steal direction from (e.g. Linear,
-   Things 3, Stripe, Vercel, Bloomberg terminal, Notion). Not to copy — to anchor.
-3. **State the one rule that makes this distinctive** (the type personality, a
-   signature color, a density choice, a motion restraint).
-
-## Specify the system (specifics, not adjectives)
-
-- **Typography** — a named typeface (not Inter/Roboto unless deliberate and
-  justified), a type scale with real sizes/weights, line-height rules, and the
-  target measure for running text (~65 characters).
-- **Color** — a real palette with roles (bg, surface, text, accent, states), not
-  default framework swatches; state the contrast floor as a number.
-  **Accent and semantic color are two different systems.** The accent is the one
-  brand hue; success/warning/error carry meaning. If the accent doubles as
-  "success", state cannot be read at a glance — pick again.
-- **Theme** — decide `light | dark | both`, and how a mode is selected (OS
-  preference, an explicit user toggle, or both). If dark is in scope, specify a
-  **second full palette, role for role**. A dark palette is re-picked, not
-  inverted: an accent that holds 4.5:1 on white usually fails on near-black.
-  Deciding light-only is allowed — but it must be written down as a decision, so
-  `design-review` knows there is nothing else to check.
-- **Space** — a spacing scale; density posture (tight/airy) tied to the product.
+Codify the project's durable visual direction — once — so every UI after it
+is consistent and unmistakably this product's. This skill does not invent the
+direction: the human already chose it by looking at rendered screens
+(`design-directions`), or the repo already has one in code. It extracts,
+regularizes, completes, and renders the result so the human approves pixels,
+not a token file.
+
+**Posture:** Senior product designer with strong opinions about typography,
+color, space, and motion. Zero tolerance for generic, AI-generated-looking
+interfaces.
+
+## Three entry paths — pick exactly one
+
+| Entry                           | Condition                                                                  | Source of truth                                    |
+| ------------------------------- | -------------------------------------------------------------------------- | -------------------------------------------------- |
+| Extract from a chosen direction | `chosen_direction` names a direction in `specs/design/directions/`         | That direction's artboard source files             |
+| Extract from existing UI        | `registry/*` shows a UI in the repo and there is no `chosen_direction`     | The repo's stylesheets, tokens, and components     |
+| Backfill                        | `taste/design-system` exists but lacks newer fields                        | The existing system; fill only the gaps            |
+
+If none holds, stop: the orchestrator must run `design-directions` first. Do
+not invent a direction the human has never seen rendered.
+
+## Extract — from source, not screenshots
+
+Read the artboard `.dc.html` / `.html` source, or the repo's stylesheets and
+component source. Inline styles and tokens carry exact values; a screenshot is
+a guess. Lift: typeface(s), every font size and weight in use, line-heights,
+colors by role (bg, surface, text, accent), spacing values, radii, borders,
+control heights.
+
+Then regularize onto scales: a type scale, a spacing scale, a palette with
+named roles. When snapping changes a value, record `before → after` in the
+entry's provenance so the human can see what moved and why.
+
+## Complete — what a sketch cannot show
+
+A low-fi direction shows the happy path in one theme. The system must also
+decide the following, and each decision carries `added` provenance because the
+human has not seen it yet:
+
+- **Typography** — line-height rules and the measure for running text
+  (~65 characters). Named typeface only; Inter/Roboto need a stated
+  justification.
+- **Color** — the contrast floor as a number. **Accent and semantic color are
+  two systems:** the accent is the one brand hue; success/warning/error carry
+  meaning and must read as distinct from it.
+- **Theme** — `light | dark | both`, and how a mode is selected (OS
+  preference, an explicit user toggle, or both). If dark is in scope, a
+  **second full palette, role for role**, re-picked — never inverted: an
+  accent that holds 4.5:1 on white usually fails on near-black. Light-only is
+  allowed, but it must be written down so `design-review` knows there is
+  nothing else to check.
+- **Space** — density posture (tight/airy) tied to the product.
 - **Layout** — grid and composition principles; how hierarchy is created.
 - **Motion** — timing, easing, where motion is used (and where it is not), and
   what `prefers-reduced-motion` removes while keeping the UI usable.
-- **Focus** — the keyboard focus indicator every interactive element carries. An
-  invisible focus ring is a broken system, not a style choice.
+- **Focus** — the keyboard focus indicator every interactive element carries.
+  An invisible focus ring is a broken system, not a style choice.
+
+Record the **memorable-thing** (one sentence: what a first-time viewer should
+remember), the **references** (2–3 named products), and the **one distinctive
+rule** — taken from the chosen direction's entry in `directions.md`, or
+derived from the existing UI.
+
+## Render — the system sheet
+
+Write the system as artboards under `specs/design/system/`, using the same
+format rules as `design-directions` (canvas files with `design.canvas`,
+standalone HTML without it), and run the check command:
+
+- `Sheet` — the type ramp at real sizes, the light palette (and the dark
+  palette when declared), the spacing scale, and the core components in every
+  state: button (default / hover / focus-visible / disabled), text input
+  (default / focus / error), one empty state, one loading state.
+- One artboard per key screen, re-rendered hi-fi on the system, in every
+  declared theme mode. These are the screens `design-ui` reuses — it does not
+  redraw them.
+
+The sheet is what the human approves. A token that is not on the sheet has
+not been approved.
 
 ## Anti-slop (the canonical list — `design-ui` and `design-review` check it too)
 
@@ -99,11 +131,11 @@ pretending to be structure.
 
 Write `taste/design-system` and `taste/brand` as structured entries (per the
 knowledge format: terse, chunked, each with `source`/`added`/`approved_by`).
-Record the memorable-thing, the references, the one distinctive rule, and each
-specified token/scale. Leave no field of the seed blank: `theme`,
-`motion.reduced_motion`, and `focus.visible_style` are decisions, and a blank
-one reads to `design-review` as unspecified rather than as "not needed". This is
-the source `design-ui` reads.
+Each token entry names where its value came from: `extracted: <file>`,
+`extracted: <file>, snapped <before → after>`, or `added`. Leave no field of
+the seed blank: `theme`, `motion.reduced_motion`, and `focus.visible_style`
+are decisions, and a blank one reads to `design-review` as unspecified rather
+than as "not needed". This is the source `design-ui` reads.
 
 **Backfilling an older system.** An upgrade refreshes skills but never rewrites
 an existing `knowledge/` — that brain belongs to the project. So a system
@@ -113,16 +145,19 @@ will report every dependent check against an assumed bar. When you re-run on
 such a project, add those fields rather than re-authoring the whole system:
 keep every existing value untouched, fill only the gaps, and give the new
 entries their own `added` date and approver. Adding a dark palette to a
-light-only product is a real design decision — put it through the same accept
-gate as the rest, don't infer it.
+light-only product is a real design decision — put it on the sheet and through
+the same accept gate as the rest, don't infer it.
 
 ## Self-critique before done
 
-Look at the system with a designer's eye: does it read as a specific, named
-point of view, or as a generic template? Could you tell it apart from a default
-AI UI? If not, sharpen it.
+Look at the sheet with a designer's eye: does it still read as the direction
+the human chose, or has regularizing flattened it into a template? Could you
+tell it apart from a default AI UI? If not, sharpen it — and check the change
+back against the chosen artboard.
 
 ## Done
 
-Write the KB, then stop for approval (`accept: inline`). On approval, `design-ui`
-applies this system per feature. Re-run only to evolve the direction.
+Write the KB and the sheet, then stop for approval (`accept: inline`). The
+orchestrator shows the sheet and the re-rendered key screens; the human
+approves those. On approval, `design-ui` applies this system per feature.
+Re-run only to evolve the direction or to backfill fields.

package/skills/design-ui/SKILL.md

@@ -2,19 +2,20 @@
 name: design-ui
 description: Use when a feature has a user interface, to design its screens and flows by applying the project's design system with world-class craft, before stories are drafted.
 license: MIT
-allowed-tools: [Read, Write, Grep, Glob]
+allowed-tools: [Read, Write, Bash, Grep, Glob, Skill]
 metadata:
   requires:
-    capabilities: [filesystem.read, filesystem.write]
+    capabilities: [filesystem.read, filesystem.write, shell.execute, "design.canvas?"]
+    model: frontier
   contract:
     inputs: [requirement, ui_context]
     reads: [taste/design-system, taste/brand]
-    outputs: [specs/<slug>-ui.md]
+    outputs: [specs/<slug>-ui.md, ui_artboards]
     updates: ["taste/design-system?", "taste/brand?"]
-    authority: "Write to the specs namespace (default docs/specs/) and design assets. No source code, no production."
-    verify: "Every screen and flow maps to a requirement; a treatment is declared and held to; expresses the design system (not generic defaults); copy and non-happy states are specified for every screen; the design plan passed its critique before the spec was written."
+    authority: "Write to the specs namespace (default docs/specs/) and design assets under it. No source code, no production."
+    verify: "Every screen and flow maps to a requirement; a treatment is declared and held to; expresses the design system (not generic defaults); copy and non-happy states are specified for every screen; every screen in the spec has a rendered artboard that passes the canvas check command; the design plan passed its critique before the spec was written."
     accept:
-      when: "Visual direction — the look is foundational; everything downstream builds on it."
+      when: "Always — the human approves the rendered artboards; the spec is what draft-story and design-review read."
       timing: inline
 ---
 
@@ -77,8 +78,13 @@ choice you must justify in one sentence in the spec.
    screen's spec names the tokens it uses, not literal colors, and calls out any
    place the two palettes need different treatment (elevation, dividers, images
    on a dark ground). If the system is light-only, say so once and move on.
-7. **Show, don't just tell.** When a layout choice is clearer shown than
-   described, produce a mockup or wireframe, not prose.
+7. **Render every screen.** Write one artboard per screen and state under
+   `specs/design/<slug>/`, in every declared theme mode, using the same format
+   rules as `design-directions` (canvas files with `design.canvas`, standalone
+   HTML without it), and run the check command. A key screen `design-system`
+   already rendered is reused, not redrawn — the spec references its file.
+   The artboards are what the human approves; the spec is what machines read.
+   Both are required.
 
 ## Copy is design material
 
@@ -128,7 +134,7 @@ from `taste/design-system` needs the same justification.
 ## Designer's-eye self-critique (mandatory gate before done)
 
 The plan critique in step 2 catches generic direction. This catches generic
-execution. Look at the result and ask:
+execution. Look at the rendered artboards and ask:
 
 - Does this look like it could ship from {the named references}, or like a
   generic AI UI? If the latter, fix it.
@@ -142,7 +148,7 @@ execution. Look at the result and ask:
 Fix until it passes. This is the visual equivalent of `run-tests` — don't claim
 done without running it.
 
-## Output: `specs/<slug>-ui.md`
+## Output: `specs/<slug>-ui.md` + `specs/design/<slug>/`
 
 ```markdown
 # <Feature> — UI Spec
@@ -162,10 +168,15 @@ done without running it.
 ## System use — tokens/components used; theme coverage; how the
 memorable-thing shows up here.
 
+## Artboards — one file per screen and state, including any reused from
+design-system.
+
 ## New patterns — anything the system lacked, with rationale (candidate for KB).
 ```
 
-`draft-story`'s `UI Reference` points to this file.
+`specs/design/<slug>/` holds the artboards (plus `canvas.json` when the canvas
+is available). `draft-story`'s `UI Reference` points to the spec;
+`design-review` walks the spec and uses the artboards as the visual bar.
 
 ## Metabolism
 
@@ -175,5 +186,6 @@ supersede rather than rewrite. Feature-only details stay in the spec.
 
 ## Done
 
-Write the UI spec, pass the self-critique, then stop for visual approval
-(`accept: inline`). On approval the orchestrator wires `draft-story`.
+Write the UI spec and the artboards, pass the self-critique, then stop
+(`accept: inline`). The orchestrator shows the artboards; the human approves
+those. On approval the orchestrator wires `draft-story`.

package/skills/draft-story/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [Read, Write, Grep, Glob]
 metadata:
   requires:
     capabilities: [filesystem.read, filesystem.write]
+    model: capable
   contract:
     inputs: [requirement, context]
     reads: [taste/coding-standards, registry/api, registry/db, "front-end-spec?"]

package/skills/implement/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [Read, Write, Edit, Bash]
 metadata:
   requires:
     capabilities: [filesystem.read, filesystem.write, shell.execute]
+    model: capable
   contract:
     inputs: [story, acceptance_criteria, scope, "qa_feedback?"]
     reads: [taste/coding-standards, registry/api, registry/db]

package/skills/investigate/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [Read, Bash, Grep, Glob]
 metadata:
   requires:
     capabilities: [filesystem.read, shell.execute]
+    model: capable
   contract:
     inputs: [symptom, "context?", "prior_attempts?"]
     reads: [registry/architecture, taste/coding-standards]

package/skills/map-codebase/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [Read, Write, Bash, Grep, Glob]
 metadata:
   requires:
     capabilities: [filesystem.read, filesystem.write, shell.execute]
+    model: capable
   contract:
     inputs: [repo_path, "focus?"]
     reads: []

package/skills/orchestrate/SKILL.md

@@ -2,11 +2,12 @@
 name: orchestrate
 description: Use when a goal must be delivered end-to-end by composing skills, with the human approving direction at the start and the result at the end.
 license: MIT
-allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Task]
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Task, Skill, Artifact]
 metadata:
-  version: 6
+  version: 7
   requires:
-    capabilities: [filesystem.read, filesystem.write, shell.execute, "agent.spawn?"]
+    capabilities: [filesystem.read, filesystem.write, shell.execute, "agent.spawn?", "design.canvas?"]
+    model: frontier
   contract:
     inputs: [intent, "constraints?"]
     reads: [core-config, skill-registry, taste/*]
@@ -46,7 +47,8 @@ no step above intent.
 4. **Dispatch.** Hand the skill exactly the `inputs` it declares, as files —
    resolving each logical namespace it reads/writes to a physical path via
    `core-config.yaml` (see Namespace resolution). If the runtime supports isolated
-   agents, run each leaf as a fresh dispatch and choose the cheapest capable model.
+   agents, run each leaf as a fresh dispatch on the model its `requires.model`
+   tier resolves to (see Model tier).
    Dispatch independent steps concurrently and await them in the same turn; keep
    dependent steps sequential. Never fire-and-forget a background agent. If the
    runtime has no isolated-agent capability, execute leaves sequentially in the
@@ -134,11 +136,16 @@ CANNOT reach — wire these by rule, not by match:
    proves the product — green unit tests are not this evidence. A `failed` or
    `untested` verdict is a real result: carry it into final acceptance
    verbatim, never round it up to passed.
-2. **`design-system` comes before `design-ui`.** `design-ui` READS
-   `taste/design-system` — it never produces it. If UI work is wired and the
-   resolved `taste/design-system` namespace is empty, wire `design-system`
-   first; otherwise `design-ui` dresses a project that has a brand in generic
-   defaults.
+2. **Direction → system → screens.** `design-ui` READS `taste/design-system`
+   and never produces it; `design-system` codifies a direction and never
+   invents one. If UI work is wired and the resolved `taste/design-system`
+   namespace is empty:
+   - the repo already has a UI (`registry/*` says so) → wire `design-system`
+     (its extract-from-source path), then `design-ui`;
+   - otherwise → wire `design-directions` first, show its artboards at the
+     gate, hand the human's pick to `design-system` as `chosen_direction`,
+     then `design-ui`.
+   A direction the human has not seen rendered is not a direction.
 
 ## Accept gate
 
@@ -151,6 +158,15 @@ CANNOT reach — wire these by rule, not by match:
 
 You are the teeth. The fields are only data; you enforce them.
 
+**Visual gates show pixels.** When the skill at an inline gate produced
+artboards (`design-directions`, `design-system`, `design-ui`), put the
+rendered result in front of the human before asking: with `design.canvas`,
+publish the canvas through the runtime's design skill; without it, give the
+local HTML paths to open. Publishing is an outward action and belongs to you
+at the gate, never to the leaf. Record the URL or path in the `gate` event's
+`shows` field. Asking a human to approve a design from a token file or a
+prose spec is a failed gate.
+
 ## Rework is a loop, not a skill — and the loop is BOUNDED
 
 A failed `verify` or a `changes_requested` review is not a separate "fix" step.
@@ -219,8 +235,8 @@ Events and when to write them:
 | ----- | ---- | ----- |
 | `run_start` | right after binding intent | `{"e":"run_start","run":"r-<yyyymmdd>-<slug>","intent":"...","ts":"..."}` |
 | `plan` | after wiring the graph, and EVERY time the graph changes | `{"e":"plan","run":"...","steps":[{"n":1,"skill":"research","title":"..."}, …]}` — full current plan; latest `plan` line wins; steps may be added, never removed |
-| `step` | immediately BEFORE each dispatch, and again after its verify | `{"e":"step","run":"...","n":3,"skill":"implement","status":"dispatched\|done\|failed\|skipped","attempt":1,"evidence":"<file or one-line result>","ts":"..."}` — rework = same `n`, next `attempt`; a step a replan made obsolete gets `skipped` with the reason in `evidence` (plan lines are never removed, so this is how an obsolete step closes) |
-| `gate` | when stopping at a human gate | `{"e":"gate","run":"...","kind":"inline_accept","question":"...","ts":"..."}` |
+| `step` | immediately BEFORE each dispatch, and again after its verify | `{"e":"step","run":"...","n":3,"skill":"implement","status":"dispatched\|done\|failed\|skipped","attempt":1,"model":"<resolved model, or session>","evidence":"<file or one-line result>","ts":"..."}` — rework = same `n`, next `attempt`; a step a replan made obsolete gets `skipped` with the reason in `evidence` (plan lines are never removed, so this is how an obsolete step closes) |
+| `gate` | when stopping at a human gate | `{"e":"gate","run":"...","kind":"inline_accept","question":"...","shows":"<artboard URL or path, visual gates only>","ts":"..."}` |
 | `run_end` | at delivery or abandonment | `{"e":"run_end","run":"...","result":"delivered\|paused\|abandoned","ts":"..."}` |
 
 A step recorded `done` is done — do not re-dispatch it. `evidence` on a `done`
@@ -250,10 +266,25 @@ session, or a wake-up — do NOT continue from what you remember. Replay:
 
 - **Files, not paste.** Move artifacts between steps as files. Never paste a
   step's full output into your context — it would be re-read every later turn.
-- **Cheapest model per step.** Mechanical step → cheap model. Judgment step →
-  capable model. State the model explicitly on every dispatch.
+- **The declared tier per step.** Resolve `requires.model` through the
+  adapter and state the model on every dispatch (see Model tier).
 - **Keep your own context small.** You coordinate; the leaves do the heavy work.
 
+## Model tier
+
+Every skill declares `metadata.requires.model: frontier | capable | cheap`.
+Resolve it through the adapter (`adapters/<runtime>/runtime.json` → `models`)
+and state the resolved model on every dispatch. The tiers encode where
+judgment lives: design and review skills are `frontier` because a weaker
+model converges on the generic default and a weaker reviewer misses what the
+implementer missed; mechanical skills are `cheap`.
+
+- Escalate `implement` to `frontier` when the story's scope is high-risk
+  (security, data, money, irreversible).
+- If the runtime cannot switch models for a step (sequential fallback), the
+  step runs on the session's model. Record that model in the `step` event and
+  say so at the next gate. Never silently run a `frontier` step on less.
+
 ## Red flags — stop
 
 - Pausing to ask the human mid-run when nothing is `inline` or irreversible
@@ -274,4 +305,10 @@ session, or a wake-up — do NOT continue from what you remember. Replay:
 - Delivering a runnable app this run changed with no `smoke-test` verdicts
   (unit tests are not that evidence)
 - Dispatching `design-ui` while the resolved `taste/design-system` is empty
+- Letting `design-system` invent a direction with no `chosen_direction` and no
+  existing UI
+- Asking for design approval on a token file or a prose spec instead of
+  rendered artboards
+- Running a `frontier` step on a cheaper model without recording it in the
+  ledger
 - Marking the run complete without every step's `verify` evidence

package/skills/research/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [Read, Write, WebSearch, WebFetch]
 metadata:
   requires:
     capabilities: [filesystem.read, filesystem.write, web.read]
+    model: capable
   contract:
     inputs: [question, scope]
     reads: []

package/skills/review-code/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [Read, Bash, Grep, Glob]
 metadata:
   requires:
     capabilities: [filesystem.read, shell.execute]
+    model: frontier
   contract:
     inputs: [diff, spec]
     reads: [taste/coding-standards]

package/skills/run-tests/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [Read, Bash]
 metadata:
   requires:
     capabilities: [filesystem.read, shell.execute]
+    model: cheap
   contract:
     inputs: [target, "expected_outcome?"]
     reads: []

package/skills/smoke-test/SKILL.md

@@ -6,6 +6,7 @@ allowed-tools: [Read, Bash, Grep, Glob]
 metadata:
   requires:
     capabilities: [filesystem.read, shell.execute]
+    model: cheap
   contract:
     inputs: [run_instructions, flows, "qa_feedback?"]
     reads: [registry/app]