bryllen-design

name	bryllen-design
description	Start (or restart) the Bryllen dev server
disallowed-tools	WebSearch

/bryllen-design

Start the Bryllen dev server and arm the annotation stream.

Steps

1. Kill only THIS project's existing servers (not other bryllen instances):

   if [ -f .bryllen-ports.json ]; then
     # Kill by PID (safe) — never by port (could kill another project's server)
     node -e "
       const f = JSON.parse(require('fs').readFileSync('.bryllen-ports.json','utf8'));
       for (const pid of [f.pid, f.vitePid, f.httpPid].filter(Boolean)) {
         try { process.kill(pid, 'SIGTERM'); } catch {}
       }
     "
     rm -f .bryllen-ports.json
   fi
   

   This reads PIDs from the ports file and kills only THIS project's processes. Other bryllen instances are untouched. It's fine if nothing was running.

2. Start the dev server in the background:

   npx bryllen design
   

3. Confirm: "Dev server running. Canvas at http://localhost:5173"

3.5. Check for existing projects:

ls src/projects/ 2>/dev/null

• If the directory is empty or missing: tell the designer "Canvas is live at http://localhost:5173 — click 'New Project' to start designing" and go straight to step 6 (arm the stream). The annotation handlers already cover the type: 'project' annotation that the New Project dialog sends.
• If projects exist: continue to step 4 (drain backlog).

4. Drain backlog: Run npx bryllen pending to check for annotations that arrived before the session started. Process each one following the guard protocol.

5. Check for context images: Before generating any designs, run:

   npx bryllen context --project <name> --iteration <v>
   

   This returns paths to inspiration images. Read them with the Read tool and analyze via Vision. Incorporate their style into your generations.

