orchestrix-skills 0.9.0 → 0.11.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "orchestrix-skills",
-  "version": "0.9.0",
+  "version": "0.11.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,19 +16,43 @@ 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)
        │                              (objective)      ↑ accept (batched)
        ├─ (verify failing, cause unknown?) ──→ investigate (root cause → rework)
        ├─ (runnable app?) ──→ smoke-test (drive real flows, evidence captured)
+       ├─ (team mode?) ──→ pull-request after commit (PR on GitHub, MR on GitLab; CI red re-enters rework)
        └─ (accepted + ship it?) ──→ deploy (inline gate, rollback-first)
 ```
 
 Human gates are front-loaded (planning = direction) and at the end (acceptance);
 the build loop runs lights-out, gated only by objective `verify`.
 
+## Team mode
+
+Uncomment the `collaboration:` block in `core-config.yaml` and the same loop
+runs for a team. Planning happens once, on a planning branch, and reaches the
+base branch through a PR. Each story is then one run on its own branch
+(`story/<origin>/<slug>`) in its own workspace — a `git worktree` when several
+sessions share a machine, a clone elsewhere — and ends with `pull-request`
+instead of a local commit. Merging stays a reviewer's act in the forge.
+
+There is no board file. A story's state is derived from git and the forge each
+time it is needed: a remote branch means claimed, an open PR means in review, a
+merged PR means done. Claiming is one push that the remote rejects if the
+branch already exists, so two people cannot take the same story. The PR body
+carries the run's evidence (acceptance criteria → code → test → verify log),
+because `.orchestrate/` never leaves the machine that produced it.
+
+GitHub and GitLab are supported through `adapters/forge/`; the exact CLI
+commands are inlined in the `pull-request` skill and kept identical by test.
+Team mode needs that forge's CLI (`gh` or `glab`) installed and logged in on
+each machine. `install` and `doctor` check for it once the block is active;
+without it a builder run still pushes its branch, then stops and asks a human
+to open the PR — it never pretends the PR exists.
+
 ## Install
 
 ```bash
