Prototype

Build a static HTML prototype of the UI the user asked for. It's for looking at and clicking through, not production code.

If you're running as a subagent (for example, launched by /ai-orchestrator), you can't launch subagents. Do the steps marked "subagent" yourself, skip open, and return only the file path and your assumptions.

1. Gather the design directions

Use these sources, highest priority first:

1. The request itself: layout, tone, palette, density, references, anything the user said about the look.
2. Project design sources, if they exist: .ai-engineering/DESIGN.md, and the global styles/tokens file named in the Project config section of AGENTS.md (colors, fonts, radii). Use them so the prototype looks like the real app.
3. Domain: Project config → Domain and Roles, plus .ai-engineering/PRD.html. Make the fake data realistic for that domain: real-looking names, entities, dates, amounts and statuses. Role-dependent UI follows the roles listed there.

If the request doesn't say which screen or flow it wants, ask one short question. Missing style directions are not a reason to ask: fall back to the project tokens, and if there are none, use a clean, neutral, dense app UI.

Gather sources 2 and 3 with an Explore subagent, not by reading the files yourself. Ask it to return a compact brief with:

• Design tokens: the colors, fonts, radii and spacing from .ai-engineering/DESIGN.md and the global styles file, as exact values.
• What the matching page has today: if a live page already exists for this screen, list its sections, components and copy (Project config → Pages and Components).
• Data fields: the fields the API really returns for this screen (Project config → Shared types and API routes), so the fake data has the right shape.

The brief keeps the raw file dumps out of your context.

2. Build

• Output: one file, .ai-engineering/workflow/prototypes/NNN-<kebab-name>.html. NNN is the next free three-digit number in that folder (001, 002, …), so several prototypes sort. Not in the app source, not at the repo root, not in another folder. Put all CSS and JS inline. Allowed external resources: Tailwind via <script src="https://cdn.tailwindcss.com"></script> and Google Fonts. Nothing else.
• Scope: only the screens or states the user asked for. For a flow, put the steps in one file and switch between them with JS. Don't use extra pages.
• Interactivity: make the key interactions work: tabs, modals, form validation messages, filters over the fake data, and status changes. Use plain JS and no framework.
• States: show the empty, loading, and error states wherever the UI would really have them. Each data state must be reachable through a ?state=<name> URL parameter (e.g. ?state=empty, ?state=error), so review tools can open it directly. A visible switcher in the corner is optional.
• Labels are a contract: use the exact field labels and button text the real page should have. /ai-review-ui drives the prototype and the live page with the same steps by label, so if the text differs, the comparison fails.
• Regions: wrap each part of the screen in an element with data-region="<name>" (e.g. page-header, summary, edit-form). Under /ai-orchestrator, use the region names from the checkpoints' ui.scope.
• State scenario: also write .ai-engineering/workflow/prototypes/NNN-<kebab-name>.states.json with the same number and name as the HTML. It lists every state the prototype shows and how to reach it. Include the regions list, and give each state the regions it exercises. Include the default, filled, validation-error and submitted states for forms, open dialogs, applied filters, and the ?state= data states. The format is in ai-review-ui step 3. It lives in .ai-engineering/workflow/prototypes/ beside its HTML.
• Responsive: the layout must work from 375px up to desktop width, with no horizontal scroll.
• Accessibility basics: semantic elements, labels on inputs, visible focus, and sufficient contrast.
• Declare colors, radii, and fonts once as CSS variables in :root, so a direction change means a one-place edit.

3. Self-check with a subagent

Screenshot the prototype at desktop and mobile widths:

OUT=.ai-engineering/workflow/playwright/prototype/<kebab-name>; mkdir -p $OUT
for vp in 1440,900 375,812; do
  npx -y playwright screenshot --full-page --viewport-size=$vp --wait-for-timeout=1000 \
    "file://$PWD/.ai-engineering/workflow/prototypes/<kebab-name>.html" $OUT/${vp%,*}.png
done

Then give a general-purpose subagent the screenshots, the HTML, the design directions from step 1, and .ai-engineering/DESIGN.md. Ask it to list, most severe first, where the prototype breaks the directions. It should check:

• horizontal scroll or broken layout at 375px;
• colors, fonts or spacing that don't match the tokens;
• interactions or states from the request that are missing;
• accessibility basics.

Apply its fixes in one pass. Don't loop on its feedback.

4. Deliver

• Run open .ai-engineering/workflow/prototypes/<kebab-name>.html to show it in the browser.
• Reply with the file path, one line naming which design directions were applied, and any assumption you made where the directions were silent.
• Iterate on feedback by editing the same file. Only create a new file (-v2) if the user wants to compare versions.
• On a standalone run, don't commit the prototype unless the user asks. Under /ai-orchestrator, it's committed along with the plan. Add .ai-engineering/workflow/prototypes/ to FILEMAP.md the first time the directory is created.

Lifecycle

Lane: standard, full Writes: .ai-engineering/workflow/prototypes/ Read by: ai-review-ui, humans Dies: when the feature plan is closed Next: none