designswarm.md

designswarm.md

name	design-swarm
description	Orchestrate a multi-agent swarm that analyzes a codebase for UI elements, then draws them in Paper.design using the Prowl design system. Use when the user wants to render codebase UI into a Paper canvas — tables, forms, dashboards, pages, or any visual element group. Triggered by phrases like "draw the UI in Paper", "render components in Paper", "design swarm", or "recreate the app in Paper".

Design Swarm — Codebase → Paper.design Orchestrator

You are a swarm orchestrator. Your mission: analyze a codebase to find a category of UI elements, then coordinate parallel agents to draw them in Paper.design matching the Prowl Storybook design system.

Arguments

The user invokes this as /design-swarm <instructions> where <instructions> describes:

• What to find — the type of UI elements to extract (tables, forms, dashboards, pages, etc.)
• Where to find them — a codebase path or repo to analyze
• Where to draw — a Paper.design file URL and target page/section
• Design system reference — defaults to the Prowl Storybook design system in this repo; user may specify otherwise

If any of these are missing, ask the user before proceeding.

---

Phase 1 — Manifest (Code Analyst Agent)

Spawn a single Code Analyst Agent to produce a structured JSON manifest.

Agent prompt template

Analyze <codebase path> and produce a JSON manifest of every <element type> found.

For each element, capture:

• id: unique slug (e.g., dashboard-overview-table)
• route: file path or route where it appears
• componentName: React component name
• group: logical grouping (e.g., "dashboard", "settings", "pricing")
• columns / fields / sections: structural details (schema depends on element type)
• variants: responsive or conditional variants (desktop, mobile, empty state, loading)
• interactivity: sorting, pagination, filters, row actions, expand/collapse, drag, etc.
• designTokens: colors, spacing, typography tokens referenced
• dependencies: other components this element composes

Output format: { "elementType": "<type>", "elements": [...], "groups": { "<name>": ["<id>", ...] }, "tokenSummary": {...} }

What you do with the manifest

• Count elements. This determines parallelism.
• Identify groups. Each group becomes one Section Agent's workload.
• If a group has > 6 elements, split it into sub-groups of ~4.

---

Phase 2 — Design System Lookup

Before spawning drawing agents, load the design system reference:

1. Invoke the prowl-storybook skill (or call list-all-documentation / get-documentation on the PROWL-DESIGN-SYSTEM MCP) to get the prop API, variants, and tokens for any components the manifest references (Table, Badge, Tag, Button, etc.).
2. Produce a Style Brief — a compact cheat sheet for Section Agents containing:
   • Color tokens and CSS custom properties to use
   • Typography scale (font sizes, weights, line heights)
   • Spacing scale
   • Border radii and shadows
   • Component-specific notes (e.g., "Table uses --table-header-bg for header background")

This brief is included in every Section Agent's prompt so they draw consistently without needing to re-query the design system.

---

Phase 3 — Canvas Setup & Placement

Before spawning Section Agents:

1. Call get_basic_info on the Paper file to understand the current canvas state.
2. Call get_tree_summary on the target page to see existing content.
3. For each group, call find_empty_space_on_canvas or calculate non-overlapping coordinates.
4. Pre-allocate artboard positions: record { groupId, x, y, width, height } for each.
5. Optionally create_artboard for each group upfront, or let Section Agents create them.

Critical rule: No two agents may edit overlapping node trees. Pre-allocation prevents collisions.

---

Phase 4 — Section Agents (Parallel Drawing)

Spawn one Section Agent per group. Run up to 8 in parallel (scale down to 3-4 if context is getting large).

Agent prompt template

You are a Section Agent drawing <element type> for the group: .

Paper file: <url> Your assigned area: artboard at (x: <x>, y: <y>, w: <w>, h: <h>) — or create an artboard named <group name> at these coordinates.

Elements to draw (from manifest):

<filtered manifest slice for this group>

Style Brief:

<style brief from Phase 2>

Workflow:

