Diagram

---
description: Generate draw.io diagrams from codebase analysis
argument-hint: <type+focus> — e.g. "architecture", "vote submission flow", "package dependencies"
allowed-tools:
  - Bash(cli-anything-drawio:*)
  - Bash(drawio:*)
  - Bash(ls:*)
  - Bash(mkdir:*)
  - Bash(which:*)
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Agent
  - AskUserQuestion
model: inherit
context: inherit
hooks: {}
user-invocable: true
---

# 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.

<progress>
- [ ] 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
</progress>

<purpose>
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.
</purpose>

<constraints>
**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
</constraints>

<antipatterns>
**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
</antipatterns>

## 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

```bash
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.

```bash
mkdir -p docs/diagrams
```

### Step 2: Check Existing Diagrams

```bash
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:

```bash
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:
```bash
ls docs/diagrams/$SLUG.*
```

2. Read the exported PNG to verify quality:
```
Read docs/diagrams/$SLUG.png
```

3. 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

4. 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/`