Skip to content

paperclipai/paperclip / .agents/skills/directions-lab

directions-lab

Verified

Scaffold a directions lab that shows shipped UI (Today) beside 2-3 design directions, with surface tabs, theme and animation toggles and the V1 MVP hover motion, registered in design-proposals Storybook. Use for a directions page or lab, or to explore design directions next to production.

FileKindSize
SKILL.mdskill md15.4 KB
agents/openai.yamlconfig291 B
assets/PRECEDENTother187 B
assets/motion/v1-mvp-motion.cssother787 B
assets/templates/api-routes.ts.mjsscript531 B
assets/templates/api-stub.ts.mjsscript1.9 KB
assets/templates/build-info.ts.mjsscript220 B
assets/templates/define-lab.ts.mjsscript3.9 KB
assets/templates/direction/MotionSpecimen.tsx.mjsscript2.3 KB
assets/templates/direction/SlotBody.tsx.mjsscript521 B
assets/templates/direction/index.tsx.mjsscript445 B
assets/templates/direction/tokens.css.mjsscript1.1 KB
assets/templates/entry.html.mjsscript752 B
assets/templates/fixtures.ts.mjsscript1.2 KB
assets/templates/frames/AppShell.tsx.mjsscript5.2 KB
assets/templates/frames/Board.tsx.mjsscript4.8 KB
assets/templates/frames/LabToolbar.tsx.mjsscript4.4 KB
assets/templates/frames/Slot.tsx.mjsscript329 B
assets/templates/frames/SurfaceFrame.tsx.mjsscript1.3 KB
assets/templates/frames/SurfaceView.tsx.mjsscript540 B
assets/templates/kit.ts.mjsscript1.9 KB
assets/templates/lab-state.ts.mjsscript1.8 KB
assets/templates/lab.css.mjsscript74 B
assets/templates/launch-entries.json.mjsscript680 B
assets/templates/main.tsx.mjsscript6.2 KB
assets/templates/providers.tsx.mjsscript920 B
assets/templates/registry.ts.mjsscript1.6 KB
assets/templates/shot.cjs.mjsscript10.0 KB
assets/templates/stories/compare.stories.tsx.mjsscript3.4 KB
assets/templates/tests/api-stub.test.ts.mjsscript1.6 KB
assets/templates/tests/lab-state.test.ts.mjsscript3.1 KB
assets/templates/tests/motion-contract.test.ts.mjsscript5.7 KB
assets/templates/tests/registry.test.ts.mjsscript2.5 KB
assets/templates/tests/today.test.tsx.mjsscript2.0 KB
assets/templates/today/SlotBody.tsx.mjsscript972 B
assets/templates/today/adapters.ts.mjsscript748 B
assets/templates/today/index.tsx.mjsscript387 B
assets/templates/vite.config.mjs.mjsscript2.9 KB
evals/asks-how-many-directions/case.yamlconfig343 B
evals/asks-how-many-directions/graders/01-expected-output.mdmarkdown347 B
evals/asks-how-many-directions/prompt.mdmarkdown197 B
evals/multi-surface-three-directions/case.yamlconfig674 B
evals/multi-surface-three-directions/graders/01-expected-output.mdmarkdown672 B
evals/multi-surface-three-directions/prompt.mdmarkdown510 B
evals/single-surface-two-directions/case.yamlconfig398 B
evals/single-surface-two-directions/graders/01-expected-output.mdmarkdown397 B
evals/single-surface-two-directions/prompt.mdmarkdown284 B
references/canonical-directory.mdmarkdown15.5 KB
references/design-proposals-storybook.mdmarkdown29.2 KB
references/drawing-phases.mdmarkdown21.7 KB
references/generator.mdmarkdown25.7 KB
references/lab-anatomy.mdmarkdown28.7 KB
references/lifecycle.mdmarkdown18.9 KB
references/motion-spec.mdmarkdown21.1 KB
references/questions-and-defaults.mdmarkdown15.6 KB
references/repo-gates.mdmarkdown20.8 KB
references/today-fixtures-and-build.mdmarkdown34.9 KB
scripts/lib/args.mjsscript2.4 KB
scripts/lib/capabilities.mjsscript2.1 KB
scripts/lib/check.mjsscript10.6 KB
scripts/lib/context.mjsscript8.6 KB
scripts/lib/modes.mjsscript1001 B
scripts/lib/ports.mjsscript1.9 KB
scripts/lib/registry-edit.mjsscript5.2 KB
scripts/lib/render.mjsscript3.6 KB
scripts/lib/shared-files.mjsscript2.9 KB
scripts/lib/verify.mjsscript1.8 KB
scripts/lib/write.mjsscript2.3 KB
scripts/scaffold.mjsscript14.3 KB
scripts/scaffold.test.mjsscript33.7 KB

