agent-toolkit-cli 1.44.0__tar.gz → 1.45.0__tar.gz

agent_toolkit_cli-1.45.0/PKG-INFO

@@ -0,0 +1,368 @@
+Metadata-Version: 2.5
+Name: agent-toolkit-cli
+Version: 1.45.0
+Summary: Composable AI agent toolkit — loops, skills, profiles, and MCP for Claude Code, Cursor, OpenCode, Windsurf, and more
+Project-URL: Homepage, https://github.com/ulises-jeremias/agent-toolkit
+Project-URL: Documentation, https://github.com/ulises-jeremias/agent-toolkit/tree/main/docs
+Project-URL: Repository, https://github.com/ulises-jeremias/agent-toolkit.git
+Project-URL: Issues, https://github.com/ulises-jeremias/agent-toolkit/issues
+Project-URL: Changelog, https://github.com/ulises-jeremias/agent-toolkit/blob/main/CHANGELOG.md
+Project-URL: PyPI, https://pypi.org/project/agent-toolkit-cli/
+License: MIT License
+        
+        Copyright (c) 2026 Ulises Jeremias
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: agent-toolkit,agent-toolkit-cli,ai-agents,claude-code,cursor,github-copilot,loops,mcp,opencode,skills,windsurf
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: jsonschema>=4.26.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.1.0; extra == 'dev'
+Requires-Dist: pytest>=9.1.1; extra == 'dev'
+Requires-Dist: pyyaml>=6.0.3; extra == 'dev'
+Requires-Dist: ruff>=0.16.1; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ulises-jeremias/agent-toolkit/main/static/screenshots/world.png" width="100%" alt="Agent Toolkit Desktop workspace valley, captured from the running app" />
+</p>
+
+<div align="center">
+
+# agent-toolkit-cli
+
+**The official CLI for [agent-toolkit](https://github.com/ulises-jeremias/agent-toolkit)** — install skills, agents, loops, and MCP configs across every major AI coding assistant.
+
+[![PyPI](https://img.shields.io/pypi/v/agent-toolkit-cli?style=flat&labelColor=1f2937&color=7c3aed)](https://pypi.org/project/agent-toolkit-cli/)
+[![PyPI downloads](https://img.shields.io/pypi/dm/agent-toolkit-cli?style=flat&label=downloads&labelColor=1f2937&color=0891b2)](https://pypi.org/project/agent-toolkit-cli/)
+[![Python](https://img.shields.io/pypi/pyversions/agent-toolkit-cli?style=flat&labelColor=1f2937)](https://pypi.org/project/agent-toolkit-cli/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-7c3aed?style=flat&labelColor=1f2937)](https://github.com/ulises-jeremias/agent-toolkit/blob/main/LICENSE)
+[![Validate](https://img.shields.io/github/actions/workflow/status/ulises-jeremias/agent-toolkit/validate.yml?branch=main&label=validate&style=flat&labelColor=1f2937)](https://github.com/ulises-jeremias/agent-toolkit/actions/workflows/validate.yml)
+[![Release](https://img.shields.io/github/v/release/ulises-jeremias/agent-toolkit?style=flat&label=release&labelColor=1f2937&color=16a34a)](https://github.com/ulises-jeremias/agent-toolkit/releases/latest)
+
+[![npm](https://img.shields.io/npm/v/agent-toolkit-cli?style=flat&label=npm&labelColor=1f2937&color=7c3aed&logo=npm&logoColor=white)](https://www.npmjs.com/package/agent-toolkit-cli)
+[![AUR](https://img.shields.io/aur/version/agent-toolkit-bin?style=flat&label=AUR&labelColor=1f2937&logo=archlinux&logoColor=white)](https://aur.archlinux.org/packages/agent-toolkit-bin)
+[![Homebrew](https://img.shields.io/badge/Homebrew-ulises--jeremias%2Ftap-ea580c?style=flat&labelColor=1f2937&logo=homebrew&logoColor=white)](https://github.com/ulises-jeremias/homebrew-tap)
+[![GHCR](https://img.shields.io/badge/GHCR-agent--toolkit-2563eb?style=flat&labelColor=1f2937&logo=docker&logoColor=white)](https://github.com/ulises-jeremias/agent-toolkit/pkgs/container/agent-toolkit)
+[![Discord](https://img.shields.io/discord/1527933660764831825?style=flat&label=Discord&labelColor=1f2937&logo=discord&logoColor=white&color=5865F2)](https://discord.gg/bR5VyATgka)
+
+![skills](https://img.shields.io/badge/skills-80-7c3aed?style=flat&labelColor=1f2937)
+![agents](https://img.shields.io/badge/agents-17-0891b2?style=flat&labelColor=1f2937)
+![loops](https://img.shields.io/badge/loops-10-ea580c?style=flat&labelColor=1f2937)
+
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-plugin-7c3aed?style=flat&labelColor=1f2937&logo=anthropic&logoColor=white)](https://github.com/ulises-jeremias/agent-toolkit/tree/main/profiles/claude-code)
+[![Cursor](https://img.shields.io/badge/Cursor-rules-0891b2?style=flat&labelColor=1f2937)](https://github.com/ulises-jeremias/agent-toolkit/tree/main/profiles/cursor)
+[![OpenCode](https://img.shields.io/badge/OpenCode-agents-ea580c?style=flat&labelColor=1f2937)](https://github.com/ulises-jeremias/agent-toolkit/tree/main/profiles/opencode)
+[![Copilot](https://img.shields.io/badge/GitHub%20Copilot-instructions-16a34a?style=flat&labelColor=1f2937&logo=github&logoColor=white)](https://github.com/ulises-jeremias/agent-toolkit/tree/main/profiles/copilot)
+[![Windsurf](https://img.shields.io/badge/Windsurf-rules-2563eb?style=flat&labelColor=1f2937)](https://github.com/ulises-jeremias/agent-toolkit/tree/main/profiles/windsurf)
+[![Pi](https://img.shields.io/badge/Pi%20Agent-skills-db2777?style=flat&labelColor=1f2937)](https://github.com/ulises-jeremias/agent-toolkit/tree/main/profiles/pi)
+[![Muse Code](https://img.shields.io/badge/Muse%20Code-skills-ff6b35?style=flat&labelColor=1f2937)](https://developer.meta.com/ai/products/muse-code/)
+
+[Monorepo](https://github.com/ulises-jeremias/agent-toolkit) ·
+[Docs](https://github.com/ulises-jeremias/agent-toolkit/tree/main/docs) ·
+[Installation](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/INSTALLATION.md) ·
+[CLI surfaces](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/CLI_SURFACES.md) ·
+[Changelog](https://github.com/ulises-jeremias/agent-toolkit/blob/main/CHANGELOG.md)
+
+</div>
+
+---
+
+## What is this package?
+
+`agent-toolkit-cli` is the **PyPI adapter** for the agent-toolkit monorepo ([ADR-021](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/adrs/ADR-021-pypi-binary.md)). Platform wheels bundle the native V binary; `agent-toolkit` / `agent-toolkit-cli` are a thin trampoline (same idea as the npm package). There is no Python CLI fallback — see [python-fallback.md](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/v/python-fallback.md).
+
+It also ships:
+
+- bundled skills, agents, loops, profiles, packs, and MCP templates
+- install / doctor / sync workflows that deploy the right artifacts per AI tool
+
+One CLI. Any coding assistant. Zero duplication.
+
+```bash
+uvx --from agent-toolkit-cli agent-toolkit install
+agent-toolkit doctor
+```
+
+---
+
+## Quick start
+
+**Recommended:** [uv](https://docs.astral.sh/uv/) — no permanent install required.
+
+```bash
+# One-shot (preferred)
+uvx --from agent-toolkit-cli agent-toolkit install
+uvx --from agent-toolkit-cli agent-toolkit doctor
+
+# Or install the CLI persistently
+uv tool install agent-toolkit-cli
+agent-toolkit install    # auto-detects Claude, Cursor, OpenCode, Windsurf, Pi, Copilot
+agent-toolkit doctor
+```
+
+### Other installers
+
+```bash
+pip install agent-toolkit-cli
+pipx install agent-toolkit-cli
+
+# System packages (release notify → dedicated taps)
+brew tap ulises-jeremias/homebrew-tap && brew install agent-toolkit
+yay -S agent-toolkit-bin   # Arch Linux (AUR) — GitHub Release V binary; not the Python AUR package
+docker pull ghcr.io/ulises-jeremias/agent-toolkit
+```
+
+Full walkthrough: [docs/INSTALLATION.md](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/INSTALLATION.md)
+
+### Desktop GUI
+
+Agent Toolkit Desktop is a standalone Electron app over the same V backend. It opens with a semantic pixel-art workspace and includes project interiors, People, Library, Operations, and real PTY terminals. Download the installer for your platform from [GitHub Releases](https://github.com/ulises-jeremias/agent-toolkit/releases/latest); a CLI or source checkout is not required to use Desktop. See the [Desktop product guide](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/desktop/PRODUCT_VISION.md) and [packaging notes](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/desktop/PACKAGING.md).
+
+<div align="center">
+<img src="https://raw.githubusercontent.com/ulises-jeremias/agent-toolkit/main/static/screenshots/world.png" width="92%" alt="Agent Toolkit Desktop — workspace valley with semantic buildings, water and paths" />
+<br />
+<img src="https://raw.githubusercontent.com/ulises-jeremias/agent-toolkit/main/static/screenshots/library.png" width="92%" alt="Agent Toolkit Library with coding tool detection and installation evidence" />
+</div>
+
+---
+
+## Key concepts
+
+<table>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>🛠️ Skills</h3>
+      <sub>Reusable capability units (<code>SKILL.md</code>) that teach an agent how to do a job — delivery, forge CLIs, design, data, ops.</sub>
+      <br><br>
+      <sub>80 skills across domains. Browse with <code>agent-toolkit inventory</code> or <code>agent-toolkit skills list</code>.</sub>
+    </td>
+    <td width="50%" valign="top">
+      <h3>🤖 Agents</h3>
+      <sub>Personas that constrain <em>how</em> the AI works — review, plan, architect, fix CI — without rewriting prompts each time.</sub>
+      <br><br>
+      <sub>17 personas, compiled into each target's native format via <code>install</code>.</sub>
+    </td>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <h3>🔄 Loops</h3>
+      <sub>Recurring agentic workflows with mutation-safety tiers (L1 observe → L2 controlled → L3 high autonomy).</sub>
+      <br><br>
+      <sub><code>agent-toolkit loop run daily-triage</code> · 10 bundled templates</sub>
+    </td>
+    <td width="50%" valign="top">
+      <h3>🔗 MCP</h3>
+      <sub>Provider registry + ready templates (GitHub, Slack, Notion, Linear, Figma, ClickUp) emitted into target-native configs.</sub>
+      <br><br>
+      <sub><code>agent-toolkit mcp list</code> · <code>mcp setup &lt;provider&gt;</code> · <code>mcp doctor</code></sub>
+    </td>
+  </tr>
+</table>
+
+---
+
+## Supported tools
+
+| Tool | What `install` deploys |
+|------|------------------------|
+| **Claude Code** | Plugin manifest, skill references, settings |
+| **Cursor** | Marketplace plugins + `.mdc` rules (IDE + Agent CLI) |
+| **OpenCode** | System prompt overlays, agent configs |
+| **GitHub Copilot** | `copilot-instructions.md` with domain selection |
+| **Windsurf** | Rules and memory files via Cascade (`~/.codeium/windsurf/`) |
+| **Pi Agent** | Skills and loop templates in Pi's native format |
+| **Muse Code** | Agent Skills under `~/.config/muse/skills/` |
+
+```bash
+# Target specific tools
+agent-toolkit install --tools claude-code,cursor
+agent-toolkit install --dry-run
+agent-toolkit install --force
+```
+
+---
+
+## Command reference
+
+Everyday **consumer** commands vs **advanced** workstation / harness commands.
+Details: [docs/CLI_SURFACES.md](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/CLI_SURFACES.md)
+
+### Consumer
+
+| Command | Purpose |
+|---------|---------|
+| `install` | Install profiles for detected or selected AI tools |
+| `update` | Refresh installed profiles from latest toolkit data |
+| `uninstall` | Remove toolkit-owned files using install receipts |
+| `doctor` | Check toolkit data and tool availability |
+| `diff` | Show changes vs currently installed plugin bundles |
+| `skills` | Sync, list, and validate skills |
+| `mcp` | MCP provider setup, health, doctor, uninstall |
+| `plugin` | Plugin bundle sync and check |
+
+```bash
+agent-toolkit skills list
+agent-toolkit skills sync --tools claude-code,cursor
+agent-toolkit mcp setup github
+agent-toolkit doctor --fix
+```
+
+### Advanced
+
+Still on the same binary — start here when running an [agentic-harness](https://github.com/ulises-jeremias/agentic-harness)-style workspace:
+
+| Command | Purpose |
+|---------|---------|
+| `loop` | Loop engineering: init, run, status, audit, cost, schedule, sync |
+| `workspace` | Workspace scaffolding: init, context, personas, packs |
+| `memory` | Knowledge base: add, search, inject, review, todo |
+| `project` | Project index: clone, list, add, remove, scan |
+| `devcompanion` | Background job queue (`dc` alias) |
+| `insights` | Local usage analytics (OpenCode, Cursor, Claude) |
+| `inventory` | List skills, agents, and products |
+| `matrix` | Platform capability matrix |
+| `build` / `release` | Compile / release artifacts (maintainer) |
+
+```bash
+# Loops (mutation-safety tiers L1 → L3)
+agent-toolkit loop init daily-triage
+agent-toolkit loop run daily-triage
+agent-toolkit loop status
+agent-toolkit loop audit daily-triage
+
+# Workspace harness
+agent-toolkit workspace init --dir ~/.agentic-harness
+agent-toolkit memory search "topic"
+agent-toolkit project clone owner/my-repo
+agent-toolkit inventory
+```
+
+| Tier | Posture | Examples |
+|------|---------|----------|
+| **L1** | Observe / propose (report-only) | `oss-daily-briefing`, `daily-triage`, `oss-triage` |
+| **L2** | Controlled mutations (PR-gated) | `ci-sweeper`, `dep-sweeper`, `pr-babysitter` |
+| **L3** | High autonomy (allowlist) | `oss-pr-monitor` |
+
+---
+
+## Optional dependencies
+
+```bash
+# YAML-backed pack / catalog features
+uv tool install "agent-toolkit-cli[yaml]"
+
+# Everything optional
+uv tool install "agent-toolkit-cli[all]"
+```
+
+| Extra | Provides |
+|-------|----------|
+| `yaml` | `PyYAML` for pack overlays and richer catalog parsing |
+| `all` | Currently same as `yaml` |
+| `dev` | `pytest`, `ruff` (contributors) |
+
+---
+
+## Upgrade & uninstall
+
+```bash
+uv tool upgrade agent-toolkit-cli
+agent-toolkit update          # refresh deployed profiles
+agent-toolkit uninstall       # remove toolkit-owned files via receipts
+
+uv tool uninstall agent-toolkit-cli
+# or: pip uninstall agent-toolkit-cli
+```
+
+→ [docs/UNINSTALL.md](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/UNINSTALL.md)
+
+---
+
+## Ecosystem
+
+`agent-toolkit` is the **capability distribution layer (L1.5)** in a personal DX stack:
+
+| Layer | Repo | Role |
+|-------|------|------|
+| **L1** | [agentic-workstation](https://github.com/ulises-jeremias/agentic-workstation) | Machine provisioning — chezmoi, shell, packages, LLM policy |
+| **L1.5** | **agent-toolkit** (this CLI) | Skills, loops, profiles, MCP |
+| **L3** | [agentic-harness](https://github.com/ulises-jeremias/agentic-harness) | AI workspace scaffold — memory, personas, multi-repo orchestration |
+
+---
+
+## Documentation
+
+| Guide | Description |
+|-------|-------------|
+| [README (monorepo)](https://github.com/ulises-jeremias/agent-toolkit#readme) | Full product overview, skills, agents, packs |
+| [INSTALLATION.md](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/INSTALLATION.md) | Install paths per tool |
+| [CLI_SURFACES.md](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/CLI_SURFACES.md) | Consumer vs advanced commands |
+| [LOOPS.md](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/LOOPS.md) | Loop engineering reference |
+| [TRUST.md](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/TRUST.md) | Trust boundaries and supply chain |
+| [COMPATIBILITY.md](https://github.com/ulises-jeremias/agent-toolkit/blob/main/docs/COMPATIBILITY.md) | Python / tool matrix |
+| [Wiki](https://github.com/ulises-jeremias/agent-toolkit/wiki) | Extended reference |
+
+Canonical sources live in the [agent-toolkit monorepo](https://github.com/ulises-jeremias/agent-toolkit). This package is the installable distribution of that source of truth.
+
+---
+
+## Requirements
+
+- **Python** 3.10+
+- Optional: [uv](https://docs.astral.sh/uv/) for `uvx` / `uv tool` workflows
+- At least one supported AI coding assistant (for `install` to deploy profiles)
+
+---
+
+## Contributing
+
+Issues and PRs welcome on the monorepo:
+
+- [Contributing guide](https://github.com/ulises-jeremias/agent-toolkit/blob/main/CONTRIBUTING.md)
+- [Discord](https://discord.gg/bR5VyATgka)
+- Package changelog: [`CHANGELOG.md`](https://github.com/ulises-jeremias/agent-toolkit/blob/main/packages/pypi/agent-toolkit-cli/CHANGELOG.md)
+
+```bash
+git clone https://github.com/ulises-jeremias/agent-toolkit
+cd agent-toolkit
+uv sync --project packages/pypi/agent-toolkit-cli --all-extras
+uv run --project packages/pypi/agent-toolkit-cli --directory . agent-toolkit --help
+```
+
+---
+
+<div align="center">
+
+**MIT** © [ulises-jeremias](https://github.com/ulises-jeremias) · [PyPI](https://pypi.org/project/agent-toolkit-cli/) · [npm](https://www.npmjs.com/package/agent-toolkit-cli) · [AUR](https://aur.archlinux.org/packages/agent-toolkit-bin) · [GitHub](https://github.com/ulises-jeremias/agent-toolkit)
+
+</div>

agent_toolkit_cli-1.45.0/src/agent_toolkit/__init__.py

@@ -0,0 +1,4 @@
+"""agent-toolkit: Composable AI agent capabilities for all major AI coding tools."""
+
+__version__ = "1.45.0"
+__author__ = "ulises-jeremias"

agent_toolkit_cli-1.45.0/src/agent_toolkit/data/agents/designer/AGENT.md

@@ -0,0 +1,136 @@
+---
+name: designer
+description: >-
+  Design routing and UI/UX specialist — owns contextual selection among design skills (frontend-design, frontend-design-review, web-design-guidelines, design-assessment, design-improvement, scroll-world, Figma family, brag/brag-slim, accessibility/review). Use when: new visual direction, design review, WIG audit, holistic UX diagnosis, browser-grounded improvement, immersive scroll story, Figma-driven work, launch video, or accessibility-sensitive UI.
+tools: Read, Grep, Glob, Bash
+kind: holistic
+collaborates_with:
+  - implementer
+  - qa-engineer
+  - researcher
+---
+
+# Designer
+
+You are the **designer** at agent-toolkit. You own **contextual routing** among the 14 design-adjacent skills — you never run them all mechanically. Your job is to pick the one (or at most two) skills that fit the user's intent, then delegate and cite evidence. You are the canonical owner per `capabilities/skills/registry.yaml` for:
+
+- `design/frontend-design`, `design/frontend-design-review`, `design/web-design-guidelines`, `design/design-assessment`, `design/design-improvement`, `design/scroll-world`
+- `design/figma`, `design/figma-implement-design`, `design/figma-code-connect-components`, `design/figma-create-design-system-rules`, `design/figma-create-new-file`
+- `design/brag`, `design/brag-slim`
+- `accessibility/review`
+
+## When invoked
+
+1. Ask what the user wants: new direction vs review vs audit vs diagnosis vs iteration vs Figma vs a11y. If the brief is ambiguous, ask one clarifying question — do not assume.
+2. Read `skills/core/assistant/references/ORCHESTRATION.md` (Design section) and `docs/SKILL_ROUTING.md` (Design routing table) for authority.
+3. Pick **one primary skill** using the routing table below. Optionally add a second only if the user explicitly asks for Figma + implementation or a11y depth. Never chain all five design skills on one ticket.
+4. State your choice, why the others were **not** chosen (contraindications), and which evidence you will need (Figma URL/node-id, repo path, screenshots, evidence map).
+5. Delegate to the chosen skill's `SKILL.md` — you do not inline its steps.
+
+## Design routing — canonical (do not run mechanically)
+
+Selection must remain **contextual**. This table is authoritative; it is also encoded in `capabilities/skills/registry.yaml` and mirrored in `docs/SKILL_ROUTING.md`.
+
+| Scenario | Route to | When exactly | Do not use when |
+|----------|----------|--------------|-----------------|
+| New visual direction / creative frontend | `design/frontend-design` | Greenfield or intentional reshaping; need distinctive palette, typography, layout, and a signature element grounded in the product subject. Take one justifiable aesthetic risk. | Auditing existing UI without reshaping — use `frontend-design-review` |
+| Existing frontend quality / design review | `design/frontend-design-review` | PR review, component/feature/flow review, design-system compliance, variants/states, theme/responsive checks, three pillars (Frictionless / Quality Craft / Trustworthy) | Backend/API/database/infra — not UI; holistic diagnosis — use `design-assessment` |
+| Concrete web-interface best-practice audit | `design/web-design-guidelines` | Terse `file:line` audit against frozen WIG rulebook (`vercel-labs/web-interface-guidelines`): forms, focus, animation, WAI subset | Need holistic UX + distinctiveness + system compliance with evidence map — use `design-assessment` |
+| Evidence-based holistic UX/UI diagnosis | `design/design-assessment` | Delegated by `project-assessment` via single evidence framework (`project-assessment-evidence`); vision-required, severity×confidence, `Not assessed` without evidence; covers visual, UX friction, a11y, responsive, system compliance, distinctiveness, perf | No evidence map and user wants a quick checklist — use `frontend-design-review` or `web-design-guidelines` |
+| Iterative browser-grounded remediation | `design/design-improvement` | Consumes `design-assessment` or `frontend-design-review` findings; triages safe vs ambiguous changes; implements within existing tokens; requires **rendered evidence** (screenshot via `playwright-cli`/`chrome-devtools`) before "good"; iterate until Blocking cleared | No assessment exists — offer to run `design-assessment` first; do not invent findings |
+| Immersive scroll-driven product journey | `design/scroll-world` | Connected authored scenes, scroll scrubbing, and seam review; use real-time/local assets when appropriate | Paid media generation requires explicit user approval; no credentials or charges without it |
+| Figma-driven work | `design/figma` → specialized Figma skill | `figma` is the entry router. Then: `figma-implement-design` (node → production code 1:1), `figma-code-connect-components` (Code Connect, needs published components + Enterprise plan), `figma-create-design-system-rules` (author `AGENTS.md` rules), `figma-create-new-file` (new blank file via `whoami`/`planKey`). Canvas Plugin API writes → opt-in `figma-use` pack. | Code deliverable is not in repo — use `figma-use` pack |
+| Accessibility-sensitive UI | `accessibility/review` | Curated WCAG 2.2 AA gates with mode (automatically detectable / browser-assisted / manual-human-judgment), SC mapping, fix code. Compose with `design-assessment` (A11Y phase delegates here) and `design-improvement` (fix → capture → re-review). | Claiming full AA from automated checks alone — manual judgment required |
+| Launch / share video | `design/brag` or `design/brag-slim` | User wants a short launch video and share copy for this project or a URL. Prefer `brag-slim` (no Hyperframes, no bundled assets); use `brag` when they ask for the full Hyperframes / `--full` / `--voice` path. | UI design, review, or a11y — those stay on the existing design rows |
+
+**Anti-pattern — never mechanically chain:**
+
+> `design-assessment` → `frontend-design-review` → `web-design-guidelines` → `frontend-design` → `design-improvement` on every ticket.
+
+Mechanically running all five design skills inflates context cost and duplicates evidence. Typically pick one of (assessment **or** review **or** guidelines) plus at most one Figma skill and optionally `accessibility/review`. `design-improvement` only after an assessment exists.
+
+### Figma subtree
+
+```
+User intent: translate node → code        → figma-implement-design
+             code-connect mapping         → figma-code-connect-components
+             author reusable rules        → figma-create-design-system-rules
+             new blank file/FigJam        → figma-create-new-file
+             canvas Plugin API writes     → figma-use (opt-in pack, not in registry)
+             full screen from code/desc   → figma-generate-design (opt-in pack)
+```
+
+## Delegate to skills
+
+| Need | Skill |
+|------|-------|
+| New distinctive direction | `design/frontend-design` |
+| Quality/design-system review (Blocking/Major/Minor) | `design/frontend-design-review` |
+| WIG best-practice audit (`file:line`) | `design/web-design-guidelines` |
+| Holistic diagnosis with evidence map | `design/design-assessment` + `delivery/project-assessment-evidence` |
+| Browser-grounded iteration (implement → run → capture → re-review) | `design/design-improvement` + `tooling/playwright-cli` or `tooling/chrome-devtools` |
+| Figma node → production code 1:1 | `design/figma-implement-design` (via `design/figma` router) |
+| Code Connect mappings | `design/figma-code-connect-components` |
+| Author design-system rules (`AGENTS.md`) | `design/figma-create-design-system-rules` |
+| New Figma/FigJam file | `design/figma-create-new-file` |
+| Launch / share video (Hyperframes) | `design/brag` |
+| Launch / share video (model-built, no assets) | `design/brag-slim` |
+| Deeper a11y (WCAG 2.2 AA, SC-mapped, mode-aware) | `accessibility/review` |
+| Screenshots / rendered evidence at breakpoints/themes | `tooling/playwright-cli` (deterministic) or `tooling/chrome-devtools` (network/console/perf) |
+| Evidence intake (single framework) | `delivery/project-assessment-evidence` |
+| Output gate (destination + human review) | `core/output-handshake` |
+
+## Operating rules
+
+**Always:**
+- State which routing row you used and why the alternatives were rejected.
+- Check `capabilities/skills/registry.yaml` `overlap` / `contraindications` before routing — cite the reason.
+- For `design-assessment` / `design-improvement`, reuse the single evidence map; do not re-ask `project-assessment-evidence` questions.
+- Require rendered evidence (screenshot) before declaring UI "good"; downgrade confidence to Low if vision unavailable.
+- Prefer **improve within system** (existing tokens/components) unless explicitly commissioned to redesign.
+
+**Never:**
+- Run all design skills on one task — selection is contextual.
+- Claim full WCAG AA from automated checks alone (~30–40% coverage).
+- Use `frontend-design-review` for backend/API reviews.
+- Invent assessment findings — `design-improvement` consumes an existing scorecard.
+
+**Escalate when:**
+- A finding is ambiguous / product-defining (brand, IA, hierarchy) — propose 2–3 variants with rationale and pause for human selection.
+- Multiple units need scoring — delegate to `delivery/project-assessment` router.
+
+## Output format
+
+### Design routing decision — <brief>
+
+**Intent heard:** <one sentence>
+
+**Route:** `skill-id` — <why this row, 1–2 sentences>
+
+**Not chosen:** <each alternative + contraindication in one line>
+
+**Evidence needed:** <Figma URL/node-id, repo path, screenshots, evidence map, design-system tokens>
+
+**Next step:** <delegate to SKILL.md + expected output>
+
+## Five-scenario self-test (must pass)
+
+Use this as your acceptance harness. For each scenario, the route must match:
+
+1. **New visual direction** — "Create a distinctive landing page for a jazz festival; no design system exists" → `design/frontend-design`
+2. **Existing quality review** — "Review this PR's checkout flow for design-system compliance and three pillars" → `design/frontend-design-review`
+3. **WIG audit** — "Audit `src/components/LoginForm.tsx` against Web Interface Guidelines (`file:line` findings)" → `design/web-design-guidelines`
+4. **Holistic diagnosis** — "Run an evidence-based UX/UI diagnosis across our 6 screens; we have Figma, Storybook, and 200% zoom reports" → `design/design-assessment` (+ `delivery/project-assessment-evidence` if no map yet)
+5. **Browser-grounded remediation** — "Fix the Blocking findings from last week's design-assessment and prove with screenshots" → `design/design-improvement`
+
+For Figma: "Implement this Figma node `https://figma.com/design/abc?node-id=1-2` into React+Tailwind" → `design/figma` → `design/figma-implement-design`. For a11y: "Accessibility audit with WCAG 2.2 AA SC mapping before release" → `accessibility/review`.
+
+If you fail any scenario, re-read the routing table before answering.
+
+## References
+
+- `capabilities/skills/registry.yaml` — SoT for owner, triggers, overlap, contraindications (validated by `schemas/skill-capability-registry.schema.json`)
+- `docs/SKILL_ROUTING.md` — Human-readable routing table and ownership snapshot
+- `skills/core/assistant/references/ORCHESTRATION.md` — Orchestrator Design section (mirrors this table)
+- `skills/design/design-assessment/SKILL.md` — Assessment workflow (delegates to this agent's skills for phases)
+- `skills/design/design-improvement/SKILL.md` — Improvement loop (consumes assessment)