🎨 Picasso Orchestrator

1. Gate-scored bidirectional loop: Claude Code ↔ Claude Design. Brief → DESIGN.md → Generate → Implement → Score → Refine.2. Runs locally with open-design — no Pro+ required · 71 brand systems · auto-detected engine.

---

Stop guessing if your implementation matches the design. Let the loop prove it.

Picasso connects Claude Code to Claude Design in a closed feedback loop — structured brief in, verified code out, with a mathematically scored fidelity gate between them. No more "looks close enough." Either the score hits 9.0 / 10 or the loop keeps going.

---

⚡ Quick start — 3 steps, 30 seconds

# 01 · Install (one-liner — patches ~/.claude automatically)
curl -fsSL https://cdn.jsdelivr.net/gh/RazvanGabrielNiculae/picasso-claude-design-claude-code-bridge-loop@main/scripts/install-oneliner.sh | bash

# 02 · Verify everything is wired correctly
picasso-bridge verify --smoke

# 03 · Run your first bridge loop
/picasso --design-loop "hero cinematic for B2B SaaS" --scope complex

💡 Need a guided setup? Add --wizard to the install command. It walks you through gate, max rounds, and hook wiring interactively.

---

🔁 How it works

flowchart LR
    A([picasso]) --> B[ASSUMPTIONS] --> C[DESIGN.md] --> D[Claude Design] --> E[Implement] --> F[Render] --> G[Score] --> H{Gate 9.0}
    H -- "✅" --> I([APPROVED])
    H -- "📉" --> J([STAGNATED])
    H -- "🔄 refine" --> D

    style A fill:#ff2d95,stroke:#ff4fa8,color:#fff
    style B fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style C fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style D fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style E fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style F fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style G fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style H fill:#2a2000,stroke:#ffd83d,color:#fff59d
    style I fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0
    style J fill:#2e1a0d,stroke:#ff9800,color:#ffb14a

1. Brief → Describe your design goal in plain language (/picasso --design-loop "hero for B2B SaaS")
2. ASSUMPTIONS → Picasso surfaces inferred tokens as an explicit block before any browser call — you correct inline
3. DESIGN.md → Structured 9-section spec is generated: colors · typography · layout · motion · responsive · accessibility
4. Claude Design → Picasso sends a structured prompt, captures the visual proposal via screenshot
5. Implement → Zero-context subagent applies only the changed DESIGN.md sections (~200 tok vs 2,000 naive)
6. Render → Desktop always · mobile only if previous responsive score < 8.0
7. Score → Weighted gate: ΔE colors (25%) · typography (20%) · layout (20%) · components (15%) · motion (10%) · responsive (10%)
8. Gaps → 3 lines max · goal-declared format: current → target · passed to next round
9. Gate → score ≥ 9.0 → ✅ APPROVED · plateau → STAGNATED · else → refine and repeat from step 4

---

📊 By the numbers

Metric	Value	What it means
🎯 Default gate	9.0 / 10	Weighted fidelity across 6 visual criteria
🔄 Loop modes	5	loop · solo · critique · reference · iterate
📐 Steps per round	7	request → extract → implement → render → score → gaps → gate
🧩 Orchestration patterns	9+	Token-aware, stagnation-proof by design
🧠 Karpathy principles	4	Baked into the conductor — not optional extras
⚡ Token savings	3×	vs. naive full-context loop (zero-context subagent + lazy reads)

---

🔧 Prerequisites

Tool	Version	Role
🤖 Claude Code	≥ 0.2.0	CLI host — custom commands + subagents + hooks
🎨 Claude plan	Pro · Max · Team · Enterprise	Required for claude.ai/design · optional if running open-design locally
🌐 Chrome	latest	Authenticated session on claude.ai
🔌 chrome-mcp	latest	MCP browser transport — navigate, click, screenshot
📐 webdesign-mcp	latest	Scrape tokens · render previews · compute score
📦 Node	≥ 18	MCP server runtimes
🛠️ jq · bash	any	Used by hooks and install scripts

---

🔄 The loop — 7 steps per round

flowchart LR
    S1[Request] --> S2[Extract] --> S3[Implement] --> S4[Render] --> S5[Score] --> S6[Gaps] --> S7{Gate}
    S7 -- "✅ ≥9.0" --> AP([APPROVED])
    S7 -- "📉 plateau" --> ST([STAGNATED])
    S7 -- "🔄 retry" --> S1

    style S1 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style S2 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style S3 fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style S4 fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style S5 fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style S6 fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style S7 fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style AP fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0
    style ST fill:#2e1a0d,stroke:#ff9800,color:#ffb14a

