supipowers 1.5.3 → 2.0.0

package/README.md

@@ -60,6 +60,7 @@ The installer scans for these and offers to install missing tooling where it can
 | ------------------------ | ------------------------------------------------------------- |
 | `/supi`                  | Interactive menu with commands and project status             |
 | `/supi:plan`             | Collaborative planning with structured task breakdown         |
+| `/supi:ui-design`        | Design Director pipeline — gather UI context, decompose target into components, build mockups in browser companion, validate, save to `.omp/supipowers/ui-design/` |
 | `/supi:review`           | AI code review with validated findings docs and fix/document/discuss actions |
 | `/supi:checks`           | Run deterministic quality gates                               |
 | `/supi:qa`               | E2E testing pipeline with Playwright                          |
@@ -83,7 +84,7 @@ Most commands steer the AI session. These are TUI-only — they open native dial
 
 **Planning.** `/supi:plan` steers the AI through planning phases (scope → decompose → estimate → verify), saves the result to `.omp/supipowers/plans/`, and presents an approval UI. On approval, tasks execute in the same session.
 
-**Quality gates.** `/supi:checks` runs deterministic quality gates. Six gates are available: `lsp-diagnostics`, `lint`, `typecheck`, `format`, `test-suite`, and `build`. Each gate can be enabled independently via `/supi:config` or `.omp/supipowers/config.json`. Gates report issues with severity levels.
+**Quality gates.** `/supi:checks` runs deterministic quality gates. Six gates are available: `lsp-diagnostics`, `lint`, `typecheck`, `format`, `test-suite`, and `build`. Each gate can be enabled independently via `/supi:config` or the shared repository config at `.omp/supipowers/config.json`. In monorepos, `/supi:checks` defaults to `All`, which runs the root target plus every workspace target sequentially; use `--target <package>` to narrow the run or `--target all` to request the batch mode explicitly. Gates report issues with severity levels.
 
 **AI code review.** `/supi:review` runs a programmatic AI review pipeline with configurable depth (quick, deep, or multi-agent). It uses headless agent sessions with structured JSON validation, always validates findings before user action, writes the current validated findings to a session `findings.md` document, and then presents three next-step choices: `Fix now`, `Document only`, or `Discuss before fixing`.
 
@@ -127,7 +128,7 @@ Use `/supi:agents` to inspect the merged set that will actually run.
 
 ## Quality gates
 
-`/supi:checks` runs deterministic quality gates. Each gate is independently configurable in `quality.gates` via `/supi:config` or the config JSON files:
+`/supi:checks` runs deterministic quality gates. Each gate is independently configurable in `quality.gates` via `/supi:config` or the shared config JSON files:
 
 | Gate               | What it checks                  | Config type       |
 | ------------------ | ------------------------------- | ----------------- |
@@ -138,7 +139,7 @@ Use `/supi:agents` to inspect the merged set that will actually run.
 | `test-suite`       | Test runner                     | enabled + command |
 | `build`            | Build verification              | enabled + command |
 
-Gates default to disabled. Enable them per-project in `.omp/supipowers/config.json` or globally in `~/.omp/supipowers/config.json`.
+Gates default to disabled. Enable them globally in `~/.omp/supipowers/config.json` or per-repository in `.omp/supipowers/config.json`. In monorepos, the repository config is shared by the root target and every workspace, and `/supi:checks` defaults to `All` (root target + every workspace target).
 
 ## Configuration
 
