claude-symphony 0.5.2 → 0.5.3

package/README.md

@@ -138,7 +138,7 @@ claude-symphony provides context management tools to help track and manage Claud
 | **Pipeline**              | `/status`, `/next`, `/handoff`, `/checkpoint`, `/context`, `/validate`, `/restore`, `/run-stage`, `/stages`       |
 | **Multi-AI**              | `/collaborate`, `/synthesize`, `/benchmark`, `/fork`, `/gemini`, `/codex`                                         |
 | **Stage Shortcuts**       | `/brainstorm`, `/research`, `/planning`, `/ui-ux`, `/tasks`, `/implement`, `/refactor`, `/qa`, `/test`, `/deploy` |
-| **Requirements & Design** | `/epic`, `/refine`, `/moodboard`, `/stitch`                                                                       |
+| **Requirements & Design** | `/epic`, `/refine`, `/moodboard`, `/moodboard generate`, `/pencil`, `/stitch`                                     |
 | **Agent**                 | `/arch-review`, `/qa-analyze`                                                                                     |
 | **Configuration**         | `/config`, `/goto`, `/init-project`                                                                               |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-symphony",
-  "version": "0.5.2",
+  "version": "0.5.3",
   "description": "Multi-AI Orchestration Framework - Create new projects with 10-stage development workflow",
   "type": "module",
   "bin": {

package/template/.claude/commands/moodboard.md

@@ -6,6 +6,7 @@ Collect visual references and analyze them to generate design tokens and design
 
 ```
 /moodboard                       # Start interactive moodboard flow
+/moodboard generate              # Generate moodboard from text description (Path B)
 /moodboard add [category]        # Add images to a category
 /moodboard analyze               # Run analysis on collected images
 /moodboard feedback "..."        # Provide feedback on analysis
@@ -59,8 +60,58 @@ Review collected images and run initial analysis.
 
 ---
 
+## Dual-Path Workflow
+
+The moodboard supports two paths based on your pre-start intake answers:
+
+### Path A: Analyze Existing References
+If you already have design references, use the standard interactive flow:
+```
+/moodboard          # Collect and analyze existing images
+```
+
+### Path B: AI-Generated Moodboard
+If you have no references, generate a moodboard from text descriptions:
+```
+/moodboard generate # Generate moodboard via AI
+```
+
+---
+
 ## Subcommands
 
+### `/moodboard generate` (Path B: AI-Generated Moodboard)
+
+Generate a moodboard from text descriptions when no existing references are available.
+
+**Flow:**
+1. **Description Collection** - Describe your desired visual style
+2. **AI Generation** - Generate visual references using provider chain
+3. **User Review** - Review and approve/reject generated references
+4. **Token Extraction** - Extract design tokens from approved selections
+
+**Generation Provider Priority:**
+1. **Pencil.dev** (via Playwright/BrowserMCP) - Text-to-UI generation
+2. **Stitch MCP** - Google Stitch text-to-UI fallback
+3. **Claude Vision** - AI-described design concepts
+
+**Example:**
+```
+/moodboard generate
+> Describe your desired visual style:
+> "Modern SaaS dashboard with dark theme, glassmorphism cards, and gradient accents"
+
+Generating via Pencil.dev...
+[Generated 3 style references]
+
+Review:
+1. [Dark glassmorphism variant] - love_it / tweak / different / discard
+2. [Gradient accent variant]    - love_it / tweak / different / discard
+3. [Minimal dark variant]       - love_it / tweak / different / discard
+
+Extracting design tokens from approved selections...
+```
+
 ### `/moodboard add [category]`
 Add images to a specific category without going through full flow.
 
@@ -89,10 +140,11 @@ Run analysis on all collected images using configured provider.
 - Component recommendations
 - Spacing/rhythm analysis
 
-**Analysis Providers:**
-- `claude_vision` (default) - Claude's native vision capabilities
-- `figma_mcp` - Figma MCP for design token export
-- `both` - Use both providers
+**Analysis Providers (priority order):**
+1. `pencil_dev` - Pencil.dev browser-automated analysis (via Playwright/BrowserMCP)
+2. `stitch` - Google Stitch MCP analysis
+3. `figma_mcp` - Figma MCP for design token export
+4. `claude_vision` - Claude's native vision capabilities
 
 **Action:**
 ```bash
@@ -160,7 +212,21 @@ stages/04-ui-ux/inputs/moodboard/
 
 ## Analysis Flow
 
-### Using Claude Vision (Default)
+### Using Pencil.dev (Primary)
+
+1. **Browser Launch**: Open Pencil.dev via Playwright (or BrowserMCP fallback)
+2. **Image Upload**: Upload moodboard images for analysis
+3. **AI Analysis**: Pencil.dev extracts design patterns
+4. **Token Generation**: Color, typography, spacing, component tokens
+
+### Using Stitch MCP (Fallback 1)
+
+When Pencil.dev is unavailable:
+1. **Design DNA Extraction**: Extract style tokens from images
+2. **Pattern Analysis**: Identify layout and component patterns
+3. **Export**: Generate design tokens
+
+### Using Claude Vision (Fallback 3)
 
 1. **Image Reading**: Claude reads all images in moodboard directories
 2. **Color Extraction**: Identifies dominant and accent colors
@@ -168,7 +234,7 @@ stages/04-ui-ux/inputs/moodboard/
 4. **Layout Patterns**: Identifies grid systems and spacing patterns
 5. **Component Identification**: Suggests UI component patterns
 
-### Using Figma MCP
+### Using Figma MCP (Fallback 2)
 
 When Figma links are provided:
 1. **Variable Extraction**: Get design variables from Figma
@@ -242,7 +308,7 @@ Moodboard state is tracked in `state/progress.json`:
 
 ## Configuration
 
-See `config/ui-ux.yaml` for detailed settings:
+See `config/ui-ux.jsonc` for detailed settings:
 - Collection flow steps
 - Analysis providers
 - Feedback loop settings

package/template/.claude/commands/pencil.md

@@ -0,0 +1,181 @@
+# /pencil - Pencil.dev Browser-Automated UI Generation & Analysis
+
+Generate UI designs and analyze visual references using Pencil.dev via browser automation.
+
+## Usage
+
+```
+/pencil                          # Show status and connection check
+/pencil generate "description"   # Generate UI from text description
+/pencil analyze path/to/image    # Analyze image for design tokens
+/pencil moodboard "description"  # Generate moodboard from text description
+```
+
+---
+
+## Commands
+
+### `/pencil` (Status)
+
+Check Pencil.dev accessibility and browser MCP status.
+
+**Output:**
+- Pencil.dev connection status
+- Browser MCP availability (Playwright / BrowserMCP)
+- Current fallback chain status
+
+### `/pencil generate "description"`
+
+Generate UI from a text description using Pencil.dev.
+
+**Example:**
+```
+/pencil generate "A modern dashboard with sidebar navigation, user avatar, and analytics cards"
+```
+
+**Process:**
+1. Launch browser via Playwright (or BrowserMCP fallback)
+2. Navigate to Pencil.dev
+3. Input design description
+4. Capture generated UI output
+5. Save to `outputs/pencil_generated/`
+
+**Output:**
+- `outputs/pencil_generated/ui_[timestamp]/` - Generated UI screenshots and assets
+
+### `/pencil analyze path/to/image`
+
+Analyze an image or screenshot to extract design tokens and patterns.
+
+**Example:**
+```
+/pencil analyze inputs/moodboard/ui-references/hero-section.png
+```
+
+**Extracts:**
+- Color palette
+- Typography patterns
+- Layout structure
+- Component identification
+- Spacing rhythm
+
+### `/pencil moodboard "description"`
+
+Generate a moodboard from a text description (Path B workflow).
+
+**Example:**
+```
+/pencil moodboard "Modern SaaS app with dark theme, glassmorphism, and gradient accents"
+```
+
+**Process:**
+1. Generate multiple style references via Pencil.dev
+2. Present to user for review
+3. Extract design tokens from approved selections
+
+---
+
+## Browser MCP Priority
+
+Pencil.dev is accessed via browser automation. The priority order:
+
+```
+1. Playwright MCP (primary)
+   - Full browser control
+   - Screenshot capture
+   - Element interaction
+
+2. BrowserMCP (fallback)
+   - Alternative browser automation
+   - Used when Playwright is unavailable
+```
+
+### Browser Configuration
+
+```jsonc
+{
+  "browser_config": {
+    "primary": "playwright",
+    "fallback": "browsermcp",
+    "timeout_ms": 30000,
+    "retry_count": 2
+  }
+}
+```
+
+---
+
+## Fallback Chain
+
+When Pencil.dev is unavailable or browser automation fails:
+
+```
+Pencil.dev (via Playwright)
+    |
+    +-- Playwright failed? --------> Pencil.dev (via BrowserMCP)
+    |
+    +-- BrowserMCP failed? --------> Stitch MCP (text-to-UI)
+    |
+    +-- Stitch unavailable? -------> Figma MCP (design tokens only)
+    |
+    +-- Figma unavailable? --------> Claude Vision (analysis only)
+    |
+    +-- All failed? ---------------> Manual wireframes (ASCII/Mermaid)
+```
+
+Fallback configuration: `config/mcp_fallbacks.jsonc`
+
+---
+
+## Integration with Moodboard Workflow
+
+### Path A (Existing References)
+```
+/moodboard              # Collect existing images
+/pencil analyze ...     # Analyze with Pencil.dev
+/moodboard export       # Export design tokens
+```
+
+### Path B (AI-Generated)
+```
+/pencil moodboard "..."  # Generate moodboard via Pencil.dev
+[User reviews and approves]
+/moodboard export        # Export design tokens
+```
+
+---
+
+## Output Files
+
+| File | Description |
+|------|-------------|
+| `outputs/pencil_generated/` | Generated UI files |
+| `outputs/pencil_analysis/` | Analysis results |
+| `outputs/design_dna.json` | Extracted Design DNA |
+
+---
+
+## Configuration
+
+See `config/ui-ux.jsonc` for settings:
+- `moodboard.analysis_provider.providers.pencil_dev` - Provider configuration
+- `moodboard.moodboard_workflow` - Dual-path workflow settings
+
+---
+
+## Troubleshooting
+
+### "Pencil.dev not accessible"
+- Check internet connection
+- Verify https://pencil.dev is available
+- Fallback will auto-activate (Stitch MCP)
+
+### "Browser MCP not available"
+- Ensure Playwright or BrowserMCP is configured
+- Run: `claude mcp list` to check available browser MCPs
+- Install Playwright: see MCP server setup docs
+
+### "Browser automation timeout"
+- Default timeout: 30 seconds
+- Retries: 2 attempts before fallback
+- If persistent, use `/stitch` as alternative

package/template/.claude/commands/stitch.md

@@ -118,12 +118,16 @@ Display detailed quota usage and history.
 
 ## Workflow Integration
 
+> **Note**: Stitch is the **2nd priority** UI generation tool. Pencil.dev is 1st priority.
+> Stitch auto-activates when Pencil.dev is unavailable or fails.
+
 Recommended workflow for Stage 04 (UI/UX):
 
 ```
-1. /moodboard                     # Collect design references
-2. /moodboard analyze             # Analyze with Claude Vision
-3. /stitch dna                    # Extract Design DNA from moodboard
+1. /moodboard                     # Collect design references (or /moodboard generate)
+2. /pencil analyze ...            # Analyze with Pencil.dev (primary)
+   └─ If Pencil.dev fails:
+3. /stitch dna                    # Extract Design DNA from moodboard (fallback)
 4. /stitch generate "..."         # Generate initial UI
 5. /stitch variants 3             # Generate alternatives
 6. [Select best variant]
@@ -170,18 +174,22 @@ At 80% usage, a warning is displayed. Consider:
 
 ## Fallback Chain
 
-When Stitch is unavailable or quota exceeded:
+Full fallback chain (Stitch is 2nd priority):
 
 ```
-Stitch MCP
-    │
-    ├─ Quota exceeded? ──────▶ Figma MCP (design tokens only)
-    │
-    ├─ API error? ──────────▶ Retry 2x, then Figma MCP
+Pencil.dev (via Playwright)        ◀── 1st Priority
     │
-    ├─ Figma unavailable? ──▶ Claude Vision (analysis only)
+    ├─ Browser failed? ────────▶ Pencil.dev (via BrowserMCP)
     │
-    └─ All failed? ─────────▶ Manual wireframes (ASCII/Mermaid)
+    └─ All browsers failed? ───▶ Stitch MCP              ◀── 2nd Priority (this tool)
+                                     │
+                                     ├─ Quota exceeded? ──────▶ Figma MCP (design tokens only)
+                                     │
+                                     ├─ API error? ──────────▶ Retry 2x, then Figma MCP
+                                     │
+                                     ├─ Figma unavailable? ──▶ Claude Vision (analysis only)
+                                     │
+                                     └─ All failed? ─────────▶ Manual wireframes (ASCII/Mermaid)
 ```
 
 Fallback configuration: `config/mcp_fallbacks.jsonc`

package/template/CLAUDE.md

@@ -204,8 +204,13 @@ Visualizes context usage, tool activity, and todo progress in the statusline.
 | `/refine` | Interactive requirements refinement (Epic → Feature → Task) |
 | `/refine --validate` | Validate requirements against INVEST criteria |
 | `/moodboard` | Collect design references and analyze design tokens |
+| `/moodboard generate` | Generate moodboard from text description (Path B: no existing refs) |
 | `/moodboard analyze` | Extract colors, fonts, styles from collected images |
 | `/moodboard skip` | Skip moodboard collection (use AI-generated design) |
+| `/pencil` | Show Pencil.dev status and connection check |
+| `/pencil generate "..."` | Generate UI from text description via Pencil.dev |
+| `/pencil analyze path` | Analyze image for design tokens via Pencil.dev |
+| `/pencil moodboard "..."` | Generate moodboard from text description via Pencil.dev |
 
 ### Task Management & Sync Commands
 | Command | Description |
@@ -428,7 +433,7 @@ Quick reference for frequently accessed files:
 |-------|-------------|----------|-------|
 | 02-research | Exa Search | Context7 | Use Exa for market data, Context7 for tech docs |
 | 03-planning | Context7 | Exa Search | Architecture patterns, framework best practices |
-| 04-ui-ux | Figma | - | Extract design tokens if Figma file available |
+| 04-ui-ux | Pencil.dev (browser) | Stitch → Figma → Claude Vision | Pencil.dev primary for UI gen/analysis; Stitch fallback |
 | 05-task-management | Notion | Markdown files | Falls back to local files if Notion not configured |
 
 ### Fallback Conditions

package/template/config/mcp_fallbacks.jsonc

@@ -124,6 +124,22 @@
       "notify_user": true
     }
   },
+  "pencil_dev": {
+    "primary": "playwright",
+    "fallbacks": ["browsermcp", "stitch", "figma-dev-mode", "claude_vision"],
+    "url": "https://pencil.dev",
+    "rules": {
+      "on_browser_failed": "use_fallback",
+      "on_timeout": "retry_then_fallback",
+      "retry_count": 2,
+      "retry_delay_ms": 2000,
+      "timeout_ms": 30000
+    },
+    "on_error": {
+      "action": "use_fallback_chain",
+      "message": "Pencil.dev browser automation failed. Falling back to {{FALLBACK_TOOL}}."
+    }
+  },
   "figma": {
     "primary": "figma-dev-mode",
     "fallbacks": [],
@@ -176,16 +192,18 @@
       "reason": "Architecture pattern/documentation search"
     },
     "04-ui-ux": {
-      "ui_generation": ["stitch", "figma-dev-mode", "claude_vision"],
+      "ui_generation": ["pencil_dev", "stitch", "figma-dev-mode", "claude_vision"],
+      "ui_analysis": ["pencil_dev", "stitch", "figma-dev-mode", "claude_vision"],
       "browser": [
-        "figma-dev-mode",
-        "playwright"
+        "playwright",
+        "browsermcp",
+        "figma-dev-mode"
       ],
       "search": [
         "exa",
         "web_search"
       ],
-      "reason": "Stitch for UI generation, Figma for design tokens"
+      "reason": "Pencil.dev for UI generation/analysis (1st), Stitch fallback, Figma for design tokens"
     },
     "06-implementation": {
       "search": [
@@ -317,6 +335,12 @@
         "on_failure": "warn",
         "message": "codex-wrapper.sh not executable"
       },
+      {
+        "name": "pencil_dev_access",
+        "command": "curl -s -o /dev/null -w '%{http_code}' https://pencil.dev | grep -q '200'",
+        "on_failure": "warn",
+        "message": "Pencil.dev not accessible. Stitch MCP will be used as fallback for UI generation."
+      },
       {
         "name": "stitch_mcp",
         "command": "claude mcp list | grep -q stitch",

package/template/config/ui-ux.jsonc

@@ -26,30 +26,32 @@
       "analyze_spacing": true
     },
     "analysis_provider": {
-      "primary": "claude_vision",
-      "fallback": "figma_mcp",
+      // Priority: pencil_dev > stitch > figma_mcp > claude_vision
+      "primary": "pencil_dev",
+      "fallback_chain": ["stitch", "figma_mcp", "claude_vision"],
       "providers": {
-        "claude_vision": {
+        "pencil_dev": {
           "enabled": true,
-          "description": "Claude's native vision capabilities",
+          "description": "Pencil.dev browser-automated UI generation and analysis",
+          "type": "browser_automated",
+          "url": "https://pencil.dev",
+          "browser_priority": ["playwright", "browsermcp"],
           "capabilities": [
+            "text_to_ui",
+            "image_to_ui",
+            "ui_analysis",
             "color_extraction",
             "layout_analysis",
             "component_identification",
-            "typography_detection",
-            "spacing_analysis",
-            "accessibility_check"
-          ]
-        },
-        "figma_mcp": {
-          "enabled": true,
-          "description": "Figma MCP server integration",
-          "capabilities": [
-            "design_token_export",
-            "component_inspection",
-            "variable_extraction",
-            "code_generation"
-          ]
+            "moodboard_generation",
+            "style_transfer"
+          ],
+          "browser_config": {
+            "primary": "playwright",
+            "fallback": "browsermcp",
+            "timeout_ms": 30000,
+            "retry_count": 2
+          }
         },
         "stitch": {
           "enabled": true,
@@ -66,6 +68,28 @@
             "standard": { "description": "Production-ready UI", "quota_cost": 1 },
             "experimental": { "description": "Cutting-edge features", "quota_cost": 1 }
           }
+        },
+        "figma_mcp": {
+          "enabled": true,
+          "description": "Figma MCP server integration",
+          "capabilities": [
+            "design_token_export",
+            "component_inspection",
+            "variable_extraction",
+            "code_generation"
+          ]
+        },
+        "claude_vision": {
+          "enabled": true,
+          "description": "Claude's native vision capabilities",
+          "capabilities": [
+            "color_extraction",
+            "layout_analysis",
+            "component_identification",
+            "typography_detection",
+            "spacing_analysis",
+            "accessibility_check"
+          ]
         }
       }
     },
@@ -305,15 +329,118 @@
     "commands": {
       "start": "/moodboard",
       "add": "/moodboard add [category]",
+      "generate": "/moodboard generate",
       "analyze": "/moodboard analyze",
       "feedback": "/moodboard feedback",
       "export": "/moodboard export",
       "status": "/moodboard status"
+    },
+    "moodboard_workflow": {
+      "description": "Dual-path moodboard workflow based on user's existing assets",
+      "path_a": {
+        "id": "analyze_existing",
+        "name": "Analyze Existing Moodboard",
+        "trigger": "User has existing design references/images",
+        "steps": [
+          "collect_images",
+          "analyze_with_provider",
+          "extract_design_dna",
+          "generate_tokens",
+          "user_feedback",
+          "finalize"
+        ]
+      },
+      "path_b": {
+        "id": "generate_new",
+        "name": "AI-Generated Moodboard",
+        "trigger": "User has no existing references",
+        "steps": [
+          "collect_text_description",
+          "generate_via_pencil_dev",
+          "user_review",
+          "extract_design_dna",
+          "generate_tokens",
+          "user_feedback",
+          "finalize"
+        ],
+        "generation_provider_priority": ["pencil_dev", "stitch", "claude_vision"]
+      }
     }
   },
+  "pre_start_intake": {
+    "enabled": true,
+    "description": "Required pre-start questions before UI/UX work begins",
+    "required": true,
+    "questions": [
+      {
+        "id": "moodboard_available",
+        "question": "Do you have existing design references or moodboard images?",
+        "impact": "Determines workflow path (Path A: analyze existing vs Path B: AI-generate)",
+        "options": ["yes", "no"],
+        "branch": {
+          "yes": "moodboard_workflow.path_a",
+          "no": "moodboard_workflow.path_b"
+        }
+      },
+      {
+        "id": "brand_assets_available",
+        "question": "Do you have brand assets (logo, colors, fonts, brand guidelines)?",
+        "impact": "Determines Design DNA extraction source",
+        "options": ["yes", "no"],
+        "branch": {
+          "yes": "Collect into brand-assets/ directory",
+          "no": "AI will suggest brand elements"
+        }
+      },
+      {
+        "id": "target_platform",
+        "question": "What is your target platform?",
+        "impact": "Sets wireframe breakpoints and component design constraints",
+        "options": ["web", "mobile", "desktop", "responsive"],
+        "default": "responsive",
+        "breakpoint_presets": {
+          "web": ["desktop", "tablet"],
+          "mobile": ["mobile"],
+          "desktop": ["desktop"],
+          "responsive": ["mobile", "tablet", "desktop"]
+        }
+      },
+      {
+        "id": "design_style",
+        "question": "What design style direction do you prefer?",
+        "impact": "Pre-sets style discovery or skips it if already decided",
+        "options": ["modern_minimal", "bold_colorful", "professional", "playful", "custom"],
+        "branch": {
+          "custom": "Proceed to style_discovery step",
+          "_other": "Skip style_discovery, apply preset"
+        }
+      },
+      {
+        "id": "competitors_references",
+        "question": "Are there competitor apps or reference sites you want to analyze?",
+        "impact": "Determines whether competitor UI analysis is performed",
+        "options": ["yes", "no"],
+        "branch": {
+          "yes": "Collect URLs, analyze with Pencil.dev",
+          "no": "Skip competitor analysis"
+        }
+      },
+      {
+        "id": "design_tool_access",
+        "question": "Do you have access to Figma or other design tools?",
+        "impact": "Determines final export format",
+        "options": ["figma", "none"],
+        "branch": {
+          "figma": "Export as .fig + HTML/CSS",
+          "none": "Export as HTML/CSS only"
+        }
+      }
+    ]
+  },
   "stitch_integration": {
     "enabled": true,
-    "auto_invoke_on_moodboard": true,
+    "auto_invoke_on_moodboard": false,
+    "auto_invoke_condition": "pencil_dev_failed",
     "design_dna": {
       "extract_on_start": true,
       "source_directories": [

package/template/stages/04-ui-ux/CLAUDE.md

@@ -66,6 +66,35 @@ User interface and experience design stage
 - `$STAGES_ROOT/03-planning/outputs/architecture.md`
 - `$STAGES_ROOT/03-planning/HANDOFF.md`
 
+## Pre-Start Intake (Required)
+
+> ⚠️ **MANDATORY**: Before any UI/UX work, ask these 6 questions and record answers.
+> Configuration: `config/ui-ux.jsonc` → `pre_start_intake`
+
+### 6 Required Questions
+
+| # | Question | Impact | Branch |
+|---|----------|--------|--------|
+| 1 | **무드보드 보유 여부** — 기존 디자인 레퍼런스/이미지가 있는가? | 전체 워크플로우 경로 결정 | 있음→Path A (분석), 없음→Path B (AI 생성) |
+| 2 | **브랜드 에셋 보유** — 로고, 컬러, 폰트 등 브랜드 가이드라인이 있는가? | Design DNA 추출 소스 결정 | 있음→brand-assets/ 수집, 없음→AI 제안 |
+| 3 | **타겟 플랫폼** — 웹/모바일/데스크톱/반응형? | 와이어프레임 브레이크포인트, 컴포넌트 설계 | 선택에 따라 breakpoint 프리셋 적용 |
+| 4 | **디자인 스타일 방향** — 모던, 볼드, 프로, 플레이풀, 커스텀? | 무드보드 생성/분석 기준점 | style_discovery 단계 스킵 또는 사전 설정 |
+| 5 | **경쟁사/레퍼런스** — 참고할 앱이나 경쟁사가 있는가? | 경쟁사 UI 분석 여부 | 있음→Pencil.dev로 분석, 없음→스킵 |
+| 6 | **디자인 도구 접근성** — Figma 계정 등 외부 도구 보유? | 최종 export 포맷 결정 | Figma→.fig export, 없음→HTML/CSS 우선 |
+
+### Intake Flow
+```
+1. Ask all 6 questions upfront
+2. Record answers in state/progress.json under "ui_ux_intake"
+3. Determine Path A or Path B based on Q1
+4. Apply platform presets based on Q3
+5. Pre-set style direction based on Q4
+6. Configure export format based on Q6
+7. THEN proceed to moodboard setup
+```
+
+---
+
 ## Prerequisites Before UI/UX Design
 
 > ⚠️ **Important**: Verify previous stage deliverables before starting UI/UX design
@@ -78,28 +107,40 @@ User interface and experience design stage
 | Stage 03 | `stages/03-planning/HANDOFF.md` | Stage 03 handoff reviewed |
 | Stage 01 | `stages/01-brainstorm/outputs/requirements_analysis.md` | User needs identified |
 
-### Moodboard Setup Requirement
-Before proceeding with wireframe design:
+### Moodboard Setup (Dual-Path)
 
-1. **Ask User**: "디자인 참고 자료(무드보드)를 제공하시겠습니까?"
-2. **If Yes**: Collect URLs, images, color preferences via `/moodboard`
-3. **If No**: Explicitly confirm AI-generated design is acceptable
+Based on Pre-Start Intake Q1 answer:
 
+#### Path A: Analyze Existing References (Q1 = "yes")
+User has existing design references/images.
 ```bash
-# Verify prerequisites
-/moodboard          # Start interactive moodboard flow
+/moodboard          # Start interactive collection flow
 /moodboard add      # Add design references directly
-/moodboard skip     # Skip moodboard (AI auto-generate)
+/moodboard analyze  # Run analysis with provider chain
+```
+
+#### Path B: AI-Generated Moodboard (Q1 = "no")
+User has no existing references — AI generates them.
+```bash
+/moodboard generate           # Generate moodboard from text description
+/pencil moodboard "..."       # Generate via Pencil.dev directly
 ```
 
+**Generation Provider Priority:**
+1. Pencil.dev (via Playwright/BrowserMCP)
+2. Stitch MCP
+3. Claude Vision
+
 ### Validation Checkpoint
+- [ ] Pre-Start Intake 6 questions answered
 - [ ] Stage 03 HANDOFF.md reviewed
-- [ ] User confirmed moodboard approach (collect or skip)
-- [ ] Brand guidelines provided (if available)
+- [ ] Moodboard path determined (Path A or Path B)
+- [ ] Brand guidelines collected (if available, Q2)
+- [ ] Platform breakpoints configured (Q3)
 
 ## Moodboard Analysis
 
-> Configuration: `config/ui-ux.yaml`
+> Configuration: `config/ui-ux.jsonc`
 > Command: `/moodboard`
 
 ### Interactive Moodboard Collection (Recommended)
@@ -155,10 +196,12 @@ inputs/moodboard/
 
 ### Analysis Providers
 
-| Provider | Capabilities |
-|----------|--------------|
-| `claude_vision` (default) | Color extraction, layout analysis, component ID |
-| `figma_mcp` | Design token export, variable extraction |
+| Priority | Provider | Capabilities |
+|----------|----------|--------------|
+| 1 | `pencil_dev` | Text-to-UI, image analysis, moodboard generation, style transfer |
+| 2 | `stitch` | Text-to-UI, image-to-UI, Design DNA, Figma/HTML export |
+| 3 | `figma_mcp` | Design token export, variable extraction, component inspection |
+| 4 | `claude_vision` | Color extraction, layout analysis, component ID, accessibility |
 
 ### Feedback Loop
 
@@ -195,10 +238,56 @@ Generates:
 
 **Note:** AI analyzes images using vision capabilities. Use `/moodboard analyze` to trigger analysis.
 
-## Stitch MCP Integration
+## Pencil.dev Integration (Primary)
+
+> Configuration: `config/ui-ux.jsonc`
+> Command: `/pencil`
+
+### Overview
+
+Pencil.dev is the **primary** UI generation and analysis tool, accessed via browser automation (Playwright or BrowserMCP).
+
+### Capabilities
+
+| Feature | Description |
+|---------|-------------|
+| Text→UI | Generate UI from text descriptions |
+| Image Analysis | Analyze images for design tokens |
+| Moodboard Generation | Generate visual references from descriptions |
+| Style Transfer | Apply style patterns to new designs |
+
+### Commands
+
+| Command | Description |
+|---------|-------------|
+| `/pencil` | Show status and connection check |
+| `/pencil generate "..."` | Generate UI from description |
+| `/pencil analyze path` | Analyze image for design tokens |
+| `/pencil moodboard "..."` | Generate moodboard from description |
+
+### Browser Automation
+
+Pencil.dev uses browser automation to interact with the web tool:
+
+```
+Playwright (primary) → BrowserMCP (fallback)
+```
+
+- **Playwright**: Full browser control, screenshot capture, element interaction
+- **BrowserMCP**: Alternative browser automation when Playwright is unavailable
+
+### Integration with Moodboard
+
+- **Path A** (existing refs): `/pencil analyze` to analyze collected images
+- **Path B** (no refs): `/pencil moodboard` to generate references from text
+
+---
+
+## Stitch MCP Integration (Fallback)
 
 > Configuration: `config/ui-ux.jsonc`
 > Command: `/stitch`
+> **Note**: Stitch activates as fallback when Pencil.dev is unavailable
 
 ### Capabilities
 
@@ -234,12 +323,13 @@ Generates:
 ### Fallback Chain
 
 ```
-Stitch → Figma MCP → Claude Vision → Manual Wireframes
+Pencil.dev (Playwright) → Pencil.dev (BrowserMCP) → Stitch → Figma MCP → Claude Vision → Manual Wireframes
 ```
 
-- **Quota exceeded**: Auto-fallback to Figma MCP
-- **API error**: Retry 2x, then fallback
-- **Timeout**: Fallback to Claude Vision
+- **Pencil.dev browser failed**: Fallback to Stitch MCP
+- **Stitch quota exceeded**: Auto-fallback to Figma MCP
+- **API error**: Retry 2x, then next fallback
+- **All tools unavailable**: Claude Vision analysis + manual wireframes
 
 ### Best Practices
 

package/template/stages/04-ui-ux/config.jsonc

@@ -92,6 +92,33 @@
       "Component list creation"
     ]
   },
+  "tools": {
+    "moodboard_providers": {
+      "description": "UI generation and analysis provider priority for moodboard workflow",
+      "priority": ["pencil_dev", "stitch", "figma_mcp", "claude_vision"],
+      "pencil_dev": {
+        "type": "browser_automated",
+        "url": "https://pencil.dev",
+        "browser_priority": ["playwright", "browsermcp"],
+        "timeout_ms": 30000,
+        "retry_count": 2,
+        "capabilities": ["text_to_ui", "image_analysis", "moodboard_generation"]
+      },
+      "stitch": {
+        "type": "mcp",
+        "auto_invoke_condition": "pencil_dev_failed",
+        "capabilities": ["text_to_ui", "image_to_ui", "design_dna", "export"]
+      },
+      "figma_mcp": {
+        "type": "mcp",
+        "capabilities": ["design_token_export", "component_inspection"]
+      },
+      "claude_vision": {
+        "type": "native",
+        "capabilities": ["color_extraction", "layout_analysis", "component_id"]
+      }
+    }
+  },
   "transition": {
     "next_stage": "05-task-management",
     "prerequisites": [