# Diagram

> Generate draw.io diagrams from codebase analysis

- **Type:** Skill
- **Install:** `agentstack add skill-qgolem-orc-diagram`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [qGolem](https://agentstack.voostack.com/s/qgolem)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [qGolem](https://github.com/qGolem)
- **Source:** https://github.com/qGolem/orc/tree/main/skills/diagram

## Install

```sh
agentstack add skill-qgolem-orc-diagram
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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

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

## Source & license

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

- **Author:** [qGolem](https://github.com/qGolem)
- **Source:** [qGolem/orc](https://github.com/qGolem/orc)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-qgolem-orc-diagram
- Seller: https://agentstack.voostack.com/s/qgolem
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.