Excalidraw Subagent Delegation

Iron Law

Main agents NEVER read Excalidraw files. No exceptions. Always delegate via Task tool.
Excalidraw JSON has extreme verbosity (4k-22k tokens per file) with <10% signal. Subagents isolate this cost.

When to Use

Trigger on ANY of these:

• File path contains .excalidraw or .excalidraw.json
• User requests: "explain/update/create diagram", "show architecture", "visualize flow"
• User mentions: "flowchart", "architecture diagram", "Excalidraw file"
• Architecture/design documentation tasks involving visual artifacts

Use delegation even for "small" files (4k tokens minimum), "quick checks", single file ops, modifications.

Critical Format Rules

Subagents must know these before writing/modifying Excalidraw JSON:

1. Labels need TWO elements - label property broken in raw JSON. Shape needs boundElements: [{type:"text", id:"x-text"}] + separate text element with containerId: "x"
2. NEVER use diamond shapes - Arrow connections broken in raw JSON. Use styled rectangles instead (coral for orchestrators, orange+dashed for decisions)
3. Elbow arrows need THREE properties - roughness: 0, roundness: null, elbowed: true for 90-degree corners
4. Arrow x,y = source shape edge, not center - Bottom: (x + width/2, y + height), Right: (x + width, y + height/2), etc.
5. Arrow width/height = bounding box of points - width = max(abs(p[0])), height = max(abs(p[1]))
6. Stagger multiple arrows from same edge - Spread at 20%-80% across edge width

Default color palette (most common):

Type	BG	Stroke
Frontend	#a5d8ff	#1971c2
Backend/API	#d0bfff	#7048e8
Database	#b2f2bb	#2f9e44
Storage	#ffec99	#f08c00
External	#ffc9c9	#e03131
Orchestration	#ffa8a8	#c92a2a

Reference Files

Subagents should read these before working on Excalidraw files:

File	Purpose	Used By
references/json-format.md	Element types, required properties, label binding, grouping	Create, Modify
references/arrows.md	Routing algorithm, edge formulas, patterns, staggering, bindings	Create, Modify
references/colors.md	Default + AWS/Azure/GCP/K8s palettes	Create
references/examples.md	Full 3-tier JSON example, layout patterns, complexity guidelines	Create
references/validation.md	Pre-flight algorithm, checklists, common bugs + fixes	Create, Modify

Delegation Pattern

Main Agent NEVER / ALWAYS

NEVER: Read .excalidraw files, parse Excalidraw JSON, load multiple diagrams, inspect files to "understand the format"

ALWAYS: Delegate via Task tool, provide clear task description, request text-only summaries (not raw JSON), keep diagram analysis isolated

Subagent Templates

Create Operation

Task: Create new Excalidraw diagram showing [description]

Context: Excalidraw JSON requires TWO elements per label (shape + text), elbow arrows need roughness:0/roundness:null/elbowed:true, NEVER use diamonds. Arrow x,y starts at shape edge not center.

Steps:
1. Read references/json-format.md, references/arrows.md, references/colors.md, references/examples.md
2. Analyze codebase to identify components and relationships
3. Plan layout (vertical flow most common: rows at y=100,230,380,530,680)
4. Generate elements with proper label bindings and arrow routing
5. Validate against references/validation.md before writing
6. Write to [file.excalidraw.json]

Return: File location + component summary

Modify Operation

Task: Add/update [component] in [file.excalidraw.json]

Context: Excalidraw JSON requires TWO elements per label (shape + text), elbow arrows need roughness:0/roundness:null/elbowed:true, NEVER use diamonds. Arrow x,y starts at shape edge not center.

Steps:
1. Read references/json-format.md and references/arrows.md
2. Read existing file, identify elements and positions
3. Make changes preserving existing element structure
4. Validate against references/validation.md before writing
5. Write updated file

Return: Confirmation + changes made

Read/Understand Operation

Task: Extract and explain the components in [file.excalidraw.json]

Steps:
1. Read the Excalidraw JSON
2. Extract text elements (ignore positioning/styling)
3. Identify relationships between components
4. Summarize architecture/flow

Return: Component list + relationships. DO NOT return raw JSON.

Compare Operation

Task: Compare architecture in [file1] vs [file2]

Steps:
1. Read both files
2. Extract text labels from each
3. Identify structural differences
4. Compare component relationships

Return: Key differences only. DO NOT return raw element details.

Anti-Rationalization

Thought	Reality
"Direct reading is most efficient"	Consumes 4k-22k tokens, use subagent
"It's a small file / quick check"	Minimum 4k tokens, still pollutes context
"I need to understand the format"	Format knowledge belongs in subagent, not main context
"The JSON is straightforward"	Problem is verbosity not complexity: 79 elements x ~280 tokens = 22k
"Just parsing text labels"	Still loads full JSON to extract 10% signal
"Within reasonable bounds"	"Reasonable" is rationalization. Hard rule: delegate

All of these mean: use Task tool with subagent instead.

Token Analysis

Scenario	Without Delegation	With Delegation	Savings
Single large file	22k tokens (45% budget)	~500 tokens (summary)	98%
Two-file comparison	18k tokens	~800 tokens (diff)	96%
Modification task	14k tokens	~300 tokens (confirmation)	98%
All 7 project diagrams	67k tokens (33% budget)	~2k tokens	97%