gen-diagram

Generate d2 Diagram Command

Produce a .d2 source file (and a rendered .svg when the d2 binary is installed) that captures a software or infrastructure architecture. Default engine is d2 (https://d2lang.com/), default icons come from https://icons.terrastruct.com/.

Why This Command Exists

Problem: Architecture diagrams in design docs and READMEs are usually either missing, drawn in a closed-source tool that no one can edit, or pasted as PNG screenshots that drift from reality. Running through d2 syntax and the icon catalog by hand takes 10-20 minutes per diagram.

Solution: One command that:

• Synthesizes a .d2 source file from a free-text description or repo analysis
• Embeds vendor icons from icons.terrastruct.com only when the URL is known to resolve
• Renders to SVG automatically if d2 is installed
• Stores both files in docs/diagrams/ for diff-able, PR-reviewable diagrams

Content Generation Rules

CRITICAL: When generating any content (.d2 source, file headers, descriptions, or any other output):

• NEVER add Claude Code attribution or co-authorship
• NEVER include phrases like "Generated by Claude", "Created with Claude Code", or similar
• NEVER add "Co-Authored-By: Claude" in commit messages or documentation
• All generated content should appear as if written by a human developer
• Focus on technical accuracy and clear, readable d2 source

Process (6 Phases)

Phase 1: Prerequisites Validation

1. Validate Git repository:

   git rev-parse --git-dir
   

   • If fails: Exit with error "Not a git repository. Run 'git init' first."

2. Detect d2 and the mise toolchain (non-blocking, and no writes in this phase):

   command -v d2
   command -v mise
   test -f mise.toml && grep -qE '^[[:space:]]*"?d2"?[[:space:]]*=' mise.toml
   

   • d2 on PATH: store d2Installed = true. Capture version: d2 --version.
   • d2 absent: store d2Installed = false (will warn later, but proceed — the .d2 source is produced either way).
   • mise on PATH: store miseAvailable = true.
   • mise.toml already pins d2: store d2Pinned = true.