amplifier-bundle-dot-graph

Reconciliation as a forcing function — the core thesis of this bundle.

What It Is

One command gives every Amplifier session complete DOT graph capabilities — authoring, validation, rendering, and structural intelligence.

No external dependencies. No API keys. No configuration. Install once, available for all sessions. The --app flag makes it global.

7 Ways DOT Graphs Make Agents Smarter

UC1 — Reconciliation Forcing Function

The headline use case. Drawing a system as a graph forces you to reconcile your mental model against reality.

Hidden dependencies surface. Dead code becomes visible. Undocumented external services appear. The act of diagramming is the audit.

This is the use case that justifies everything else.

UC1 Demo — Reconciliation in Action

BEFORE: What we believed

AFTER: What the graph revealed

UC2 — Dense Context Representation

A DOT graph encodes nodes, edges, attributes, clusters, and labels in a fraction of the tokens a prose description would require.

For an LLM, this is compressed, structured knowledge — orders of magnitude more efficient than natural language for representing system architecture.

One well-structured DOT file replaces pages of documentation.

UC3 — Multi-Scale Navigation

Think Google Maps for architecture. Zoom out to see 5 subsystem clusters. Zoom in to see 22 nodes with full pipeline detail inside a single cluster.

DOT subgraphs provide natural zoom levels. The same system at different scales — no separate diagrams needed.

Cluster → Subgraph → Node → Edge — each level tells a different story.

UC3 Demo — Zoom Out

ZOOM OUT: System at cluster level — 5 subsystems

UC3 Demo — Zoom In

ZOOM IN: Auth subsystem expanded — 22 nodes, full pipeline detail

UC4 — Analysis Substrate

8 analysis operations. Zero LLM cost. Millisecond execution.

• validate — Syntax + structural checks via pydot
• stats — Node count, edge count, density, DAG status, components
• cycles — Find all simple cycles, annotate guilty edges
• unreachable — Dead code / orphaned node detection
• reachability — Blast radius: "if X fails, what breaks?"
• critical_path — Longest dependency chain through a DAG
• diff — Structural diff between two graphs
• render — SVG/PNG output via Graphviz

UC5 — Multi-Modal Bridge

DOT is text. Rendered output is an image. This bundle bridges the two seamlessly.

An LLM works in text. A human reviewer works in visuals. DOT graphs serve both — the source is machine-readable, the render is human-readable.

Text in → Image out. One artifact, two audiences.

UC6 — Workflow & Recipe Visualization

Amplifier recipes are multi-step workflows. Visualizing them as directed graphs makes step dependencies, branching, and approval gates immediately clear.

UC7 — Investigation Artifacts

When debugging a complex system, you need artifacts that survive the session — shareable, versionable, diffable records of what you found.

DOT graphs are text files. They live in git. They diff cleanly. They render on demand. They're the perfect investigation artifact.

Commit your understanding alongside your code.

Intelligence Demo — Dead Code Detection

One call to dot_analyze(operation='unreachable') identified the graph entry point. The annotated PNG highlights it in red instantly. Zero code reading. Milliseconds.

Intelligence Demo — Cycle Detection

billing → shipping → warehouse → billing — a circular dependency caught structurally in one call. The annotated DOT renders cycle edges in red bold, making the problem visually undeniable.

Intelligence Demo — Structural Diff

What changed between mental model and reality? dot_analyze(operation='diff') answers objectively.

14 nodes unchanged · 14 edges unchanged · Core service layer intact

Intelligence Demo — Real Architecture Stats

Structural health metrics in milliseconds — no LLM needed.

4 weakly connected components in resolve = architecturally independent sub-graphs.
1 component in modes = a single cohesive system. Both confirmed DAGs — no cycles.

What's Inside — Agents & Tools

What's Inside — Skills & Knowledge

Architecture

Three tiers — Skills (knowledge), Tools (operations), Agents (orchestration) — all shipped in one includable bundle.

By the Numbers

Everything runs locally. No API keys. No cloud services. No network calls required.

Try It

Run once. Available for all sessions. Get DOT authoring, validation, rendering, and structural intelligence.

The diagram isn't the deliverable.
The understanding is.

github.com/bkrabach/amplifier-bundle-dot-graph