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.

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

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