architecture-overview-diagram

name	architecture-overview-diagram
description	Generate a README-level architecture overview DOT diagram for a repository through code-first investigation, iterative design, and antagonistic review. Use when the user says "create an architecture diagram", "make a README diagram", "top-level overview diagram", or wants a single diagram that gives a non-technical reader the "I get it" understanding of a system. Produces a .dot source, .svg, and .png — reviewed to PASS quality. Also surfaces doc/code discrepancies and optionally generates detail diagrams.
user-invocable	true
allowed-tools	["read_file","write_file","edit_file","bash","glob","grep","delegate","dot_graph","load_skill"]
model_role	reasoning

Architecture Overview Diagram

Generate a single, README-level architecture overview diagram for a repository. The diagram should give a non-technical reader an instant "I get it" understanding of what the system does, how it works, and what value it provides — from the diagram alone, without reading any docs.

The process is code-first: read the actual source code, not documentation, to determine what the system really does. Then iterate the diagram design with user feedback and antagonistic review until it passes quality gates.

This skill commonly surfaces doc/code discrepancies, dead code, and stale artifacts as a side effect of the investigation. Those findings should be presented to the user for cleanup alongside the diagram work.

Inputs

• <repo_path>: Path to the repository to diagram.
• <reference_diagram>: (Optional) Path to a gold-standard diagram to use as a style/structure reference. If this repo is part of an ecosystem with sibling repos that already have overview diagrams, use those as implicit references for visual consistency — even if the user doesn't explicitly provide one.

Steps

1. Deep Code Investigation

Launch parallel agents to read the actual source code and build a ground-truth understanding of the system architecture. Do NOT read documentation first — code is the source of truth.

Execution: Delegate to foundation:explorer (2-3 parallel instances with different scopes) and python-dev:code-intel or rust-dev:code-intel for semantic call-graph tracing.

Investigation targets:

