Diagram

Diagram

Generate draw.io diagrams from codebase exploration. Spawns a orc:drawio agent that explores the code, builds the diagram, and exports to PNG. Reuses existing diagrams when available.

• [ ] Step 1: Parse request + check prerequisites
• [ ] Step 2: Check existing diagrams
• [ ] Step 3: Gather context
• [ ] Step 4: Generate diagram
• [ ] Step 5: Verify and iterate
• [ ] Step 6: Present result

You receive a diagram request, check for existing assets, gather codebase context, then spawn a orc:drawio agent to build the diagram. You are the orchestrator — the agent does the drawing, you handle verification and iteration.

Hard rules:

• Always check for existing diagrams before generating new ones
• Existing hand-crafted diagrams are preferred over generated ones
• Always export to PNG and verify visually with Read tool
• Keep .drawio source alongside .png exports in docs/diagrams/
• Never delete existing diagrams without user confirmation

Avoid:

• Regenerating diagrams that already exist and are correct
• Generating diagrams without reading code first — every shape must reflect real components
• Skipping visual verification — always Read the exported PNG
• Creating diagrams with ASCII art when draw.io is available
• Relying on draw.io auto-routing — programmatic diagrams need explicit anchor points and waypoints

Input

$ARGUMENTS is the diagram request describing what to visualize.

If provided: parse into $TYPE and $FOCUS.

If not provided: AskUserQuestion:

• "What should I diagram?"
• Options: "Architecture overview" / "Execution flow" / "Package dependencies" / Other

Diagram types:

| Type keyword | Canvas | Template | |-------------|--------|----------| | architecture | 1600x1000 | 3-tier layered (apps/packages/infra) | | flow, lifecycle, sequence | 1200x1800 | Swim lane flowchart | | dependency, packages | 1200x800 | Package DAG | | seams, boundaries | 1400x800 | Interface boundary diagram |

Derive $SLUG from the focus (kebab-case, max 30 chars).

Process

Step 1: Parse Request + Check Prerequisites

which cli-anything-drawio 2>/dev/null || echo "NOT FOUND — run /orc:install and select 'draw.io diagrams'"

If not found, tell the user to run /orc:install and select "draw.io diagrams", then stop.

mkdir -p docs/diagrams

Step 2: Check Existing Diagrams

ls docs/diagrams/*.drawio 2>/dev/null

If an existing .drawio file covers the requested topic:

AskUserQuestion:

• "Existing diagram {name}.drawio covers this topic. What should we do?"
• Options: "Update existing" / "Create new" / "Just re-export PNGs"

If "Just re-export PNGs":

• Export all pages to PNG and stop
• Use drawio --export --format png --page-index N --output docs/diagrams/{name}-pageN.png

If "Update existing":

• Pass the existing .drawio path to the agent for modification

Step 3: Gather Context

Read available codebase context to inform the diagram:

ls .claude/context/*.md 2>/dev/null

If .claude/context/ exists (from /orc:map), read relevant files:

| Diagram Type | Read These Context Files | |-------------|-------------------------| | architecture | ARCHITECTURE.md, STRUCTURE.md, STACK.md | | flow/lifecycle | FLOWS.md, ARCHITECTURE.md | | dependency | CODEMAP.md, STRUCTURE.md | | seams | BOUNDARIES.md, TYPES.md |

If no context files exist, the orc:drawio agent will explore the codebase directly.

Step 4: Generate Diagram

Spawn the orc:drawio agent:

Agent(
  subagent_type="orc:drawio",
  description="Generate {$TYPE} diagram",
  prompt="
    Generate a {$TYPE} diagram for this codebase.

    Focus: {$FOCUS}
    Output: docs/diagrams/{$SLUG}.drawio + docs/diagrams/{$SLUG}.png

    {context from Step 3, if available}

    {if updating existing: 'Modify existing diagram at: docs/diagrams/{existing}.drawio'}

    Requirements:
    - Explore the codebase to verify all components shown are real
    - Use the standard color palette (blue=apps, green=packages, amber=storage, purple=blockchain)
    - CRITICAL: Set explicit exitX/exitY and entryX/entryY on every edge — never rely on auto-routing
    - Before adding edges, check for intermediate boxes that would be crossed by the natural path
    - Add waypoints to route edges around obstacles (30px minimum clearance from unrelated shapes)
    - Export to PNG and verify visually — fix any overlaps before finishing
    - Return the paths of created files
  "
)

Step 5: Verify and Iterate

After the agent completes:

1. Check the output files exist:

ls docs/diagrams/$SLUG.*

1. Read the exported PNG to verify quality:

Read docs/diagrams/$SLUG.png

1. Check for common issues:

• Labels overlapping boxes or edges
• Edges crossing through unrelated shapes (trace each edge's path against all shape bounding rects)
• Edges without explicit exit/entry anchors (grep the drawio XML for edges missing exitX/exitY)
• Parallel edges sharing the same visual path (need offset anchor points)
• Edges entering containers they shouldn't cross
• Text too small or clipped
• Missing connections between components

1. If issues found: fix directly using cli-anything-drawio commands, re-export, re-verify.

Step 6: Present Result

Show the diagram to the user (Read the PNG). Report:

• .drawio source path
• .png export path
• Number of pages (if multi-page)
• Components visualized

File Ownership

| File | Access | Purpose | |------|--------|---------| | docs/diagrams/*.drawio | Write | Diagram source files | | docs/diagrams/*.png | Write | Exported diagram images | | Source files | Read only | Codebase exploration |

Completion Criteria

• [ ] Prerequisites checked (cli-anything-drawio available)
• [ ] Existing diagrams checked before generating
• [ ] Context gathered from .claude/context/ if available
• [ ] Diagram generated with real codebase components (no placeholders)
• [ ] PNG exported and visually verified (no overlaps)
• [ ] Both .drawio source and .png export present in docs/diagrams/

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: qGolem
• Source: qGolem/orc
• License: MIT

Install and usage instructions live in the source repository linked above.