Inventory Design

Inventory Design

!accelerator config context --skill inventory-design --fail-safe !accelerator config agents --fail-safe

If no "Agent Names" section appears above, use these defaults: accelerator:reviewer, accelerator:codebase-locator, accelerator:codebase-analyser, accelerator:codebase-pattern-finder, accelerator:documents-locator, accelerator:documents-analyser, accelerator:web-search-researcher, accelerator:browser-locator, accelerator:browser-analyser.

Design inventories directory: !accelerator config path research_design_inventories --fail-safe

You are tasked with crawling a design source and producing a structured design-inventory artifact. The artifact captures the design tokens, components, screens, and features of the source so a downstream analyse-design-gaps run can compute a structured diff between two snapshots.

Crawler Modes

Default selection: if --crawler is not specified, the skill selects:

• hybrid — when the location is a code-repo path (auto-downgrades to code if Playwright is unavailable; see Steps 3–5)
• runtime — when the location is an https:// URL

Steps

1. Validate Arguments

Run:

accelerator design validate-source \
  "<location>" ${allow_internal_flag} ${allow_insecure_scheme_flag}

where allow_internal_flag is --allow-internal if the user passed that flag (otherwise omit it), and allow_insecure_scheme_flag is --allow-insecure-scheme if the user passed that flag (otherwise omit it).

If it exits non-zero, report the error to the user and stop. Do not create any artifact directory.

By default, https:// URLs to public hosts and http://localhost / http://127.0.0.1 are accepted without any flag. Other internal hosts (RFC1918, link-local, other loopback IPs) require --allow-internal — on either scheme. --allow-internal subsumes --allow-insecure-scheme for internal hosts: a user accepting internal-host SSRF risk has already accepted the strictly-greater concern. Plain http:// to a non-localhost public host requires --allow-insecure-scheme (NOT --allow-internal, which would be a misleading flag name for that case).

Source-id format: source-id must match ^[a-z0-9][a-z0-9-]*$ (kebab-case, lowercase, no leading hyphen, no spaces). If it does not, report a clear error naming the offending characters and stop.

2. Resolve Auth Mode

Run:

accelerator design resolve-auth

Capture the output (header, form, or none). If it exits non-zero, report the error to the user and stop.

[!WARNING] The header-auth path is currently inert. The daemon imports its auth-header handler and never calls it, and the origin allowlist that handler requires (ACCELERATOR_BROWSER_LOCATION_ORIGIN) is set nowhere. An authenticated crawl therefore produces an unauthenticated inventory, and the allowlist described below is not enforced by anything. Do not put a live credential in ACCELERATOR_BROWSER_AUTH_HEADER until that is wired up.

Auth-header origin allowlist (security-critical, once wired up): if auth mode is header, the ACCELERATOR_BROWSER_AUTH_HEADER value is injected only on navigations whose origin (scheme+host+port) matches the resolved [location] origin or the ACCELERATOR_BROWSER_LOGIN_URL origin. On any cross-origin navigation (off-site link, OAuth redirect, or any attacker-controlled target reached during the crawl), strip the header before the request is issued. Instruct the {browser analyser agent} to enforce this explicitly.

Auth-walled route handling: when auth mode is none and a route appears to require authentication, skip it and record it in Crawl Notes with the message:

inventory-design: skipped <url> (appears auth-walled). Set ACCELERATOR_BROWSER_AUTH_HEADER, or ACCELERATOR_BROWSER_USERNAME / _PASSWORD / _LOGIN_URL, to crawl authenticated routes.

Do not fabricate observations for auth-walled screens.

3. Provisional Crawler-Mode Resolution

Determine the provisional crawler mode from the CLI flag and defaults:

• Explicit --crawler code → code (skip Steps 4–6)
• Explicit --crawler runtime → runtime (proceed to Step 4)
• Explicit --crawler hybrid → hybrid (proceed to Step 4)
• No flag, location is a code-repo path → hybrid (proceed to Step 4)
• No flag, location is an https:// URL → runtime (proceed to Step 4)

4. Resolve the Playwright Runtime

Only if provisional mode is runtime or hybrid.

The vendored Playwright runtime — the driver bundle and the browser — is materialised on demand by the executor; there is no bootstrap script to run. On a warm cache this is instant; on a cold cache the first runtime command fetches the artifacts (a few hundred MB), which can take time on a slow connection. Resolution, liveness and any host-level downgrade are all confirmed by the single executor ping in Step 5.

