# Autodesign

> Two-phase design loop like /swarm but for visual design. EXPLORE: launches N parallel subagents in Figma — each designs a distinct concept on its own page simultaneously, then cross-model consensus (Claude + Codex) picks the winner. DEEP: iterates the chosen concept with critique → impeccable skills → fixes until it converges. Use when starting a new UI from scratch or iterating an existing design, when asked to "autodesign", "explore designs", "design this in Figma", "go wide then deep", or "make it look good".

- Skill: `jonmumm/autodesign` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add jonmumm/autodesign`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jonmumm/autodesign/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Design & Media
- Author: jonmumm (https://skillmd.com/u/jonmumm)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/jonmumm/autodesign

---


# Autodesign

Two-phase design loop modeled after `/swarm`. **Explore phase**: launch N parallel
subagents in Figma — each designs a distinct concept on its own page simultaneously.
Cross-model consensus (Claude + Codex) picks the winner. **Deep phase**: iterate the
chosen concept with critique → impeccable skills → fixes until it converges. Go wide,
then go deep.

## Concept

```
Phase 1: PREFLIGHT (interactive, human present)
  ├── Understand the design target (what are we designing?)
  ├── Detect context: new design from scratch (→ Exploration phase) vs. iterating existing
  ├── IF new design from Figma:
  │   ├── How many parallel concepts? (default: 3–5)
  │   ├── Name + direction for each concept
  │   └── Confirm Figma file to work in
  ├── Choose capture method (Playwright / Chrome MCP / Maestro / XCUITest / Detox / Storybook)
  ├── Define viewports (mobile 390x844, desktop 1440x900, tablet, etc.)
  ├── Define design judges via /evals-first (LLM judges for subjective criteria)
  ├── Optional: Connect Figma source of truth via Figma MCP
  ├── Confirm deploy command (if applicable)
  └── User confirms → agent takes over

Phase 1.5: EXPLORATION — go wide (Figma new-design mode only)
  ├── Create one Figma page per concept (e.g. "A — Madden Playbook", "B — Arrow Overlay")
  ├── Launch N parallel subagents — one per concept, each designing in its own page
  │   ├── Each subagent has full independent context — no cross-contamination
  │   ├── Each designs its concept fully: real content, real layout, real colors
  │   └── All run simultaneously → N concepts done in the time of 1
  ├── Wait for all subagents to complete
  ├── Screenshot all concept pages → cross-model eval (Claude + Codex)
  ├── Synthesize: which designs do BOTH models rank highly?
  ├── Present ranked shortlist to the user with side-by-side reasoning
  ├── User selects the direction (or requests another round)
  └── Chosen concept page becomes the working design → continue to Phase 2 LOOP

Phase 2: LOOP — go deep (AFK, autonomous)
  ├── 1. Capture screenshots across all viewports
  ├── 2. Run design eval stack (critique → targeted skills → cross-model review)
  ├── 3. Prioritize findings (critical → high → medium → low)
  ├── 4. Implement top 3-5 fixes
  ├── 5. Deploy (if deploy command configured)
  ├── 6. Re-capture screenshots → verify fixes, check for regressions
  ├── 7. Commit with detailed message
  ├── 8. Each iteration saved as a named Figma frame (see Figma Organization)
  ├── 9. If converged (2+ consecutive no-change passes) → stop
  └── 10. Otherwise → loop to step 1

Phase 3: HANDOFF (waiting for human)
  ├── Design briefing in .autodesign/BRIEFING.md
  ├── Before/after screenshots in .autodesign/captures/
  ├── Figma organized with full exploration + iteration history
  └── Eval gap notes for next run
```

## Exploration Phase (Go Wide Before Going Deep)

When designing something **new** in Figma, autodesign runs an exploration phase before
the polish loop. The mechanism is **parallel subagents** — one per concept, launched
simultaneously, each with full independent context. No sequential generation, no shared
state, no context bleed between directions.

### How many explorations?

During preflight, ask:

> "How many design concepts should we explore before picking a direction?" (default: 3–5)

3–5 is the right number for subagents — enough variety to surface genuinely different
directions without becoming unwieldy to evaluate. If the user wants more coverage,
run a second round.

### Setting up Figma pages

Before launching subagents, create one Figma page per concept using Figma MCP:

```javascript
// Example: 3 concepts for a play-calling UI
const page1 = figma.root.children[0];
page1.name = "A — Madden Playbook";

