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.
SKILL.md
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):
# In recipe context
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:
