excalidraw · diff
git:20260427.85307e1 to git:20260812.afc9950
69 added, 183 removed. Audit A to A.
---
name: excalidraw
- description: "Work with .excalidraw/.excalidraw.json diagrams and architecture flowcharts; delegate JSON-heavy Excalidraw operations to avoid context exhaustion."
+ description: Work with .excalidraw and .excalidraw.json diagrams, including reading, explaining, comparing, creating, and editing them. Use context-isolated native agents for JSON-heavy operations when available, with a bounded sequential fallback when delegation is unavailable.
---
- # Excalidraw Subagent Delegation
-
- ## Overview
-
- **Core principle:** Main agents NEVER read Excalidraw files directly. Always delegate to subagents to isolate context consumption.
-
- Excalidraw files are JSON with high token cost but low information density. Single files range from 4k-22k tokens (largest can exceed read tool limits). Reading multiple diagrams quickly exhausts context budget (7 files = 67k tokens = 33% of budget).
-
- ## The Problem
-
- Excalidraw JSON structure:
- - Each shape has 20+ properties (x, y, width, height, strokeColor, seed, version, etc.)
- - Most properties are visual metadata (positioning, styling, roughness)
- - Actual content: text labels and element relationships (<10% of file)
- - **Signal-to-noise ratio is extremely low**
-
- Example: 14-element diagram = 596 lines, 16K, ~4k tokens. 79-element diagram = 2,916 lines, 88K, ~22k tokens (exceeds read limit).
-
- ## 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 (smallest is 4k tokens - still significant)
- - "Quick checks" (checking component names still loads full JSON)
- - Single file operations (isolation prevents context pollution)
- - Modifications (don't need full format understanding in main context)
-
- ## Delegation Pattern
-
- ### Main Agent Responsibilities
+ # Excalidraw Context-Isolated Operations
- **NEVER:**
- - ❌ Use Read tool on *.excalidraw files
- - ❌ Parse Excalidraw JSON in main context
- - ❌ Load multiple diagrams for comparison
- - ❌ Inspect file to "understand the format"
+ Excalidraw JSON has high token cost and low semantic density. Keep raw element metadata out of the
+ main conversation when possible, but do not make delegation a prerequisite for completing the task.
- **ALWAYS:**
- - ✅ Delegate ALL Excalidraw operations to subagents
- - ✅ Provide clear task description to subagent
- - ✅ Request text-only summaries (not raw JSON)
- - ✅ Keep diagram analysis isolated from main work
+ ## Role Contract
- ### Subagent Task Templates
+ Choose the role by side effect, not by a vendor-specific tool name.
- #### Read/Understand Operation
- ```
- Task: Extract and explain the components in [file.excalidraw.json]
+ | Operation | Semantic role | Contract |
+ |-----------|---------------|----------|
+ | Read, explain, compare | Read-only explorer | Read target diagrams; return only labels, relationships, and evidence. Do not write files. |
+ | Create, modify | General writer | Own only the designated output files; preserve unrelated elements; validate written JSON; report changed paths and checks. |
- Approach:
- 1. Read the Excalidraw JSON
- 2. Extract only text elements (ignore positioning/styling)
- 3. Identify relationships between components
- 4. Summarize architecture/flow
+ Use the current CLI's built-in explorer or general worker that satisfies the contract. Do not require a
+ custom agent name or assume a particular `Task`/spawn argument schema. The main context owns scope,
+ acceptance criteria, final verification, and the user-facing explanation.
- Return:
- - List of components/services with descriptions
- - Connection/dependency relationships
- - Key insights about the architecture
- - DO NOT return raw JSON or verbose element details
- ```
+ If native delegation is unavailable or fails, perform the same operations sequentially in the main
+ context using the bounded fallback below. Never refuse an Excalidraw task solely because subagents are absent.
- #### Modify Operation
- ```
- Task: Add [component] to [file.excalidraw.json], connected to [existing-component]
+ ## Routing
- Approach:
- 1. Read file to identify existing elements
- 2. Find [existing-component] and its position
- 3. Create new element JSON for [component]
- 4. Add arrow elements for connections
- 5. Write updated file
+ 1. Determine whether the request is read-only or writes a diagram.
+ 2. Prefer native delegation when the file is large, multiple diagrams are involved, or the main context is already crowded.
+ 3. Give the selected role exact input paths, allowed output paths, and the required return format.
+ 4. Verify the result in the main context without importing raw JSON into the final response.
- Return:
- - Confirmation of changes made
- - Position of new element
- - IDs of created elements
- ```
+ ## Delegated Task Templates
- #### Create Operation
- ```
- Task: Create new Excalidraw diagram showing [description]
+ ### Read or Explain
- Approach:
- 1. Design layout for [number] components
- 2. Create rectangle elements with text labels
- 3. Add arrows showing relationships
- 4. Use consistent styling (colors, fonts)
- 5. Write to [file.excalidraw.json]
+ ```text
+ Role: read-only explorer
+ Task: Explain [file.excalidraw.json].
+ Extract text labels and relationships. Ignore visual metadata unless it changes meaning.
Return:
- - Confirmation of file created
- - Summary of components included
- - File location
+ - components or steps
+ - connections and direction
+ - important visual grouping
+ - evidence by element label or id when useful
+ Do not modify files or return raw JSON.
```
- #### Compare Operation
- ```
- Task: Compare architecture approaches in [file1] vs [file2]
+ ### Compare
- Approach:
- 1. Read both files
- 2. Extract text labels from each
- 3. Identify structural differences
- 4. Compare component relationships
+ ```text
+ Role: read-only explorer
+ Task: Compare [file1] and [file2].
- Return:
- - Key differences in architecture
- - Components unique to each approach
- - Relationship/flow differences
- - DO NOT return full element details from both files
+ Return semantic differences in components, flow, grouping, and missing or added relationships.
+ Do not modify files or reproduce full element objects.
```
- ## Common Rationalizations (STOP and Delegate Instead)
-
- | Excuse | Reality | What to Do |
- |--------|---------|------------|
- | "Direct reading is most efficient" | Consumes 4k-22k tokens unnecessarily | Delegate to subagent |
- | "It's token-efficient to read directly" | Baseline tests showed 9-45% budget used | Always delegate |
- | "This is optimal for one-time analysis" | "One-time" still pollutes main context | Subagent isolation |
- | "The JSON is straightforward" | Simplicity ≠ token efficiency | Delegate anyway |
- | "I need to understand the format" | Format understanding not needed in main agent | Subagent handles format |
- | "Within reasonable bounds" (18k tokens) | "Reasonable" is subjective rationalization | Hard rule: delegate |
- | "Just a quick check of components" | "Quick check" still loads full JSON | Extract text via subagent |
- | "File is small (16K)" | 4k tokens is NOT small | Size threshold doesn't matter |
-
- ## Red Flags - STOP and Delegate
-
- Catch yourself about to:
- - Use Read tool on .excalidraw file
- - "Quickly check" what components exist
- - "Understand the structure" before modifying
- - Load file to "see what's there"
- - Compare multiple diagrams side-by-side
- - Parse JSON to "extract just the text"
-
- **All of these mean: Use Task tool with subagent instead.**
-
- ## Quick Reference
-
- | Operation | Main Agent Action | Subagent Returns |
- |-----------|-------------------|------------------|
- | **Understand diagram** | Delegate with "Extract and explain" template | Component list + relationships |
- | **Modify diagram** | Delegate with "Add [X] connected to [Y]" template | Confirmation + changes made |
- | **Create diagram** | Delegate with "Create showing [description]" template | File location + summary |
- | **Compare diagrams** | Delegate with "Compare [A] vs [B]" template | Key differences (not raw JSON) |
-
- ## Token Analysis (Why This Matters)
-
- Real data from baseline testing:
-
- | Scenario | Without Delegation | With Delegation | Savings |
- |----------|-------------------|-----------------|---------|
- | Single large file | 22k tokens (45% budget) | ~500 tokens (subagent summary) | 98% |
- | Two-file comparison | 18k tokens (9% budget) | ~800 tokens (diff summary) | 96% |
- | Modification task | 14k tokens (7% budget) | ~300 tokens (confirmation) | 98% |
-
- **Context pollution impact:**
- - Reading all 7 project diagrams: 67k tokens (33% of 200k budget)
- - With delegation: ~2k tokens (isolated in subagents)
- - **Savings: 97% context budget preserved**
+ ### Modify
- ## Implementation Example
+ ```text
+ Role: general writer
+ Task: Apply [requested change] to [file.excalidraw.json].
+ Allowed writes: [exact target path]
- **❌ BAD (Direct Read):**
- ```
- User: "What architecture is shown in detailed-architecture.excalidraw.json?"
- Agent: Let me read that file... [reads 22k tokens into main context]
+ Preserve unrelated elements and style conventions. Validate that the result parses as JSON.
+ Return changed paths, a concise change summary, created or updated element ids, and validation results.
```
- **✅ GOOD (Subagent Delegation):**
- ```
- User: "What architecture is shown in detailed-architecture.excalidraw.json?"
- Agent: I'll use a subagent to extract the architecture details.
+ ### Create
- [Dispatches Task tool with general-purpose subagent]
- Task: Extract and explain components in .ryanquinn3/ticketing/detailed-architecture.excalidraw.json
+ ```text
+ Role: general writer
+ Task: Create [output.excalidraw.json] showing [description].
+ Allowed writes: [exact output path]
- [Receives ~500 token summary with component list and relationships]
- [Responds to user with architecture explanation, main context preserved]
+ Use clear labels, readable grouping, and explicit arrows. Validate the completed JSON.
+ Return the output path, component summary, and validation results.
```
- ## Why "Straightforward JSON" Doesn't Matter
-
- Agents often rationalize: "The format is simple, I can just read it."
+ ## Bounded Sequential Fallback
- **The problem isn't complexity - it's verbosity:**
- - Simple structure with 20+ properties per element
- - Repetitive metadata (seed, version, nonce, roughness)
- - Positioning data (x, y, width, height) not semantically useful
- - Visual styling (strokeColor, opacity, fillStyle) irrelevant to content
+ When no native agent can be delegated:
- **Token cost comes from volume, not complexity.**
+ 1. Inspect file size without printing file contents.
+ 2. Process one diagram at a time.
+ 3. For reading, parse JSON and emit only text labels, element ids, types, bindings, and minimal coordinates needed to infer relationships. Bound or page the extracted output.
+ 4. For comparison, build a compact semantic summary for each file, discard raw payloads, then compare the summaries.
+ 5. For creation or modification, write only the requested target, parse it again, and inspect the focused diff before reporting completion.
+ 6. If a file exceeds a tool read limit, use an available JSON parser or a temporary local extraction command rather than loading the raw document into the conversation.
- Even "straightforward" JSON consumes 4k-22k tokens because:
- - 79 elements × ~280 tokens/element = 22k tokens
- - Most tokens are metadata noise
- - Only text labels and relationships matter (~10% of content)
+ The fallback is sequential to prevent multiple verbose JSON documents from occupying the main context at once.
- ## The Iron Law
+ ## Verification
- **Main agents NEVER read Excalidraw files. No exceptions.**
+ For every write operation:
- Not for:
- - "Quick checks"
- - "Small files"
- - "Understanding format"
- - "One-time analysis"
- - "Optimal efficiency"
+ - Confirm the output parses as JSON.
+ - Confirm the top-level Excalidraw structure expected by the existing file or project is preserved.
+ - Inspect the focused diff for accidental deletion or unrelated style churn.
+ - Confirm every requested label and relationship exists.
+ - Report the exact output path and validation performed.
- **Always delegate. Isolation is free via subagents.**
+ For read-only operations, return semantic content rather than raw JSON. Visual metadata matters only
+ when the question concerns layout, grouping, color, or position.