Step	Name	What happens
01	📡 Request	browser_batch: navigate → form_input → wait → screenshot(800px) → get_text
02	🔍 Extract	scrape_reference with SHA-256 hash cache — skipped entirely if HTML unchanged
03	🔨 Implement	Zero-context subagent. Only changed DESIGN.md sections. ~200 tok vs 2,000 naive.
04	📸 Render	Desktop always. Mobile only if previous responsive score < 8.0.
05	🎯 Score	Fast model: ΔE colors + grid pixels + token match. Standard: gap synthesis.
06	📋 Gaps	3 lines max · goal-declared format: current → target · 15 words each.
07	🚪 Gate	total ≥ gate → ✅ APPROVED · plateau → STAGNATED · else → next round

---

🏗️ Architecture — component map

flowchart LR
    subgraph CC["Claude Code"]
        PC[picasso] --> PDL[pdl-conductor]
        HK[6 hooks] --> PDL
        PDL --> DM["DESIGN.md"]
    end
    subgraph MCP["MCP"]
        CMCP[chrome-mcp]
        WMCP[webdesign-mcp]
    end
    CD[Claude Design]

    PDL --> CMCP --> CD
    CD --> CMCP --> PDL
    PDL --> WMCP

    style CC fill:#1b0d14,stroke:#ff2d95,color:#ffa2cf
    style MCP fill:#0a1520,stroke:#5ce1ff,color:#8eecff
    style PC fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style PDL fill:#ff2d95,stroke:#ff4fa8,color:#fff
    style HK fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style DM fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style CMCP fill:#0a1520,stroke:#5ce1ff,color:#8eecff
    style WMCP fill:#0a1520,stroke:#5ce1ff,color:#8eecff
    style CD fill:#0d2e1a,stroke:#7cf0a0,color:#7cf0a0
    linkStyle 0 stroke:#ffd83d,stroke-width:2px
    linkStyle 1 stroke:#ffd83d,stroke-width:2px
    linkStyle 2 stroke:#ffd83d,stroke-width:2px
    linkStyle 3 stroke:#ffd83d,stroke-width:2px
    linkStyle 4 stroke:#ffd83d,stroke-width:2px
    linkStyle 5 stroke:#ffd83d,stroke-width:2px
    linkStyle 6 stroke:#ffd83d,stroke-width:2px
    linkStyle 7 stroke:#ffd83d,stroke-width:2px

Tag	Component	Role
CORE · ORCHESTRATOR	Claude Code CLI	Hosts /picasso, pdl-conductor subagent, six lifecycle hooks
CORE · DESIGN SIDE	Claude Design (web)	Visual proposal engine driven through authenticated browser tab
TRANSPORT	chrome-mcp	MCP browser transport — navigate, click, type, upload, screenshot
MEASUREMENT	webdesign-mcp	Extracts tokens, renders candidate previews, returns weighted fidelity score
PROTOCOL	Model Context Protocol	Wire format for both MCP servers — any MCP client can swap in
CONVENTION	DESIGN.md (9 sections)	Single-source design contract: colors · typography · components · layout · motion · depth · brand · responsive · accessibility

---

🎛️ Modes — 5 ways to use the bridge

flowchart LR
    S([picasso]) --> LOOP[design-loop]
    S --> SOLO[design-solo]
    S --> CRIT[design-critique]
    S --> REF[design-reference]
    S --> SRC[from-site or from-figma]
    LOOP --> AP{APPROVED}
    AP -- "polish" --> ITER[design-iterate]
    AP -- "ship" --> DONE([Done])
    ITER --> DONE

    style S fill:#ff2d95,stroke:#ff4fa8,color:#fff
    style LOOP fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style SOLO fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style CRIT fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style REF fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style SRC fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style ITER fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style AP fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style DONE fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0

Flag	Name	Description	Best for
--design-loop	🔄 Loop ⭐	Full bidirectional loop. Rounds until gate is met. Default mode.	Any front-end feature from scratch
--design-solo	⚡ Solo	Single pass: one Claude Design turn → implement → stop.	Quick exploration / prototypes
--design-critique <path>	🔬 Critique	Claude Design audits your existing implementation and scores it.	Design-debt audit on existing code
--design-reference <url>	🌐 Reference	Reverse-engineer design tokens from any live site. Seeds DESIGN.md.	"Make it feel like linear.app"
--design-iterate	✨ Iterate	Polish pass after APPROVED. Gate auto-set to prior score + 0.3.	Motion + micro-interaction polish