• Entry points (CLI, API, main)
• Core data flows (what goes in, what comes out)
• Component boundaries (what are the major subsystems)
• External dependencies (what does it call out to)
• User-facing interaction patterns (how do humans interact)
• Safety/enforcement mechanisms
• Plugin/extension points
• Awareness boundaries (what should this repo know about, what shouldn't it?)

Success criteria: A complete mental model of what the system does, its components, data flows, external dependencies, and user-facing behaviors — all derived from source code with file:line citations.

2. Catalog Existing Documentation

In parallel with Step 1, catalog all existing docs and diagrams in the repo.

Execution: Delegate to foundation:explorer (separate instance, context_depth="none").

Find:

• All .dot, .svg, .png diagram files
• All architecture/design docs
• README claims about system structure
• Any discrepancies between docs and code (note these for later)
• Stale artifacts, dead code, duplicate files, awareness boundary violations

Artifacts: Compile a cleanup backlog of doc/code discrepancies, stale references, and other issues found. Present this to the user alongside the diagram work — the investigation commonly surfaces significant cleanup needs.

Success criteria: Complete inventory of existing documentation with accuracy assessment against code findings from Step 1, plus a cleanup backlog for the user to review.

3. Analyze Reference Diagram (if provided or available)

If a gold-standard reference diagram was provided, OR if sibling repos in the same ecosystem already have overview diagrams, analyze their design principles to guide our diagram's style and structure.

Execution: Delegate to design-intelligence:design-system-architect with the reference diagram.

Extract:

• Node count, edge density, cluster strategy
• Color system and shape vocabulary
• Information hierarchy (how it guides the eye)
• Text density per node and edge
• What makes it work as an "I get it" overview
• Concrete design principles to follow

Rules: When working within an ecosystem of repos, visual consistency matters. If sibling repos use specific color palettes, shape vocabularies, or cluster patterns, match them — the diagrams should look like a family. If the system has an underlying DSL with defined shape semantics (e.g. a pipeline DSL where hexagon=human gate), the overview diagrams should use those same shapes — don't introduce conflicting meanings at different documentation layers.

Success criteria: A numbered list of design principles extracted from the reference, ready to apply to our diagram.

4. Design the Value Story

Before creating any DOT, define what story the diagram tells. This is the most important step — a diagram without a clear story is just boxes and arrows.

Answer these questions:

• What is the one-sentence value proposition? ("You provide X, the system does Y, you get Z")
• What are the INPUTS from the user's perspective?
• What is the PROCESSING at the right abstraction level?
• What are the OUTPUTS the user cares about?
• What external dependencies need to be shown?
• What should be EXCLUDED (too detailed for this level)?
• What is the distinctive feature that makes this system different?

Present the story to the user for feedback before proceeding.

Rules:

• Do NOT name specific plugin implementations — show the plugin concept generically
• Do NOT name specific frontend applications — show the interface concept generically
• DO name real ecosystem dependencies that all users will encounter
• DO show safety/enforcement mechanisms if they exist
• DO show bidirectional interactions (human-in-the-loop, feedback channels)
• Respect awareness boundaries — the repo should only reference its direct deps

Success criteria: User confirms the story and scope before diagram creation.

Human checkpoint: Present the story framing and get explicit approval.

5. Create Initial DOT Diagram

Generate the DOT source following these hard constraints:

• ≤20 nodes (target 12-17 for overview)
• Edge-to-node ratio ≤ 1.5:1
• Maximum cluster nesting depth = 2
• Pure DAG (top-to-bottom flow, feedback loops use constraint=false)
• ≤3 node shapes plus special shapes for gates/safety (note=data, rounded-box=process, folder=external, hexagon=human-gate, octagon=safety). If the system has an underlying DSL with its own shape vocabulary (e.g. the attractor pipeline DSL), align overview shapes with that vocabulary — don't introduce shape meanings in the overview that conflict with the DSL layer.
• ≤6 semantic fill colors, all pastel (~90% lightness)
• Cluster border color matches node fill family
• Node labels: ≤3 lines, name what it IS not what it DOES
• Edge labels: verb phrases, ≤3 words
• Dashed = external/swappable/planned, solid = core/implemented
• All edges labeled with verb phrases

Execution: Delegate to dot-graph:dot-author with the complete design specification from Step 4 and the design principles from Step 3.

Render to .svg and .png alongside the .dot source.

Success criteria: A valid, rendered DOT diagram that follows all constraints.

6. Present to User for Feedback

Show the rendered diagram to the user. Ask for specific feedback:

• Does the story come through?
• Is anything missing that's important?
• Is anything shown that's too detailed?
• Do the labels make sense?

Iterate Steps 5-6 as needed based on feedback. Expect 2-4 iterations.

Success criteria: User says the direction is right.

Human checkpoint: User reviews and provides feedback each iteration.

7. Hunt for Missing Mechanisms

Before the antagonistic review, proactively search for important mechanisms that the diagram does NOT yet show. Send fresh agents to read the code with the specific question: "what user-facing capabilities exist that aren't in this diagram?"

Execution: Delegate to foundation:explorer (fresh, context_depth="none") and resolve:resolve-expert or domain-appropriate expert agents. Give them the current diagram's node list and ask them to find what's missing.

Rate each finding: CRITICAL (users need to know), IMPORTANT (valuable but detail-level), or IMPLEMENTATION (skip for overview).

Present the findings to the user for decision on what to add.

Success criteria: User confirms which missing mechanisms to add (if any).

Human checkpoint: Present missing mechanism candidates and get approval.

8. Antagonistic Review

Launch parallel antagonistic reviews from three different perspectives:

8a. Fresh code audit — Delegate to foundation:explorer with context_depth="none" and model_role="critique". Give it the diagram's claims and ask it to verify each against the actual source code. For each claim: ACCURATE, INACCURATE, or PARTIALLY ACCURATE with file:line evidence.

8b. Diagram quality review — Delegate to dot-graph:diagram-reviewer. Get a structured PASS/WARN/FAIL verdict covering syntax, structure, color consistency, edge labels, readability, and comparison to reference.

8c. Design critique — Delegate to design-intelligence:design-system-architect with model_role="critique". Ask it to compare against the reference diagram and find problems in story clarity, balance, missing/excess information, edge label quality, and feedback loop clarity.

Success criteria: All three reviews complete. All factual claims verified as ACCURATE. Diagram reviewer returns PASS or WARN (no FAIL). Design critique identifies only minor issues.

9. Incorporate Review Findings

Fix any issues found in Step 8:

• Factual inaccuracies → fix the diagram to match code reality
• Missing mechanisms identified by code audit → add if README-level important
• Quality warnings → fix per reviewer guidance
• Design issues → fix per critique guidance

Re-render the diagram after fixes.

Success criteria: All review findings addressed. Diagram re-rendered.

10. Final Review

Run one more dot-graph:diagram-reviewer pass on the final version to confirm PASS (or acceptable WARN).

Success criteria: Diagram reviewer returns PASS or WARN with no blocking issues.

11. Place and Commit

1. Copy the .dot, .svg, and .png to the target repo's docs/ directory
2. Add an ![Architecture](docs/<name>.svg) reference to the repo's README.md (near the top, after the title and description, before prerequisites)
3. Commit and push

Success criteria: Diagram is committed, pushed, and visible in the repo's README on GitHub.

Human checkpoint: Confirm the placement and commit message before pushing.

12. Detail Diagrams (Optional)

After the overview is placed, assess whether detail-level diagrams would add value. Good candidates are:

• The system's most architecturally distinctive feature
• Core data flows that are non-obvious from the overview
• Plugin/extension lifecycle if the system is extensible
• State machines if the system has a rich lifecycle

Look at sibling repos for patterns — if the backend has 7 detail diagrams covering different angles, the frontend likely benefits from 2-3 covering its distinctive perspectives.

Execution: Delegate to dot-graph:dot-author with specific angle and code-level findings from Step 1. Use the same visual conventions as the overview. Save to docs/diagrams/ subdirectory.

Success criteria: Detail diagrams committed and pushed.

Human checkpoint: Confirm which detail diagrams to create.