autodesign

name	autodesign
description	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".
dependsOn	["jonmumm/skills@evals-first","jonmumm/skills@codex-review","pbakaus/impeccable"]

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:

// 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):

   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

# 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):

# 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

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

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

# 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:

# 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

{
  "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:

~/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:

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

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:

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