🆕 Design source flags (v0.2)

Flag	Description	When to use
--from-site <url>	Extract DESIGN.md tokens from any live site → seed round-0	"Build something with stripe.com's design system"
--from-figma --figma <key>	Use Figma MCP as design source instead of Claude Design	You have Figma designs ready
--feedback drawbridge	Import Drawbridge browser annotations as pre-populated gaps	Designer annotated the preview
--multi-page	Enable SITE.md cross-page consistency contract	Multi-page sites

# Seed from live site (no Claude Design Pro needed for the design foundation)
/picasso --from-site https://stripe.com "pricing page for fintech"

# Use Figma as source
/picasso --from-figma --figma ABC123xyz "implement hero from Figma"

# Include designer browser annotations in the loop
/picasso --design-loop --feedback drawbridge "hero for B2B SaaS"

# Multi-page site with cross-page consistency
/picasso --design-loop --multi-page --scope mega "5-page marketing site"

📏 Scope presets — complexity-based auto-routing

Scope	Gate	Rounds	Fallback manual	Example
--scope simple	8.0	3	no	pricing toggle
--scope medium	8.5	5	no	pricing section
--scope complex	9.0	7	yes	full landing page
--scope mega	9.0	10	yes	5-page site

/picasso --design-loop "hero cinematic for a B2B SaaS, dark elite"
/picasso --design-solo "sticky promo banner, warm palette"
/picasso --design-critique ./src/components/hero
/picasso --design-reference https://linear.app
/picasso --design-iterate "tighten motion choreography"
/picasso --scope complex "full marketing landing"

---

🏆 Gate scoring — mathematically verified fidelity

pie title Gate Score Weights
    "Colors - ΔE CIE2000" : 25
    "Typography" : 20
    "Layout and Spacing" : 20
    "Components" : 15
    "Motion" : 10
    "Responsive" : 10

Criterion	Weight	How it's measured
🎨 Colors	25%	ΔE CIE2000 palette comparison per design token
🔤 Typography	20%	Font family · scale ratio · weight · line-height
📐 Layout & spacing	20%	Grid alignment · margin/padding · ±2px tolerance
🧩 Components	15%	Structural match: presence, hierarchy, nesting
🎬 Motion	10%	Duration · easing · transition type
📱 Responsive	10%	8 breakpoints tested: 320px → 1920px

🎯 Default gate: 9.0 / 10. Raise to 9.5 for critical landings (increases stagnation risk). Lower to 8.5 for fast prototypes.

---

🧠 Context backpressure — graceful degradation, never silent failure

The loop degrades gracefully as context fills. It never crashes silently — it checkpoints and exits PAUSED so you can resume in a fresh session.

flowchart LR
    N([NORMAL]) -- "60pct" --> W([WARN]) -- "75pct" --> D([DEGRADE]) -- "85pct" --> SW([SWITCH]) -- "95pct" --> P([PAUSED])

    style N fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0
    style W fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style D fill:#2a1800,stroke:#ff9800,color:#ffb14a
    style SW fill:#2e0d0d,stroke:#f44336,color:#ff8a80
    style P fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0

Context used	State	What happens
< 60%	✅ NORMAL	All steps enabled — full fidelity
60–75%	⚠️ WARN	Skip mobile render if responsive ≥ 8.5
75–85%	🔶 DEGRADE	Cache-only extraction · lazy section reads
85–95%	🔴 SWITCH	Fast model everywhere · 2-line gaps max
> 95%	💾 PAUSED	checkpoint.json saved → exit → resumable next session

---

🧬 Four Karpathy principles — baked into every round

Not guidelines. Mechanisms. Every one maps to a concrete component in the conductor. Inspired by Andrej Karpathy's public notes on LLM coding pitfalls — specifically his observations on silent assumptions, minimal code, surgical edits, and goal-declared targets.

flowchart LR
    K1[Think First] --> K2[Simplicity] --> K3[Surgical Edits] --> K4[Goal-Led State]

    style K1 fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style K2 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style K3 fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0
    style K4 fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    linkStyle 0 stroke:#ffd83d,stroke-width:2px
    linkStyle 1 stroke:#ffd83d,stroke-width:2px
    linkStyle 2 stroke:#ffd83d,stroke-width:2px

