🎨 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

hljs language-bash

# 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

hljs language-mermaid

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

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

hljs language-mermaid

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

hljs language-mermaid

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

hljs language-mermaid

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

hljs language-bash

# 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

hljs language-bash

/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

hljs language-mermaid

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.

hljs language-mermaid

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.

hljs language-mermaid

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.

hljs language-mermaid

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.

hljs language-mermaid

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)

hljs language-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):

hljs language-bash

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

Manual clone

hljs language-bash

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)

hljs language-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

hljs language-python

.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.

hljs language-mermaid

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

hljs language-bash

# 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

hljs language-bash

# 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

hljs language-bash

bash scripts/uninstall.sh

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

_{Not affiliated with Anthropic. "Claude", "Claude Code", and "Claude Design" are trademarks of Anthropic.

This project only orchestrates user-owned sessions of those tools. · MIT License}

🎨 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

hljs language-bash

# 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

hljs language-mermaid

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

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

hljs language-mermaid

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

hljs language-mermaid

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

hljs language-mermaid

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

hljs language-bash

# 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

hljs language-bash

/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

hljs language-mermaid

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.

hljs language-mermaid

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.

hljs language-mermaid

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.

hljs language-mermaid

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.

hljs language-mermaid

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)

hljs language-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):

hljs language-bash

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

Manual clone

hljs language-bash

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)

hljs language-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

hljs language-python

.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.

hljs language-mermaid

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

hljs language-bash

# 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

hljs language-bash

# 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

hljs language-bash

bash scripts/uninstall.sh

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

_{Not affiliated with Anthropic. "Claude", "Claude Code", and "Claude Design" are trademarks of Anthropic.

This project only orchestrates user-owned sessions of those tools. · MIT License}

picasso-claude-design-claude-code-bridge-loop

🎨 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.

⚡ Quick start — 3 steps, 30 seconds

🔁 How it works

📊 By the numbers

🔧 Prerequisites

🔄 The loop — 7 steps per round

🏗️ Architecture — component map

🎛️ Modes — 5 ways to use the bridge

🆕 Design source flags (v0.2)

📏 Scope presets — complexity-based auto-routing

🏆 Gate scoring — mathematically verified fidelity

🧠 Context backpressure — graceful degradation, never silent failure

🧬 Four Karpathy principles — baked into every round

🧩 Nine orchestration patterns

🪝 Lifecycle hooks — full control over every event

📦 Install

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

Manual clone

Windows (PowerShell)

📁 Output structure

🚦 Exit codes

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

What open-design adds

Install open-design

Use brand tokens as DESIGN.md seed

🔌 Companion tools

📋 Changelog

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

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

v0.1.0 — 2026-04 · First public release

v0.2 — operator-grade internals

v0.1 — initial bridge

📚 Docs

🗑️ Uninstall

Similar Packages

picasso-claude-design-claude-code-bridge-loop

🎨 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.

⚡ Quick start — 3 steps, 30 seconds

🔁 How it works

📊 By the numbers

🔧 Prerequisites

🔄 The loop — 7 steps per round

🏗️ Architecture — component map

🎛️ Modes — 5 ways to use the bridge

🆕 Design source flags (v0.2)

📏 Scope presets — complexity-based auto-routing

🏆 Gate scoring — mathematically verified fidelity

🧠 Context backpressure — graceful degradation, never silent failure

🧬 Four Karpathy principles — baked into every round

🧩 Nine orchestration patterns

🪝 Lifecycle hooks — full control over every event

📦 Install

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

Manual clone

Windows (PowerShell)

📁 Output structure

🚦 Exit codes

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

What open-design adds

Install open-design

Use brand tokens as DESIGN.md seed

🔌 Companion tools

📋 Changelog

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

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

v0.1.0 — 2026-04 · First public release

v0.2 — operator-grade internals

v0.1 — initial bridge

📚 Docs

🗑️ Uninstall

Similar Packages

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.

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.