prototype

What this skill does

# Parallel Prototype Orchestration

Build and compare multiple web app prototypes simultaneously using sub-agents. Design first, spawn parallel builders, serve all variants, then iterate or finalize.

## When to Use

- User says "PROTOTYPE", "WEBAPP", or wants to explore multiple approaches
- Need to compare different design directions
- Want rapid parallel development with live preview
- Orchestra MCP is available for sub-agent spawning

## Overview

This skill orchestrates a multi-prototype workflow:

1. **Propose** n prototype variants (default: 3)
2. **Spawn** executor sub-agents to build each in parallel git worktrees
3. **Serve** all prototypes on different ports with live preview
4. **Select** the winning prototype, iterate, or kill all servers

---

## Phase 1: Design Variants (10-15 min)

Before spawning any agents, design multiple distinct approaches. Each variant should explore a different:

- **Visual style** (minimal vs rich, dark vs light)
- **Interaction pattern** (modals vs inline, tabs vs panels)
- **Architecture approach** (SPA vs multi-page, stateful vs stateless)
- **Feature focus** (speed vs features, simplicity vs power)

### Variant Proposal Template

Present variants to the user in this format:

```
## Prototype Variants

### Variant A: [Name] - [One-liner]
**Focus**: [Primary design goal]
**Visual**: [Style description]
**Interaction**: [How user interacts]
**Trade-off**: [What it optimizes for vs sacrifices]

### Variant B: [Name] - [One-liner]
**Focus**: [Primary design goal]
**Visual**: [Style description]
**Interaction**: [How user interacts]
**Trade-off**: [What it optimizes for vs sacrifices]

### Variant C: [Name] - [One-liner]
**Focus**: [Primary design goal]
**Visual**: [Style description]
**Interaction**: [How user interacts]
**Trade-off**: [What it optimizes for vs sacrifices]

Which variants would you like me to build? (A/B/C/all/suggest more)
```

### Example Variants for a Note-Taking App

```
### Variant A: "Zen" - Distraction-free writing
**Focus**: Minimal UI, maximum focus
**Visual**: White background, single centered column, no sidebar
**Interaction**: Everything via keyboard shortcuts, hidden toolbar
**Trade-off**: Speed over discoverability

### Variant B: "Dashboard" - Power user's command center
**Focus**: Information density, quick navigation
**Visual**: Dark theme, three-column layout, visible sidebar
**Interaction**: Click-driven with command palette (⌘K)
**Trade-off**: Features over simplicity

### Variant C: "Mobile-First" - Touch-optimized responsive
**Focus**: Works great on all devices
**Visual**: Large touch targets, bottom navigation, swipe gestures
**Interaction**: Thumb-friendly actions, pull-to-refresh
**Trade-off**: Mobile experience over desktop power features
```

---

## Phase 2: Spawn Parallel Builders (2-3 min)

Once user approves variants, spawn executor sub-agents in parallel using Orchestra MCP.

### Pre-Spawn Checklist

1. Confirm Orchestra MCP is available
2. Get source path from project config
3. Generate unique session names for each variant

### Spawning Pattern

For each approved variant, call `spawn_subagent` with:

```python
spawn_subagent(
    parent_session_name="main",
    child_session_name="prototype-{variant_letter}",
    source_path="/path/to/project",
    agent_type="executor",
    instructions="""
# Prototype {Variant Letter}: {Variant Name}

## Your Mission
Build a working prototype implementing this specific design direction.

## Design Spec
{Full design specification from Phase 1}

## Tech Stack
- Frontend: React + Vite
- Backend: FastAPI (if needed) or static
- Database: SQLite (if needed)
- Styling: Tailwind CSS or vanilla CSS

## Requirements
1. Must run on port {assigned_port}
2. Create in: src/prototypes/variant-{letter}/
3. Include a launcher script that starts the dev server
4. Implement core features only (no gold plating)
5. Add ⌘S (save) and ⌘/ (help) keyboard shortcuts

## Success Criteria
- App runs on http://localhost:{port}
- Core user flow works end-to-end
- No console errors
- Clean, readable code

## When Done
Message the main session with:
- Confirmation prototype is running
- The URL to access it
- Brief summary of implementation choices
"""
)
```