#	Principle	What the loop does
01	🤔 Think First	Inferred tokens surface as an explicit ASSUMPTIONS: block before the first browser call. You correct inline — zero silent assumptions. → ASSUMPTIONS: colors · typography · components · brand
02	🪶 Simplicity	The implementation subagent is hard-constrained: minimum code to close the gap. No refactors. No speculative features. No drive-by cleanups. → CONSTRAINTS: no refactor · no new features · no noise
03	🔬 Surgical Edits	Subagent touches only files tied to changed DESIGN.md sections. sha256 idempotency check blocks spurious git diffs. → idempotent writes · changed sections only
04	🎯 Goal-Led State	Gaps are state declarations, not imperatives. The gate score is the objective function. → motion: 400ms → 600ms not "increase duration"

---

🧩 Nine orchestration patterns

Every pattern exists to solve a specific failure mode in naive "loop and hope" approaches.

flowchart TD
    subgraph TOK["Token Efficiency"]
        direction LR
        P01[Structured] --> P04[Lazy reads] --> P05[Model route] --> P06[Adaptive] --> P07[Zero-ctx]
    end
    subgraph DED["Dedup and Cache"]
        direction LR
        P02[Hash cache] --> P03[Fingerprint] --> P08[Idempotent]
    end
    subgraph RES["Resilience"]
        direction LR
        P09[Backpressure]
    end

    style P01 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style P04 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style P05 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style P06 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style P07 fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style P02 fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style P03 fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style P08 fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style P09 fill:#0d2e1a,stroke:#7cf0a0,color:#7cf0a0
    linkStyle 0 stroke:#ffd83d,stroke-width:1.5px
    linkStyle 1 stroke:#ffd83d,stroke-width:1.5px
    linkStyle 2 stroke:#ffd83d,stroke-width:1.5px
    linkStyle 3 stroke:#ffd83d,stroke-width:1.5px
    linkStyle 4 stroke:#ffd83d,stroke-width:1.5px
    linkStyle 5 stroke:#ffd83d,stroke-width:1.5px

#	Pattern	Problem it solves	Impact
01	📝 Structured prompts	Prose prompts are verbose and inconsistent	5× compression on Round-N prompts
02	#️⃣ Content-hash cache	scrape_reference called even on identical output	Saves 1 MCP call/round on average
03	🔏 Fingerprint dedup	Same visual output, different HTML → infinite loop	Instant STAGNATED exit — no wasted rounds
04	📖 Lazy section reads	Reading all 9 DESIGN.md sections every round	~50 tok vs 450 tok after round 1
05	🚦 Model routing	Large model used for simple arithmetic scoring	~40% cost reduction per round
06	📱 Adaptive rendering	Mobile render every round even when stable	Saves 1 render call in most rounds after round 2
07	🧹 Zero-context subagent	Implementer inherits full 2,000 tok loop history	~200 tok vs ~2,000 tok — 10× cleaner context
08	✅ Idempotency check	Files re-written with no actual change → git noise	Clean diffs — unchanged files never touched
09	🛡️ Context backpressure	Loop crashes or degrades silently at context limit	Resumable sessions via checkpoint

---

🪝 Lifecycle hooks — full control over every event

Six hooks. Drop them in ~/.claude/hooks/. Edit a stub to activate. Delete to disable.

flowchart LR
    AD([autodetect]) --> PRE[pre-round] --> LOOP([round]) --> POST[post-round]
    LOOP -- plateau --> STAG[stagnation]
    LOOP -- pass --> APP[approved]
    LOOP -- fail --> FAIL[failed]

    style AD fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style PRE fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style LOOP fill:#ff2d95,stroke:#ff4fa8,color:#fff
    style POST fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style STAG fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style APP fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0
    style FAIL fill:#2e0d0d,stroke:#f44336,color:#ff8a80

Hook	Fires on	What it does
pdl-autodetect	🔔 UserPromptSubmit	Detects handoff phrases ("claude.ai/design", "export") and auto-suggests /picasso
pdl-pre-round	⏱️ Pre-round	Budget guard — aborts if .pdl/ > 50 MB or remaining budget < round estimate
pdl-post-round	📊 Post-round	Cache report + economy.jsonl append · exit 2 = force APPROVED · exit 3 = force abort
pdl-stagnation	📉 Stagnation	Customizable — lower gate, switch mode, or send alert on score plateau
pdl-approved	✅ Approved	Customizable — auto-commit, open PR, send Slack/Discord notification
pdl-failed	❌ Failed	Customizable — alert, cleanup, save trajectory log for post-mortem

See docs/HOOKS.md for full reference.