@@ -148,23 +149,27 @@ Gates default to disabled. Enable them per-project in `.omp/supipowers/config.js
 
 Opens an interactive settings screen. Toggles flip instantly, selects open a picker, text fields open an input dialog.
 
-Configuration is a three-layer deep-merge (lowest to highest priority):
+Configuration uses built-in defaults plus two user-managed override layers:
 
 1. Built-in defaults
 2. `~/.omp/supipowers/config.json` — global overrides
-3. `.omp/supipowers/config.json` — per-project overrides
+3. `.omp/supipowers/config.json` — repository overrides
 
+`/supi:config` exposes only `Global` and `Repository`. In monorepos, the repository config is shared across every workspace; there are no per-workspace Supipowers config files for general settings.
 
 ## Release channels
 
 Three built-in channels are available: `github` (GitHub Release via `gh` CLI), `gitlab` (GitLab Release via `glab` CLI), and `gitea` (Gitea Release via `tea` CLI). Channels are selected per-project in `release.channels`.
 
-Release notes are generated from conventional commits scoped to the paths listed in `package.json`'s `files` field — commits touching files outside those paths are excluded.
+`/supi:release` auto-detects publishable release targets at runtime. In single-package repos it keeps the classic root-package flow. In Bun, npm, pnpm, and Yarn workspaces it discovers publishable packages from workspace metadata, auto-selects the only publishable target when there is one, and otherwise opens a picker that lists all publishable packages with changed packages first. Target choice is runtime-only and is not persisted to config.
 
-`/supi:release` accepts two optional flags:
+Release notes are scoped to the selected target's publishable paths. When that target declares a `files` whitelist in its `package.json`, only commits touching those paths are included. Otherwise the changelog falls back to the target package directory plus its `package.json`. Root releases keep the configured `release.tagFormat`; workspace releases use `<package-name>@<version>` tags to avoid collisions across packages.
+
+`/supi:release` accepts three optional flags:
 
 | Flag | Effect |
 | ----------- | ------ |
+| `--target <package>` | Skip the target picker and release the named package directly |
 | `--raw` | Skip AI polish of release notes; use raw conventional-commit output |
 | `--dry-run` | Run the full release flow without publishing |
 
@@ -187,7 +192,7 @@ Custom channels can be defined in `release.customChannels`:
 | Field            | Required | Description                                                    |
 | ---------------- | -------- | -------------------------------------------------------------- |
 | `label`          | yes      | Display name shown in the release picker                       |
-| `publishCommand` | yes      | Shell command run to publish; `$tag`, `$version`, `$changelog` are passed as environment variables |
+| `publishCommand` | yes      | Shell command run to publish; `$tag`, `$version`, `$changelog`, `$targetName`, `$targetId`, `$targetPath`, `$manifestPath`, and `$packageManager` are passed as environment variables |
 | `detectCommand`  | no       | Shell command to detect availability; exit 0 = available. If omitted, the channel is assumed available |
 
 ## Skills
@@ -197,6 +202,7 @@ Supipowers ships runtime-loaded prompt skills that are also available to the age
 | Skill                   | Used by                 |
 | ----------------------- | ----------------------- |
 | `planning`              | `/supi:plan`            |
+| `ui-design`             | `/supi:ui-design`       |
 | `code-review`           | Manual prompting / reusable review guidance |
 | `qa-strategy`           | `/supi:qa`              |
 | `fix-pr`                | `/supi:fix-pr`          |

package/bin/install.mjs

@@ -5,11 +5,26 @@ import { dirname, join } from "node:path";
 
 const isWindows = process.platform === "win32";
 const __dirname = dirname(fileURLToPath(import.meta.url));
-// When invoked via bunx/npx, always force a full install to guarantee
-// node_modules/ and a consistent extension directory. The --force flag
-// bypasses the "already up to date" version check.
-const args = [join(__dirname, "install.ts"), "--force", ...process.argv.slice(2)];
-const result = spawnSync("bun", args, {
+
+const userArgs = process.argv.slice(2);
+const subcommand = userArgs[0];
+
+let script;
+let scriptArgs;
+
+if (subcommand === "migrate") {
+  // `bunx supipowers migrate [...]` — execution-state migration.
+  script = join(__dirname, "migrate.ts");
+  scriptArgs = userArgs.slice(1);
+} else {
+  // Default: installer flow. When invoked via bunx/npx, always force a full
+  // install to guarantee node_modules/ and a consistent extension directory.
+  // The --force flag bypasses the "already up to date" version check.
+  script = join(__dirname, "install.ts");
+  scriptArgs = ["--force", ...userArgs];
+}
+
+const result = spawnSync("bun", [script, ...scriptArgs], {
   stdio: "inherit",
   env: process.env,
   shell: isWindows,

package/bin/install.ts

@@ -25,6 +25,11 @@ import { resolve, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { homedir } from "node:os";
 import { scanAll, installDep, formatReport } from "../src/deps/registry.js";
+import {
+  runMempalaceSetup,
+  snapshotMempalaceInstall,
+} from "../src/mempalace/installer-helper.js";
+import { createPaths } from "../src/platform/types.js";
 import type { ExecResult } from "../src/platform/types.js";
 
 const isWindows = process.platform === "win32";
@@ -128,6 +133,7 @@ async function exec(cmd: string, args: string[]): Promise<ExecResult> {
 
 const cliArgs = process.argv.slice(2);
 const skipDeps = cliArgs.includes("--skip-deps");
+const skipMempalace = cliArgs.includes("--skip-mempalace");
 const FORCE = cliArgs.includes("--force");
 const DEBUG = cliArgs.includes("--debug");
 
@@ -555,6 +561,14 @@ async function main(): Promise<void> {
     }
   }
 
+  // ── Step 5: MemPalace memory (optional) ─────────────────────
+
+  if (!skipMempalace) {
+    await offerMempalaceSetup();
+  } else {
+    log("--skip-mempalace flag set, skipping MemPalace prompt");
+  }
+
   // ── Done ───────────────────────────────────────────────────
 
   const targetNames = targets.map((t) => t.name.toLowerCase()).join(" or ");
@@ -566,6 +580,87 @@ async function main(): Promise<void> {
   outro(`supipowers is ready!`);
 }
 
+async function offerMempalaceSetup(): Promise<void> {
+  const cwd = process.cwd();
+  const paths = createPaths(".omp");
+  const snap = snapshotMempalaceInstall(paths, cwd);
+
+  if (!snap.bridgeOk) {
+    note(
+      `MemPalace bridge missing at ${snap.bridgePath}.\n` +
+        "The supipowers package was installed without the bundled Python bridge.\n" +
+        "Reinstall supipowers and rerun setup.",
+      "MemPalace",
+    );
+    return;
+  }
+
+  const message = snap.ready
+    ? `Reinstall MemPalace memory (mempalace==${snap.packageVersion})? Recreates the managed venv.`
+    : "Install MemPalace memory now? Downloads uv (~30MB), Python 3.12, and the mempalace package.";
+
+  const ok = await confirm({
+    message,
+    initialValue: !snap.ready,
+  });
+  if (isCancel(ok) || !ok) {
+    note(
+      "Skipped. Run `/supi:memory setup` from inside OMP, or rerun the installer to revisit this step.",
+      "MemPalace",
+    );
+    return;
+  }
+
+  const s = spinner();
+  s.start("Installing MemPalace...");
+
+  const runner = async (
+    cmd: string,
+    args: string[],
+    runnerOpts?: { input?: string; timeoutMs?: number },
+  ) => {
+    const result = run(cmd, args, {
+      ...(runnerOpts?.input ? { input: runnerOpts.input } : {}),
+      ...(runnerOpts?.timeoutMs ? { timeout: runnerOpts.timeoutMs } : {}),
+    });
+    return {
+      code: result.status ?? 1,
+      stdout: result.stdout ?? "",
+      stderr: result.stderr ?? "",
+    };
+  };
+
+  const result = await runMempalaceSetup({
+    paths,
+    cwd,
+    runner,
+    onProgress: (msg) => s.message(msg),
+  });
+
+  if (!result.ok) {
+    s.stop("MemPalace installation failed");
+    note(
+      `${result.error.message}\n\n${result.error.remediation ?? ""}`.trim(),
+      "MemPalace error",
+    );
+    return;
+  }
+
+  s.stop(
+    `MemPalace v${result.details.packageVersion} ready (Python ${result.details.managedPython} via uv)`,
+  );
+  note(
+    `palace path: ~/.mempalace/palace\n` +
+      `managed venv: ${result.details.venvPath}\n` +
+      `uv binary: ${result.details.uvPath} (${result.details.uvVersion})\n\n` +
+      "On the first OMP session in this project, ask the agent to run\n" +
+      `  mempalace(action="init", dir=".", yes=true)\n` +
+      `  mempalace(action="mine", dir=".", limit=20)\n` +
+      "or just say `init mempalace` and the agent will register the project's wing and seed memory.",
+    "MemPalace",
+  );
+}
+
 main().catch((e) => {
   console.error(e);
   process.exit(1);

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "supipowers",
-  "version": "1.5.3",
+  "version": "2.0.0",
   "description": "Workflow extension for OMP coding agents.",
   "type": "module",
   "scripts": {
-    "test": "bun test tests/",
+    "test": "bun test --timeout 20000 tests/",
     "typecheck": "tsc --noEmit",
-    "test:watch": "bun test --watch tests/",
+    "test:watch": "bun test --timeout 20000 --watch tests/",
+    "test:evals": "bun test --timeout 20000 tests/evals/",
     "build": "tsc -p tsconfig.build.json",
+    "install:visual-server": "npm --prefix src/visual/scripts ci --ignore-scripts --no-audit --no-fund",
+    "postinstall": "bun run install:visual-server",
     "prepare": "git config core.hooksPath hooks || true"
   },
   "engines": {
@@ -61,7 +64,8 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.10.0",
-    "handlebars": "^4.7.8"
+    "handlebars": "^4.7.8",
+    "yaml": "^2.8.3"
   },
   "peerDependencies": {
     "@oh-my-pi/pi-coding-agent": "*",

package/skills/context-mode/SKILL.md

@@ -4,9 +4,9 @@ Route high-output tool calls through sandboxed execution to protect the context
 
 | Scope | Tool routing rules for supi-context-mode |
 |-------|-----------------------------------------------------|
-| Trigger | Always active when supi-context-mode tools are available |
+| Trigger | Active-aware; only currently active `ctx_*` tools can be used or named as enforced replacements |
 | Goal | Prevent context flooding — a single unrouted command can dump 56 KB into context |
-| Key rule | Blocked tools return errors; use sandbox equivalents instead |
+| Key rule | Blocked native tools are blocked only when an active `ctx_*` replacement exists |
 
 ## Tool Selection Hierarchy
 
@@ -16,27 +16,28 @@ Pick the highest-priority tool that fits the task:
 |----------|------|---------|
 | 1 — GATHER | `ctx_batch_execute(commands, queries)` | Primary tool. Runs all commands, auto-indexes, returns search results. ONE call replaces 30+ individual calls. |
 | 2 — FOLLOW-UP | `ctx_search(queries: ["q1", "q2", ...])` | Query already-indexed content. Pass ALL questions as array in ONE call. |
+| 2.5 — CACHE | `ctx_open_cached(handle, offset?, limit?)` | Open `cache://<sha>` handles when this tool is active. Returns bounded slices only. |
 | 3 — PROCESSING | `ctx_execute(language, code)` / `ctx_execute_file(path, language, code)` | Sandbox execution. Only stdout enters context. |
 | 4 — WEB | `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` | Fetch, chunk, index, query. Raw HTML never enters context. |
 | 5 — INDEX | `ctx_index(content, source)` | Store content in FTS5 knowledge base for later search. |
 
 ## Blocked Commands
 