@@ -51,7 +75,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.11.0", "ide": "claude", "skills": ["brainstorm", "commit", "…"] }
 ```
 
 Two things read it. The installer prunes skills a previous version placed that
@@ -88,12 +112,21 @@ 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.
+- **A team adds no shared state.** In team mode a run lives on a branch in
+  its own workspace, story state is derived from git and the forge, and an
+  epic is accepted on base with `smoke-test` — N green PRs do not prove the
+  composition.
 
 ## Runtime adapters
 
 `skills/` is the runtime-neutral source of truth. `adapters/` describes how a
-runtime maps generic capabilities to its tools. During a Codex install the CLI
+runtime maps generic capabilities to its tools, and how a forge (GitHub,
+GitLab) maps the generic pull-request operations to its CLI. During a Codex install the CLI
 removes Claude-only `allowed-tools`, preserves the contract, and adds Codex
 runtime guidance. If the target has an unmanaged `AGENTS.md`, its content is left
 untouched and the guidance is placed at `.codex/orchestrix/AGENTS.md` for manual

package/adapters/claude/runtime.json

@@ -8,6 +8,13 @@
     "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",
+    "forge.pr": "Bash + the forge CLI (gh | glab) named by core-config collaboration.forge; op table in the pull-request skill"
+  },
+  "models": {
+    "frontier": "fable",
+    "capable": "opus",
+    "cheap": "haiku"
   }
 }

package/adapters/codex/AGENTS.md

@@ -4,8 +4,10 @@
 - 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.
+- When `core-config.yaml` has a `collaboration:` block, follow the `orchestrate` skill's Collaboration section: one story per branch per workspace (`git worktree add`, then `cd` into it — Codex has no worktree tool), builder runs end with `pull-request`, and forge operations come from that skill's op table.
 <!-- orchestrix:end -->

package/adapters/codex/runtime.json

@@ -8,6 +8,13 @@
     "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",
+    "forge.pr": "runtime shell tool + the forge CLI (gh | glab) named by core-config collaboration.forge; op table in the pull-request skill"
+  },
+  "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/adapters/forge/github.json

@@ -0,0 +1,20 @@
+{
+  "name": "github",
+  "term": "pull request",
+  "cli": "gh",
+  "ops": {
+    "auth": "gh auth status",
+    "pr_for_branch": "gh pr list --head {branch} --state all --json number,url,state,isDraft,headRefOid,mergedAt",
+    "pr_create_draft": "gh pr create --draft --base {base} --head {branch} --title {title} --body-file {body_file}",
+    "pr_view": "gh pr view {pr} --json number,url,state,isDraft,headRefOid,baseRefName",
+    "pr_update_body": "gh pr edit {pr} --body-file {body_file}",
+    "pr_ready": "gh pr ready {pr}",
+    "ci_status": "gh pr checks {pr}",
+    "ci_watch": "gh pr checks {pr} --watch --fail-fast"
+  },
+  "notes": {
+    "pr_for_branch": "An empty JSON array means no PR exists for the branch.",
+    "ci_status": "Exit code 0 = all checks passed, 8 = pending, 1 = at least one failed (gh 2.63).",
+    "protection": "Enforce on the base branch via rulesets: require a pull request, require status checks, require the branch to be up to date before merging."
+  }
+}

package/adapters/forge/gitlab.json

@@ -0,0 +1,20 @@
+{
+  "name": "gitlab",
+  "term": "merge request",
+  "cli": "glab",
+  "ops": {
+    "auth": "glab auth status",
+    "pr_for_branch": "glab mr list --source-branch {branch} --all --output json",
+    "pr_create_draft": "glab mr create --draft --yes --source-branch {branch} --target-branch {base} --title {title} --description \"$(cat {body_file})\"",
+    "pr_view": "glab mr view {pr} --output json",
+    "pr_update_body": "glab mr update {pr} --description \"$(cat {body_file})\"",
+    "pr_ready": "glab mr update {pr} --ready",
+    "ci_status": "glab ci status --branch {branch} --compact",
+    "ci_watch": "glab ci status --branch {branch} --live"
+  },
+  "notes": {
+    "pr_for_branch": "An empty JSON array means no MR exists for the branch. The JSON carries state (opened | merged | closed), sha, and web_url.",
+    "ci_status": "Read the pipeline status word from the output (success | failed | running | pending); the exit code alone does not encode it in glab 1.50.",
+    "protection": "Enforce on the target branch: protected branch (no direct push), merge requests required, pipelines must succeed, and the merge method setting that requires the source to be up to date (fast-forward or semi-linear)."
+  }
+}

package/bin/install.js

@@ -3,7 +3,7 @@
 // Copies skills into the runtime's skills dir + scaffolds knowledge/.
 // No MCP, no license, no network calls. The hosted layer is a separate opt-in.
 import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join } from "node:path";
+import { delimiter, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
 const PKG = join(dirname(fileURLToPath(import.meta.url)), "..");
@@ -45,6 +45,7 @@ What it does:
   1. Copies the skills into your runtime's skills dir (default: .claude/skills/)
   2. Scaffolds knowledge/ + core-config.yaml (never overwrites an existing brain)
   3. Stamps <skills-dir>/.orchestrix-skills.json so upgrades and pruning are exact
+  4. Adds .orchestrate/ to .gitignore (once; ledger and verify logs are per-run state)
 
 Hosted orchestration, knowledge hosting, and team features:
   see https://orchestrix-mcp.youlidao.ai`);
@@ -115,6 +116,18 @@ function installSkills(dir, runtimeName, runtime) {
   return { count: names.length, pruned };
 }
 
