radimsem/forge-skills/blueprint

Blueprint

Explore UI options in the browser, approve a design, and hand off a spec.

Overview

Read the project's design language and show interactive proposals in the browser. The user pastes each screen's copied response into the agent session. That paste is the only return channel; the companion server keeps no session state. After approval, write the spec and offer a handoff to plans, tickets, or orchestration.

The interactive machinery ships in scripts/ and is never reimplemented inline; each session authors only HTML content fragments per references/screens.md.

Parameters

Flags compose and are parsed from anywhere in the invocation; the canonical matrix with composition rules is references/flags.md.

When to Use

Use for UI/UX brainstorming: new screens, redesigns, component-level polish, anything where the user should see options before choosing. If the topic has no visual dimension (pure backend or API design), say so in one line and defer to a plain brainstorming workflow instead of forcing a browser on a text problem.

Workflow

Part 1 — Setup (1–3): classify → harvest → start companion Part 2 — Rounds (4–5): push screen → read pasted response, ledger it (loop) Part 3 — Close (6–8): [GATE] recap + approval → spec → handoff

Step 1: Classify & parse

Confirm the topic is visual (see When to Use). Parse flags. Enumerate the UI items in scope. Sessions typically batch several; each becomes a track through the rounds.

Step 2: Design harvest

Build or refresh .brainstorm/style.css and .brainstorm/design-notes.md per references/harvest.md. No screen may be pushed before the harvest exists.

Step 3: Start the companion

Run node <skill>/scripts/serve.mjs --project-dir <project> --open in the background. Verify aliveness by statting .brainstorm/server-info; share the printed URL every round as fallback. If the server cannot start twice, or the terminal flag is set, degrade per the terminal-fallback section of references/screens.md with a one-line warning.

Step 4: Push a round

Author a content fragment per references/screens.md into .brainstorm/screens/, then summarize in the terminal what is on screen and ask the user to click and paste.

HARD GATE: nothing touches the target codebase before Step 6 approval. No flag bypasses this.

Step 5: Resolve the round

Parse the pasted response per references/composer.md: verify the screen header, map answers by order, treat nits as change requests. Append decisions to the ledger per references/ledger.md. Revise (new -vN screen) or advance; push a waiting screen when returning to terminal-only discussion.

Step 6: GATE: recap and approval

Push a recap screen rendered from the ledger (data-mode="recap"). The user approves in the terminal, or clicks Copy approval and pastes the phrase. No approval: stop here.

Step 7: Spec

Assemble the design doc from the ledger into docs/specs/YYYY-MM-DD-<topic>-design.md: design decisions per UI item plus a one-line-each "Rejected alternatives" appendix. Self-review for placeholders, contradictions, scope, ambiguity; fix inline; commit.

Step 8: Handoff

Push the handoff screen per references/handoff.md: plans route, /to-tickets route, and the blacksmith invocation builder with generated flag chips.

Anti-patterns

New lessons go to references/anti-patterns.md, the canonical home, not into this file.