const page2 = figma.createPage();
page2.name = "B — Arrow Overlay";

const page3 = figma.createPage();
page3.name = "C — Coaching Clipboard";
```

Name pages with a letter prefix so they sort clearly (A, B, C...) and a short concept
description. This makes it obvious at a glance what each direction is.

### Naming concepts

Spend a moment naming the concepts before launching agents — the names shape what
each subagent designs. Good names are evocative and directionally specific:

| Good | Bad |
|------|-----|
| "Madden Playbook" | "Option 1" |
| "Arrow Overlay" | "Design A" |
| "Coaching Clipboard" | "Concept 3" |
| "Stadium Scoreboard" | "Alternative" |

The name is the brief. Make it mean something.

### Launching parallel subagents

Use the `Agent` tool to launch all subagents in a single message — they run in parallel:

```
Agent("Design Madden Playbook concept", "
  You are designing the 'A — Madden Playbook' concept in Figma.
  File key: [fileKey]. Work on the page named 'A — Madden Playbook'.

  Design a play-calling UI that feels like a Madden NFL playbook overlay:
  3 play cards, each containing a mini pitch diagram with colored arrows,
  player names, and a brief play name. Dark semi-transparent overlay on the
  game board. Tap a card to preview it full-size. Warm amber accent on selected.

  Use real content — real player names, real play names (Wing Run, Triangle Pass,
  Long Ball). Make it look like a real game UI, not a wireframe.

  When done, output the Figma frame node ID you created.
")

Agent("Design Arrow Overlay concept", "...")
Agent("Design Coaching Clipboard concept", "...")
```

Each subagent:
- Works on its own Figma page — no conflicts
- Designs its concept fully with real content
- Has no awareness of the other concepts being designed in parallel

### What to put in each subagent prompt

Each prompt should specify:
1. **The concept name and its page** — where to work
2. **The visual metaphor** — what this concept feels like (Madden playbook, chalkboard, etc.)
3. **Key layout decisions** — where plays appear, how selection works, what info shows
4. **Real content** — actual player names, play names, game state data to render
5. **The interaction model** — how the user picks a play in this concept

Don't over-specify — leave room for the subagent to make design decisions. Give it the
concept direction, not a pixel-level spec.

### After subagents complete

Once all subagents finish:

1. **Take screenshots** of each concept page via Figma MCP `get_screenshot`
2. **Claude evaluation** (you, now): score each concept on:
   - Visual hierarchy — does the eye go to the right place?
   - Fit-for-purpose — does this feel right for the product?
   - Distinctiveness — does it avoid generic AI design?
   - Polish potential — how close to production-ready?
3. **Codex evaluation** (cross-model):
   ```bash
   codex exec -c model_reasoning_effort="xhigh" \
     "Evaluate these [N] play-calling UI concepts. Screenshots at: .autodesign/captures/explorations/
      Score each 1-10 on: hierarchy, fit, distinctiveness, polish potential.
      Rank your top picks with specific reasoning." \
     > .autodesign/codex-exploration-review.md
   ```
4. **Synthesize**: find consensus between Claude and Codex rankings
5. **Present to user**: show the shortlist table with both models' reasoning

If no consensus, show top picks from each model separately. Let the user decide.

### If the user wants more concepts

Launch another round of subagents. Name pages `D — ...`, `E — ...` continuing the alphabet.
Don't delete earlier concepts — they're the audit trail of what was considered.

### Figma organization during exploration

```
Figma file
  ├── Page: "A — Madden Playbook"     ← ★ SELECTED (winner gets this label)
  ├── Page: "B — Arrow Overlay"
  ├── Page: "C — Coaching Clipboard"
  ├── Page: "D — ..."                 ← Round 2 concepts, if needed
  └── Page: "Iterations"             ← Created when deep loop begins
```

The selected concept page gets `★ SELECTED` added to its name. All other pages stay
as-is — they're the record of what was explored and rejected.

### Why subagents, not sequential generation

Sequential generation in a single context means each concept is influenced by the last.
The 3rd concept will unconsciously echo patterns from the 1st and 2nd. Parallel subagents
each start from zero — genuinely independent directions, genuinely divergent results.

The speed is a bonus. The independence is the point.

## Figma Organization (Iteration History)

When going deep on the selected design, every iteration is preserved in Figma.
This creates a clear visual record of the design's progression.

### Page structure

```
Figma file
  ├── Page: "Explorations"       ← All N initial explorations (see above)
  ├── Page: "Iterations"         ← One frame per deep iteration
  │     ├── Frame: "v0 — Baseline"  (the chosen exploration, copied here)
  │     ├── Frame: "v1 — [key change]"
  │     ├── Frame: "v2 — [key change]"
  │     └── …
  └── Page: "Final"              ← Current best version (updated each iteration)
        └── Frame: "Final"
```

### Naming convention

Each iteration frame in the **Iterations** page is named descriptively:

```
v0 — Baseline
v1 — Tightened hierarchy, removed feature card grid
v2 — Dark CTA section → inline strip, footer contrast fix
v3 — Mobile hero padding, copy compression
v4 — CONVERGED (clean pass)
```

The name is written after the iteration completes — it summarizes the primary change,
not the process. This means reading down the Iterations page tells the design story.

### Laying out iteration frames

Arrange iteration frames left-to-right in chronological order on the Iterations page.
Space them with consistent gutters (e.g., 100px) so the progression is clear at a glance.
Include a small annotation below each frame with the date and key eval findings that drove the change.

### Updating the Final page

After each iteration, copy the latest design to the **Final** page and replace the
previous frame. The Final page always shows the current production-bound design.

### Copy before modifying (CRITICAL)

Before making ANY changes to the Working frame, always:
1. Check if the "Iterations" page exists (create it if not)
2. Duplicate the Working frame to the Iterations page
3. Name the duplicate `v{N} — {brief summary of what's about to change}`
4. THEN modify the Working frame

This is non-negotiable. Skipping it loses design history permanently.

### Never delete exploration frames

Explorations and earlier iterations must never be removed. They are the design audit trail.
Even discarded explorations stay — they show what was considered and rejected.

## Prerequisites

### Capture Method

Autodesign needs a way to see the UI. During preflight, detect or ask which method to use:

| Platform | Capture Method | Detection |
|----------|---------------|-----------|
| **Web (static/SSR)** | Playwright | `playwright` in deps, or `npx playwright` available |
| **Web (live browser)** | Chrome MCP | `mcp__claude-in-chrome__*` tools available |
| **Web (components)** | Storybook | `storybook` in deps, `.storybook/` dir |
| **iOS (Swift)** | XCUITest screenshots | `*.xcodeproj` with UI test targets |
| **iOS (Expo/RN)** | Maestro / Detox | `maestro` CLI or `detox` in deps |
| **React Native** | Detox | `detox` in package.json |
| **Figma (source)** | Figma MCP | `mcp__claude_ai_Figma__*` tools available |

Multiple capture methods can be combined (e.g., Playwright for web + Figma MCP for design source).

### Screenshot Capture Commands

```bash
# Playwright (web) — full page, multiple viewports
npx playwright screenshot --viewport-size=1440,900 --full-page <url> <output.png>
npx playwright screenshot --viewport-size=390,844 --full-page <url> <output.png>

# Chrome MCP (live browser) — via resize_window + screenshot
mcp__claude-in-chrome__resize_window(width, height, tabId)
mcp__claude-in-chrome__computer(action: "screenshot", tabId)

# XCUITest (iOS) — capture in test
let screenshot = app.screenshot()
let attachment = XCTAttachment(screenshot: screenshot)

# Maestro (iOS/Android)
maestro test flow.yaml  # with takeScreenshot commands

# Storybook — via test runner or Playwright against Storybook URL
npx playwright screenshot http://localhost:6006/iframe.html?id=<story> <output.png>
```

## Design Eval Stack

The eval stack runs in order. Each tier produces findings. Critical/high findings
must be fixed before the iteration is considered passing.

```
Tier 1: /critique (blocking)
  └── Holistic design critique: AI slop detection, hierarchy, composition,
      typography, color, emotional resonance, states, microcopy
  └── Returns prioritized issues with severity

Tier 2: Targeted impeccable skills (blocking for critical findings)
  └── Based on /critique findings, run the most relevant skill:
      ├── /typeset    — typography issues (hierarchy, readability, font choices)
      ├── /arrange    — layout, spacing, visual rhythm issues
      ├── /colorize   — color palette, contrast, purposeful color use
      ├── /clarify    — unclear copy, labels, error messages
      ├── /distill    — over-designed, needs simplification
      ├── /bolder     — too safe/boring, needs more impact
      ├── /quieter    — too aggressive, needs toning down
      ├── /animate    — missing motion, microinteractions
      ├── /harden     — error states, i18n, edge cases, overflow
      ├── /adapt      — responsive issues, cross-device problems
      ├── /polish     — final-pass alignment, consistency, details
      ├── /delight    — missing personality, joy, memorable touches
      ├── /onboard    — first-time UX, empty states, getting-started flow
      ├── /optimize   — performance, loading, rendering issues
      ├── /normalize  — design system inconsistency
      ├── /extract    — opportunities for reusable components/tokens
      └── /overdrive  — technically ambitious effects (shaders, physics, scroll-driven)
  └── Pick 1-3 skills per iteration based on what /critique surfaced

Tier 3: Cross-model consensus (advisory)
  └── Pass the screenshots + critique findings to both Claude and Codex
  └── Look for findings that BOTH models agree on (high confidence)
  └── Discard findings only one model flags (lower confidence)
  └── This replaces /codex-review's code focus with a design focus

Tier 4: Figma diff (optional, if Figma MCP available)
  └── Compare implementation screenshots against Figma source
  └── Flag visual deviations from the design spec
```

### Cross-Model Design Review

The cross-model review is the key differentiator from a simple /critique loop.
Two models reviewing the same screenshots catches more issues than one model
reviewing twice.

**Claude review (primary):**
Run /critique as a sub-agent with the screenshots.

**Codex review (cross-validation):**
```bash
# Build a design review prompt with screenshots encoded
codex exec \
  -c model_reasoning_effort="xhigh" \
  "Review these UI screenshots for design quality. Focus on:
   1. Visual hierarchy — does the eye flow to the most important element?
   2. Consistency — are spacing, colors, typography consistent?
   3. Mobile/responsive — does the mobile version work as well as desktop?
   4. AI slop — does this look like generic AI-generated design?
   5. Polish — alignment, spacing details, edge cases

   Screenshots are at: .autodesign/captures/current/

   Return findings as:
   CRITICAL: [issue] — FIX: [concrete fix]
   HIGH: [issue] — FIX: [concrete fix]
   MEDIUM: [issue] — FIX: [concrete fix]

   Only flag issues you are confident about." \
  2>&1 | tee .autodesign/codex-design-review.md
```

**Consensus filter:**
Only implement findings that BOTH models flag, OR that one model flags as CRITICAL.
This prevents churn from model-specific preferences.

## Design Judges (from /evals-first)

During preflight, define LLM judges for the project's specific design criteria.
These are more specific than /critique's general evaluation.

### Example Judge Prompts

```markdown
# Judge: Brand Consistency
Evaluate whether the UI matches the app's established visual identity.

## Criteria
- Uses the project's color palette (not generic blues/grays)
- Typography matches the app's font family and weight scale
- Interactive elements match the app's button/card/chip styles
- Spacing follows the app's rhythm (not generic 8px grid)

## Verdict
<eval>PASS</eval> or <eval>FAIL: specific deviation</eval>
```

```markdown
# Judge: Mobile Usability
Evaluate the mobile screenshot for touch-friendly design.

## Criteria
- Touch targets >= 44px
- No horizontal scroll (viewport fits content)
- Text is readable without zooming (>= 14px body)
- Primary action is visible without scrolling
- Forms stack vertically with full-width inputs

## Verdict
<eval>PASS</eval> or <eval>FAIL: specific issue</eval>
```

```markdown
# Judge: AI Slop Detection
Evaluate whether this looks like generic AI-generated design.

## Red Flags
- The blue-purple-pink gradient palette
- Gradient text on headings
- Dark mode with glowing neon accents
- Glassmorphism cards with blur
- Hero section with big metrics
- Identical card grids (3 cards, same height)
- Stock-illustration style decorations
- Generic sans-serif (Inter/Poppins with no personality)

## Verdict
<eval>PASS</eval> if distinctive, or <eval>FAIL: specific AI tells detected</eval>
```

Judges are stored in `.autodesign/judges/` and run as parallel sub-agents
against the captured screenshots.

## Convergence Detection

The loop stops when design quality has stabilized:

1. **Hard stop:** 2 consecutive iterations where /critique returns no critical or high issues
2. **Soft stop:** 5 total iterations completed (diminishing returns)
3. **Time stop:** Optional duration limit (e.g., "2 hours")

After convergence, write the handoff briefing and stop.

## Directory Structure

```
.autodesign/
  BRIEFING.md              ← Design briefing for human review
  config.json              ← Saved preflight config (capture method, viewports, etc.)
  judges/
    brand-consistency.md   ← LLM judge prompts
    mobile-usability.md
    ai-slop-detection.md
    custom-*.md            ← Project-specific judges
  captures/
    explorations/          ← Screenshots of all N exploration frames (new design only)
      exploration-01.png
      exploration-02.png
      ...
    baseline/              ← The selected exploration (start of deep iteration)
      desktop.png
      mobile.png
    iteration-1/
      desktop.png
      mobile.png
    iteration-2/
      ...
    current/               ← Latest screenshots (symlinked)
  codex-exploration-review.md  ← Cross-model exploration rankings (new design only)
  codex-design-review.md   ← Latest cross-model iteration review
  eval-gaps.md             ← Gaps found, feeds next run
```

**NEVER commit `.autodesign/` to git.** Add to `.gitignore` during preflight.

## Preflight Checklist

Interactive setup with the human. Formalize requirements into judges.

### Step 0: New design vs. iteration?

**This is the first question.** It determines whether the Exploration phase runs.

- **New design** — nothing exists yet, or the user wants to explore fresh directions.
  → Run Exploration phase (Phase 1.5) before the polish loop.
- **Iterating existing** — there's already a design (Figma, live app, or codebase).
  → Skip Exploration, go directly to Phase 2 LOOP.

If unclear, ask: *"Are we starting fresh or polishing something that already exists?"*

### Step 1: Understand the target

Ask:
- What are we designing? (landing page, app screen, component, full app)
- Is there a Figma source of truth? (if yes, connect via Figma MCP)
- What's the URL or entry point?
- What viewports matter? (default: mobile 390x844 + desktop 1440x900)

**If new design (from Step 0):**
- How many parallel concepts to explore? (default: **3–5**)
- A short name/direction for each concept — these become the subagent briefs
- Which Figma file to work in? (create new if none)
- Any non-negotiable constraints? (brand colors, typography, platform conventions)

### Step 2: Choose capture method

Auto-detect from the project, then confirm:
- Playwright available? → Use for static/SSR web
- Chrome MCP connected? → Use for live browser interaction
- Storybook running? → Use for component-level design
- iOS project? → Use XCUITest or Maestro
- React Native? → Use Detox or Maestro

### Step 3: Define design judges

Run `/evals-first` Phase 1-3 scoped to design criteria:

1. **Collect reference materials** — the app's existing design system, color palette,
   typography scale, component patterns. Read from the codebase or Figma.
2. **Distill into judge criteria** — concrete, evaluatable rules
3. **Write judge prompts** — store in `.autodesign/judges/`

Default judges (always included):
- AI Slop Detection
- Mobile Usability
- Visual Hierarchy

Project-specific judges (defined during preflight):
- Brand Consistency (if the app has an established visual identity)
- Design System Compliance (if a design system exists)
- Figma Fidelity (if Figma source is connected)

### Step 4: Capture baseline

Take screenshots before any changes. Store in `.autodesign/captures/baseline/`.
These are the "before" for the handoff briefing.

### Step 5: Confirm deploy

If the project can be deployed (e.g., Cloudflare Pages, Vercel):
- Confirm deploy command
- Confirm whether to deploy after each iteration or only at the end

### Step 6: Generate Script and Hand Off

Autodesign runs each iteration in a **fresh subprocess** — no context bleed between
iterations. During preflight, Claude generates a customized `autodesign.sh` script
and hands it off to the user to run.

1. Write `.autodesign/config.json` with all preflight answers
2. Copy `autodesign.sh` from the skill's `scripts/` directory to `.autodesign/autodesign.sh`
3. Apply configuration: inject TARGET, CAPTURE_METHOD, DEPLOY_CMD, EXPLORATION settings, etc.
   The script reads from `config.json` at startup — most overrides go there rather than
   hardcoded into the script.
4. Confirm the script with the user:

```
✓ Config saved to .autodesign/config.json
✓ Script ready at .autodesign/autodesign.sh

Run it:
  bash .autodesign/autodesign.sh

Each iteration runs as a fresh Claude subprocess — you can safely close this terminal.
Monitor progress via: watch cat .autodesign/HEARTBEAT
```

5. Do NOT start the loop yourself. The script is the entry point.

## Iteration Loop (Detail)

Each iteration follows this exact sequence:

```
1. CAPTURE
   - Run capture command for each viewport
   - Save to .autodesign/captures/iteration-N/
   - Update .autodesign/captures/current/ symlink

2. EVALUATE
   a. Run /critique on all screenshots
      → Produces prioritized issue list with severity
   b. Run design judges in parallel
      → Each returns PASS/FAIL with evidence
   c. Select 1-3 targeted impeccable skills based on findings
      → Run each, collect additional specific recommendations
   d. Run cross-model review (Claude + Codex)
      → Filter for consensus findings

3. PRIORITIZE
   - Merge all findings into a single list
   - Deduplicate (same issue from multiple sources = higher confidence)
   - Sort: CRITICAL > HIGH > MEDIUM > LOW
   - Select top 3-5 actionable fixes for this iteration
   - Skip LOW items unless nothing else to do

4. IMPLEMENT
   - Apply fixes directly to source code
   - For each fix, note what changed and why
   - Run any feedback commands (typecheck, lint, etc.)

5. VERIFY
   - Re-capture screenshots
   - Quick-check: did the fix actually work? Any regressions?
   - If regression: revert that specific fix, note it

6. DEPLOY (if configured)
   - Run deploy command
   - Wait for deployment to propagate

7. COMMIT
   - Stage changed files (specific paths, not git add .)
   - Commit with descriptive message listing what was fixed
   - Push to remote

8. CONVERGENCE CHECK
   - If /critique returned 0 critical + 0 high issues for 2 consecutive iterations → STOP
   - If iteration count >= 5 → STOP (diminishing returns)
   - If duration limit reached → STOP
   - Otherwise → loop to step 1
```

## Handoff Briefing

`.autodesign/BRIEFING.md` — written for the human, readable in 2 minutes:

```markdown
# Autodesign Briefing — 2026-03-29

## Summary
Ran 4 iterations. Converged after iteration 4 (2 consecutive clean passes).

## What changed
1. **Iteration 1** — Removed redundant feature cards section, dark CTA bookend,
   tighter section padding. (critique: page felt padded, generic bottom half)
2. **Iteration 2** — Compressed "How it works" into inline strip, dark footer
   for seamless bottom half. (critique: disconnected section, jarring footer transition)
3. **Iteration 3** — Removed screenshot heading, tighter language grid, mobile
   hero padding. (critique: redundant heading, sparse grid)
4. **Iteration 4** — No changes needed. Converged.

## Before / After
- Baseline: .autodesign/captures/baseline/
- Final: .autodesign/captures/iteration-4/

## Judge Results (final pass)
- AI Slop Detection: PASS
- Mobile Usability: PASS
- Visual Hierarchy: PASS
- Brand Consistency: PASS

## Remaining (not fixed)
- Page would benefit from an app mockup/screenshot in the hero (requires asset creation)
- "How it works" section is still the most generic part of the page

## Eval Gaps
- No judge for animation quality (waveform timing, easing)
- No judge for dark mode (page is light-only currently)
```

## Configuration

Autodesign can persist settings so you don't re-answer preflight questions:

**Location:** `.autodesign/config.json`

```json
{
  "target": "https://escuchame.app",
  "captureMethod": "playwright",
  "viewports": [
    { "name": "desktop", "width": 1440, "height": 900 },
    { "name": "mobile", "width": 390, "height": 844 }
  ],
  "deployCommand": "CLOUDFLARE_ACCOUNT_ID=xxx npx wrangler pages deploy ./apps/web/public --project-name=escuchame-web --commit-dirty=true",
  "feedbackCommands": [],
  "maxIterations": 5,
  "convergenceThreshold": 2,
  "figmaFileKey": null,
  "judges": ["ai-slop", "mobile-usability", "visual-hierarchy", "brand-consistency"],
  "exploration": {
    "enabled": false,
    "count": 10,
    "figmaFileKey": null,
    "figmaPageName": "Explorations",
    "selectedExploration": null
  }
}
```

## Git Rules

- **NEVER commit `.autodesign/` to git.** Add to `.gitignore` during preflight.
- Use specific file paths when staging (not `git add .`)
- Push after each iteration (don't accumulate commits locally)
- Commit messages should describe the design change, not the process

## Gotchas

- **Screenshots are static.** Playwright captures a frozen moment — animations, hover states,
  and transitions aren't visible. Use Chrome MCP for interactive evaluation when needed.
- **LLM judges can't see subtle alignment issues.** They're good at hierarchy, color, and
  composition but miss 1-2px alignment problems. /polish handles that.
- **Cross-model review adds latency.** Each iteration takes longer with Codex review.
  Skip it for trivial iterations (only CSS spacing changes).
- **Exploration diversity matters more than quantity.** 10 varied explorations beats 20
  slight variations. If you find yourself making minor adjustments across explorations,
  stop — invent a completely different visual direction instead.
- **Don't over-iterate.** 5 iterations is usually enough. After that you're shuffling
  preferences between models, not improving design quality.
- **Capture after deploy, not before.** CDN caching can serve stale content. Hard-refresh
  or add cache-busting to capture commands.
- **Dark mode needs separate captures.** If the app supports dark mode, capture both.
  Add dark mode viewports to the config.

## Composing with Other Skills

| Skill | How it composes |
|-------|----------------|
| **/critique** | Core of the eval stack — runs every iteration |
| **/evals-first** | Preflight judge definition |
| **/codex-review** | Cross-model consensus (design-focused variant) |
| **/nightshift** | Autodesign can run as a post-nightshift polish pass |
| **/teach-impeccable** | Run once before autodesign to establish design context |
| **/frontend-design** | Referenced by /critique for anti-pattern detection |
| **/dogfood** | Complementary — dogfood finds UX bugs, autodesign fixes visual quality |
| **/babysit-pr** | Run autodesign on preview deployments during PR review |

## Launching

### Figma-direct mode (Figma iteration, no code changes)

The `scripts/autodesign.sh` script handles Figma-only design iteration. Pass the
Figma file key, working frame node ID, and your design target:

```bash
~/src/skills/autodesign/scripts/autodesign.sh \
  --figma-file SmM43Vo4vKFNVg2q1TAPH2 \
  --working-frame "7:2" \
  --target "CLI tool landing page for skpm — the skill package manager" \
  --iterations 10 \
  --wide
```

Each iteration:
1. Screenshots the Working frame
2. Critiques the design
3. **Copies the Working frame to the "Iterations" Figma page** (preserving history)
4. Implements the top 3-5 improvements on the Working frame
5. Verifies with a post-change screenshot
6. Updates `.autodesign/state.json` with convergence tracking

Monitor progress:
```bash
watch -n 5 cat .autodesign/HEARTBEAT
```

Flags:
- `--wide`: explore dramatically different directions (go wide before deep)
- `--iterations N`: max iterations (default: 10)

State persists across re-runs via `.autodesign/state.json` — re-run to continue.

### Interactive (web/native, preflight, then hand off)

```
/autodesign
```

Preflight runs interactively with you present. At the end, Claude generates
`.autodesign/autodesign.sh` and hands it off — **you run the script**:

```bash
bash .autodesign/autodesign.sh
```

Each iteration runs as a fresh `claude -p` subprocess. The script is the loop controller
— you can leave it running AFK. Monitor live progress:

```bash
watch -n 5 cat .autodesign/HEARTBEAT
# or
tail -f .autodesign/logs/iteration-*.log
```

### With options (passed to preflight)

```
/autodesign 3h                        — run for 3 hours max (sets MAX_ITERATIONS hint)
/autodesign --skip-codex              — skip cross-model review (faster iterations)
/autodesign --figma <url>             — use Figma as source of truth
/autodesign --capture chrome-mcp      — force Chrome MCP capture instead of Playwright
/autodesign --explore                 — force exploration phase (go wide first, default: 10)
/autodesign --explore-count 20        — generate 20 explorations instead of default 10
/autodesign --skip-explore            — skip exploration phase, go straight to deep loop
```

These flags are baked into `.autodesign/config.json` during preflight, not passed
to the script at runtime. Edit `config.json` directly to change them later.

### Re-run (skip preflight)

If `.autodesign/config.json` exists from a previous run:

```
/autodesign --resume
```

Skips preflight, regenerates the script from the saved config, tells you to run it.

### Environment overrides (for the script)

You can also override config values inline when running the script:

```bash
MAX_ITERATIONS=10 bash .autodesign/autodesign.sh
EXPLORATION_ENABLED=true EXPLORATION_COUNT=15 bash .autodesign/autodesign.sh
AGENT_RUNTIME=codex bash .autodesign/autodesign.sh   # use Codex instead of Claude
```