Reading a Capability Graph

A capability graph looks like a lot of other diagrams you've probably seen: boxes connected by arrows. What makes it different is what the boxes and arrows are actually made of. Each node is a capability with a real contract behind it, not a service boundary drawn from memory or a box added to make an architecture diagram look complete. Each edge is a dependency that the contracts themselves declare, one capability stating that it needs another to do its job.

Reading the graph is mostly about noticing shape. A capability with several edges pointing into it is one that a lot of the system leans on, which usually means it deserves a higher bar for legibility, since a change there can propagate further than a change to something more isolated. A node sitting off by itself with no edges either way is worth a second look too, for the opposite reason. Sometimes that isolation is correct, a genuinely self-contained capability. Sometimes it just means nobody has contracted its neighbors yet, so the dependency exists in the code but hasn't shown up in the graph.

cdad graph renders this in three formats at once. The Mermaid output is what you'd actually look at, a diagram you can drop into a doc or a PR description. The Markdown output gives you the same information in a form that reads well inline. The JSON adjacency list is the one worth treating as the source of truth if you're feeding graph state into other tooling, an agent, a CI check, a dashboard, because it's the stable, machine-friendly format the other two are rendered from.

You can also scope a run instead of rendering the whole thing at once. --capability <id> narrows the graph to one capability and its immediate neighbors, useful when you're about to touch something and want to know what else might feel it.--domain <name> narrows to a domain, and--state <state> filters by lifecycle state, which matters once a repo has a mix of contracted and not-yet-contracted capabilities living side by side.

The graph is only as trustworthy as the contracts behind it, though. It reflects what the contracts declare, not what prose documentation says elsewhere, so if a dependency relationship changes, the fix goes into the contract first and the graph gets regenerated after, not the other way around.