diagram— agent skill

You are in AUTONOMOUS MODE. Do NOT ask questions. Analyze the project codebase and generate comprehensive architecture diagrams using Mermaid.

INPUT: $ARGUMENTS

Accepted arguments:

• No arguments: generate all applicable diagram types.
• c4: generate C4 Context and Container diagrams only.
• sequence: generate sequence diagrams for key flows only.
• er: generate ER diagram from database schema only.
• deps or dependency: generate module dependency graph only.
• A specific flow description (e.g., "user login flow"): generate a sequence

diagram for that specific flow.

============================================================ PHASE 1: CODEBASE ANALYSIS ============================================================

Step 1.1 -- Tech Stack and Architecture Detection

Scan config files to determine: project type (web app, API, mobile, CLI, library, monorepo), primary language/framework, database(s), external services (auth, payment, email, storage), message queues, caching layers, and API gateway config.

Step 1.2 -- Service and Module Mapping

For monorepos/microservices: read docker-compose.yml or K8s manifests for service definitions, map inter-service communication, identify external deps per service.

For monoliths: read directory structure to identify modules/domains, trace import statements to map module dependencies, identify layer boundaries.

Step 1.3 -- Database Schema Extraction

Scan for schema definitions in: schema.prisma, .entity.ts (TypeORM/MikroORM), models/.js (Sequelize), models.py (Django), db/schema.rb (Rails), models/.py (SQLAlchemy), schema.ts (Drizzle), migrations/.sql, *.model.ts (Mongoose).

Extract: table/collection names, columns with types, primary/foreign keys, relationships (1:1, 1:N, M:N), indexes, and enums.

Step 1.4 -- Key Flow Identification

Identify the most important flows to diagram:

• Authentication flow (login, signup, token refresh)
• Primary business flow (main use case)
• Data write flow (create/update through layers)
• API request lifecycle (middleware, validation, handler, response)
• Background job flow (if applicable)

For each flow, trace: entry point, middleware, service layer, data access, external calls, and response construction.

============================================================ PHASE 2: DIAGRAM GENERATION ============================================================

Generate Mermaid diagrams. Use C4 syntax for architecture diagrams.

Step 2.1 -- C4 Context Diagram

Show the system in its environment: users/actors, the system boundary, and all external systems it connects to. Use C4Context with Person, System, System_Ext, and Rel elements. Keep it high-level -- no internal details.

Step 2.2 -- C4 Container Diagram

Show major containers within the system boundary: web apps, API servers, databases, caches, workers, message queues. Use C4Container with Container, ContainerDb, ContainerQueue elements. Show relationships with protocols (HTTPS, SQL, AMQP).

Step 2.3 -- Sequence Diagrams

For each key flow, generate a sequenceDiagram showing participants and message flow. Always generate auth flow if auth exists. Generate the primary business flow. Include request/response payloads as notes where helpful.

Step 2.4 -- ER Diagram

Generate from extracted schema using erDiagram syntax. Include all tables with columns (name, type, PK/FK/UK markers) and relationships with cardinality notation (||--o{, }o--o{, etc.).

Step 2.5 -- Module Dependency Graph

Generate a graph TD showing how internal modules depend on each other. Place entry points (routes/controllers) at top, data stores at bottom, external systems on sides. Flag circular dependencies as warnings. Use style directives to color-code layers.

============================================================ PHASE 3: OUTPUT AND ORGANIZATION ============================================================

Create docs/diagrams/ directory if it does not exist.

Write individual files:

• docs/diagrams/c4-context.md -- C4 Context diagram
• docs/diagrams/c4-container.md -- C4 Container diagram
• docs/diagrams/sequence-auth.md -- Auth sequence (if applicable)
• docs/diagrams/sequence-[flow].md -- Business flow sequence
• docs/diagrams/er-diagram.md -- ER diagram (if database exists)
• docs/diagrams/dependency-graph.md -- Module dependency graph

Each file: heading, brief explanation, Mermaid code block, notes on simplifications. Skip diagram types with no data (no ER if no database).

Generate docs/diagrams/README.md index linking all diagrams with descriptions.

============================================================ SELF-HEALING VALIDATION (max 2 iterations) ============================================================

After producing documentation, validate completeness:

1. Verify all required sections are present and non-empty.
2. Verify internal cross-references and links resolve correctly.
3. Verify no placeholder text remains ("{TODO}", "[TBD]", "...", "etc.").
4. Verify code examples are syntactically valid.

IF VALIDATION FAILS:

• Identify which sections are incomplete or contain placeholders
• Re-generate only the deficient sections
• Repeat up to 2 iterations

============================================================ OUTPUT ============================================================

Diagrams Generated

System Profile

• Type: [monolith / microservices / monorepo]
• Services: [count]
• Database Tables: [count]
• External Systems: [count]

Diagrams Created

Observations

• [Circular dependencies detected]
• [Isolated modules with no connections]
• [Missing relationships that could not be determined]

============================================================ SELF-EVOLUTION TELEMETRY ============================================================

After producing output, record execution metadata for the /evolve pipeline.

Check if a project memory directory exists:

• Look for the project path in ~/.claude/projects/
• If found, append to skill-telemetry.md in that memory directory

Entry format:

### /diagram — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}

Only log if the memory directory exists. Skip silently if not found. Keep entries concise — /evolve will parse these for skill improvement signals.

============================================================ DO NOT ============================================================

• Do NOT fabricate components, services, or tables. Only diagram what exists.
• Do NOT include internal implementation details in C4 Context diagrams.
• Do NOT generate diagrams for types with no data (no ER if no database).
• Do NOT use PlantUML -- use Mermaid exclusively for GitHub compatibility.
• Do NOT include sensitive info (credentials, internal URLs, IPs) in diagrams.
• Do NOT overwrite existing diagram files without reading them first.

NEXT STEPS:

After generating diagrams:

• "Run /document to check overall documentation health."
• "Run /adr to create ADRs explaining architectural decisions shown in diagrams."
• "Run /onboarding to include these diagrams in the developer onboarding guide."