D2 Diagram Creator

Three-agent pipeline for high-quality diagram generation:

AskUserQuestion → Agent 1 (Analyzer) → Agent 2 (Generator) → Agent 3 (Validator)

Each agent is a general-purpose subagent with its own focused instructions. You (the main agent) orchestrate the pipeline — ask the user questions, then spawn agents in sequence, passing outputs forward.

Step 1: Ask Requirements

Use AskUserQuestion to ask all questions at once. Do not split into multiple rounds, do not skip any.

First round (always required)

{
  "questions": [
    {
      "question": "How detailed should the diagram be?",
      "header": "Detail Level",
      "options": [
        { "label": "Core Flow", "description": "5-8 nodes" },
        { "label": "Moderate", "description": "10-15 nodes" },
        { "label": "Full Detail", "description": "Include all details and exception branches" }
      ]
    },
    {
      "question": "What is the layout direction of the diagram?",
      "header": "Layout Direction",
      "options": [
        { "label": "Horizontal", "description": "direction: right, left to right" },
        { "label": "Vertical", "description": "direction: down, top to bottom" }
      ]
    },
    {
      "question": "What format to export as?",
      "header": "Export Format",
      "options": [
        { "label": "D2 Code Only", "description": "No image export" },
        { "label": "SVG", "description": "Vector graphics (recommended)" },
        { "label": "PNG", "description": "Bitmap" },
        { "label": "Preview", "description": "ASCII text" }
      ]
    }
  ]
}

Second round (only when SVG/PNG is selected)

{
  "questions": [
    {
      "question": "Which theme to use?",
      "header": "Theme",
      "options": [
        { "label": "Light Theme", "description": "--theme 0, white background (default)" },
        { "label": "Dark Theme", "description": "--theme 200, dark background" }
      ]
    },
    {
      "question": "Enable hand-drawn sketch style?",
      "header": "Sketch",
      "options": [
        { "label": "No", "description": "Normal style (default)" },
        { "label": "Yes", "description": "--sketch, hand-drawn effect" }
      ]
    },
    {
      "question": "Choose layout engine?",
      "header": "Layout Engine",
      "options": [
        { "label": "dagre", "description": "Default, fast and efficient" },
        { "label": "elk", "description": "Complex diagrams, 100+ nodes" },
        { "label": "tala", "description": "Most powerful, SVG only, requires installation" }
      ]
    }
  ]
}

Only provide 2 theme options (Light/Dark). Do not add colorful, terminal, or other themes.

Step 2: Spawn Analyzer Agent

Use the Agent tool to spawn the requirements analyzer. This agent deeply analyzes the user's request and produces a structured JSON document.

• subagent_type: general-purpose
• description: Analyze diagram requirements

The prompt should be:

Read the file at \x3Cskill-base-path>/agents/analyzer.md for your instructions.

Analyze this diagram request:

User request: \x3Cuser's original description>

User preferences:
- Detail level: \x3Canswer>
- Layout direction: \x3Canswer>
- Export format: \x3Canswer>
- Theme: \x3Canswer, or "not selected">
- Sketch: \x3Canswer, or "not selected">
- Layout engine: \x3Canswer, or "not selected">

Return the structured requirements JSON.

Save the returned JSON — you will pass it to the generator agent.

Step 3: Spawn Generator Agent

Use the Agent tool to spawn the D2 code generator.

• subagent_type: general-purpose
• description: Generate D2 diagram code

The prompt should be:

Read the file at \x3Cskill-base-path>/agents/generator.md for your instructions.

Generate D2 code based on these requirements:

\x3Cthe requirements JSON from Step 2>

Read the diagram type guide at:
\x3Cskill-base-path>/references/diagram-types/\x3Cdiagram_type>.md

Save the D2 code to a .d2 file (use a descriptive filename).
Return the file path.

Save the returned file path — you will pass it to the validator agent.

Step 4: Spawn Validator Agent

Use the Agent tool to spawn the validator.

• subagent_type: general-purpose
• description: Validate and export diagram

The prompt should be:

Read the file at \x3Cskill-base-path>/agents/validator.md for your instructions.

Your skill base directory is: \x3Cskill-base-path>
The watermark removal script is at: \x3Cskill-base-path>/scripts/remove_watermark.py

Validate and export:

D2 file: \x3Cpath from Step 3>
Requirements: \x3Cthe requirements JSON>

Export preferences:
- Format: \x3Cexport_format>
- Theme: \x3Ctheme or "default">
- Sketch: \x3Csketch or false>
- Layout engine: \x3Cengine or "dagre">

Fix any issues and export the final diagram.

Report the validator's summary to the user.

Diagram Types Reference

Prohibitions

1. Do not skip requirement questions — always ask first
2. Do not add visual styles unless the user explicitly requests them
3. Do not add a diagram title unless the user explicitly requests one
4. Do not skip any of the three agents — the pipeline must run to completion