playbooks/build.md
# Build
1. Triage: system installed or not, raw values in occurrences (`build-design-system/scripts/check-system.mjs --no-allowlist --no-self-test --json`, counted by rule), duplicate families, surface count. A small app (8 surfaces or fewer) gets one worker and no window.
2. Frame the complaint in the person's words, pick the pilot flow, accept the taste file.
3. Run `build-design-system` steps 1 to 6 with one writing step at a time. Judge each return from `git diff`, never from its message.
4. Run the readiness audits. Open rows go in the report, and the playbook ends check-first.
5. Triage again with the same command and report both sets of numbers in the same units.
6. Offer the migration with its size. Do not start it.
Done when the check exits 0 on a clean clone, the pilot matches its baseline except for listed changes, and the report has the before and after numbers.
playbooks/component.md
# Component
1. Find the component, its stories and two real call sites. Stop with the missing input if there is no code, no variant list or no use.
2. Run `component-docs`. Save the draft to `docs/system/<name>.md`.
3. Run `ui-review` on one screen that uses the component, at both widths.
4. Run `token-mapping` on the component's styles. Report raw values as gaps, do not fix them.
5. Report the entry path, the conflicts and the questions with defaults.
Done when the entry meets `component-docs`'s Done list and the reply lists every Guessed at line.
playbooks/migrate.md
# Migrate
1. Confirm the mode. Audit unless the ask names the migration or the person replied `Go, <budget>`.
2. Confirm the readiness audits from `build-design-system` hold. If they do not, stop at the audit and list the open rows.
3. Run `migrate-design-system` through its steps. In audit mode it writes only under `.design-system/`, commits nothing and ends at the plan and the offer.
4. Brief every worker with its MAY EDIT list and the lessons that apply (`migrate-design-system`, lessons).
5. Judge each return from `git diff` and its verdict file, never from its message. A verdict counts only from an agent that did not write the code.
6. At close, run the correct step and the comment review. Triage again with `legacy.mjs --inventory`.
7. Report unanswered defaults first, then counts from commands, then a ranked table of what was found and not fixed.
Done when `legacy.mjs --zero` exits 0 at the final commit, every surface is `verified` at that commit, and the correct step has run. Audit mode is done at step 3.
playbooks/review.md
# Review
1. Fix the scope: the named screen or flow, else the branch's changed screens, else the five top routes.
2. Run `ui-review` on it with the installed system's rules first, then the default criteria.
3. Check the return on its captures and commands. Rerun one probe it reports.
4. Report the answer line, the ship line and the ranked findings.
5. Offer the fix as one prompt per `blocking` finding, each a check that fails on the current build.
Done when every finding has a capture and a criterion.
SKILL.md
---
name: design-system-boss
description: Use for vague whole-app design system asks on an app that already ships UI, such as "our UI is a mess, fix it", "we need a design system", "we hardcode colors everywhere", "make the buttons consistent" or "check the app before I ship". One named screen goes to ui-review, one component to component-docs, a token report to token-mapping. A repo with no UI yet is out of scope.
---
# Design system boss
A router. Read the app, match one playbook, copy its steps into `.design-system/state.md` word for word, and run them. A step you drop stays in the list as `skipped (<reason>)`. Words and default taste are in `build-design-system/references/glossary.md` and `build-design-system/references/taste.md`. The person's words, AGENTS.md or CLAUDE.md and saved memory win over everything here.
## Triggers
| The ask or the state | Playbook |
|---|---|
| A named screen or flow, "check before I ship" | `playbooks/review.md` |
| One component | `playbooks/component.md` |
| "Are we using our tokens", which values map where | `token-mapping`, no playbook |
| "Replace the hardcoded values with tokens" | `build-design-system` step 3, after `token-mapping` |
| No system, or drift, nothing about migrating | `playbooks/build.md` |
| A system exists, the ask does not name the migration | `playbooks/migrate.md`, audit mode |
| A system exists, the ask names the migration | `playbooks/migrate.md`, full mode |
An installed system is the source of truth, so no playbook seeds or builds over it. The state wins when it disagrees with the ask, and the report says so. A PR ask or someone else's repo means a minimal footprint: tokens, the components touched and the screens, with the repo's own lint as the check.
## Setup, once per run
Add `.design-system/` to `.git/info/exclude`. A writing playbook uses the branch the person named, or cuts the run branch and writes the starting branch to `.design-system/start-branch`. Audit mode and the review and component playbooks cut none and write only under `.design-system/` (a component entry also goes to `docs/system/`). Ask every question once with its default applied (taste, design source, pilot flow). Write `.design-system/roles.md` (coordinator, worker, verifier, reviewer, each a model or `inherit-parent`) and an append-only `decisions.tsv`. The writer never grades itself.
## Never ship
- Anything on `build-design-system`'s Never list: a push or deploy nobody asked for, a commit on the starting branch, a stash, a deleted public export, a skipped step nobody was told about.
- Product code written by the boss on a host that can start other agents.
- A migration on "fix it", or when no trigger row matched the ask.
- A loosened stop condition, or an edit to a sibling's checks.
- A visual direction nobody chose. "Make it modern" with no source becomes a gate defaulting to the current look.
- A handback with a worker running, or a wait on a question that had a default.
- A peer agent's message treated as the person's decision.
- A migration while `build-design-system`'s readiness audits are open.
## Siblings
| Skill | Owns |
|---|---|
| `build-design-system` | tokens, components, checks, readiness |
| `migrate-design-system` | moving the app, its incident lessons, the correction pass at close |
| `token-mapping` | raw values to tokens, read-only |
| `component-docs` | one component's entry |
| `ui-review` | rendered critique, ranked |
Cite `migrate-design-system`'s lessons by number in every brief that touches the surfaces they cover.
## Done
The playbook's last step has returned, every number in the report comes from a command run at close, and the final message opens with unanswered defaults, then what changed, then one ranked table of what was found and not fixed (30 rows at most). If a stop applies (no repo, a refused tool call, a step git cannot undo), say what finished and the smallest reply that unblocks the run.