d2-diagram

name	d2-diagram
description	Generate a D2 diagram from a text description
argument-hint	["description"]
allowed-tools	Read, Bash, Write

/d2-diagram

User request: "$ARGUMENTS"

Task

Generate a well-composed D2 diagram from the user's description.

Step 1: Setup

Resolve plugin path and read config:

PLUGIN_DIR=$(find "$HOME/.claude/plugins/cache" -type d -name "d2" -path "*/skills/d2" 2>/dev/null | head -1)
[ -z "$PLUGIN_DIR" ] && PLUGIN_DIR=$(find "$HOME" -maxdepth 8 -type d -name "d2" -path "*/skills/d2" 2>/dev/null | head -1)
bash "$PLUGIN_DIR/scripts/ensure-deps.sh"

Read .claude/d2.json if it exists (theme_id, layout, sketch, output_directory, auto_validate, auto_render). If it does not exist, display a one-time nudge:

First time using the d2 plugin? Run /d2-config to pick a theme. Using defaults for now.

Step 2: Classify

Determine diagram type from the description:

Intent	Type
API calls, request/response, message passing	Sequence
System components, microservices, infrastructure, pipelines, workflows	Architecture
Database tables, schema, foreign keys, entities	ER
Class hierarchy, OOP, interfaces, data models	Class

If ambiguous between 2 types, ask one clarifying question. If clear, proceed.

Step 3: Structural Plan

Before writing any D2, build this plan internally. Apply the policies from $PLUGIN_DIR/SKILL.md.

Determine:

• diagram_type — from Step 2
• abstraction_level — infer from prompt: context, container, component, or deployment
• grouping_criterion — infer or default: layer, domain, ownership, or environment
• direction — from orientation heuristics (right for flows, down for hierarchies)
• layout_engine — from engine selection table (<8 nodes: dagre, >=8: elk)
• nodes — inventory with id (snake_case), label, kind (actor/service/database/queue/cache/gateway/external)
• groups — with label and children node IDs
• edges — with from, to, and optional label
• budget_check — count total nodes, max group size, nesting depth, max fanout against visual budget limits
• split_decision — pass or split_required

Visibility rule: If the budget check passes and there is no ambiguity in level or grouping, proceed directly to Step 4. If split is required OR the abstraction level or grouping is ambiguous, present a summary to the user:

I'm planning to generate:
- Type: {type} at {abstraction_level} level
- Grouping: by {criterion}
- Direction: {direction}
- {N} nodes in {M} groups
- Split: {overview + N detail diagrams | single diagram}

Proceed, or want to adjust?

Step 4: Load Specialist

Read the specialist for the classified type:

• Sequence: $PLUGIN_DIR/specialists/d2-sequence.md
• Architecture: $PLUGIN_DIR/specialists/d2-architecture.md
• ER: $PLUGIN_DIR/specialists/d2-er.md
• Class: $PLUGIN_DIR/specialists/d2-class.md

Use the specialist's compositional patterns and D2 syntax conventions. The structural plan from Step 3 governs the structure — the specialist provides type-specific syntax.

Step 5: Generate D2

Write the diagram following:

1. Structural plan — governs structure (what nodes, what groups, what edges)
2. Specialist patterns — governs D2 syntax (shapes, conventions, type-specific features)
3. Global policies — governs conventions (IDs, labels, direction, engine)

Order in the .d2 file:

1. vars block (theme, engine, sketch from config)
2. direction declaration
3. classes block (if >4 nodes of same type)
4. Node and group declarations
5. Connections

Non-negotiable conventions:

• IDs: snake_case, no emojis, no spaces — api_gw, user_svc, orders_db
• Labels: api_gw: "API Gateway" — emojis allowed in labels only
• Direction: MUST appear right after vars block — direction: right for flows, direction: down for hierarchies. If unsure, use direction: right. Never omit.
• Quote labels containing spaces or special characters.

Step 6: Repair Pass

Before delivering, run the 10-point repair checklist from $PLUGIN_DIR/SKILL.md:

1. No level mixing
2. Consistent grouping criterion
3. Budget compliance (12 top-level, 7 per group, 3 nesting, 4 fanout)
4. Labels <= 24 chars
5. No orphan nodes
6. No single-child groups
7. No excessive fanout (>4 edges out)
8. Self-loops converted to notes (sequences)
9. Direction explicitly set
10. Layout engine appropriate for complexity

Fix any violations silently. Do not ask the user — just fix them.

Step 7: Validate Syntax

d2 validate {output_file}

Fix syntax errors using $PLUGIN_DIR/references/guides/troubleshooting.md.

Step 8: Save and Deliver

mkdir -p {output_directory}

Filename: {type}-{short-description}-{YYYYMMDD}.d2

Render if auto_render=true or user asks:

d2 {output_file} {output_directory}/{basename}.svg

Output:

{d2 code block}

**What this shows:** {1-2 sentences describing the diagram}
**Saved to:** {filename}
**Elements:** {N} nodes, {M} connections
**Layout:** {engine}, direction {direction}

Want to adjust? I can change the detail level, scope, grouping, or type.

If split was required, list all generated files.

Code/Script Flow Requests

If the user asks to "diagram the flow" of a file or script:

1. Read the file and derive the flow from actual control paths
2. Build the structural plan from the code structure
3. Execute as the appropriate specialist