The living blueprint for your codebase.
Code shows an agent what the system does. Architecture Graph shows what it's meant to be: who owns what, which contracts hold, what must stay true. Compact enough to read before every change, and updated with every change.
Task changed
Announced after a change is saved, never before. Carries the task after the change. May be delivered more than once, so consumers ignore events they have already seen.
eventId | stringUnique per event; consumers use it to ignore duplicates. |
|---|---|
type | "created" | "updated" | "completed" | "reopened" | "deleted" |
taskId | string |
version | integerTask version after this change. |
changedFieldsoptional | string[]Fields that changed, for updates. |
changedBy | stringPerson or device that made the change. |
occurredAt | string (date-time) |
task | TaskThe task after the change. Present for deletes as the last known state. |
{
"eventId": "evt_7Q2M9",
"type": "updated",
"taskId": "task_01HZX3",
"version": 4,
"changedFields": [
"dueAt"
],
"changedBy": "person_sam",
"occurredAt": "2026-11-02T21:12:09Z",
"task": {
"id": "task_01HZX3",
"listId": "list_home",
"title": "Renew passport",
"dueAt": "2026-11-14T17:00:00Z",
"completed": false,
"version": 4,
"updatedAt": "2026-11-02T21:12:09Z"
}
}- consumesReminder schedulerSchedules, moves or cancels reminders when due times change or tasks are completed.
- consumesSync enginePushes other people's changes to connected devices.
- consumesNotifierNotifies a person when a task is assigned to them.
- consumesSearch indexerUpdates the search copy after each change; ignores duplicate events.
ag validate checks against each other starting with the next release. Hover or focus a consumer to see why it depends on the contract.Architecture, not archaeology
Without a blueprint, every session digs intent back out of the code. A coding agent can read what a function does, but not why it lives where it does or what the rest of the system relies on it to keep doing. The questions that get lost are the ones that matter most before a change:
- Who owns this responsibility? So the change lands in the part that is meant to make it.
- Which part decides what this value means? So a shared meaning has one authority instead of several quiet copies.
- What must stay true when this interface changes? So every consumer of a contract is considered, not only the one in front of you.
Code remains the source of truth for what the system does. The graph is the source of truth for what it is meant to be, and it works the same way in any language.
How it works
Record
Your coding agent, guided by the bundled skill, writes a small graph from your requirements and code: components, the responsibilities they own, the contracts between them, the rules that hold, and the questions still open.
Retrieve before a change
Before editing, the agent runs
ag contextfor the file, module or contract it is about to touch, and gets the owners, consumers, guarantees and open decisions around it in a bounded answer.Keep it current
After the change, the agent updates the graph alongside the code.
ag validatechecks the records andag checkconfirms the generated guidance is up to date.
Honest about what it checks
The graph records intent. AG's checks make sure the records are well formed and agree with each other; they do not read your code or prove that it follows the design. When code and graph disagree, that is drift for people and tests to resolve.
What validate and check establish
- Every record has the required fields, a known kind and a status.
- Relationships point at records that exist, and each idea has at most one declared owner and one authority.
- Referenced files exist, and implemented records reference real implementation files.
- Relationships that cross modules are declared as imports and exports.
- Contract schemas are valid JSON Schema and every example matches its schema (in the next release).
- Generated guidance and indexes match the graph.
What they do not
- That the code does what the graph says, or that a record marked implemented is implemented correctly.
- That the graph covers everything important.
- That a contract example matching its schema means the code sends that data. A project test can check that with
sidecarValidator. - That the design is good.
See limits and upgrades for the full statement.
Explore a real graph, then start your own
Task manager
A familiar design at the design stage: tasks, reminders, offline sync, notifications and search, with contract schemas, examples and open questions.
Open in viewerAG models itself
The toolkit's own responsibilities, contracts, boundaries and decisions: the graph used when developing AG.
Open in viewerHello-world
A tiny runnable application that shows a design decision recorded, retrieved before a change, and kept current afterward.
Open in viewer
Add AG to a project with Node.js 22 or later, whatever language the project is written in, then install the skill for your coding agent:
npm install --save-dev @billbliss/architecture-graph@0.3.1
./node_modules/.bin/ag skill install --agent claude # or codex, or claude,codexRead the full guide for bootstrapping the first graph with your agent.