Fluxwing Screen Scaffolder

What this skill does

# Fluxwing Screen Scaffolder

Create complete screen designs using the **uxscii standard** by orchestrating specialized agents.

## Data Location Rules

**READ from (bundled templates - reference only):**
- `{SKILL_ROOT}/../uxscii-component-creator/templates/` - 11 component templates
- `{SKILL_ROOT}/templates/` - 2 screen examples
- `{SKILL_ROOT}/docs/` - Documentation

**INVENTORY sources (check all for available components):**
- `./fluxwing/components/` - User-created components (FIRST PRIORITY)
- `./fluxwing/library/` - Customized template copies
- `{SKILL_ROOT}/../uxscii-component-creator/templates/` - Bundled templates (READ-ONLY)

**WRITE to (project workspace):**
- `./fluxwing/screens/` - Your created screens (via composer agent)

**NEVER write to skill directories - they are read-only!**

**LOAD for copy-on-update logic:**
- `{SKILL_ROOT}/../shared/docs/copy-versioning.md` - Versioning pattern for existing screens

## Your Task

**⚠️ YOU ARE AN ORCHESTRATOR - DO NOT DO THE WORK YOURSELF! ⚠️**

Your role is to **spawn agents** using the Task tool. You coordinate agents, you don't create components directly.

Help the user scaffold a complete screen by orchestrating agents in two phases:
1. **Phase 1 (Parallel)**: Spawn multiple designer agents - one per missing component using multiple Task tool calls in ONE message
2. **Phase 2 (Sequential)**: After all components exist, spawn composer agent

**Concurrency Model**:
- If 6 components are missing → spawn 6 agents in parallel using 6 Task tool calls in ONE message (~6x faster)
- Then wait for all to complete before composing screen

**CRITICAL**: Use the Task tool to spawn agents. Do NOT use TodoWrite and work through tasks yourself. Do NOT create files yourself.

**MULTI-SCREEN SCENARIOS:**

If user requests N screens (N > 1):
- ⚠️ **DO NOT** create TodoWrite list with N screen tasks and work through them
- ⚠️ **DO NOT** use Write/Edit tools to create screen files yourself
- ⚠️ **DO NOT** "help" composer agents by pre-creating any files
- ✅ **DO** spawn N composer agents in parallel (one per screen)
- ✅ **DO** send ONE message with ALL Task calls (parallel execution)
- ✅ **DO** let each composer agent independently create all 3 files (.uxm, .md, .rendered.md)

**Example:** 6 screens = ONE message with 6 Task tool calls → 18 files created by agents

You are an ORCHESTRATOR. Your job is to spawn agents, not do their work.

## Quality Presets

Scaffolder supports different quality levels for speed vs fidelity tradeoffs:

### fast (60-90s)
- Create components (sketch fidelity)
- Compose screen
- Skip enhancement
- Use when: Rapid prototyping, early iteration

**Output:**
- Components: sketch fidelity (.uxm only initially, .md by composer)
- Screen: .rendered.md with basic quality
- Time: ~60-90s for 6 components

### balanced (90-150s)
- Create components (sketch fidelity)
- Compose screen
- Enhance to basic fidelity
- Use when: Quick iteration with decent quality

**Output:**
- Components: basic fidelity (.uxm + improved .md)
- Screen: .rendered.md with good quality
- Time: ~90-150s for 6 components

### detailed (180-240s) **[DEFAULT]**
- Create components (sketch fidelity)
- Compose screen
- Enhance to detailed fidelity (hover + focus states)
- Use when: Production-ready screens, demos

**Output:**
- Components: detailed fidelity (.uxm + polished .md + states)
- Screen: .rendered.md with high quality
- Time: ~180-240s for 6 components

### production (300-400s)
- Create components (sketch fidelity)
- Compose screen
- Enhance to production fidelity (all states + full a11y)
- Use when: Final polish, publication

**Output:**
- Components: production fidelity (complete)
- Screen: .rendered.md with publication quality
- Time: ~300-400s for 6 components

**Default: detailed** (best balance of quality and speed)

## Workflow

### Step 1: Understand the Screen

Ask about the screen they want to create:

