canvas-generate: AI-Orchestrated Canvas Generation

The flagship command. Takes a high-level description and produces a complete, populated canvas.

Read ../canvas/references/template-catalog.md for archetype descriptions. Read ../canvas/references/media-guide.md for image/SVG/GIF integration. Read ../canvas/references/mermaid-patterns.md for native diagram options. Read ../canvas/references/performance-guide.md for node limits.

---

Pipeline

User: "/canvas generate [description]"
          │
          ▼
   1. Analyze description
          │
          ▼
   2. Detect archetype
          │
          ▼
   3. Plan content (what nodes, what media)
          │
          ▼
   4. Generate in parallel:
      ┌─────────────┬────────────────┐
      │ Composer     │ Media agent    │
      │ (text nodes) │ (images/SVGs)  │
      └──────┬──────┴───────┬────────┘
             │              │
             ▼              ▼
   5. Instantiate template with content
          │
          ▼
   6. Apply layout algorithm
          │
          ▼
   7. Validate + write

---

Workflow

Step 1: Analyze Description

Parse the user's description to extract:

• Topic: What is the canvas about?
• Purpose: What will it be used for? (presenting, planning, exploring, showcasing)
• Content hints: Any specific items, data, or requirements mentioned?
• Visual requests: Does the user want images, diagrams, or text-only?

Step 2: Detect Archetype

Map the description to one of the 12 template archetypes:

Keywords in description	Archetype
"presentation", "slides", "deck", "present"	presentation
"flowchart", "process", "workflow", "steps"	flowchart
"mind map", "brainstorm", "ideas", "explore"	mind-map
"gallery", "images", "photos", "showcase"	gallery
"dashboard", "metrics", "KPIs", "status"	dashboard
"storyboard", "scenes", "video", "script"	storyboard
"knowledge graph", "entities", "relationships"	knowledge-graph
"mood board", "inspiration", "aesthetic", "vibe"	mood-board
"timeline", "events", "history", "milestones"	timeline
"comparison", "vs", "compare", "options"	comparison
"kanban", "tasks", "board", "sprint"	kanban
"brief", "kickoff", "project plan", "objectives"	project-brief

If the archetype is ambiguous, ask the user to clarify.

Step 3: Plan Content

Based on the archetype and description, plan:

• Node count: How many nodes does this canvas need? (respect <120 target)
• Text content: What text goes in each node?
• Media assets: What images, SVGs, or GIFs are needed?
• Mermaid diagrams: What data visualizations should be embedded as Mermaid?
• Edges: What connections exist between nodes?

Step 4: Generate Content and Media

For simple canvases (text-only, <10 nodes): Generate content inline — no agents needed.

For complex canvases (media required or >10 nodes): Dispatch agents in parallel:

a. Dispatch canvas-composer agent with:

• Archetype name
• Topic description
• Number of text nodes needed
• Any source files for context

b. Dispatch canvas-media agent with (if media requested):

• List of images/SVGs/GIFs needed
• Prompt descriptions for each
• Target dimensions

c. Wait for both agents to complete. Collect their JSON output.

Step 5: Instantiate Template

Use the template engine to create the base canvas:

python3 scripts/canvas_template.py [archetype] [output_path] \
  --param title="[topic]" --param [archetype_param]=[count]

Then update each node's content with the composer agent's output using the Edit tool.

If the media agent generated images:

• Add each as a file node inside the appropriate zone/slide
• Use the auto-positioning algorithm or manual placement inside groups

Step 6: Apply Layout

If the template's built-in layout is insufficient (e.g., mind-map needs radial, knowledge-graph needs force), apply the appropriate algorithm:

python3 scripts/canvas_layout.py [output_path] [algorithm]

Step 7: Quality Gate (MANDATORY)

This is the most critical step. A canvas that passes validation but has placeholder text is a FAILURE.

1. Content check: Read every text node in the canvas. Search for these forbidden strings:

   • "Describe this" — replace with real content
   • "YYYY-MM-DD" — replace with real dates
   • "Content goes here" — replace with real content
   • "Value: 0" — replace with realistic values
   • "Define this entity" — replace with real definition
   • "What happened" — replace with real event If ANY are found, edit the canvas to replace them before proceeding.

2. Layout check: Verify the correct layout was applied:

   • Mind-map → radial layout (nodes should expand from center, not in a grid)
   • Knowledge-graph → force layout (nodes should be organically spread, not in a grid)
   • Flowchart → dagre layout (hierarchical top-down or left-right flow) If the layout looks wrong, run python3 scripts/canvas_layout.py <path> <algorithm>.

3. Spacing check: Run validation to catch overlaps:

   python3 scripts/canvas_validate.py [output_path]

   Must return valid: true with 0 errors and 0 overlap warnings.

4. Visual scan: Is this canvas something you'd be proud to show? Would a user open it and immediately understand it? If not, improve it.

Only after ALL four checks pass, report success.

---

Examples

Example 1: Text-Only Dashboard

User: /canvas generate "project dashboard for mobile app launch"

1. Archetype: dashboard
2. Plan: 4 metric cards (Downloads, DAU, Crashes, Rating), 1 status zone
3. Generate content inline (simple, text-only)
4. Instantiate: python3 scripts/canvas_template.py dashboard output.canvas --param title="Mobile App Launch" --param metric_count=4
5. Edit metric nodes with specific content
6. No layout change needed (grid is fine)
7. Validate and report

Example 2: Mood Board with AI Images

User: /canvas generate "mood board for a cyberpunk game"

1. Archetype: mood-board
2. Plan: 8 image slots, title card with aesthetic description
3. Dispatch canvas-composer: write title card content (mood, colors, style)
4. Dispatch canvas-media: generate 8 images via /banana:
   • "neon cityscape, cyberpunk, rain, reflections"
   • "cyberpunk character portrait, augmented, glowing eyes"
   • (6 more themed prompts)
5. Instantiate mood-board template
6. Replace placeholder text nodes with generated image file nodes
7. Validate and report

Example 3: Presentation from Topic

User: /canvas generate "presentation about our Q3 results"

1. Archetype: presentation
2. Plan: 6 slides (title, overview, revenue, growth, challenges, next steps)
3. Dispatch canvas-composer: write 6 slides of content
4. Optionally dispatch canvas-media: 1-2 hero images
5. Instantiate presentation template with slide_count=6
6. Edit each slide's text with composer output
7. Validate and report

---

Fallback Behavior

Scenario	Action
User description too vague	Ask: "What type of canvas? (presentation, mood board, dashboard, etc.)"
Archetype detected but uncertain	Confirm: "I'll create a [archetype] canvas. Sound right?"
Media skills not available	Build text-only canvas, suggest manual image addition
Canvas would exceed 120 nodes	Warn and suggest splitting into sub-canvases
Template instantiation fails	Fall back to manual canvas construction with the orchestrator