references/generator.md

View on GitHub
# Generator: how `scaffold.mjs` renders a lab

For maintainers of the skill. The agent using the skill reads `SKILL.md`; this file explains the machinery
under `scripts/` and `assets/`, how it was derived from the artifact lab, and how to keep it in step. Every
rule the generator enforces is stated here and nowhere in code: the generator's own JavaScript carries no
comments, for the same repo rule it enforces on the files it writes (`CONTRIBUTING.md`: no code comments).

## Contents

1. Layout
2. Running it
3. The context object (`ctx`)
4. Templates
5. The generated lab, file by file, and the precedent each file came from
6. The motion asset and the drift test
7. Verification, rollback and the shared files
8. `check`, `add-direction`, `list`
9. Tests: `scaffold.test.mjs`
10. Adding or changing a template
11. Re-deriving after the precedent changes
12. Known limits of this version

## 1. Layout

```
.agents/skills/directions-lab/
  assets/
    motion/v1-mvp-motion.css        the V1 MVP hover block with <id> and <p> placeholders (section 6)
    templates/                      JS modules, `export default (ctx, ...) => string` (section 4)
  scripts/
    scaffold.mjs                    CLI: new, check, add-direction, list
    scaffold.test.mjs               node --test, runs in under a second
    lib/args.mjs                    flag grammar per subcommand (--k v, --k=v, booleans), UsageError
    lib/context.mjs                 flags -> ctx: casings, ids, surfaces, directions, landing, company, provenance
    lib/ports.mjs                   first free (dev, preview) pair from 5200/5210 in steps of 20
    lib/capabilities.mjs            validates --capabilities through <root>/scripts/feature-map.mjs
    lib/render.mjs                  loads the templates and produces Map<repo-relative path, content>
    lib/write.mjs                   refuses comments, 600-line files and existing paths; writes; rolls back
    lib/shared-files.mjs            idempotent .claude/launch.json and .gitignore edits with originals kept
    lib/registry-edit.mjs           reads and edits the generator-owned lines of registry.ts and the story
    lib/modes.mjs                   mode A/B detection from scripts/storybook-catalog.mjs
    lib/verify.mjs                  runs the verification commands and formats a failure
    lib/check.mjs                   the `check` rules
  references/generator.md           this file
```

The skill directory is git-ignored (`/.agents/` in `.gitignore`), so every file is added with `git add -f`.

## 2. Running it

From the repo root (`node .agents/skills/directions-lab/scripts/scaffold.mjs ...`):

| Subcommand | Flags | What it does |
| --- | --- | --- |
| `new` | `--slug`, `--title`, `--surfaces id:Label:width@nav,...`, `--directions 2\|3`, `--names a,b[,c]`, `--group`, `--capabilities a/k,...`, `--company name:PREFIX`, `--landing auto\|all\|today\|<id>`, `--ports dev,preview`, `--force-count`, `--dry-run`, `--json`, `--skip-verify`, `--no-build`, `--keep-on-failure`, `--root <dir>` | renders in memory, refuses existing paths, writes, edits the two shared files, verifies, rolls back on failure |
| `check` | `--slug`, `--strict`, `--run`, `--json`, `--skip-verify`, `--root` | the lab's structural rules plus the motion-contract test; `--run` executes the hand-off list |
| `add-direction` | `--slug`, `--name`, `--force-count`, `--json`, `--skip-verify`, `--root` | next digit; one directory from the direction templates; one registry line; one story export; re-runs `check` |
| `list` | `--json`, `--root` | every `ui/src/*-directions/registry.ts`, with launch.json ports |

