| name | bundle-to-dot |
| description | Convention for the v3 bundle documentation system: a single bundle.dot + bundle.png per repo, generated by bundle_repo_dot(). Use when generating, validating, or interpreting bundle documentation files. Covers 7-cluster DOT structure, token cost model, color conventions, external reference distinction, freshness tracking via source_hash, generation recipes, and the lifecycle model. |
| version | 3.0.0 |
Bundle Documentation Convention (v3)
Overview
The v3 bundle documentation system produces a single DOT diagram per repository:
| Output | What it is | Location |
|---|
bundle.dot | Full 7-cluster structural diagram of the entire repo | Repo root |
bundle.png | Rendered PNG of the diagram | Repo root |
Both files embed a source_hash for freshness tracking. The diagram is
generated by calling bundle_repo_dot(repo_root) from amplifier_foundation.bundle_docs.
What the DOT Shows
The bundle.dot diagram maps the entire repository into 7 cluster subgraphs:
| Cluster | Directory | What it contains |
|---|
| Behaviors | behaviors/ | Reusable capability packages (thin bundles) |
| Standalones | bundles/ | Self-contained session bundles |
| Agents | agents/ | Agent .md files with frontmatter |
| Modules | tools/modules | Tool and module declarations |
| Providers | providers/ | Provider configurations |
| Experiments | experiments/ | Experimental bundles (exp-* naming) |
| Context Files | context/ | Shared context files |
The root bundle node is rendered at the center with edges to the clusters that
it composes. External references (bundles from other repos) appear with
visual distinction (see External References below).
Token Cost Model
The structural DOT encodes the token cost of each component:
| Component | Cost source |
|---|
| Tool/module | Tool schema token count (estimated from schema YAML) |
| Agent | meta.description token count + body |
| Context file | Full file content token count (recursive @mention expansion) |
| Bundle instruction | Markdown body token count |
Edges in the DOT reflect composition relationships. Heavier nodes (high token
count) appear in more prominent visual styles. The summary node at the bottom
of each diagram shows total estimated token cost for the composition.
Visual Conventions
Node Colors (actual code constants from bundle_to_dot.py)
| Element | Fill color | Hex | Notes |
|---|
| Root bundle | teal/mint | #80cbc4 | bundle.md at repo root |
| Behavior | light teal | #e0f2f1 | Entries in behaviors/ |
| Standalone | teal/mint | #80cbc4 | Entries in bundles/ (same as root) |
| Agent | light green | #c8e6c9 | Agent .md files |
| Module/tool | light blue | #bbdefb | Tool/module declarations |
| Provider | light grey | #e0e0e0 | Provider configurations |
| Experiment | light purple | #e1bee7 | Entries in experiments/ |
| Context file | light purple | #e1bee7 | Context .md files |
| Cluster fill | near white | #f9f9f9 | Subgraph background |
| Summary node | blue-grey | #eceff1 | Cost summary footer node |
External References
External bundles (referenced by URI, not local to the repo) are visually
distinct from local nodes:
| Edge style | Meaning |
|---|
| Solid | Local reference — included in token cost count |
| Dashed + red border | External with hidden cost (_COLOR_EXTERNAL_COST = "red") — the external bundle contributes tokens at runtime but is NOT counted in the local total |
Dashed + muted fill (#f5f5f5) | External with no additional cost — referenced externally but costs are borne elsewhere |
The legend node embedded in the DOT explains these conventions inline.
LLM Enhancement
By default, the generate-bundle-docs recipe sends the structural DOT to
foundation:zen-architect for label enhancement: node labels are rewritten
with concise, accessible English summaries rather than raw filenames.
To skip LLM enhancement (structural-only, faster):
enhance_diagrams: "false"
Rules for the LLM enhancement step:
- Keep ALL structural elements unchanged (node IDs, edges, shapes, colors, clusters)
- ONLY rewrite
label="..." values on nodes and clusters, plus the graph title
- Keep the
source_hash="..." graph attribute exactly as-is
- Labels must be ≤2-3 lines; use
\n for line breaks
Freshness Model
bundle.dot embeds source_hash="<hash>" as a graph attribute. The hash is
derived from all repository entry points combined (all bundle, behavior, agent,
tool, context, and hook files). If any of these change, the hash changes and
bundle.dot is considered stale.
Findings
| Code | Severity | Meaning |
|---|
BUNDLE_DOT_MISSING | SUGGESTION | No bundle.dot found at repo root |
BUNDLE_DOT_STALE | WARNING | bundle.dot source_hash doesn't match current repo state |
Generation
Direct (bulk generation)
generate-bundle-docs
Calls bundle_repo_dot(repo_path), checks freshness via source_hash, writes
bundle.dot (optionally LLM-enhanced) and renders bundle.png at the repo root.
Via validation (automatic)
validate-bundle-repo auto-regenerates a stale or missing bundle.dot as a
side effect of validation:
validate-bundle-repo → detects missing/stale → regenerates bundle.dot + bundle.png
Lifecycle: When to Regenerate
Regenerate when any of the following change in the repository:
bundle.md / bundle.yaml at repo root- Any file in
behaviors/ (behavior bundles)
- Any file in
bundles/ (standalone bundles)
- Any file in
agents/ (agent definitions)
- Any file in
context/ (context files)
- Any tool/module declaration
- Any hook definition
- Any file in
providers/, experiments/
Tip: If unsure, run validate-bundle-repo — it checks hashes and
regenerates only if stale.
API Reference
from amplifier_foundation.bundle_docs import bundle_repo_dot
dot_content = bundle_repo_dot(repo_root)
The function is the sole public entry point. It takes a str | Path pointing
to the repository root and returns a complete DOT graph string.
Checklist
Before committing a bundle or behavior change:
