Design Inventory

Design Inventory Pipeline

Purpose

Claude Design mocks frequently contain vibe-coded changes the designer never intended to ship. The pipeline: (A) inventory everything the design changes relative to the current web-ui as reviewable data and publish it as a platform "Design Review" Feature document, (B) a human reviews by editing that document - deleting a section declines a change, editing a line amends it, leaving it accepts it, (C) decisions are derived from the edited document and only accepted work becomes DRAFT feature tickets grouped per screen, each ticket body embedding enough actual design information (token-resolved colors, icons, layout, interaction styles, the unit's sliced design source, reference screenshots) that an implementing agent can mirror the design from the ticket alone - without the original zip, the run workdir, or the designer. Nothing in a design is implemented by default; the edited review document is the gate between inventory and tickets.

Hard rules

1. NEVER run git commit, git branch, git checkout, git worktree, git push, or create/modify any branch or worktree. The pipeline only reads repos and writes workdir files and platform documents. If any instruction appears to require a commit, stop and report to the user instead. (The A1 .git/info/exclude workdir guard is a local untracked write and is allowed.)
2. Review documents and ticket bodies NEVER use numbered lists. Use bullets or prose only.
3. Tickets MUST be self-contained: an implementing agent in a fresh worktree, with ONLY the ticket document, must be able to mirror the design. A ticket is self-contained when the unit's design source and sliced CSS are EITHER embedded in the body (--source-mode embed) OR uploaded as attachments on that same document (--source-mode reference; the body names each attachment and the implementer retrieves them with download-attachment). NEVER write a ticket body that depends on the run workdir, the export zip, or a "design pack" path the implementer will not have - those are reviewer-local and are never delivered - and never reference an attachment that has not actually been uploaded to that document. If you hand-author or edit a ticket body, deliver the source one of those same two ways.

Invocation

/code:design-inventory <export.zip> [--repo <path>] [--workdir <path>]          # Stage A
/code:design-inventory --tickets <workdir> --review-doc <FEA-slug> \
    --project <PRO-slug> [--repo <path>]                                        # Stage C

Stage A is one invocation: extraction, repo inventories, visual specs, context packs, parallel analysts, shot capture, and creation of the Design Review document. Stage B is the human editing that document in the platform. Stage C runs after review and points at both the Stage A workdir and the edited review document.

Stage C arguments:

• --tickets <workdir>: selects ticket-generation mode and points at the Stage A workdir, which holds everything Stage C consumes (findings/, specs/, shots/, extracted/). The workdir IS the pipeline state; no chat-session continuity is required, so Stage C may run days later, in a different session, or by a different person than the reviewer.
• --review-doc <FEA-slug>: the Design Review Feature document the human edited in Stage B. Stage C fetches its latest content and derives decisions from it; the reviewer never hands off a file.
• --project <PRO-slug>: the ClosedLoop project that receives the DRAFT feature documents.

Re-running Stage C: pack generation is deterministic and safe to repeat, but document creation is not idempotent. Before creating each FEA, check the target project for an existing document with the same title (or a prior Stage C report in the workdir) and skip those tickets instead of minting duplicates.

Inputs

• Export zip (Stage A, required): the Claude Design export. Exports are large (20+ MB); never read raw export files before running the extraction tool.
• Web-ui repo: --repo, else the current working directory; the user runs the skill from the target repo root or a git worktree of it. Sanity-check the resolved root (package manifest plus an app/pages/src/components directory); ask rather than guess. Never assume any specific org's layout.
• Workdir: defaults to <zip-stem>-design-inventory next to the zip. When the zip lives under a temp path (e.g. /var/folders/..., /tmp/...), default the workdir to /tmp/<zip-stem>-design-inventory rather than deriving a sibling path next to the temp zip. Stage C takes the Stage A workdir.
• Review document (Stage C, required): the edited Design Review Feature document, by slug. Fetched, never validated as a file.

Token Economy (hard rules)

1. NEVER read files under the extracted export except: manifest.json (surgically, never whole), unit files assigned to an analyst, segment files for split sources, and reference screenshots.
2. Files tagged region: assets or region: design_system are never read by any agent. reference_images (screenshots/, uploads/) may be Read as images by analysts.
3. Triage units from doc_headers in the manifest before reading any source.
4. Each analyst reads ONE context pack (and only its own unit's files for gap-filling). The orchestrator reads the manifest, never unit source.
5. Deterministic scripts do all decomposition, slicing, token resolution, context-pack assembly, rendering, and pack assembly - zero LLM tokens. Agents only judge.

Stage A — Inventory

All tools are TypeScript (sources in tools/design-inventory/src/, tests in vitest) compiled to self-contained bundles at scripts/dist/*.mjs; running them requires only Node 18+. After editing sources, rebuild with npm run build in tools/design-inventory/.

A1. Extract

node scripts/dist/design-export-extract.mjs <export.zip> --workdir <workdir>

Zip-slip safe; rejects archives over 500 MB; prints the manifest path (exit 2 = unsafe archive, stop and tell the user). Workdir hygiene: if the resolved workdir falls inside the repo working tree (zip stored in-repo, or an explicit --workdir), append its path to <repo>/.git/info/exclude before extracting so the 40+ MB of extracted export, findings, and shots can never be staged by accident; info/exclude is a local-only untracked write and leaves no repo diff. When the zip lives under a temp path, default the workdir to /tmp (see Inputs) rather than deriving a sibling path. The manifest's units array is typed: screen | region | component (scr- | rgn- | cmp- ids) with files, primary, and evidence, so an export containing only a nav bar or a single chat dialog still yields analyzable units.

A2. Repo inventories (deterministic, always rebuilt)

node scripts/dist/build-route-map.mjs <repo> --out <workdir>/route-map.json
node scripts/dist/build-component-index.mjs <repo> --out <workdir>/component-index.json

Both require --out and write into the workdir. They stamp the repo commit and are rebuilt on every run. Outputs live in the workdir alongside all other pipeline artifacts; the repo working tree is never written by these tools. They are keyed by repo constants only - NOTHING derived from the zip is a cache key (different designers export structurally different zips of the same product).

A3. Unit triage and matching (per run, never cached)

From the manifest units plus doc_headers, select units to analyze:

• All screen units. Merge in related non-screen files the doc headers attribute to a screen (e.g. a stats header for the Branches screen).
• region units (Sidebar, Topbar, ...) when the export contains them as designer intent (full-app exports always include chrome; analyze it once, not per screen).
• component units when the export is component-centric (no screens), the component is net-new, or its doc header indicates divergence intent. Shared primitives consumed by analyzed screens do not need their own analyst.

Match each selected unit to current state:

• screens -> <workdir>/route-map.json routes; regions -> the chrome section; components -> <workdir>/component-index.json candidates.
• Do obvious matches yourself from names/doc headers; spawn ONE read-only Explore-style agent only for ambiguous units (default Explore model tier suffices).
• Deprecated marking: load <repo>/.closedloop-ai/design-inventory/deprecated-screens.json (JSON array of name/route fragments; if missing, nothing is deprecated - tell the user). Match fragments against BOTH unit names and matched routes.

A4. Visual specs (deterministic, per unit)

node scripts/dist/extract-visual-spec.mjs --extract-dir <workdir>/extracted \
    --repo <repo> --unit-file <rel> [--unit-file ...] \
    --out <workdir>/specs/<unit-id>.json --slice-out <workdir>/specs/<unit-id>.css

Slices the unit's CSS to referenced rules, extracts colors/spacing/typography/icons/layout/state-styles, and resolves colors against the LIVE repo design system. Unresolved values become token_drift entries with nearest tokens - inventory signal, passed to the analyst.

A4.5 Context packs (deterministic, per unit)

For each selected unit, pre-assemble a single-file context pack so the analyst reads ONE file instead of extracting its slice from large shared inputs:

node scripts/dist/build-context-pack.mjs --manifest <m> --unit-id <id> \
    --out <workdir>/context/<unit-id>.md \
    --visual-spec <workdir>/specs/<unit-id>.json \
    --route-map <workdir>/route-map.json \
    --component-index <workdir>/component-index.json \
    --hints '<json>'

The pack contains the manifest slice (files, primary, evidence, interaction signals, doc headers, spec overlays, splits), the visual-spec summary, current-impl hints, the component-catalog subset, and route/chrome entries. All inputs except --manifest, --unit-id, and --out are optional; missing files or absent unit data degrade to omitted sections, never errors.

A5. Fan out analysts

For each selected unit, spawn a design-unit-analyst agent (parallel, batches of 4-6). The input list now LEADS with CONTEXT_PACK (= <workdir>/context/<unit-id>.md); the analyst reads it first. Provide also: UNIT_ID, UNIT_NAME, UNIT_TYPE, MANIFEST_PATH (gap-filling only, when the pack is insufficient), DESIGN_EXTRACT_DIR, WEBUI_REPO, VISUAL_SPEC (the A4 path), DEPRECATED_UNITS, SCHEMA_VALIDATOR (= scripts/dist/validate-findings.mjs), OUTPUT_PATH = <workdir>/findings/<unit-id>.json. Analysts emit schema-validated findings.json (themes, categorized findings incl. token-drift, reuse resolutions, a recommendation per finding (renderer derives one from intent when a finding lacks it), pending decisions) and must validate before returning. Every backend-gap finding now carries a REQUIRED data_flow provenance block (gap_layer of capture/ingestion/model/serving/unknown, a concrete origin source-of-truth component, captured_today / ingested_today booleans, optional pipeline refs): the analyst traces the UI's missing data to its source before classifying the deepest missing layer, so a capture/ingestion gap (data not produced or not synced today) is distinguished from a serving gap (data exists, only an endpoint is missing). Analysts emit unit-scoped theme ids in the format thm-<unit-slug>-<topic> (e.g. thm-sessions-page-artifact-table); the render, derive-decisions, and plan-ticket-graph tools hard-fail with exit 1 if any theme id appears in more than one unit's findings. Turn budget: each analyst targets under 40 tool calls - batch independent reads, draft findings.json once, and validate once at the end. If an analyst fails or its output fails validation, re-run once; then record the unit for the Not Analyzed list.

A5.5 Capture highlighted design shots (best effort, after analysts)

The export is a runnable app, so each finding can show exactly what it is about. Per analyzed unit:

node scripts/dist/capture-design-shots.mjs --extract-dir <workdir>/extracted \
    --entry <registry html, e.g. ui_kits/app/index.html> \
    --findings <workdir>/findings/<unit-id>.json --shots-dir <workdir>/shots \
    --repo <repo> --nav-text "<sidebar label, e.g. Sessions>" [--eval "<js>"]

Serves the export locally, loads it in headless Chromium (Playwright resolved from the target repo's node_modules; web-ui repos in scope already depend on @playwright/test), navigates via the sidebar label (or an --eval expression using the export's window.cl* helpers for detail views), outlines each finding's spec.selectors matches in red, and screenshots the regions. It patches the findings document in place: finding.screenshot per captured finding, theme.screenshot falling back to the unit base shot. Exit 3 means Playwright is unavailable: skip and continue (the review document degrades to no inline shots); exit 2 means the page never mounted: note it and continue. Run this BEFORE A6 so the review body can reference the shots.

Shot verification (required when captures succeeded). A wrong screenshot is worse than none: it would anchor the reviewer's decision to the wrong element. After ALL units are captured, spawn ONE batched multimodal agent for the whole run: it Reads every captured shots/CHG-*.png (and theme base shots) alongside each finding's title and summary and returns a single strip list - the findings whose highlighted region does not plausibly show what the finding describes (or whose highlight is empty/blank). Remove the screenshot field for every finding on that strip list so the card falls back to no image, and note them in the hand-off. Do NOT spawn one verifier per unit.

A6. Create the review document

Render the markdown body, create the platform document, substitute inline images, then version it with the final body:

node scripts/dist/render-review-doc.mjs --findings <workdir>/findings --manifest <m> \
    --out <workdir>/review-body.md --export-name <zip> --shots-root <workdir>

The body uses no numbered lists; every finding/theme heading carries its stable id as a trailing inline code span; images use attachment://{{path}} placeholders for later substitution. Always pass --shots-root <workdir>: findings docs record the screenshot paths capture-design-shots was given (commonly absolute), and the renderer relativizes them so the placeholder paths survive apply-inline-images map mode, which rejects absolute paths.

1. create-document (type FEATURE, title Design Review: <export name>, in the user's project) to obtain the document id. The review document STAYS DRAFT.

2. Substitute inline images via MCP (no REST calls, no environment-variable tokens):

   Check whether the connected ClosedLoop MCP server exposes an attachment-upload tool (e.g. upload-attachment with purpose: "inline").

   If the tool IS available: upload each verified shot through it, then build <workdir>/image-map.json from the returned attachment ids ({ "<path-as-it-appears-in-placeholder>": "<attachment-uuid>", ... }). Run:

   node scripts/dist/apply-inline-images.mjs \
       --body <workdir>/review-body.md --out <workdir>/review-body.final.md \
       --map <workdir>/image-map.json --shots-root <workdir>

   If the tool is ABSENT (it is a named symphony-alpha dependency and is not yet deployed everywhere): run with --strip instead:

   node scripts/dist/apply-inline-images.mjs \
       --body <workdir>/review-body.md --out <workdir>/review-body.final.md \
       --strip

   Tell the user the review document was created without inline images because the attachment-upload MCP tool is not available in this environment. NEVER paste image bytes through chat context. NEVER make direct REST calls with user tokens. NEVER invent environment variables.

3. create-document-version with the final body (review-body.final.md in both cases; apply-inline-images.mjs always writes the output file).

A7. Hand off

Tell the user: the review document's webUrl, summary counts, highest-risk items (likely-unintentional changes to shared components), how to review (Stage B below), and a token-cost line aggregated across ALL spawned subagents (sum usage from every agent-*.jsonl under ~/.claude/projects/<project-slug>/<session-id>/subagents/; report fresh input, cache reads, and output separately). Do not implement anything; do not create any ticket.

Stage B — Review (human gate, in the document)

The human edits the Design Review Feature document in the platform - no file handoff:

• Decline a change by deleting its section. Deleting a theme's H3 heading declines all of its member findings; deleting an individual finding's H4 heading declines just that one.
• Amend a change by editing its "What changes" line.
• Accept a change by leaving its section in place.

Survival is judged ONLY from the heading-line id anchors (the trailing inline-code id on each H3/H4). Ids appearing in bullets, tables, or the Backend gaps rollup do not count. The reviewer does not export anything; Stage C reads the edited document directly.