1. Read the Paper MCP guide: get_guide({ topic: "paper-mcp-instructions" })
2. Call get_basic_info to orient yourself on the canvas
3. For each element in your manifest slice: a. Build the HTML using the style brief's tokens and the component patterns b. Call write_html to render it into your assigned artboard c. Call get_screenshot to verify it looks correct d. If misaligned or wrong, call update_styles / set_text_content to fix
4. When all elements are drawn and verified, call finish_working_on_nodes
5. Report back: list of element IDs completed, any issues encountered

Rules:

• Stay within your assigned coordinates. Do not create nodes outside your area.
• Use design tokens (CSS custom properties), not hardcoded hex values.
• Match the Prowl design system — refer to the style brief for exact values.
• Take a screenshot after each major element to catch layout issues early.

Spawning strategy

Manifest size	Parallel agents	Notes
1–4 elements	1–2 agents	Small job, minimal parallelism
5–12 elements	3–6 agents	One agent per group
13+ elements	Up to 8 agents	Split large groups; cap at 8

Use the Agent tool with run_in_background: true for all Section Agents so they execute concurrently.

---

Phase 5 — Monitoring & Progress

While Section Agents run:

• Track completions as agents return results
• Output a progress update after each agent completes:

  Progress: X/Y elements drawn | Agents: Z active | Groups done: [list]
  

• If an agent fails, apply the error recovery rules (see below)

---

Phase 6 — Polish & Visual QA

After all Section Agents complete, spawn a single QA Agent:

Review the Paper canvas at <url>.

Checklist:

1. Call get_tree_summary to see all nodes created by the swarm
2. Call get_screenshot on each artboard / section to visually inspect
3. Check for:
   • Consistent spacing between elements
   • Correct typography hierarchy
   • Token usage (no hardcoded colors)
   • Alignment within and across artboards
   • Missing elements (compare against manifest)
   • Overlapping or clipped content
4. Fix minor issues directly via update_styles / set_text_content
5. Flag major issues for the user
6. Call finish_working_on_nodes when done
7. Report: summary of fixes applied, any flagged issues, final screenshot of each section

---

Error Recovery

These rules apply to any agent in the swarm:

Condition	Action
Agent timeout or MCP error	Re-spawn with the same prompt + latest canvas state. Retry up to 3 times.
Agent returns partial results	Spawn a new agent for the remaining elements only.
3 consecutive failures on same task	Pause the swarm. Report to user with error details + screenshots. Wait for manual instruction.
Node collision detected	Immediately stop the conflicting agent. Re-assign with corrected coordinates.

---

Concurrency Safety

• Lock protocol: Every agent that writes to the canvas must call start_working_on_nodes (or the Paper equivalent) before its first write, and finish_working_on_nodes when done.
• No overlapping trees: Agents are assigned non-overlapping regions. If an agent needs to reference another agent's work, it reads via get_screenshot — never by editing shared nodes.
• Sequential fallback: If the design tool doesn't support concurrent edits well, downgrade to 2 agents at a time.

---

Final Output

When the swarm completes, report to the user:

1. Summary table: element name, group, status (drawn / skipped / failed), artboard ID
2. Link to the Paper canvas
3. Screenshots of each completed section (inline via Read tool if available)
4. Issues log: anything the QA agent flagged or couldn't auto-fix
5. Manifest diff: any elements in the codebase that were intentionally skipped and why

---

Customization Points

This skill is generic. The user controls specificity via their /design-swarm arguments:

What the user says	What changes
"draw all the tables"	Element type = tables; manifest captures columns, sorting, etc.
"recreate the dashboard pages"	Element type = pages; manifest captures layout, widgets, routes
"render the form components"	Element type = forms; manifest captures fields, validation, submit actions
"draw everything"	Full UI audit; manifest covers all visual elements; more groups, more agents

The Phase 1 Code Analyst adapts its extraction logic based on the element type. The Phase 4 Section Agents adapt their HTML generation based on what they're drawing.