/auto-diagram

name: auto-diagram
description: Analyze inspected source and generate a scoped architecture overview. Use when the user asks to "diagram this repo", "visualize the architecture", "auto diagram", or requests a codebase overview without specifying components. Do NOT use when the user provides a specific description, sample diagram, or component list — use the excalidraw skill instead.

Auto-Diagram: Codebase Overview

Read the requested source scope and draw its supported components and connections. State analysis limits and unknowns. For changes to an existing saved `.excalidraw` file, load the installed `scoped-edit` skill first; its file workflow does not need the live MCP canvas.

Prerequisite Check

Before starting analysis, verify the Excalidraw MCP server is available:

mcp__excalidraw__read_diagram_guide()

If the tool is unavailable, inspect the client configuration and report the concrete missing capability. For an installed toolkit, use its recorded absolute CLI path to run `doctor`; if the configured owned canvas is stopped and the user requested a live diagram, run `start` and recheck. Use the configured URL from the result. If installation is missing, point to the README's local archive setup; a registry `npx` invocation may fetch an older feature set. Source analysis can continue while live rendering is unavailable, but report that no rendered diagram was produced.

---

Context Budget

To prevent context window blowout on large codebases, follow these hard limits:

| Operation | Limit | |-----------|-------| | Grep results per pattern | 20 matches (use head_limit) | | Files read per component | 5 files | | Tool calls in Phase 2 | 15 | | Tool calls in Phase 3 | 10 |

If limits are exceeded, proceed with partial results and note gaps to the user.

---

Analysis Pipeline

Phase 1: Project Detection

Run these file checks to identify the project type and tech stack:

1. **Read root files** -- check for `package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `pom.xml`, `Gemfile`, `composer.json`, `mix.exs`, `Makefile`, `Dockerfile`, `docker-compose.yml`, `*.tf` 2. **Scan directory structure** -- `ls` the root and first-level subdirectories to identify the layout pattern 3. **Detect project type:**

• **Monorepo**: `workspaces` in package.json, `lerna.json`, `pnpm-workspace.yaml`, multiple `go.mod` files, `packages/` or `apps/` directories
• **Microservices**: Multiple `Dockerfile` files, `docker-compose.yml` with 3+ services
• **Standard app**: Single service with standard directory structure

4. **Check for frameworks** -- look for markers:

• React/Next.js: `next.config.*`, `src/app/`, `src/pages/`
• Express/Fastify/Hono: `routes/`, `controllers/`, `middleware/`
• Nest.js: `@nestjs/core` in package.json
• Django/Flask/FastAPI: `manage.py`, `wsgi.py`, `app.py`, `main.py` with `uvicorn`
• Spring: `src/main/java/`, `application.properties`
• Go services: `cmd/`, `internal/`, `pkg/`
• Rust: `src/main.rs`, `src/lib.rs`
• Rails: `Gemfile` + `config/routes.rb`
• Laravel: `artisan`, `app/Http/`
• Phoenix/Elixir: `mix.exs` + `lib/*_web/`

**Output:** A mental model of the project type, primary language, and framework.

**Monorepo handling:** If monorepo detected, scope analysis to the top-level package structure first. Show one box per package/app. Offer to drill into specific packages on request.

Phase 2: Component Discovery

Based on project type, identify architectural components. **Max 15 tool calls.**

For Web Applications:

1. **Frontend** -- Glob `*.tsx`, `*.jsx`, `*.vue`, `*.svelte` in `src/`, `app/`, `pages/` (head_limit: 20) 2. **API routes** -- Grep route definitions: `router\.(get|post|put|delete)`, `@(Get|Post|Put|Delete)`, `@app\.route`, `HandleFunc` (head_limit: 20) 3. **Database** -- Look for `prisma/schema.prisma`, `models.py`, `*.entity.ts`, `migrations/`, `@Entity`, `db.Model` (head_limit: 20) 4. **External services** -- Grep for SDK/HTTP client imports: `axios`, `fetch(`, `requests\.`, `http\.NewRequest` (head_limit: 20) 5. **Message queues** -- Grep: `amqp`, `kafka`, `bull`, `celery`, `SQS`, `pubsub` (head_limit: 10) 6. **Cache** -- Grep: `redis`, `memcached`, `cache` in imports (head_limit: 10) 7. **Auth** -- Grep: `passport`, `jwt`, `oauth`, `@Auth`, `middleware.*auth` (head_limit: 10)

For Infrastructure:

1. **Services** -- Read `docker-compose.yml` service definitions 2. **Cloud resources** -- Grep `*.tf` for `resource "` blocks (head_limit: 20) 3. **K8s** -- Glob `**/k8s/*.yaml` or `**/manifests/*.yaml` (head_limit: 20)

For Libraries/CLIs:

1. **Entry points** -- Find `main`, `bin`, `exports` in package config 2. **Modules** -- Map public API surface (read index/main files) 3. **Dependencies** -- Read dependency list from package config

**Output:** A list of 4-12 components with names, types, and key file locations.

Phase 3: Connection Mapping

Determine how components connect. **Max 10 tool calls.** Focus on entry points and their immediate dependencies -- don't trace every import.

1. **Read entry point files** -- For each major component, read the main/index file (max 5 files total). Look for:

• Import statements that reference OTHER components (not third-party packages)
• Function calls to other services (HTTP clients, RPC calls, queue publishers)
• Database connection/query code
• Event emitters/listeners

2. **Map connection types** -- Categorize each connection:

• `REST/HTTP` -- fetch/axios/requests calls
• `SQL/ORM` -- database queries
• `gRPC/RPC` -- inter-service calls
• `Event/Queue` -- pub/sub, message queues
• `Import` -- direct module import (same codebase)

3. **Build edge list** -- Record each directed edge with a source path and line range or symbol. Label its basis as an import, an observed call site, or an assumption. An SDK import does not establish a payment call; a connection string does not establish a successful datab