+// The ledger and verify logs are per-run, per-workspace state. Committed, they
+// conflict on every PR in team mode, so the ignore line is written once and
+// left alone if the project already has it.
+function ignoreRuntimeDir(dir) {
+  const path = join(dir, ".gitignore");
+  const current = existsSync(path) ? readFileSync(path, "utf8") : "";
+  if (current.split("\n").some((line) => /^\.orchestrate\/?\s*$/.test(line))) return false;
+  const separator = current.length === 0 || current.endsWith("\n") ? "" : "\n";
+  writeFileSync(path, `${current}${separator}.orchestrate/\n`);
+  return true;
+}
+
 function installRuntimeGuidance(dir, runtimeName) {
   if (runtimeName !== "codex") return;
   const source = join(PKG, "adapters", "codex", "AGENTS.md");
@@ -160,6 +173,37 @@ function nonemptyFile(path) {
   return isFile(path) && readFileSync(path, "utf8").trim().length > 0;
 }
 
+// Team mode is opt-in: an uncommented `collaboration:` block in core-config.
+// Returns the forge name it declares, or null when the block is absent.
+function activeForge(configContent) {
+  const block = configContent.match(/^collaboration:\s*(?:#.*)?\n((?:[ \t]+.*\n?)*)/m);
+  if (!block) return null;
+  return block[1].match(/^[ \t]+forge:\s*([A-Za-z0-9_-]+)/m)?.[1] ?? "";
+}
+
+function forgeCli(forge) {
+  const path = join(PKG, "adapters", "forge", `${forge}.json`);
+  return isFile(path) ? JSON.parse(readFileSync(path, "utf8")).cli : null;
+}
+
+function onPath(bin) {
+  const exts = process.platform === "win32" ? ["", ".exe", ".cmd"] : [""];
+  return (process.env.PATH ?? "").split(delimiter).some((dir) => dir && exts.some((ext) => isFile(join(dir, bin + ext))));
+}
+
+// The pull-request skill drives the forge through its CLI (gh | glab). Without
+// it, builder runs stop at "push the branch, open the PR by hand" — better to
+// hear that from install/doctor than mid-run.
+function forgeCheck(configContent) {
+  const forge = activeForge(configContent);
+  if (forge === null) return null;
+  const cli = forgeCli(forge);
+  if (!cli) return { ok: false, detail: `collaboration.forge "${forge}" has no adapter (known: github, gitlab)` };
+  return onPath(cli)
+    ? { ok: true, detail: `${cli} on PATH (collaboration.forge: ${forge})` }
+    : { ok: false, detail: `${cli} not on PATH — team mode needs it installed and logged in (collaboration.forge: ${forge})` };
+}
+
 function validSkill(path, runtimeName, expectedName) {
   if (!nonemptyFile(path)) return false;
   const content = readFileSync(path, "utf8");
@@ -203,6 +247,14 @@ function install() {
     console.log("✓ core-config.yaml scaffolded");
   }
 
+  // 4. Runtime dir — ledger + verify logs never belong in history.
+  if (ignoreRuntimeDir(dir)) console.log("✓ .orchestrate/ added to .gitignore");
+  else console.log("• .gitignore already ignores .orchestrate/");
+
+  // 5. Team mode, if the project turned it on: say now whether the forge CLI is there.
+  const forge = forgeCheck(nonemptyFile(cfgTarget) ? readFileSync(cfgTarget, "utf8") : "");
+  if (forge) console.log(`${forge.ok ? "✓" : "✗"} forge CLI: ${forge.detail}`);
+
   if (ide === "cursor" || ide === "windsurf") {
     console.log(`\nNote: ${ide} does not auto-load Anthropic skills yet — copied as reference rules.`);
   }
@@ -234,6 +286,8 @@ function doctor() {
     ["core config valid", /(^|\n)knowledge:\s*(#.*)?\n/.test(configContent) && /(^|\n)work:\s*(#.*)?\n/.test(configContent), configPath],
     ["knowledge brain", isDirectory(join(dir, "knowledge")), join(dir, "knowledge")],
   ];
+  const forge = forgeCheck(configContent);
+  if (forge) checks.push(["forge CLI (team mode)", forge.ok, forge.detail]);
   if (ide === "codex") {
     const reference = join(dir, ".codex", "orchestrix", "AGENTS.md");
     const rootInstructions = join(dir, "AGENTS.md");

package/package.json

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

package/project-scaffold/core-config.yaml

@@ -18,6 +18,20 @@ work: # work products — skills WRITE these (outputs:), humans review at gates
 # here for transparency only.
 runtime: .orchestrate # ledger + verify logs (ephemeral, gitignored)
 
+# Team mode (opt-in). Uncomment to make orchestrate run each story on its own
+# branch in its own workspace and end builder runs with a PR/MR instead of a
+# local commit. Absent = solo behaviour, unchanged. See the orchestrate skill,
+# "Collaboration".
+#
+# collaboration:
+#   forge: github # github | gitlab
+#   base: main
+#   branch: story/{origin}/{slug}
+#   plan_branch: plan/{origin}
+#   workspace: worktree # worktree (same machine) | in-place (a clone elsewhere)
+#   pr:
+#     reviewers: []
+
 # Org-level cascade (shared taste/standards across many products) is intentionally
 # NOT enabled yet (YAGNI). When needed: add an `extends:` base that project paths
 # override. The logical namespaces above do not change when cascade is added.

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,9 +59,9 @@ 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
+       └─ draft-story → implement → run-tests → review-code → commit ──(team mode)─→ pull-request
                                       ↑ verify         ↑ design-review (UI only)
                                       (objective)      ↑ accept (batched)
 ```
@@ -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             |
@@ -80,6 +86,7 @@ Human gates are front-loaded (planning = direction) and at the very end
 | `review-code`         | build                    | deferred           |
 | `design-review`       | build (UI only)          | deferred           |
 | `commit`              | build                    | deferred           |
+| `pull-request`        | build (team mode)        | inline (first open) |
 
 ## Attribution
 

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.