### Port Assignment

Use this port scheme to avoid conflicts:

| Variant | Frontend Port | Backend Port |
|---------|--------------|--------------|
| A       | 5173         | 8001         |
| B       | 5174         | 8002         |
| C       | 5175         | 8003         |
| D       | 5176         | 8004         |
| E       | 5177         | 8005         |

### Parallel Spawn Example

```python
# Spawn all variants in parallel (single message with multiple tool calls)
spawn_subagent(
    parent_session_name="main",
    child_session_name="prototype-a",
    source_path=source_path,
    instructions="... Variant A spec ..."
)
spawn_subagent(
    parent_session_name="main",
    child_session_name="prototype-b",
    source_path=source_path,
    instructions="... Variant B spec ..."
)
spawn_subagent(
    parent_session_name="main",
    child_session_name="prototype-c",
    source_path=source_path,
    instructions="... Variant C spec ..."
)
```

---

## Phase 3: Monitor & Serve (During Build)

### Tracking Progress

While executors build, periodically check:

1. `.orchestra/messages.jsonl` for status updates
2. Git worktrees at `/Users/wz/.orchestra/subagents/{session-id}/`
3. Port availability for each prototype

### Status Dashboard (Show to User)

```
## Prototype Status

| Variant | Session         | Status      | URL                    |
|---------|-----------------|-------------|------------------------|
| A       | prototype-a     | ⏳ Building | http://localhost:5173  |
| B       | prototype-b     | ✅ Running  | http://localhost:5174  |
| C       | prototype-c     | ⏳ Building | http://localhost:5175  |

Last updated: [timestamp]
```

### Opening Prototypes

When an executor reports completion:

1. Verify the dev server is running on the assigned port
2. Open in browser: `open http://localhost:{port}`
3. Update status dashboard
4. Notify user: "Variant {X} is now live at http://localhost:{port}"

### Bulk Open Command

Once all prototypes are ready:

```bash
# Open all prototypes in browser tabs
open http://localhost:5173 http://localhost:5174 http://localhost:5175
```

---

## Phase 4: Selection & Iteration

### Presenting Options

Once all prototypes are running, ask the user:

```
## All Prototypes Ready!

🅰️ Variant A "Zen" - http://localhost:5173
🅱️ Variant B "Dashboard" - http://localhost:5174
🅲️ Variant C "Mobile-First" - http://localhost:5175

**What would you like to do?**

1. **Select winner** - Choose one to continue developing
2. **Iterate** - Request changes to specific variants
3. **Combine** - Merge features from multiple variants
4. **More variants** - Generate n more prototype ideas
5. **Kill all** - Stop all servers and clean up
```

### User Choice Handling

#### Choice 1: Select Winner

```
User: "I like Variant B"

Action:
1. Kill dev servers for A and C
2. Merge Variant B branch to main (with user approval)
3. Continue development on selected prototype
4. Clean up unused worktrees
```

#### Choice 2: Iterate

```
User: "Can you make Variant A have a sidebar like B?"

Action:
1. Send iteration instructions to prototype-a executor:
   send_message_to_session(
       session_name="prototype-a",
       message="Add a collapsible sidebar similar to Variant B's implementation...",
       source_path=source_path,
       sender_name="main"
   )
2. Wait for completion
3. Refresh browser / notify user
```

#### Choice 3: Combine

```
User: "I want A's minimal editor with B's sidebar and C's mobile responsiveness"

Action:
1. Create new variant specification combining features
2. Spawn new executor: prototype-combined
3. Use existing code as reference
```

#### Choice 4: More Variants

```
User: "Show me 2 more ideas"

Action:
1. Return to Phase 1
2. Generate 2 new distinct variants