dgv

Dia-GramV (DGV)

One diagram per system, stored as dgv/<name>.dgv.json in the project. The agent authors it through MCP tools; the developer sees it live in the viewer and can drag, edit, and save from there. The file is the single source of truth — both sides read and write it.

Why it exists: a plan written in prose hides incompatibilities (a module calling a DB over HTTP, a service that nobody starts, a bridge with one side, an API nobody calls, an import cycle). DGV makes every component a typed node with ports, every relation a typed edge with a protocol, and lints the whole thing so those mistakes surface before code — instead of after a day of tokens.

Workflow (always this order)

1. dgv_catalog once per session — the allowed node kinds, edge kinds, protocols. Never invent a kind.
2. dgv_list / dgv_read — is there already a diagram for this system? Read it before reading code: it is the map, and it is cheaper than the tree. Extend it; do not create a second one for the same system.
3. dgv_create (new) then dgv_apply in a few large batches, not one node per call:
   • frames first (boundaries: machine, process, service group, remote), then nodes with frame, then edges.
   • every node: kind, label, short sublabel, tech, and path — the file or directory that implements it (a glob or a list is fine). No path on things that are not code here: devices, externals, stores. Add ports on anything that is called (api, service, db, model, sidecar): { id, protocol, dir, shape } where shape says what crosses it ("JSON /api/v1", "text[] → float[][]").
   • every edge: kind (sync | async | data | import | deploy | control), protocol, label (what happens), targetPort when the target declares ports, payload when the shape matters.
   • never send position — DGV places new nodes; call dgv_layout after a batch.
4. Read the lint report dgv_apply returns. Fix every error by changing only the named subject using one of its fixes. Warnings are advice: fix them when they reveal a real gap (orphans, unspecified contracts, one-sided bridges). When a warning is intentional, set ack: "<why>" on that element via dgv_apply — it becomes info and the reason travels with the diagram. Never ack something you have not verified.
5. Flag what lint cannot see. A diagram can lint clean and still be wrong. When you read it and spot an incoherence — a process with an exec edge in and nothing else, so every settings change is a restart; the same module imported by three programs that each load it again; a spawned child with no death-pact; a store written by two producers with no shared schema — dgv_flag it on the element: title (one line, what is wrong), note (what you saw, why it matters), fix (the concrete change), kind issue | idea | question. The viewer shows it as a bubble on that card until it is resolved, and lint lists it (flag/issue = warning). Flag the element, not the diagram; never flag what a lint rule already reports; never flag what you have not verified in the code. When you fix it — or the user says it is intentional — dgv_resolve. Open flags appear as ⚑ in dgv_read and at session start: treat them as the to-do list of the architecture.
6. dgv_layout then dgv_open — tell the user the URL. They may rearrange and save; re-read with dgv_read before your next edit so you never overwrite their layout.
7. dgv_export format=markdown when the plan is agreed → paste into the project's docs / CLAUDE.md so the build follows it.
8. While building and before you stop: dgv_drift. Fix drift/missing first (the code moved: update path; the node is gone: remove it, or status: todo if it is not written yet). For drift/unclaimed, add a node or widen a path — or put the directory in meta.driftIgnore with good reason. Then set status on what you built or changed. A diagram that is not updated is worse than none: the next session will trust it. Every dgv_apply, dgv_flag and dgv_resolve is recorded in the diagram's history (dgv_history, also the tail of dgv_read): who (agent or viewer) changed what on which element. Read it when the user asks what changed, or when the file differs from what you remember — the viewer's saves show up there as viewer.