claude-symphony 0.5.2 → 0.5.4

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.4",
   "description": "Multi-AI Orchestration Framework - Create new projects with 10-stage development workflow",
   "type": "module",
   "bin": {

package/template/.claude/commands/arch-review.md

@@ -76,6 +76,13 @@ Automatically runs at Stage 03 completion.
 
 Prevents 50-100% of Stage 06 rework by catching issues early.
 
+## Agent Model Selection
+
+When spawning **architecture-review-agent**:
+1. Read `.claude/agents/architecture-review-agent/agent.json`
+2. Pass the `model` field value to the Task tool's `model` parameter
+3. If `"inherit"` or absent, omit the `model` parameter
+
 ## Fallback
 
 If agent fails, performs basic file existence check only.

package/template/.claude/commands/benchmark.md

@@ -105,6 +105,13 @@ scripts/ai-benchmark.sh --history weekly
 
 See `config/ai_benchmarking.yaml`
 
+## Agent Model Selection
+
+When spawning **benchmark-analyzer-agent**:
+1. Read `.claude/agents/benchmark-analyzer-agent/agent.json`
+2. Pass the `model` field value to the Task tool's `model` parameter
+3. If `"inherit"` or absent, omit the `model` parameter
+
 ## Related Commands
 
 - `/collaborate` - AI collaboration

package/template/.claude/commands/checkpoint.md

@@ -88,6 +88,15 @@ Continue? [y/N] y
 - `06-implementation`: At major milestones during implementation
 - `07-refactoring`: Before/after refactoring
 
+## Agent Model Selection
+
+When spawning **checkpoint-manager-agent**:
+1. Read `.claude/agents/checkpoint-manager-agent/agent.json`
+2. Pass the `model` field value to the Task tool's `model` parameter (expected: `haiku`)
+3. If `"inherit"` or absent, omit the `model` parameter
+
+> **Cost note**: checkpoint-manager-agent uses `haiku` for lightweight background execution.
+
 ## Options
 - `--list`: Display checkpoint list
 - `--delete [CP-ID]`: Delete checkpoint

package/template/.claude/commands/handoff.md

@@ -33,6 +33,13 @@ By default, this command uses the **handoff-generator-agent** which:
 - Applies conditional sections based on stage context
 - Uses extended thinking for complex analysis
 
+## Agent Model Selection
+
+When spawning **handoff-generator-agent**:
+1. Read `.claude/agents/handoff-generator-agent/agent.json`
+2. Pass the `model` field value to the Task tool's `model` parameter
+3. If `"inherit"` or absent, omit the `model` parameter
+
 ## Fallback
 
 If agent fails, automatically falls back to legacy bash script.

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/qa-analyze.md

@@ -66,6 +66,13 @@ Report: state/qa_analysis/qa_report_20260128_143000.json
 
 Automatically runs as part of Stage 08 (QA) workflow.
 
+## Agent Model Selection
+
+When spawning **qa-analysis-agent**:
+1. Read `.claude/agents/qa-analysis-agent/agent.json`
+2. Pass the `model` field value to the Task tool's `model` parameter
+3. If `"inherit"` or absent, omit the `model` parameter
+
 ## Fallback
 
 If agent fails, runs basic npm audit only.

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/commands/synthesize.md

@@ -57,6 +57,13 @@ Final output: stages/01-brainstorm/outputs/ideas.md
 - Default: 0.8 (80%)
 - If below threshold: Triggers review prompt
 
+## Agent Model Selection
+
+When spawning **output-synthesis-agent**:
+1. Read `.claude/agents/output-synthesis-agent/agent.json`
+2. Pass the `model` field value to the Task tool's `model` parameter
+3. If `"inherit"` or absent, omit the `model` parameter
+
 ## Fallback
 
 If agent fails, falls back to best_of_n scoring method.

package/template/.claude/commands/validate.md

@@ -167,6 +167,13 @@ See `config/output_validation.yaml`
 Validation runs automatically when executing `/next` command.
 Stage transition is blocked if validation fails.
 
+## Agent Model Selection
+
+When spawning **validation-agent**:
+1. Read `.claude/agents/validation-agent/agent.json`
+2. Pass the `model` field value to the Task tool's `model` parameter
+3. If `"inherit"` or absent, omit the `model` parameter
+
 ## Related Commands
 
 - `/next` - Next stage transition

package/template/.claude/hooks/auto-checkpoint-hook.md

@@ -152,6 +152,15 @@ agent:
 
 **Note**: All checkpoint errors are non-blocking and logged only.
 
+## Agent Model Selection
+
+When spawning **checkpoint-manager-agent**:
+1. Read `.claude/agents/checkpoint-manager-agent/agent.json`
+2. Pass the `model` field value to the Task tool's `model` parameter (expected: `haiku`)
+3. If `"inherit"` or absent, omit the `model` parameter
+
+> **STRICT**: checkpoint-manager-agent MUST use `haiku` model for cost efficiency. This agent runs frequently in background — using a larger model wastes resources.
+
 ## Related
 
 - `/checkpoint` - Manual checkpoint

package/template/.claude/hooks/model-enforcement-hook.md

@@ -0,0 +1,113 @@
+# Model Enforcement Hook
+
+Verifies that sub-agent spawns use the correct model as defined in their `agent.json`.
+
+## Trigger Conditions
+
+- Task tool invocation that spawns a known sub-agent
+- Agent name detected in Task tool prompt or description
+
+## Verification Flow
+
+```
+Task Tool Call Detected
+
+↓
+
+Extract Agent Name from prompt/description
+
+↓
+
+Read .claude/agents/{agent-name}/agent.json
+├─ Extract "model" field
+└─ If file not found → Skip verification
+
+↓
+
+Compare Expected vs Actual Model
+├─ Match → ✅ Log success
+├─ Mismatch (advisory agent) → ⚠️ Log warning
+└─ Mismatch (strict agent) → ❌ Log error + alert
+
+↓
+
+Log Result → state/model_enforcement.log
+```
+
+## Enforcement Modes
+
+### Advisory Mode (Default)
+
+For most agents, model mismatches produce a **warning log** but do not block execution:
+
+```
+⚠️ [MODEL_MISMATCH] validation-agent: expected "sonnet", got "inherit"
+   Action: Warning logged (advisory mode)
+```
+
+### Strict Mode
+
+For cost-critical agents, model mismatches produce an **error log** and alert:
+
+```
+❌ [MODEL_MISMATCH] checkpoint-manager-agent: expected "haiku", got "sonnet"
+   Action: Error logged (strict mode) — cost impact detected
+```
+
+## Strict Agents
+
+The following agents are in strict enforcement mode:
+
+| Agent | Required Model | Reason |
+|-------|---------------|--------|
+| checkpoint-manager-agent | haiku | Frequent background task, cost-critical |
+
+## Known Agents
+
+| Agent | Expected Model | Mode |
+|-------|---------------|------|
+| validation-agent | sonnet | advisory |
+| output-synthesis-agent | sonnet | advisory |
+| handoff-generator-agent | sonnet | advisory |
+| benchmark-analyzer-agent | sonnet | advisory |
+| checkpoint-manager-agent | haiku | **strict** |
+| architecture-review-agent | sonnet | advisory |
+| qa-analysis-agent | sonnet | advisory |
+| requirements-validation-agent | sonnet | advisory |
+| research-analysis-agent | sonnet | advisory |
+| task-decomposition-agent | sonnet | advisory |
+| refactoring-analysis-agent | sonnet | advisory |
+| test-execution-agent | sonnet | advisory |
+| smart-rollback-agent | sonnet | advisory |
+| cicd-validation-agent | sonnet | advisory |
+| moodboard-analysis-agent | sonnet | advisory |
+
+## Log Format
+
+```
+[2026-01-28T14:30:00Z] [MODEL_OK] validation-agent: model=sonnet ✅
+[2026-01-28T14:30:05Z] [MODEL_MISMATCH] checkpoint-manager-agent: expected=haiku, actual=sonnet ❌ (strict)
+[2026-01-28T14:31:00Z] [MODEL_SKIP] unknown-agent: no agent.json found, skipping
+```
+
+## Log Location
+
+- `state/model_enforcement.log`
+
+## Configuration
+
+See `config/model_enforcement.yaml` for enforcement settings.
+
+## Error Handling
+
+| Error | Behavior |
+|-------|----------|
+| agent.json not found | Skip verification, log info |
+| agent.json parse error | Skip verification, log warning |
+| Log file write error | Continue execution silently |
+
+## Related
+
+- Sub-Agent Model Enforcement Policy (CLAUDE.md)
+- `config/model_enforcement.yaml` - Enforcement configuration
+- `.claude/agents/*/agent.json` - Agent definitions

package/template/.claude/hooks/stage-transition-hook.md

@@ -122,6 +122,18 @@ agents:
 /config hooks stage-transition disable
 ```
 
+## Agent Model Selection
+
+When spawning agents during stage transition, read each agent's `agent.json` and pass the `model` field:
+
+| Agent | Config Path | Expected Model |
+|-------|-------------|----------------|
+| handoff-generator-agent | `.claude/agents/handoff-generator-agent/agent.json` | sonnet |
+| output-synthesis-agent | `.claude/agents/output-synthesis-agent/agent.json` | sonnet |
+| validation-agent | `.claude/agents/validation-agent/agent.json` | sonnet |
+
+**Protocol**: For each agent spawn, read its `agent.json`, extract the `model` field, and pass it to the Task tool's `model` parameter. If `"inherit"` or absent, omit the `model` parameter.
+
 ## Related
 
 - `/handoff` - Manual HANDOFF generation

package/template/.claude/hooks/validation-hook.md

@@ -158,6 +158,13 @@ If agent fails or is disabled:
 3. Skip command validation
 4. Return basic pass/fail
 
+## Agent Model Selection
+
+When spawning **validation-agent**:
+1. Read `.claude/agents/validation-agent/agent.json`
+2. Pass the `model` field value to the Task tool's `model` parameter
+3. If `"inherit"` or absent, omit the `model` parameter
+
 ## Related
 
 - `/validate` - Manual validation

package/template/.claude/skills/auto-checkpoint/prompts/CLAUDE.md

@@ -94,12 +94,22 @@ Proceed with rollback?
    - Next steps: {recommendations}
 ```
 
+## Agent Model Selection
+
+When this skill spawns the **checkpoint-manager-agent**:
+1. Read `.claude/agents/checkpoint-manager-agent/agent.json`
+2. Pass the `model` field value to the Task tool's `model` parameter (expected: `haiku`)
+3. If `"inherit"` or absent, omit the `model` parameter
+
+> **STRICT**: checkpoint-manager-agent MUST use `haiku` model. This is a cost-critical background agent.
+
 ## Prohibited Actions
 
 - Execute rollback without user confirmation
 - Skip checkpoint before destructive action
 - Create incomplete checkpoints
 - Omit recovery guide after rollback
+- Spawn checkpoint-manager-agent without passing its designated model (haiku)
 
 ## Priorities