Exit codes: 0 on success, 1 on any failure (the failing command's output is printed); after a flag-grammar error
(unknown subcommand or flag, missing value) the help text is printed too, after any other usage error only the
message. `--root` points every path at another directory; it exists so the tests can
scaffold into a temporary tree. Verification needs the real repo (`ui/node_modules`), so a scaffold under a
temporary root uses `--skip-verify`.

Defaults: `--title` is the slug in sentence case (`agent-profile-card` -> `Agent profile card`); `--group Components`; `--names` are Refine, Rework, Rethink
(two directions: Refine, Rethink); `--company acmehats:ACM`; `--landing auto`; `--ports` from `ports.mjs`;
`--capabilities` empty, which makes the story carry `capabilities: []` and the exception sentence (the
generator says so on stderr). Four to nine directions need `--force-count` and explicit `--names`.

## 3. The context object (`ctx`)

`context.mjs` derives everything once; templates never compute names. Built by `buildContext(flags, { root,
ports, capabilities })` and, for `add-direction`, by `assembleContext` from a parsed registry.

| Field | Example (`--slug inbox-row`) | Used by |
| --- | --- | --- |
| `slug`, `SLUG` | `inbox-row`, `INBOX_ROW` | paths, env names, the vite define |
| `title`, `group` | `Inbox row`, `Components` | toolbar labels, the story title |
| `labDir`, `entry`, `configFile`, `storyFile` | `ui/src/inbox-row-directions`, `inbox-row-directions.html`, `vite.inbox-row-directions.config.mjs`, `ui/storybook/stories/design-proposals/inbox-row-directions.stories.tsx` | render targets |
| `storyId` | `design-inbox-row-directions` | story meta id, registry, toolbar tooltip |
| `envOutDir`, `envPort`, `buildDefine` | `INBOX_ROW_DIRECTIONS_OUT_DIR`, `INBOX_ROW_DIRECTIONS_PORT`, `__INBOX_ROW_DIRECTIONS_BUILD_COMMIT__` | vite config, launch entries, `lab-env.d.ts`, `build-info.ts` |
| `distDir`, `staticDir` | `ui/dist-inbox-row-directions/`, `node_modules/.inbox-row-directions-dist` | .gitignore line, the preview launch entry |
| `ports` | `{ dev: 5220, preview: 5230 }` | config default port, launch entries |
| `directions[]` | `{ id: "d1-refine", key: "1", digit: 1, name: "1.Refine", label: "Refine", tagline, prefix: "refine", stage: "proposed" }` | registry, kits, tokens, story exports |
| `today` | `{ id: "today", key: "0", name: "0.Today", tagline: "What ships now", baseline: true, stage: "shipped" }` | registry (last), Today kit |
| `kits` | `[...directions, today]` | registry order (Today last) |
| `surfaces[]` | `{ id: "inbox", label: "Inbox", width: 960, nav: "other", Pascal: "Inbox", UPPER: "INBOX", fixture: "INBOX_ITEMS", body: "InboxBody", frame: "InboxFrame" }` | kit contract, frames, fixtures, bodies |
| `multiSurface`, `cells` | `false`, `3` | toolbar row 2, landing rule |
| `landing` | `{ direction: "all", view: "board" }` | registry; `d=all&s=board` when `cells <= 8`, else `d=all&s=<first surface>` |
| `capabilities`, `exception`, `notes` | `[]`, the two house sentences | story paperclip block, registry |
| `company`, `tasks` | `{ id: "company-acmehats", name: "acmehats", issuePrefix: "ACM" }`, three tasks | registry shell, fixtures, stub session |
| `tag` | `[inbox-row-directions]` | the stub's `console.debug` line |
| `publicUrl`, `vercelProject` | `https://paperclip-inbox-row-directions.vercel.app` | registry, story description |
| `forceCount` | `false` | `allowMore: true` in the registry |
| `provenance` | `{ runtimeCommit: <git short sha or "unknown">, skillVersion: "1", createdAt: "YYYY-MM-DD" }` | registry |

`<p>` (the token prefix) is the direction's kebab-cased name, so `--names Bold` gives `d1-bold` and
`--bold-*`. The motion-contract test derives the prefix from the id (`id.replace(/^d\d+-/, "")`), so a
renamed directory keeps its tokens consistent only if the prefix is renamed with it.

## 4. Templates

Every file under `assets/templates/` is an ES module whose default export returns the file's text:

- lab-level: `(ctx) => string` (`main.tsx.mjs`, `kit.ts.mjs`, `registry.ts.mjs`, `stories/compare.stories.tsx.mjs`, ...)
- per surface: `(ctx, surface) => string` (`frames/SurfaceFrame.tsx.mjs`, `today/SlotBody.tsx.mjs`)
- per direction: `(ctx, direction) => string` (`direction/index.tsx.mjs`, `direction/tokens.css.mjs`, `direction/MotionSpecimen.tsx.mjs`)
- per direction and surface: `(ctx, direction, surface) => string` (`direction/SlotBody.tsx.mjs`)
- `launch-entries.json.mjs` returns the two launch objects and exports `launchNames(ctx)`
- `build-info.ts.mjs` also exports `envDts(ctx)` for `lab-env.d.ts`
- `direction/tokens.css.mjs` also exports `motionBlock(direction)`, the asset with placeholders substituted

`render.mjs` owns the mapping from template to target path (`LAB_FILES` for one-per-lab files, loops for
per-surface and per-direction files) and returns a `Map`. Templates are ordinary template literals, so a
backtick or `${` that must reach the output is written `\`` and `\${`; loops over surfaces and directions
are plain `.map().join("\n")`. A template never reads the repo: everything it needs is in `ctx`.

Conventions the templates follow, and `write.mjs` enforces on the result:

- no line starts with `//`, `/*`, `{/*` or `<!--`; the one exception is a `// @vitest-environment <env>` pragma
  on line 1 of a test (`jsdom` in `today.test.tsx` and `api-stub.test.ts`), which vitest requires because
  `ui/vitest.config.ts` sets `environment: "node"`
- no file reaches 600 lines (the repo's hard rule is 1,000; 600 is the house limit for a lab file)
- no `package.json` script or dependency; the lab is invoked through its own vite config
- strings that the catalog must read as literals (the story's `paperclip` block) are emitted with
  `JSON.stringify`, never as template interpolation inside the generated file

## 5. The generated lab, file by file

Precedent: `ui/src/artifact-directions` (`lab-anatomy.md`, `today-fixtures-and-build.md`). Each generic
file was read from the precedent and parameterised; comments were removed; the registry replaced the
hand-maintained literals (`DirectionId`, `DIRECTION_IDS`, `KIT_KEYS`, `KIT_META`, `SURFACE_IDS`,
`VIEW_OPTIONS`, the Board's columns, `shot.cjs`'s `KITS`/`SURFACES`/`KIT_NAMES`).

| Generated | From | What changed |
| --- | --- | --- |
| `ui/<slug>-directions.html` | `ui/artifact-directions.html` | title; script path; the unlayered html/body style block kept verbatim, comment removed |
| `ui/vite.<slug>-directions.config.mjs` | `ui/vite.artifact-directions.config.mjs` | slug in ENTRY, env names, plugin names, cacheDir, watch paths; `define` with the per-lab build commit (`git rev-parse --short HEAD` in try/catch, `"unknown"` fallback) |
| `.claude/launch.json` entries | entries 27-44 | names, config file, ports, env var, static dir |
| `main.tsx` | `main.tsx` | KindsSheet removed; providers moved to `providers.tsx`; `window.__LAB__`; `proposal=1` wraps the page in `AvatarInitialProvider` + `.design-proposal-theme`; `d=all` always renders the Board |
| `providers.tsx` | `main.tsx:182-198` | the provider stack as a component so `today.test.tsx` can reuse it |
| `lab.css` | `lab.css` | verbatim rule |
| `define-lab.ts` | new | registry types and `defineLab()` validation (ids, digit keys, one baseline last, 2-3 explorations unless `allowMore`, `d<N>-<name>` ids keyed `N`, 1-6 surfaces, landing valid) |
| `registry.ts` | `kit.ts:16,130-150` + `SurfaceView.tsx:9-11` | pure data, the single source |
| `kit.ts` | `kit.ts:99-163` | `LabRecord` placeholder, `SurfaceData` (one member per surface, extends `Record<SurfaceId, unknown>` so a missing member fails tsc), `DirectionKit` with one `<Pascal>Body` per surface, ids and maps derived from the registry, the literal `import.meta.glob` |
| `lab-state.ts` | `lab-state.ts` | landing from the registry; `proposal` param; `landingSearch()` |
| `api-stub.ts` | `api-stub.ts` | verbatim minus comments; the debug tag and the stub session's e-mail follow the company |
| `api-routes.ts` | `today/panel-api.ts` pattern | the experimental-settings route answering `registry.today.flags`; an empty `registerFeatureRoutes()` for Phase 2 |
| `fixtures.ts` | `fixtures.ts` | `COMPANY`/`TASKS` from the registry shell, `LAB_NOW`, one `<UPPER>_ITEMS` export per surface with three placeholder records pinned to one week |
| `build-info.ts`, `lab-env.d.ts` | new | `LAB_BUILD` from the vite define (`"dev"` when undefined, so vitest never sees a ReferenceError) |
| `frames/Slot.tsx` | `frames/Slot.tsx` | verbatim |
| `frames/LabToolbar.tsx` | `frames/LabToolbar.tsx` | options from the registry; the label is a link to the landing with the `story <id> · build <sha>` tooltip; row 2 rendered only when `surfaces.length > 1`, otherwise the legend joins row 1; the `0–N` legend (`LEGEND`, the largest digit in `KIT_KEYS`), the Overview hint and the surface options are derived at run time, so `add-direction` and a hand-added surface need no toolbar edit; stage hint for adopted/current |
| `frames/Board.tsx` | `frames/Board.tsx` | `Tile` with the `proposal` prop passed through to its iframe links and `view` narrowed to `SurfaceId`; `KitBoard` columns = surfaces; `AllBoard` rows = directions and columns = every surface (`s=board`) or one (`s=<surface>`) |
| `frames/AppShell.tsx` | `frames/AppShell.tsx` | company and recent tasks from the registry; `active: ShellNav` with `other` |
| `frames/SurfaceView.tsx` | `frames/SurfaceView.tsx` | a `FRAMES` record, one entry per surface |
| `frames/<Pascal>Frame.tsx` | `ThreadFrame.tsx`/`PanelFrame.tsx` shape | a stub: shell, top bar, a dashed region frozen at the registry width marked `data-lab-stub="frame-<id>"` around `<Slot><kit.<Pascal>Body items={<UPPER>_ITEMS} /></Slot>` |
| `directions/today/*` | `directions/today/` | `index.tsx` with literal id/name/tagline; `adapters.ts` with `guid`, `agentId`, `issueIdFor` verbatim plus `issueHref`; one `<Pascal>Body.tsx` stub rendering the items in a dashed box `data-lab-stub="today-<id>"`; no tokens.css |
| `directions/d<N>-<name>/*` | `d5-v1-mvp/` | `index.tsx` importing `./tokens.css`; `tokens.css` (section 6); `MotionSpecimen.tsx` (a `<button>` with two `data-rotate data-spread` backings at inline `-14deg`/`-5deg`, geometry-derived `transform-origin`, static shadow filter, one `[data-front]` sheet, `transition-colors` fills); one `<Pascal>Body.tsx` per surface rendering a specimen per item inside `data-lab-stub="<id>-<surface>"` |
| `shot.cjs` | `shot.cjs` | reads `window.__LAB__` on a first `chrome=0` load instead of mirrored constants (fails with "page did not expose window.__LAB__; main.tsx did not run, read the console"); `--hover` writes `<kit>__<surface>__<theme>__hover.png` from a context without reduced motion; the board sheet is `150px repeat(<surfaces>, minmax(0,1fr))`; no excuse list |
| tests | `lab-state.test.ts`, `api-stub.test.ts`, `Thread.test.tsx` | `registry.test.ts`, `lab-state.test.ts`, `motion-contract.test.ts`, `today.test.tsx`, `api-stub.test.ts` (section 7 of `repo-gates.md` for the conventions) |
| the story | `artifact-directions-compare.stories.tsx` | `installApiStub` in a story-scoped effect with restore; `loadKit`; `SurfaceView`; the `animation` arg sets and restores `data-lab-anim`; `argTypes` and `args` precede `parameters` so `paperclip` is the last parameter; exports `Compare`, `Today`, `D1..DN`, `TodayProductionPalette` |

## 6. The motion asset and the drift test

`assets/motion/v1-mvp-motion.css` is `ui/src/artifact-directions/directions/d5-v1-mvp/tokens.css` lines 68-97 (67 is the comment above the block)
with the comments removed and `d5-v1-mvp` -> `<id>`, `--v1-` -> `--<p>-`. It is the skill's only copy of the
block. `direction/tokens.css.mjs` appends it, substituted, after the direction's light tokens
(`[data-direction="<id>"]`) and dark overrides (`.dark [data-direction="<id>"]`, the `index.css` idiom; d5's
`html:not(.dark)` is the copy hazard named in `lab-anatomy.md`). `add-direction` uses the same template, so
every exploration carries the block; Today never does.

Two tests pin it:

- `scaffold.test.mjs` "motion asset": reads the d5 file, strips `/* */` comments, cuts from the
  `[data-rotate]` rest rule to the end of the `@media (prefers-reduced-motion: no-preference)` block,
  normalises whitespace, substitutes, and asserts equality with the normalised asset. A tune of d5 turns
  this red before any scaffold.
- the generated `motion-contract.test.ts` (node environment, `fs.readFileSync`, never `?raw`, which this
  repo's vitest css pipeline swallows): per exploration, the curve declared once under its scope and no
  other `cubic-bezier(` or `\d+ms`; exactly one `transition:` and it is `transform var(--<p>-hover-ease)` on
  `:is([data-rotate][data-spread], [data-front])`; four gated rules, each starting
  `html[data-lab-anim="1"] [data-direction="<id>"]`, no `data-lab-anim` outside the gate; hover targets
  `[data-front]` (`translateY(-6px)`), `[data-spread="left"]` (`+ 5deg`), `[data-spread="right"]`
  (`- 5deg`) keyed on `button:hover` or `.<p>-tile:hover`; the rest rule outside both gates; no transition
  on filter, box-shadow, opacity or scale; the direction's `.tsx` sources carry `data-front`, `data-rotate`,
  `data-spread` and `--<p>-base`. The hook assertion reads every `.tsx` in the direction directory together,
  so a drawing may keep the hooks in a component rather than in `<Pascal>Body.tsx` itself.

## 7. Verification, rollback and the shared files

`new` is transactional:

1. `validateCapabilities` resolves `--capabilities` through `featureIndex(root)`; `pickPorts` chooses the
   pair; `buildContext` validates every other flag.
2. `renderLab` renders everything in memory; `checkRendered` refuses comment lines, files of 600 lines or
   more, and any target path that exists (so a half-written lab never overwrites a drawn one).
3. `writeFiles` creates directories and files, journaling what it created; `addLaunchEntries` and
   `addGitignoreLine` edit the two shared files and keep their originals in memory. launch.json is parsed,
   appended by name (an entry with the same name is replaced) and written back with
   `JSON.stringify(..., null, 2)`, which reproduces the tracked file byte for byte; the gitignore line goes
   after `dist-flow-preview/` when that line exists, else at the end.
4. Unless `--skip-verify`: `node scripts/storybook-catalog.mjs --check` from the root, then
   `npx vitest run src/<slug>-directions` from `ui/`, then (unless `--no-build`)
   `<SLUG>_DIRECTIONS_OUT_DIR=node_modules/.<slug>-directions-dist npx vite build --config
   vite.<slug>-directions.config.mjs` from `ui/`. The first failure stops the sequence.
5. On failure the failing command's output is printed, then `rollback` unlinks every written file and
   removes every directory it created, `restoreShared` writes the originals back, the build output and the
   lab's vite cache directory are removed, and the exit code is 1. `--keep-on-failure` leaves everything in
   place and prints the removal command instead.

`tsc` is not part of `new`'s verification: `ui/tsconfig.json` includes all of `src` and `storybook`, so a
lab-only typecheck needs a temporary tsconfig (`extends ./tsconfig.json`, `include` the lab directory, its
story and `src/vite-env.d.ts`); `check --run` runs the ui package's `pnpm typecheck` (from `ui/`) instead.

## 8. `check`, `add-direction`, `list`

`check --slug <slug>` reads the registry (`registry-edit.mjs` recognises the generator-owned lines by exact
text and fails loudly when a hand edit changed their shape) and verifies: `directions/` holds exactly the
registry ids and each `index.tsx` carries the registry's id and name; keys are unique digits with one
baseline; every exploration has a tokens.css and Today has none; no comment lines and no file of 600 lines;
none of the artifact lab's names (`DENY_LIST` in `check.mjs`: `artifact-directions`, `LabArtifact`,
`GalleryFrame`, `d5-v1-mvp`, `--v1-`, ...) appear unless listed in `registry.allow`; `<slug>-directions`
appears in no code file under `ui/src`, `ui/storybook` or at the top of `ui/` outside the lab, its html, its
config, its story, launch.json and .gitignore;
no `.css` or `.html` file outside `directions/<id>/tokens.css` carries a `data-lab-anim` rule;
the story's meta id equals `registry.storyId`, the stable exports exist, the `paperclip` parameter comes
last and its status matches the detected mode and the lab's stage (`modes.mjs`: `labStage` is `proposed`
while any exploration is `proposed` or `adopted`, `historical` when every exploration is `historical`,
else `current`; `expectedStoryStatus` maps it to `proposed` in mode A and to itself in mode B; a
`historical` story must also carry `replacement: "<repo-relative .stories.tsx>"` naming an existing
file, and a `replacement:` line in another story never counts as naming `<slug>-directions` outside the
lab); the launch entries and the gitignore line exist. It then
runs `npx vitest run src/<slug>-directions/motion-contract.test.ts`. `--strict` fails on any
`data-lab-stub`; placeholder taglines are warned about on every run. `--run` adds the hand-off list in order (lab vitest,
catalog check, token gates, lab build, the ui `pnpm typecheck`) and prints a `## Verification` block with `Not run:`
lines for `pnpm build-storybook` and the repo-wide typecheck (`NOT_RUN` in `check.mjs`); `--json` carries the
same list as `notRun` beside `ok`, `errors`, `warnings` and `verification`.

`add-direction --slug <slug> --name <Name>` computes the next digit, refuses a fourth without
`--force-count` (and sets `allowMore: true` in the registry when forced), renders the direction templates
through `assembleContext` built from the parsed registry, inserts the registry line before the Today entry
and the story export before `TodayProductionPalette`, then runs `check`; a failing check rolls the
direction back.

`list` prints every lab found with its directions, surfaces, launch ports and story id.

## 9. Tests: `scaffold.test.mjs`

`node --test .agents/skills/directions-lab/scripts/scaffold.test.mjs` (about half a second). It covers flag
parsing, context derivation (casings, landing rule, refusals of every invalid input, `--force-count`),
ports, the write guards (the pragma exception, the 600-line limit, existing paths), the shared-file edits
(idempotence, the anchor), mode detection, the motion asset (drift test, substitution), and then scaffolds
the three eval shapes (`composer` with two surfaces and three directions, `inbox-row` with one surface and
two, `agent-profile-card` with one surface and three) into a temporary `--root` with `--skip-verify` to
assert the file set, the surfaces-row rule, the motion block at the end of every exploration tokens.css,
the specimen hooks and stub markers, no comments and no 600-line file, the story's literal block and
exports, the launch entries and gitignore line, the refusal to overwrite, `list`, `check`, `add-direction`
(including the forced fourth), `--strict`, the `data-lab-anim` placement rule and, after switching the
temporary root to mode B, the Compare status for every lab stage (proposed, current, historical with and
without `replacement`) with `notRun` in the JSON. Two cases run against the real repo without writing:
capability validation through the feature map (`--dry-run`) and an in-memory render of every template.

## 10. Adding or changing a template

1. Read the precedent file the template mirrors (section 5) and the reference that cites it.
2. Edit or add the module under `assets/templates/`; register a new one-per-lab file in `LAB_FILES` in
   `render.mjs`, or add the loop for a per-surface or per-direction file next to the existing ones.
3. Keep the output comment-free and under 600 lines; `checkRendered` refuses otherwise and the test
   "writes no comments and no file of 600 lines or more" fails first.
4. Run `node --test .agents/skills/directions-lab/scripts/scaffold.test.mjs`, then prove a real scaffold:
   `scaffold.mjs new --slug labproof --title Labproof --surfaces thread:Task-thread:960@tasks,panel:Right-panel:434@tasks --directions 3`
   without `--skip-verify`, read any failure, fix the template, repeat until it exits 0; typecheck the lab
   with a temporary tsconfig; then remove the proof lab (the lab directory, its html, its config, its story,
   the two launch entries, the gitignore line, `ui/node_modules/.labproof-directions-dist` and
   `ui/node_modules/.vite-labproof-directions-*`) and confirm with `git status --short`.
5. Update section 5 of this file when a template's relationship to the precedent changes.

## 11. Re-deriving after the precedent changes

The artifact lab stays on master as the frozen reference, so a change there is deliberate and rare. When one
lands: diff the precedent file against the template's output for a scaffolded lab (`git diff --no-index`),
carry the change into the template if it is generic (toolbar, Board, api-stub, main bootstrap, config
options, shot.cjs flags), leave it if it is artifact-specific, and update the line numbers cited in
`lab-anatomy.md` and `today-fixtures-and-build.md`. For the motion block, update `assets/motion/v1-mvp-motion.css`
only after the design decision is taken (the block is never tuned per lab), then run the drift test.

## 12. Known limits of this version

- No shared runtime under `ui/src/directions-lab`: every lab carries its own copy of the generic files, as
  the precedent does. A fix to a generic file reaches existing labs only by hand or by re-scaffolding.
- Subcommands are `new`, `check`, `add-direction`, `list`. `add-surface`, `rename-direction`,
  `direction-story`, `stage`, `diff`, `smoke`, `deploy.sh` and `--answers` are not implemented; a new surface,
  a rename or a stage change is a hand edit of `registry.ts`, the `directions/` tree and the story, confirmed
  with `check`.
- `add-direction` edits the registry and the story by exact-text recognition; a hand-reformatted registry
  (for example by Prettier changing the one-line entries) makes it refuse, quoting the line it could not read;
  only a missing baseline line or a missing `TodayProductionPalette` anchor prints the line to add by hand.
- `check` does not cross-check stage against story sentences beyond the status, and never reads `DESIGN.md`.
- The Board story (`InlineBoard`) is not emitted; the Storybook entry has `Compare`, `Today`, `D1..DN` and
  `TodayProductionPalette`; a board export is a hand-written story in the same file.
- Ports are chosen from launch.json, the reserved list and the vite cache directories, not by probing
  sockets.
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall