How to Integrate Diagram Design with CI/CD Pipelines: A Complete Automation Guide

Install the Diagram Design skill in your CI environment, generate source diagrams as build artifacts, and export production-ready visuals using built-in verification gates.

The Diagram Design skill—distributed via the cathrynlavery/diagram-design repository—transforms raw diagram sources into editorial-grade HTML, SVG, and PNG assets. Because it lives in a standard Git repository, you can pull it into any CI/CD pipeline just like any other dependency. This guide walks through the exact integration steps using the project's own CI implementation as the reference architecture.

CI/CD Integration Architecture

The Diagram Design skill follows a five-phase pipeline pattern that mirrors software build workflows:

• Install the skill into the CI environment
• Generate diagram sources from .drawio, .mmd, or JSON files
• Redraw using the skill's extraction scripts to produce structured HTML
• Export final artifacts via /export-diagram with format-specific flags
• Verify using the repository's gate scripts to enforce contracts and accessibility

Each phase maps to specific files in the cathrynlavery/diagram-design source tree.

Phase 1: Installing Diagram Design in CI

The skill installs into any supported agent (Claude Code, Codex, or Pi). In CI, you have two options:

Option A: Direct install via Pi CLI

pi install https://github.com/cathrynlavery/diagram-design

Option B: Symlink the skill directory

git clone https://github.com/cathrynlavery/diagram-design.git /tmp/diagram-design
pi install /tmp/diagram-design

The repository's README.md documents both approaches. For containerized CI environments, Option B ensures reproducible builds by pinning to a specific commit.

Phase 2: Generating Source Diagrams

Diagram Design consumes three source formats. Commit these alongside your codebase:

Format	File Extension	Import Command
draw.io	.drawio	/import-drawio
Mermaid	.mmd	/import-mermaid
Raw JSON	.json	Direct template binding

The import commands are documented in commands/import-drawio.md and commands/import-mermaid.md. Both support flags for detail level and sizing:

• --detail=simplified|balanced|comprehensive
• --size=slide-16x9|doc-wide|social-square

Phase 3: Redrawing with Extraction Scripts

Behind the import commands, the skill runs Python extraction scripts to parse source files into an internal representation, then binds them to HTML templates.

Key implementation files:

• skills/diagram-design/scripts/drawio_extract.py — Parses draw.io XML into structured data
• skills/diagram-design/scripts/mermaid_extract.py — Translates Mermaid AST to the skill's IR

These scripts produce template*.html files that serve as the editorial-grade intermediate format.

Phase 4: Exporting Production Artifacts

The /export-diagram command (documented in commands/export-diagram.md) renders final assets:

# SVG export (headless, fast)

pi -c "export-diagram assets/diagram.html --svg-only"

# PNG export (requires Playwright/Chromium)

pi -c "export-diagram assets/diagram.html --png-only --scale=3"

Critical CI requirement: PNG export depends on Playwright. Install it before running exports:

pip install playwright
playwright install chromium

The --scale parameter controls resolution—use 2 for standard displays, 3 for high-DPI or print.

Phase 5: Running Verification Gates

The repository ships purpose-built verification scripts that enforce diagram quality contracts. Run these in CI to prevent regressions:

Script	Purpose	Source File
verify-drawio-import.py	Validates draw.io import correctness and schema compliance	scripts/verify-drawio-import.py
verify-mermaid-import.py	Validates Mermaid import and AST transformation	scripts/verify-mermaid-import.py
verify-docs-sync.py	Ensures documentation, examples, and skill references remain synchronized	scripts/verify-docs-sync.py

These scripts exit non-zero on failure, making them ideal CI gates.

Complete GitHub Actions Example

The repository's own .github/workflows/ci.yml demonstrates production-grade integration. Adapt this pattern for your pipeline:

name: Diagram CI

on: [push, pull_request]

jobs:
  build-diagrams:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Setup Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      
      - name: Install Diagram Design
        run: |
          pip install pi-cli
          pi install https://github.com/cathrynlavery/diagram-design
      
      - name: Install Playwright
        run: |
          pip install playwright
          playwright install chromium
      
      - name: Import Mermaid source
        run: |
          pi -c "import-mermaid docs/architecture.mmd --detail=balanced --size=doc-wide"
      
      - name: Export artifacts
        run: |
          pi -c "export-diagram assets/architecture.html --svg-only"
          pi -c "export-diagram assets/architecture.html --png-only --scale=2"
      
      - name: Run verification gates
        run: |
          python scripts/verify-mermaid-import.py
          python scripts/verify-docs-sync.py

Verification Script Integration

For existing pipelines, add verification as a final stage:

#!/usr/bin/env bash
set -euo pipefail

echo "Running Diagram Design verification suite..."

python scripts/verify-drawio-import.py
python scripts/verify-mermaid-import.py
python scripts/verify-docs-sync.py

echo "All diagram verification gates passed"

The -e flag ensures the build fails on any script exit code, matching the behavior in cathrynlavery/diagram-design's own CI.

Additional CI Automation: Icon Regeneration

When your diagram icon set changes, regenerate assets in CI using:

python scripts/build-icons.py

This script (scripts/build-icons.py) rebuilds the icon collection used by diagram templates. Run it when icons/ directory contents change to ensure visual consistency.

Summary

Integrating Diagram Design with CI/CD pipelines requires five coordinated steps:

• Install the skill via Pi CLI or filesystem symlink
• Commit .drawio, .mmd, or JSON diagram sources to version control
• Run import commands to generate HTML intermediates using drawio_extract.py or mermaid_extract.py
• Export production artifacts with /export-diagram, installing Playwright for PNG output
• Gate every build with verify-drawio-import.py, verify-mermaid-import.py, and verify-docs-sync.py

The cathrynlavery/diagram-design repository's .github/workflows/ci.yml provides a working reference implementation that validates the entire pipeline on every push.

Frequently Asked Questions

What agents support the Diagram Design skill?

Claude Code, Codex, and Pi all support the skill installation model. The examples in this guide use Pi syntax (pi install, pi -c), but equivalent commands exist for other agents. The skill structure in skills/diagram-design/ follows a standard layout that any plugin-capable agent can load.

Why does PNG export require Playwright?

PNG generation renders HTML templates through a headless browser to capture exact styling, fonts, and responsive layout. The /export-diagram command with --png-only invokes Playwright/Chromium to perform this rendering. SVG export does not require Playwright and completes faster, making it preferable for validation stages.

How do I pin to a specific Diagram Design version?

Clone the repository to a specific commit or tag instead of using pi install with a remote URL:

git clone --depth 1 --branch v1.2.3 \
  https://github.com/cathrynlavery/diagram-design.git /tmp/dd-fixed
pi install /tmp/dd-fixed

This guarantees reproducible builds and prevents upstream changes from breaking your pipeline.

What happens if verification scripts fail?

Each verification script (verify-drawio-import.py, verify-mermaid-import.py, verify-docs-sync.py) exits with code 1 and prints diagnostic output when checks fail. Typical failures include: malformed source files, broken internal links, accessibility regressions (missing alt text), or documentation drift. Fix the reported issue and re-run the pipeline.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}