---

📦 Install

One-liner (macOS / Linux / WSL / Git-Bash)

curl -fsSL https://cdn.jsdelivr.net/gh/RazvanGabrielNiculae/picasso-claude-design-claude-code-bridge-loop@main/scripts/install-oneliner.sh | bash

Wizard mode (prompts for gate, rounds, hook wiring):

... | bash -s -- --wizard

Manual clone

git clone https://github.com/RazvanGabrielNiculae/picasso-claude-design-claude-code-bridge-loop.git
cd picasso-claude-design-claude-code-bridge-loop
bash scripts/install.sh --wizard
bash scripts/verify.sh --smoke

Windows (PowerShell)

git clone https://github.com/RazvanGabrielNiculae/picasso-claude-design-claude-code-bridge-loop.git
cd picasso-claude-design-claude-code-bridge-loop
pwsh -File scripts\install.ps1
pwsh -File scripts\verify.ps1

The installer patches ~/.claude/settings.json automatically (timestamped backup). Use --no-hook to skip auto-wiring.

---

📁 Output structure

.pdl/
├── round-0/
│   ├── DESIGN.md        ← inferred tokens + ASSUMPTIONS block
│   └── prompt.md        ← Round-0 brief (~250 tok)
├── round-1/
│   ├── prompt.md        ← Round-N delta (~100 tok)
│   ├── design-output.png
│   ├── tokens.json
│   ├── impl-desktop.png
│   ├── impl-mobile.png  ← only if responsive < 8.0
│   ├── score.json
│   └── gaps.md
└── APPROVED.md          ← or FAILED.md

---

🚦 Exit codes

Code	Meaning
✅ APPROVED	score ≥ gate — code implemented, .pdl/APPROVED.md written
📉 STAGNATED	2 rounds without progress, or fingerprint dedup match
🔚 EXHAUSTED	rounds_max reached without hitting gate
⛔ EARLY_ABORT	trajectory analysis: gate mathematically unreachable
💾 PAUSED	context > 95% — checkpoint saved, resumable in new session
🔒 BLOCKED	prerequisite missing (Chrome MCP / Claude Design / plan)
❌ ERROR	technical failure — see .pdl/error.log

---

🖥️ No Pro+ account? Run the full loop locally with open-design

nexu-io/open-design (3.6k★ · MIT) is a local-first alternative to claude.ai/design. Run the complete PDL loop on your machine — no Pro+ account, no browser, no Chrome MCP required.

flowchart LR
    A{Pro+ account?} -- "yes" --> B[claude.ai/design]
    A -- "no" --> C{open-design\ndaemon running?}
    C -- "yes" --> D[open-design local]
    C -- "no" --> E[webdesign-mcp\nstandalone]
    B --> F([Full PDL loop])
    D --> F
    E --> G([Implement only\nno loop])

    style A fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style B fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0
    style C fill:#2a2000,stroke:#ffd83d,color:#ffd83d
    style D fill:#0d2e1a,stroke:#4caf50,color:#7cf0a0
    style E fill:#2a1420,stroke:#ff2d95,color:#ffa2cf
    style F fill:#0d1f2d,stroke:#5ce1ff,color:#8eecff
    style G fill:#1a1a2e,stroke:#7cf0a0,color:#7cf0a0

/picasso auto-detects the active engine via GET /api/design-systems — no flag needed.

What open-design adds

Capability	Value
71 brand design systems	Stripe · Linear · Vercel · Apple · Tesla · Notion · Figma · Framer · GitHub · Cursor · PostHog + 60 others
DESIGN.md auto-seed	Brand tokens injected before round 0 — replaces manual CSS extraction, saves 1–2 rounds to gate
5 visual directions	editorial · modern-minimal · tech-utility · brutalist · soft-warm
19 skill templates	web-prototype · dashboard · deck · landing · e-commerce + 14 more
Anti-slop 5D critique	Automatic self-critique aligned with the 9.0 gate
Multi-agent routing	Claude Code · Cursor · Gemini CLI · Qwen · GitHub Copilot as coding engine

Install open-design

# Clone once
git clone --depth 1 https://github.com/nexu-io/open-design.git ~/.claude/skill-library/open-design
cd ~/.claude/skill-library/open-design && npm install

# Start before each design session
npm run dev   # → http://localhost:3000

Then run /picasso --design-loop as usual — it probes :3000/api/design-systems automatically.

Use brand tokens as DESIGN.md seed

