/diagram

description: Generate comprehensive infrastructure and architecture diagrams using D2
argument-hint: "[--incremental] [--infrastructure-only] [--architecture-only] [--scope=<path>] [--force]"

/diagram - Generate Infrastructure & Architecture Diagrams

Generate comprehensive infrastructure and architecture diagrams using D2 (terrastruct/d2).

---

Arguments

| Argument | Description | |----------|-------------| | `--incremental` | Only regenerate changed components | | `--infrastructure-only` | Generate only infrastructure diagram | | `--architecture-only` | Generate only architecture diagram | | `--scope=<path>` | Limit analysis to specific directory | | `--force` | Regenerate all, ignore cache |

---

Overview

This command orchestrates multiple specialized agents to analyze a codebase and produce visual diagrams:

**Agents Used:**

• **Scanner** (sonnet) - Fast discovery of IaC and documentation
• **Documenter** (opus) - Deep analysis and documentation
• **Renderer** (sonnet) - D2 diagram generation
• **Verifier** (sonnet) - Quality validation

**Output:**

• `./diagrams/infrastructure.md` - Detailed infrastructure documentation
• `./diagrams/infrastructure-simplified.md` - High-level infrastructure overview
• `./diagrams/architecture.md` - Detailed architecture documentation
• `./diagrams/architecture-simplified.md` - High-level architecture overview
• `./diagrams/*.d2` - D2 source files (4 types)
• `./diagrams/*-light.svg` + `*-dark.svg` - Themed SVG diagrams (8 total)
• Main README.md - Simplified diagrams embedded with "More diagrams" link
• `./diagrams/README.md` - All diagrams (simple + detailed)

---

State Management

The command uses two directories:

**`./diagrams/`** - Committed output and configuration:

./diagrams/
├── README.md                         # Landing page with all diagrams
├── rules.md                          # Project-specific customization (optional)
├── infrastructure.md                 # Detailed infrastructure
├── infrastructure.d2
├── infrastructure-*.svg
├── infrastructure-simplified.md      # High-level infrastructure
├── infrastructure-simplified.d2
├── infrastructure-simplified-*.svg
├── architecture.md                   # Detailed architecture
├── architecture.d2
├── architecture-*.svg
├── architecture-simplified.md        # High-level architecture
├── architecture-simplified.d2
└── architecture-simplified-*.svg

**`.diagram/`** - Ephemeral runtime state (gitignored):

.diagram/
├── state.json          # Progress checkpoints for resume
└── cache/              # Incremental mode cache
    ├── iac-hash.txt
    └── scan-results.json

**Note:** The `.diagram/` folder is automatically added to `.gitignore` if one exists. This folder can be safely deleted at any time - it only enables resume and incremental features.

State File Format

{
  "phase": "documenter",
  "completed": ["scanner"],
  "total": 6,
  "timestamp": "ISO8601",
  "args": {
    "incremental": false,
    "scope": null
  },
  "checkpoints": {
    "scanner": {"timestamp": "...", "result": "success"},
    "documenter": null
  }
}

---

Execution Workflow

Phase 0: Initialization

**IMPORTANT**: Before any work, initialize state tracking and ensure proper gitignore setup.

**STEP 1 - Create directories FIRST (use Bash tool, not Write):**

mkdir -p ./diagrams .diagram/cache

**STEP 2 - Add to .gitignore (use Bash tool):**

if [ -f ".gitignore" ] && ! grep -q "^\.diagram" .gitignore 2>/dev/null; then
  echo -e "\n# Diagram plugin ephemeral state\n.diagram/" >> .gitignore
fi

**STEP 3 - Note on icons:**

Icons are added directly to nodes using the `icon:` property. No need to copy icons.d2 to the project. The `class:` property provides styling (stroke color, shape) while `icon:` provides the visual.

Example:

database: MySQL Config {
  class: mysql
  icon: https://icons.terrastruct.com/dev%2Fmysql.svg
}

See the Technology → Icon URL mapping in Phase 7 for all available icons.

**STEP 4 - Initialize state file (use Bash tool, NOT Write tool):**

echo '{"phase":"initialization","completed":[],"total":11}' > .diagram/state.json

**WHY BASH**: The Write tool will fail if the directory doesn't exist. Always use `mkdir -p` via Bash first, then write files.

**Check for project rules** (OPTIONAL - only if file exists):

# rules.md is OPTIONAL - do NOT error if missing
if [ -f "./diagrams/rules.md" ]; then
  echo "Project rules found - will apply customizations"
  # Read and incorporate rules into subsequent phases
else
  echo "No custom rules (./diagrams/rules.md not found - this is normal)"
fi

**IMPORTANT**: The rules.md file is user-created and optional. Do NOT attempt to read it unless you first confirm it exists with Glob or the bash check above.

---

Phase 1: Discovery (Scanner Agent)

**Model hint**: Use haiku for fast parallel discovery.

**Delegate to Scanner agent** with prompt:

TASK: Rapid codebase scan for infrastructure and architecture artifacts.

NOTE: Existing documentation (docs/, diagrams/, *.md) are collected for REFERENCE ONLY.
They may be outdated. The code (IaC, source files) is the source of truth.

EXECUTE IN PARALLEL (spawn multiple Glob/Grep calls simultaneously):

Batch 1 - Infrastructure-as-Code:
- Glob: **/*.tf, **/*.tfvars
- Glob: **/Pulumi.yaml, **/Pulumi.yml
- Glob: **/*.template.yaml, **/*.template.json, **/cdk.json
- Glob: **/serverless.yml, **/serverless.yaml

Batch 2 - Container/Orchestration:
- Glob: **/Dockerfile*, **/docker-compose*.yml
- Glob: **/*.yaml then Grep for "apiVersion:" (Kubernetes)
- Glob: **/helmfile.yaml, **/Chart.yaml

Batch 3 - Documentation:
- Glob: **/README.md, **/ARCHITECTURE.md, **/INFRASTRUCTURE.md
- Glob: **/docs/**/*.md, **/diagrams/**/*

Batch 4 - Application Structure:
- Glob: **/package.json, **/go.mod, **/Cargo.toml, **/requirements.txt
- Glob: **/main.*, **/index.*, **/app.*

CONSTRAINTS:
- READ-ONLY: Do NOT modify a