5. Confirm the Runtime and Executor

Only if provisional mode is runtime or hybrid, run:

accelerator design executor ping

This drives the executor's availability check in order — platform probe, runtime materialisation, browser resolution — then launches the daemon and probes it. Interpret the outcome:

• {"ok":true,...} on stdout (exit 0) → the runtime and executor are healthy; proceed to Step 6.
• {"error":"downgrade","reason":"<enum>"} on stderr (exit 3) → the runtime is unavailable on this host. Extract <enum>.
  • If provisional mode was hybrid: downgrade to code. Print the downgrade notice (see below) and record it in Crawl Notes. Then skip to Step 7.
  • If provisional mode was runtime: hard-fail with the reason and stop.
• Any other error or non-zero exit → treat as executor-ping-failed and apply the same hybrid/runtime handling.

Downgrade notice: run:

accelerator design notify-downgrade --from <mode> --to code --reason <enum>

and print its stdout before the crawl starts (not only in Crawl Notes).

6. Finalize Crawler Mode

The crawler mode is now finalised. Use what survived Steps 3–5:

• If Step 3 set code, use code.
• If Steps 4–5 succeeded for runtime or hybrid, use that mode.
• If downgrade occurred in Steps 4 or 5, use code.

7. Compute Next Sequence Number

Scan all *-{source-id}/inventory.md files under the design inventories root. Read each frontmatter sequence field. Take max + 1, starting at 1 if none exist. This is the sequence number for the new inventory.

8. Spawn Agents in Parallel

Based on the chosen crawler mode:

code mode: spawn {codebase locator agent} and {codebase analyser agent} in parallel to discover and extract:

• Design tokens (Tailwind config, CSS custom properties, design-token JSON, theme files)
• Component inventory (JSX/TSX/Vue/Svelte files, named exports, prop signatures)
• Routing config (React Router, Next.js pages/app, Vue Router)
• Feature flags and conditional blocks

runtime mode: spawn {browser locator agent} to enumerate routes/screens, then spawn {browser analyser agent} for each screen group in parallel.

hybrid mode: spawn both code and browser agents in parallel. Use code-static output as ground truth for tokens and component names; use runtime output for screen states, computed styles, and screenshots.

Forward the allowances to the browser agents (security-relevant): when spawning {browser locator agent} or {browser analyser agent}, tell each to substitute {allow-flags} in its executor calls with exactly the allowance flags this invocation received — the same ${allow_internal_flag} / ${allow_insecure_scheme_flag} values passed to validate-source in Step 1. The executor injects them into every forwarded request so the daemon classifies each navigate and each links destination under them. Omitting this would let a legitimate --allow-internal crawl pass the front door and then be refused mid-crawl.

Crawl bounds (enforced regardless of crawler mode):

• Page cap: at most 50 distinct routes per crawl. On cap hit, write the inventory with status: incomplete and list unreached routes in Crawl Notes.
• Wall-clock timeout: 5 minutes total per crawl. Same handling.
• Screenshot byte budget: 50 MB per crawl. When exhausted, skip remaining screenshots and record which screens have no visual capture in Crawl Notes. The crawl continues until another bound fires; the inventory is written with screenshots_incomplete: true in frontmatter.

Screenshot masking: the executor automatically masks [type=password], [autocomplete*=token], and [data-secret] selectors in screenshots. Never attempt to read or expose the values of masked fields.

URL scrubbing: strip query strings from any URL written into the inventory body (screen routes, references). Document this reduction in Crawl Notes.

Auth-header origin allowlist (security-critical): if auth mode is header, the executor's route() handler enforces that ACCELERATOR_BROWSER_AUTH_HEADER is injected only on navigations whose origin matches the resolved [location] origin or the ACCELERATOR_BROWSER_LOGIN_URL origin. Instruct the {browser analyser agent} to enforce this explicitly for any manual header injection it performs.

9. Synthesise

Compile agent findings into the five inventory categories:

1. Design tokens — colour, typography, spacing, radius, shadow (with token names and computed values)
2. Component catalogue — name, variants, props summary, usage count
3. Screen inventory — route, observed states (loading/empty/error/success), screenshot paths
4. Feature catalogue — named features, activation mechanism (route, flag, interaction)
5. Information architecture — navigation structure, primary user flows