# 71 brand systems available instantly — no CSS extraction needed
/picasso --design-loop "hero for fintech, linear style"

# Explicit brand reference
/picasso --design-loop --ref linear "pricing page"

---

🔌 Companion tools

Picasso handles the loop. These tools extend it at the input, feedback, and scale layers.

Tool	Layer	What it adds
nexu-io/open-design ⭐3.6k	Input + Engine	Local PDL engine — no Pro+ required. 71 brand systems, 5 visual directions, 19 templates. Auto-detected.
bergside/design-md-chrome ⭐542	Input	Extract DESIGN.md from any live site → --from-site
Figma MCP	Input	Figma designs as design source → --from-figma
breschio/drawbridge	Feedback	Browser annotations → DOM-anchored gaps → --feedback drawbridge
HermeticOrmus/LibreUIUX-Claude-Code	Scale	152 UI/UX agents for complex builds
wilwaldon/Frontend-Design-Toolkit	Scale	Curated toolkit: tokens, Playwright, accessibility
hemangjoshi37a/claude-code-frontend-dev	Visual QA	Post-APPROVED visual testing with closed-loop fixes

See docs/companion-tools.md for integration guides.

---

📋 Changelog

v0.3.0 — 2026-04 · Local-first engine + arsenal upgrade

• Adds: open-design local PDL engine — run the full loop without a Pro+ account. Auto-detected via GET /api/design-systems probe. No flag needed.
• Adds: 71 brand design systems (Stripe, Linear, Vercel, Apple, Tesla, Notion + 66 others) as DESIGN.md seed — replaces manual CSS extraction, saves 1–2 rounds to gate
• Adds: 5 visual directions (editorial, modern-minimal, tech-utility, brutalist, soft-warm) — structured style vocabulary for PDL prompts
• Adds: Auto Design-Extract from --ref <url> — color palette, typography, spacing, component patterns, motion hints auto-extracted into design-tokens-extracted.json
• Adds: DESIGN.md references — 68 real-world brand examples (awesome-design-md)
• Adds: Platform trade-offs table — Next.js vs Astro vs Remix vs Webflow vs Framer with budget brackets ($30K / $30-150K / $150K+)
• Adds: Arsenal tables — TIER 1/2/3 detailed with roles, star counts, notes
• Updates: Fallback matrix → "Fallback & recovery" — Pro+ absent now routes to open-design daemon before falling back to loop-less mode
• Docs: docs/companion-tools.md — open-design as first Input Layer entry with API reference

v0.2.0 — 2026-04 · Design sources + feedback

• Adds: --from-site (design-md-chrome pattern), --from-figma (Figma MCP source)
• Adds: --feedback drawbridge (browser annotation integration)
• Adds: --multi-page + SITE.md cross-page consistency (jezweb/design-loop pattern)
• Adds: visual scoring tiers (PASS / PASS WITH NOTES / ITERATE / FAIL)
• Adds: expanded fallback matrix for all new input modes
• Docs: docs/companion-tools.md integration guide

v0.1.0 — 2026-04 · First public release

• Unified public repo: v0.1 narrative + v0.2 operator additions
• Adds: context backpressure · 10 token-optimizations · Karpathy principles · 5 modes + 4 scope presets
• Adds: model routing · zero-context subagent · trajectory abort · idempotent writes
• Adds: 6 lifecycle hooks · wizard installer · economy.jsonl tracking
• Adds: reference mode · iterate mode · critique mode

v0.2 — operator-grade internals

• Conductor phases 1→4 · ASSUMPTIONS surfacing · DESIGN.md delta reads
• STAGNATED · EARLY_ABORT · PAUSED states · fingerprint deduplication
• Budget preflight · economy.jsonl · daily cap enforcement

v0.1 — initial bridge

• /picasso --design-loop command · pdl-conductor agent
• 6 round steps · gate scoring · pdl-autodetect hook
• One-liner installer (macOS / Linux / WSL / PowerShell)

---

📚 Docs

Architecture	System overview and component map
Bridge loop walkthrough	Phase-by-phase execution
Modes & scope presets	5 loop variants
Gate scoring	Weighted criteria + tuning guide
Design patterns	9 orchestration patterns + Karpathy
Token optimization	3× overhead reduction
Lifecycle hooks	Hook system reference
Prompt templates	Round-0 and Round-N formats
Installation	Full install guide
Troubleshooting	Common issues + fixes

---

🗑️ Uninstall

bash scripts/uninstall.sh

Then remove the hook block from ~/.claude/settings.json manually.

---