-Blocked commands are intercepted and replaced with an error. Do NOT retry via Bash.
+Blocked commands are intercepted only when their replacement `ctx_*` tool is active for the turn. Do NOT retry via Bash when a block reason names an active replacement.
 
 | Blocked tool | Replacement |
 |---|---|
 | `curl` / `wget` in Bash | `ctx_fetch_and_index(url, source)` or `ctx_execute` with `fetch()` |
 | Inline HTTP (`fetch('http`, `requests.get(`, etc.) in Bash | `ctx_execute(language, code)` — only stdout enters context |
 | WebFetch / Fetch tool | `ctx_fetch_and_index(url, source)` then `ctx_search(queries)` |
-| Grep tool | `ctx_search(queries)`, `ctx_batch_execute(commands, queries)`, or `ctx_execute(language: "shell", code: "grep ...")` |
+| Search tool | `ctx_search(queries)`, `ctx_batch_execute(commands, queries)`, or `ctx_execute(language: "shell", code: "grep ...")` |
 | Find / Glob tool | `ctx_execute(language: "shell", code: "find ...")` or `ctx_batch_execute(commands, queries)` |
 
-### Example: routing a grep call
+### Example: routing a search call
 
 ```
 // WRONG — blocked, returns error
-grep(pattern: "TODO", path: "src/")
+search(pattern: "TODO", paths: ["src/"])
 
 // CORRECT — runs in sandbox, only printed summary enters context
 ctx_execute(language: "shell", code: "grep -rn TODO src/")
@@ -58,15 +59,21 @@ For everything else:
 - `ctx_batch_execute(commands, queries)` — multiple commands + search in ONE call
 - `ctx_execute(language: "shell", code: "...")` — sandbox, only stdout enters context
 
+When OMP's `shellMinimizer` is active, large bash output ends with a `[raw output: artifact://<id>]` footer. The footer is OMP's pointer to the full bytes — supipowers leaves it untouched. Recover the original with `read artifact://<id>`.
+
 ### Read
 
-Reads are never blocked — OMP's native read tool preserves hashline anchors (`N#XX`) for the edit contract. Large reads (>110 lines) are auto-compressed to head (80) + tail (30) with a `sel` hint.
+Reads are never blocked — OMP's native open/read tool preserves hashline anchors (e.g., `120th|content` after 14.4.1) for the edit contract. Large reads (>110 lines) are auto-compressed to head (80) + tail (30) with a `sel` hint.
 
 For analysis-only reads where anchors are not needed, prefer `ctx_execute_file(path, language, code)` — only your printed summary enters context.
 
-## Subagent Routing
+### Cache handles
+
+When a prompt or prior output contains a `cache://<sha>` handle, open it with `ctx_open_cached(handle, offset?, limit?)` only if `ctx_open_cached` is active in the current tool catalog. Use bounded offsets/limits for follow-up reads; do not assume cached handles can be opened when the tool is inactive.
+
+## Runtime Routing Guidance
 
-The routing block is automatically injected into subagent prompts. Bash-type subagents are upgraded to general-purpose for tool access. You do NOT need to manually instruct subagents about context-mode.
+The injected prompt is a compact, active-aware summary generated from the current active tool list. This static file is reference documentation; it is not injected wholesale.
 
 ## Output Constraints
 
@@ -82,7 +89,7 @@ The routing block is automatically injected into subagent prompts. Bash-type sub
 
 ## Checklist
 
-- [ ] Used tool hierarchy (batch_execute > search > execute > fetch) — not raw Bash/Grep/Find
+- [ ] Used tool hierarchy (batch_execute > search > execute > fetch) — not raw Bash/Search/Find
 - [ ] No blocked tool calls attempted
 - [ ] Artifacts written to files, not returned inline
 - [ ] Source labels are descriptive for later search

package/skills/harness/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: harness
+description: Guides the harness-engineering pipeline — turn a codebase into one that resists agentic slop with agent-neutral docs, mechanically enforced architecture, and three runtime guardrails
+---
+
+# Harness Skill
+
+Loaded by `/supi:harness`. Drives a six-phase pipeline that turns an arbitrary codebase into a *harness-friendly* one and installs a persistent **anti-slop** layer that catches the failure modes LLMs reliably fall into.
+
+## What it produces
+
+- **Tier 1 — agent-neutral**: `AGENTS.md`, `docs/architecture.md`, `docs/golden-principles.md`, native lint/structural-test/eval configs at the repo root. Usable by any harness (Codex, Claude Code, Cursor, supipowers, …).
+- **Tier 2 — supipowers-aware**: `.omp/supipowers/config.json` gate wiring + `.omp/supipowers/review-agents/harness-architecture.md`.
+- **Tier 3 — anti-slop**: persistent slop queue, layer-aware context injection on every agent turn, pre-edit duplication probe, post-session dead-code sweep, lenient + strict scorecard, and architecture-aware LLM reviewer.
+
+## Phases
+
+|#|Phase|Artifact|Validator|Gate|
+|---|---|---|---|---|
+|1|Discover|`<session>/discover.json`|TypeBox schema + cross-check vs deps registry|user review|
+|2|Research|`<session>/research/<topic>.md`|≥2 primary sources + `## Options` / `## Recommendation`|none|
+|3|Design|`<session>/design-spec.md` + `<session>/decisions.jsonl`|Spec-reviewer sub-agent|user approval|
+|4|Plan|`~/.omp/supipowers/projects/<slug>/plans/<plan>.md`|Reuses `validatePlanMarkdown`|OMP plan-mode UI|
+|5|Implement|repo writes (Tier 1+2+3)|`bun typecheck` + `bun test` + anti-slop hooks loadable|none|
+|6|Validate|`<session>/validate-report.json`|Re-runs every artifact + anti-slop scan + synthetic-edit test|user accept|
+|—|GC|drift report + targeted fix sub-agents|reuses Validate|none|
+
+Each stage runs as a fresh `platform.createAgentSession` with a per-stage prompt. Stage runners are idempotent: if the canonical artifact exists and validates, the stage is skipped.
+
+## Gate modes
+
+- `default`: gate at Discover review, Design approval, Plan-approval, Validate-accept.
+- `auto`: end-to-end without user gates.
+- `manual`: gate every stage.
+
+## Anti-slop guardrails
+
+Three project-scoped runtime hooks, all individually toggle-able in `.omp/supipowers/config.json`:
+
+```json
+{
+  "harness": {
+    "anti_slop": {
+      "pre_edit_dupe_probe": { "enabled": true, "threshold": 0.85, "min_token_count": 30 },
+      "post_session_sweep": { "enabled": true, "block_on_new_dead_code": false },
+      "layer_context_inject": { "enabled": true, "addendum_max_chars": 800 },
+      "score_floor": { "strict": 75, "lenient": 90, "release_blocking": false }
+    }
+  }
+}
+```
+
+Hooks register only when `.omp/supipowers/harness/marker.json` exists at session start. Other repos see no behavior change.
+
+## Backend selection
+
+Discover recommends a backend based on repo languages; Design lets the user override:
+
+|Repo profile|Recommended backend|Why|
+|---|---|---|
+|TypeScript / JavaScript only|`fallow` + supi-native|No Python dep, deepest supipowers integration|
+|3+ languages, or Python/Rust/Go|`desloppify`|29-language coverage, battle-tested LLM review|
+|TS-dominant + non-TS subtrees|`hybrid`|fallow on TS, desloppify on the rest|
+|Niche / no external CLIs allowed|`supi-native`|Manual lint/dupe per stack|
+
+## Score model
+
+Scorecard has lenient + strict scores (0–100). Strict counts `wontfix` items as cost so it cannot be gamed. Score floor in config gates `/supi:checks` and CI when `release_blocking: true`.
+
+## Subcommands
+
+- `/supi:harness` — bare entry. New repos start the pipeline; harness-installed repos prompt **harden / rebuild / cancel**.
+- `/supi:harness discover|research|design|plan-draft|implement|validate` — run/advance one stage.
+- `/supi:harness resume` — resume an in-flight session.
+- `/supi:harness status` — display stage + score badge.
+- `/supi:harness gc` — drain the slop queue, classify mechanical vs judgmental, and dispatch fix sub-agents.
+- `/supi:harness next` — pop the next unresolved queue entry.
+- `/supi:harness resolve <id>` — mark an entry resolved.
+- `/supi:harness backlog` — list every open entry.
+- `/supi:harness score` — recompute and display the score.
+
+## Conventions you MUST follow
+
+- Every phase persists a typed artifact before claiming done. Validate owns the completion claim.
+- Re-running a phase is idempotent: unchanged inputs produce identical outputs.
+- The slop queue is content-addressed; duplicate violations from different backends collapse to the same id.
+- Hooks must complete in ≤500 ms p95. On timeout, emit a one-line warning and skip — never block on perf.
+- Agent-neutral artifacts (Tier 1) MUST NOT depend on supipowers being installed.
+
+## When to run
+
+- New repo: install the harness on day 0 so the anti-slop hooks observe every change.
+- Existing repo: install after a major refactor so duplicates and dead code don't compound.
+- Recurring: run `/supi:harness gc` weekly (or pin to CI) to drain the queue.

package/skills/ui-design/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: ui-design
+description: Design Director state machine for `/supi:ui-design`. Drives 9 model-owned phases from scope selection through user review, producing a validated HTML mockup artifact.
+---
+
+# Design Director
+
+Guide the Design Director through 9 model-owned phases to produce a validated design artifact under `<sessionDir>`. Loaded by `/supi:ui-design` via system-prompt override.
+
+You **MUST NOT** generate production code, write outside the session directory, or skip phases. You **MUST NOT** call `exit_plan_mode`. Use `planning_ask` for every user question — never the raw `ask` tool.
+
+## Director state machine
+
+Before advancing to the next phase, you MUST verify the precondition output is on disk. `manifest.json` is the single source of truth for "what phase are we in". If state is unclear, re-read it and resume the first phase whose precondition output is missing.
+
+| # | Phase | Precondition (file on disk) | Output (file to produce) | Manifest status on completion |
+|---|---|---|---|---|
+| 1 | Scope selection | `manifest.json` with `status: "in-progress"` | `planning_ask` result → update `manifest.scope`; write to `manifest.json` | `in-progress` |
+| 2 | Context review | `manifest.scope` populated | `<session>/context.md` (rendered ContextScan + gap-interview answers) | `in-progress` |
+| 3 | Decomposition | `<session>/context.md` exists | `<session>/screen-decomposition.html` (companion) + `<session>/decomposition.json` (kebab-case names, uniqueness asserted via `new Set(names).size === names.length`) | `in-progress` |
+| 4 | Parallel components | `<session>/decomposition.json` exists | `<session>/components/<name>.html` + `<session>/components/<name>.tokens.json` per non-reused component | `in-progress` |
+| 5 | Section assembly | all non-reused components present | `<session>/sections/<name>.html` per section | `in-progress` |
+| 6 | Page composition | all sections present | `<session>/page.html`; update manifest | `critiquing` |
+| 7 | Design-critic pass | `<session>/page.html` exists | `<session>/critique.md` with `## Fixable` and `## Advisory` headers | `awaiting-review` |
+| 8 | Fix loop (≤ 2 iterations) | `<session>/critique.md` exists | Fixes applied in-place; critic re-run; leftover fixable items become advisory when budget exhausted | `awaiting-review` |
+| 9 | User review gate + finalize | critic fix loop terminated | `<session>/screen-review.html`; `planning_ask` → approve / request-changes / discard; set `manifest.status = "complete"` + `approvedAt` on approve; revert to Phase 8 on request-changes; set `manifest.status = "discarded"` on discard | `complete` or `discarded` |
+
+## Parallelism rules
+
+- Phase 4: parallel fan-out via a single `task` call carrying one sub-task per component. Pass each sub-agent its kebab-cased component name, a short brief, and the exact target path.
+- Phase 5: serial. Later sections may reference earlier sections; avoid races on shared assets.
+- Phase 7: single sub-agent. Cheap, focused pass.
+
+## Filename collision prevention
+
+During Phase 3, before writing `decomposition.json`:
+
+1. Kebab-case every component name.
+2. Assert `new Set(names).size === names.length`.
+3. On collision, disambiguate with a numeric or semantic suffix (e.g., `hero-primary`, `hero-secondary`) and re-check.
+
+Do **NOT** invoke `task` if the collision check fails — sub-agents will race on the same output path.
+
+## Sub-agent invocation guide
+
+Use `task` for sub-agents; never `createAgentSession`. Three templates live under `skills/ui-design/sub-agent-templates/`:
+
+- `component-builder.md` — Phase 4
+- `section-assembler.md` — Phase 5
+- `design-critic.md` — Phase 7
+
+Every sub-agent MUST be passed the full `context.md` so component authors share the same design brief.
+
+## HARD-GATE
+
+You MUST NOT:
+- Write outside `<sessionDir>`.
+- Generate production code (`.ts`, `.tsx`, `.vue`, `.svelte`, `.py`, etc.) intended for the user's codebase.
+- Call `exit_plan_mode` or `ExitPlanMode` — the `/supi:ui-design` completion flow runs through the `agent_end` approval hook.
+- Use the `ask` tool — use `planning_ask` for every user prompt.
+- Skip a phase or declare "done" without updating `manifest.json`.
+- Invoke `task` without a completed filename-collision check (Phase 3).
+- Claim a phase is complete before the file named in its "Output" column exists on disk.

package/skills/ui-design/sub-agent-templates/component-builder.md

@@ -0,0 +1,29 @@
+# Component Builder Sub-agent
+
+You are building a single self-contained HTML fragment for the `/supi:ui-design` pipeline.
+
+## Inputs (passed by the Design Director)
+
+- `contextMd` — the full design brief (tokens, existing components, design.md, package info)
+- `componentSpec` — `{ name, brief, reusedFrom? }` (kebab-cased name, short prose brief)
+- `outPath` — absolute path where the HTML fragment MUST be written
+- `tokensOutPath` — absolute path where a `tokens-used.json` summary MUST be written
+
+## Contract
+
+1. Read `contextMd` and internalize the design tokens and existing components.
+2. Produce a single-file HTML fragment at `outPath`:
+   - Self-contained: inline `<style>` or `<script>` only.
+   - No external dependencies, no remote URLs, no CDN imports.
+   - Must render standalone in a browser.
+3. Write `tokensOutPath` as JSON: `{ "colors": ["primary", "..."], "fonts": ["sans"], "spacing": ["8px", "16px"] }` listing the token identifiers actually used.
+4. Do NOT write outside `outPath` and `tokensOutPath`.
+
+## Output
+
+Return a single status line in your final message:
+
+- `ok` — both files written.
+- `failed: <short reason>` — nothing was written or the spec was unbuildable.
+
+Never return HTML in your message body; the directory listing is the product.

package/skills/ui-design/sub-agent-templates/design-critic.md

@@ -0,0 +1,46 @@
+# Design Critic Sub-agent
+
+You critique a composed page for consistency with the design brief in the `/supi:ui-design` pipeline.
+
+## Inputs
+
+- `contextMd` — the full design brief
+- `pageHtml` — absolute path to the composed `page.html`
+- `allTokensUsedJson` — absolute path to a file aggregating every component's `tokens-used.json`
+- `outPath` — absolute path where `critique.md` MUST be written
+
+## Contract
+
+1. Read the page HTML and the aggregated tokens summary.
+2. Compare against `contextMd` for:
+   - Token consistency — are colors, fonts, and spacing drawn from the declared design system?
+   - Component reuse — are shared components used where they should be?
+   - Spacing and rhythm — are vertical/horizontal gaps consistent?
+   - Accessibility essentials — alt text, contrast, heading hierarchy.
+3. Write `outPath` as markdown with exactly two top-level headings:
+
+   ```markdown
+   # Critique
+
+   ## Fixable
+
+   - <finding-1>
+   - <finding-2>
+
+   ## Advisory
+
+   - <finding-1>
+   ```
+
+   - `Fixable`: issues the director can resolve by editing existing files in the session dir.
+   - `Advisory`: issues that require design-system or scope changes — not fixable in this session.
+
+4. Do NOT modify the page or component files.
+5. Do NOT write outside `outPath`.
+
+## Output
+
+Single status line in your final message:
+
+- `ok` — critique written.
+- `failed: <short reason>` — nothing written.

package/skills/ui-design/sub-agent-templates/pencil/component-builder.md

@@ -0,0 +1,29 @@
+# Component Builder Sub-agent (pencil-mcp)
+
+You are building a single reusable frame inside a `.pen` file for the `/supi:ui-design` pipeline.
+
+## Inputs (passed by the Design Director)
+
+- `contextMd` — the full design brief (tokens, existing components, design.md, package info)
+- `componentSpec` — `{ name, brief, reusedFrom? }` (kebab-cased name, short prose brief)
+- `penFilePath` — absolute path to the target `.pen` file; EVERY `mcp__pencil_*` call MUST pass `filePath: <penFilePath>`
+- `parentNodeId` — the `Components` frame id under which the new reusable frame must be inserted
+- `nodeOutPath` — absolute path where you MUST write the returned node id (plain text, just the id) so the Director can record it in `node-manifest.json.componentNodeIds`
+
+## Contract
+
+1. Read `contextMd` and internalize the design tokens and existing components. Do NOT invent tokens.
+2. Use `mcp__pencil_batch_design` to insert a single reusable frame under `parentNodeId` named exactly `componentSpec.name`. The frame MUST set `reusable: true` so the Director can instantiate it later via a `ref`.
+3. Compose the internal structure with nested `batch_design` operations on the returned id. Prefer existing reusable components inside the `.pen` file when the user's design system already covers the shape.
+4. Write `nodeOutPath` with the ID of the top-level reusable frame you created — nothing else, no JSON, no prose.
+5. Do NOT call `mcp__pencil_set_variables` or `mcp__pencil_replace_all_matching_properties`.
+6. Do NOT write any file outside `nodeOutPath`.
+
+## Output
+
+Return a single status line in your final message:
+
+- `ok` — reusable frame inserted, `nodeOutPath` written.
+- `failed: <short reason>` — nothing inserted or the spec was unbuildable.
+
+Never dump node JSON in your message body; the `.pen` file and `nodeOutPath` are the product.