**Screen details:**
- **Screen name and purpose**: login, dashboard, profile, settings, checkout, etc.
- **Required components**: forms, navigation, cards, modals, lists, etc.
- **Layout structure**: vertical, horizontal, grid, sidebar+main, etc.

**Quality preset** (optional):
- **fast** - Quick prototype (60-90s)
- **balanced** - Good quality (90-150s)
- **detailed** - High quality (180-240s) [DEFAULT]
- **production** - Publication ready (300-400s)

If user doesn't specify, use **detailed** preset.

**Detect multi-screen requests:**

If the user's request indicates multiple screens, detect by:
- **Plural language**: "screens", "pages", "all of them"
- **Multiple file references**: Glob results showing multiple screenshots or files
- **Explicit numbers**: "5 screens", "all these", "create pages for..."

**When multiple screens detected**, confirm with the user:

```
I see you want to create [N] screens:
- [screen-name-1]
- [screen-name-2]
- [screen-name-3]
- ...

I'll create these in parallel using one composer agent per screen.
Each screen will get all 3 files (.uxm, .md, .rendered.md).

Quality preset: [preset] (default: detailed)
Estimated time: ~[X-Y] seconds

Proceed? [Yes/No]
```

**Purpose:**
- Sets clear expectations upfront
- Emphasizes .rendered.md is included for ALL screens
- Provides time estimate
- Prevents surprises

After confirmation, use **Path B workflow** (see below).

### Step 2: Component Inventory

Check what components are available **in this order**:

1. **User-created**: `./fluxwing/components/` (FIRST PRIORITY)
2. **Library**: `./fluxwing/library/` (customized templates)
3. **Bundled examples**: `{SKILL_ROOT}/../uxscii-component-creator/templates/` (READ-ONLY)

List what exists vs what needs to be created.

```typescript
// Example inventory check
const userComponents = glob('./fluxwing/components/*.uxm');
const libraryComponents = glob('./fluxwing/library/*.uxm');
const bundledComponents = glob('{SKILL_ROOT}/../uxscii-component-creator/templates/*.uxm');

const available = [...userComponents, ...libraryComponents, ...bundledComponents];
const missing = requiredComponents.filter(c => !available.includes(c));
```

### Step 2.5: Pre-Scaffolding Validation (Check for Existing Screen)

**IMPORTANT**: Before creating any screen, check if it already exists to prevent data loss.

1. **Convert screen name to kebab-case ID**:
   ```
   "Login Screen" → "login-screen"
   "User Dashboard" → "user-dashboard"
   ```

2. **Check if screen exists**:
   ```bash
   # Check for existing screen
   test -f ./fluxwing/screens/{screen-id}.uxm
   ```

3. **If screen EXISTS**:

   **Inform user and offer choices**:
   ```
   Screen '{screen-id}' already exists (version {current-version}).

   Options:
   (a) Create new version (copy-on-update: {screen-id}-v{N+1})
   (b) Create with different name
   (c) Cancel operation

   What would you like to do?
   ```

   **Handle user response**:

   - **Choice (a) - Create new version**:
     1. Load copy-versioning logic from `{SKILL_ROOT}/../shared/docs/copy-versioning.md`
     2. Read existing `{screen-id}.uxm`
     3. Find highest version (check for `{screen-id}-v2`, `-v3`, etc.)
     4. Calculate next version: `v{N+1}`
     5. Pass to composer agent with versioning parameters:
        - `baseScreenId`: Original ID (e.g., "login-screen")
        - `newScreenId`: Versioned ID (e.g., "login-screen-v2")
        - `baseOnExisting`: true
        - `sourceVersion`: Highest existing version
     6. Composer creates THREE files:
        - `{screen-id}-v{N+1}.uxm`
        - `{screen-id}-v{N+1}.md`
        - `{screen-id}-v{N+1}.rendered.md`
     7. Metadata: Increment minor version (1.0.0 → 1.1.0), update modified, preserve created

   - **Choice (b) - Different name**:
     1. Ask: "What would you like to name this screen?"
     2. Wait for user response
     3. Use new name for screen ID
     4. Proceed with normal scaffolding

   - **Choice (c) - Cancel**:
     1. Do not create any files
     2. Inform user: "Operation cancelled. No files were created."