10. Generate Metadata

Run:

accelerator corpus metadata derive --filename-timestamp-format compact-time

11. Populate frontmatter and write artifact (atomic)

Build the inventory under a sibling temporary directory:

<design_inventories>/.YYYY-MM-DD-HHMMSS-{source-id}.tmp/
  inventory.md
  screenshots/

Use the design-inventory template:

!`accelerator config template design-inventory --fail-safe`

Before writing inventory.md, substitute every field below with the indicated value, using the helper output captured in Step 10 (Current Date/Time (UTC):, Current Revision:, Repository Name:):

• type: ← design-inventory
• id: ← the inventory directory name (e.g. YYYY-MM-DD-HHMMSS-{source-id}), always quoted as a YAML string
• title: ← Design Inventory: {source-id}
• date: ← the Current Date/Time (UTC): value
• author: ← the author resolved per the standard chain (config → VCS user → prompt)
• producer: ← inventory-design
• status: ← draft
• revision: ← the Current Revision: value (omit when the source is not a code repository — the helper omits the line itself in that case)
• repository: ← the Repository Name: value (same omission rule)
• last_updated: ← the same Current Date/Time (UTC): value
• last_updated_by: ← the same value resolved for author
• schema_version: ← 1 (bare integer)

Optional linkage keys are omit-by-default (ADR-0040): the template shows each as ""/[], but write a key into the artifact only when it has a value, and omit it entirely otherwise (do not carry the empty placeholder through).

• parent: ← the work item this inventory supports, as a typed-linkage ref ("work-item:NNNN"). Fill when the inventory has an owning work item; otherwise omit the key.
• relates_to: ← list of typed-linkage refs to related artifacts (["design-inventory:NNNN", ...]). Fill when relationships are explicit; otherwise omit the key.

The domain fields (source, source_kind, source_location, crawler, sequence, screenshots_incomplete) are filled from the values resolved in earlier steps.

Pre-write secret scrubber: before moving the tmp directory to its final name, run:

accelerator design scrub-secrets "<tmp_dir>/inventory.md"

If it exits non-zero, delete the tmp directory and report the error. Do not write the artifact. Do not print the value of any environment variable in the error message.

Move the tmp directory to its final name:

<design_inventories>/YYYY-MM-DD-HHMMSS-{source-id}/

Both the directory glob and the resolver explicitly skip leading-dot directories, so an in-progress .tmp/ is invisible to readers.

Supersede prior inventories: after the new directory is in place, glob *-{source-id}/ under the inventory root (excluding leading-dot names). Exclude the just-written directory. For each remaining directory where inventory.md has status: draft or status: accepted, set status: superseded. This step is idempotent; if it fails partway through, the new directory is already authoritative (the resolver uses sequence as its primary tiebreaker).

Validate the frontmatter: after the inventory is at its final path, run

accelerator corpus frontmatter validate \
  --file <design_inventories>/YYYY-MM-DD-HHMMSS-{source-id}/inventory.md

If it exits non-zero, the document violates the canonical frontmatter standard; report the emitted violation and fix the frontmatter before completing.

12. Cleanup

If a Playwright daemon was started (Steps 4–5 succeeded), stop it:

accelerator design executor daemon-stop

This is belt-and-braces — the browser agents also call accelerator design executor daemon-stop as their final action. Running it here ensures cleanup even if an agent exits abnormally.

13. Present Summary

Report:

• The artifact path
• Source-id, location, crawler mode used
• Count of tokens, components, screens, and features discovered
• Any crawl bounds that fired (cap, timeout, screenshot budget)
• Any auth-walled routes that were skipped
• Whether a prior inventory was superseded

Suggest next steps:

• Run /accelerator:inventory-design <target-source-id> <target-location> for the target design surface if not already done
• Run /accelerator:analyse-design-gaps <current-source-id> <target-source-id> to compute the gap

Important Guidelines

• Never fabricate observations. Record only what agents actually found.
• If a partial crawl fires a bound, write what was found and mark the inventory status: incomplete — do not silently drop data.
• Do not expose env-var values in any output, log, or artifact body.
• The sequence field is the resolver's primary tiebreaker. Always compute it by reading existing inventories before writing.
• The .tmp/ → final directory rename is atomic on POSIX filesystems. Do not write directly to the final directory name.

!accelerator config instructions inventory-design --fail-safe