diegomarino/claude-toolshed/d2-architect

/d2-architect

User request: "$ARGUMENTS"

Task

Analyze a codebase or project path and generate a relevant suite of D2 diagrams (typically 3-4 types based on what's found).

Difference from /d2-diagram

• /d2-diagram generates one diagram from a text description
• /d2-architect generates multiple diagrams from actual code/files at a given path

Process

Step 1: Resolve Plugin Path

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)

If still empty, stop: "Plugin not found. Is it installed?"

Step 2: Ensure Dependencies

bash "$PLUGIN_DIR/scripts/ensure-deps.sh"

If .claude/d2.json does not exist, display a one-time nudge before continuing:

First time using the d2 plugin? Run /d2-config to pick a theme and output settings. Using defaults for now (theme 0 / Neutral, ./diagrams).

Step 3: Read Config

If .claude/d2.json exists, read output_directory, theme_id, layout, sketch, auto_validate, auto_render.

Resolve output path:

• If output_directory is "same" AND an input path is known: OUTPUT_DIR={input_directory}
• Otherwise: OUTPUT_DIR={output_directory or ./diagrams}

Step 4: Resolve Target Path

• If no argument, use current directory.
• If argument is a file, analyze that single file.
• If argument is a directory, explore it.

Step 5: Explore Codebase

find {path} \( -name "*.py" -o -name "*.ts" -o -name "*.js" -o -name "*.rb" -o -name "*.go" \) | grep -v node_modules | grep -v dist | head -50
find {path} \( -name "*.sql" -o -name "*.prisma" -o -name "*schema*" \) | grep -v node_modules | head -20
find {path} \( -name "routes*" -o -name "router*" -o -name "urls*" -o -name "endpoints*" \) | grep -v node_modules | head -20
find {path} \( -name "docker-compose*" -o -name "Dockerfile*" -o -name "k8s" -o -name "*.yaml" \) | grep -v node_modules | head -10

Read key files to understand the domain (models, routes, services, main entry point).

Step 6: Infer Diagram Types

Based on what's found:

Select 2-4 most relevant types. Do not generate all 4 unless the codebase clearly warrants it.

Step 6b: Apply Composition Policies

Read the global policies from $PLUGIN_DIR/SKILL.md. For each diagram to generate:

1. Determine abstraction level (context/container/component/deployment)
2. Choose grouping criterion (layer/domain/ownership/environment)
3. Check estimated node count against visual budget (max 12 top-level, 7 per group)
4. Select layout engine (dagre for <8 nodes, elk for >=8)
5. Set direction explicitly (right for flows, down for hierarchies)

If a diagram would exceed the visual budget, split into overview + detail.

Step 7: Generate Each Diagram

For each selected type, load the specialist:

cat "$PLUGIN_DIR/specialists/d2-{type}.md"

Follow the specialist's compositional patterns using the actual code found in Step 5. The structural decisions from Step 6b (abstraction, grouping, direction, engine) govern the output. After generating, run the repair pass from $PLUGIN_DIR/SKILL.md before validating.

Step 8: Validate

For each generated diagram:

d2 validate {output_file}

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

Step 9: Render (if auto_render=true or user requests)

d2 {file} {OUTPUT_DIR}/{basename}.svg

Step 10: Report

Analyzed: {path}
Generated {N} diagrams:
 
  ✅ {OUTPUT_DIR}/er-{name}-{timestamp}.d2       (ER — 5 tables, 4 relationships)
  ✅ {OUTPUT_DIR}/sequence-{name}-{timestamp}.d2  (Sequence — 4 actors, 8 messages)
  ✅ {OUTPUT_DIR}/architecture-{name}-{timestamp}.d2 (Architecture — 6 components)
 
Validation: all passed

Step 11: Offer design document (opt-in)

If 3 or more diagrams were generated:

Generated {N} diagrams — want me to assemble them into a system design document?
I'll embed each diagram in the relevant section.

If fewer than 3 diagrams: skip silently.

Common Mistakes

• Generating all 4 diagram types when only 2 are warranted — select only types with clear evidence in the code.
• Empty PLUGIN_DIR — if both find commands return nothing, stop and report the install message.
• Including node_modules or dist — always exclude with -not -path "*/node_modules/*" and -not -path "*/dist/*".
• Inferring from file names only — read actual function bodies, model fields, and route handlers.