6. Arm the annotation stream with the Monitor tool:

   • command: npx bryllen watch --stream
   • persistent: true
   • description: Bryllen canvas annotations

   The stream prints one compact JSON line per annotation; each line arrives as a notification that wakes you. Between annotations you are free — no polling loop, and the designer can chat with you while the stream is armed. Monitor notifications are canvas events, not user replies. If the stream emits a server unreachable error line (or the monitor exits), the dev server died: restart it (steps 1–2) and re-arm the Monitor.

   Fallback — only if the Monitor tool is unavailable in this harness: run npx bryllen watch in a loop. Each call waits up to 15 seconds and prints either an annotation or {"timeout": true}; on timeout, run it again.

   When an annotation arrives, process it by type:

   Regular annotation arrives (JSON with annotation data) — process it:

   The annotation IS the map. Read the fields, construct the path, done:

   • project → src/projects/{project}/
   • frameId prefix (e.g. v9-shell) → v9/ folder
   • componentName → file in components/ or pages/

   NEVER guess the project from git commits, Explore agents, or "which is active" heuristics.

   • Run npx bryllen progress <id> "Reading file..." to show status on canvas
   • Grep for componentName in src/projects/{project}/{iteration}/ — that's the file
   • Read the comment, selector, and computedStyles for what to change
   • Follow the guard protocol (see CLAUDE.md "Before any edit")
   • Map to file in v<N>/components/ or v<N>/pages/
   • Run npx bryllen progress <id> "Applying changes..."
   • Token routing: Route visual value changes through tokens.css
   • Apply the requested changes
   • Run npx bryllen progress <id> "Taking screenshot..."
   • Visual review: Run npx bryllen screenshot --frame <frameId>
     • Read the returned screenshot file to see the result
     • Check for: broken contrast, overflow/clipping, misalignment, wrong colors, missing styles
     • If issues found: fix them and screenshot again
     • If clean: proceed
   • Run npx bryllen resolve <id> (this auto-commits project changes)
   • Log the change to CHANGELOG.md
   • Done — the Monitor stays armed for the next annotation (poll fallback: run npx bryllen watch again)

   Iteration request arrives (JSON has type: 'iteration') — run the iteration protocol:

   1. Read manifest.ts, find the active iteration (last with frozen: false)
   2. Freeze it (frozen: true)
   3. Copy folder: cp -r v<N>/ v<N+1>/
   4. Rename CSS scope in v<N+1>/tokens.css: .iter-v<N> → .iter-v<N+1>
   5. Add new iteration to manifest with frozen: false, update import paths
   6. Apply the changes described in the annotation's comment
   7. Follow all guards (showcase, component hierarchy, token routing)
   8. Visual review: Run npx bryllen screenshot (no --frame = all frames)
      • Read the screenshot to verify the new iteration looks correct
      • Fix any visual issues before resolving
   9. Run npx bryllen resolve <id> (this auto-commits project changes)
   10. Log to CHANGELOG.md
   • Done — the Monitor stays armed for the next annotation (poll fallback: run npx bryllen watch again)

   Project request arrives (JSON has type: 'project') — create a new project:

   1. Parse the JSON comment: { name, description, prompt }
   2. Create the project folder structure: src/projects/<name>/v1/{tokens.css, components/index.ts, pages/, context/}
   3. CRITICAL: tokens.css MUST use :root, .iter-v1 as the selector — without :root, frames render as unstyled plain text because they don't have the .iter-v1 class wrapper. This is the #1 cause of "designs show unstyled text" bug.
   4. Create manifest.ts (with import './v1/tokens.css' at the top) and CHANGELOG.md
   5. If prompt is provided, follow the "What happens next" sequence from /bryllen-new EXACTLY — especially step 1 which REQUIRES generating 3-5 genuinely different design directions. The "All Directions" page must be the first thing the designer sees.
   6. Run npx bryllen resolve <id>
   7. Done — the Monitor stays armed for the next annotation (poll fallback: run npx bryllen watch again)

   Share request arrives (JSON has type: 'share') — deploy to GitHub Pages:

   1. Parse the JSON comment: { project: '<name>' }
   2. Run npx bryllen progress <id> "Checking GitHub authentication..."
   3. Check GitHub auth: run gh auth status
      • If not logged in: check for token in ~/.bryllen/auth.json
      • If token exists: set GH_TOKEN env var for gh-pages
      • If no token: tell designer to click "Login with GitHub" in the Share popover
   4. Check gh CLI: run which gh
      • If not installed: use npm:gh-pages package directly (it uses GH_TOKEN)
   5. Run npx bryllen progress <id> "Building project..."
   6. Invoke /bryllen-share <project-name> — this handles build, deploy, and URL writing
   7. Run npx bryllen resolve <id>
   8. Done — the Monitor stays armed for the next annotation (poll fallback: run npx bryllen watch again)

   Pick request arrives (JSON has type: 'pick') — promote the picked direction(s) to a new iteration:

   1. Read the frameId, frameIds, and comment from the annotation
      • frameIds is an array when multiple frames were selected (marquee multi-select)
      • frameId is a +-joined string of all IDs (e.g., "dir-a+dir-b+dir-c")
   2. Run npx bryllen progress <id> "Picking direction..."
   3. Find each frame's source file (component or page) from the frameIds
   4. Create a new iteration that:
      • Single pick: Copies the picked direction as the starting point
      • Multi-pick: Combines ALL picked directions — extract shared patterns, merge complementary elements, resolve conflicts thoughtfully
      • Builds out all states (loading, error, empty, success, etc.)
      • Names it appropriately (e.g., "V3 — Picked Direction" or "V3 — Combined")
   5. Update the previous iteration's manifest entry:
      • Single pick: Set pickedFrameId to the chosen frame's ID (this fades other frames)
      • Multi-pick: Set pickedFrameIds to the array of chosen frame IDs (all picked frames stay unfaded)
      • Set frozen: true
   6. Add the new iteration to manifest with frozen: false
   7. Run npx bryllen progress <id> "Taking screenshot..."
   8. Run npx bryllen screenshot to verify the result
   9. Run npx bryllen resolve <id> (auto-commits)
   10. Log to CHANGELOG.md
   • Done — the Monitor stays armed for the next annotation (poll fallback: run npx bryllen watch again)

   Multi-pick strategy: When the designer selects multiple frames, they want to combine strengths from each:

   • Extract what works best from each direction (layout from A, color palette from B, interaction from C)
   • Resolve conflicts by choosing the stronger solution or creating a synthesis
   • The result should feel cohesive, not like a Frankenstein of disconnected parts
   • When in doubt, ask the designer which element they prefer via a comment in the annotation response

   Context image annotation arrives (annotation on a Context Image component) — use the image for inspiration:

   • Run npx bryllen context --project <name> --iteration <v> to get image paths
   • Read the images with the Read tool to analyze via Vision
   • Apply the designer's comment (e.g., "use these colors", "make more like this")
   • Reference specific visual elements from the context images when generating

   Timeout (JSON contains "timeout": true) — poll-fallback mode only; the stream never prints timeouts. No annotation arrived: run npx bryllen watch again to keep waiting.

7. Chat while watching: The designer can send messages at any time — the armed Monitor doesn't block the conversation. Handle the message (answer a question, make a change, kill the server, etc.); the stream keeps delivering annotations as they arrive. If you stopped the monitor (e.g. via /bryllen-close), re-arm it as in step 6.

CLI Commands Reference

All annotation commands output JSON for easy parsing:

# Stream annotations forever — one JSON line each (use with the Monitor tool)
npx bryllen watch --stream

# Wait for next annotation once (15s default timeout, poll fallback)
npx bryllen watch [--timeout N]

# Mark annotation as resolved (auto-commits)
npx bryllen resolve <id>

# List pending annotations
npx bryllen pending

# List all annotations
npx bryllen list

# Screenshot canvas
npx bryllen screenshot [--frame <id>] [--delay <ms>]

# Get context image paths
npx bryllen context --project <name> --iteration <v>