Concepts

Six ideas that make it work

An intent graph describes a system at mixed levels of detail. You look at it through a lens, you are honest about what you do not know through epistemic state, and you generate everything else as projections. Agents do the work.

1. The graph

An IntentGraph is a tree of units of intent plus relations that cut across the tree. Three building blocks:

intentnode: A unit of intent at some level of detail: what this part of the system is for and why. Fields include intent, constraints, epistemic_state, assumptions, design_notes and examples.
treearc: A refinement edge from parent to child. All treearcs together form a tree: one parent per node, no cycles.
intentlink: A directed, valued relation between any two nodes at any depth: data exchange, dependency, coordination. It says what must be true between them.

The tree is an abstraction hierarchy, not a call graph. A parent does not “call” its children; it summarises them at lower resolution. The test: if a reader has to open the children to learn what the parent is for, the parent is badly written. Zooming in adds information and never changes meaning.

A small example. The tree gives zoom; the dashed intentlinks give the relations that the tree alone cannot. The last line of each node is its epistemic state.

Specification: vocabulary and formalism, intentlink specification.

2. Levels of detail

Not every part of a system deserves the same precision. IntentGraph lets each node be shown at one of three levels:

The three levels of detail, from least to most
Level	What you see	Use it for
skeleton	Identifier and name only.	Distant context: it exists, and where.
lean	Adds the intent sentence and the epistemic state.	Orientation: the ancestors of what you work on.
full	Every field: constraints, design notes, examples, pointers to code, history.	The part you are actually changing.

This is the same idea as the level of detail on a map: precision is spent where it matters. Cross-cutting facts are stated once, at the right level, and linked, not copied.

3. The lens

A lens is a view of the graph: a set of nodes that always includes the ancestors of every node it shows, each node at a chosen level of detail, plus the intentlinks whose two ends are both visible. You work through a lens rather than on the whole graph, so a person or an agent never has to hold the whole system in mind.

The default shape is simple: the target at full detail, its ancestors at lean, everything else at skeleton. The hierarchy stays visible, so you never lose your place. Lens operations include focus, promote and demote (change a node’s level), expand (reveal children) and prune. Given a size budget, pruning removes the most distant branches first and keeps the tree valid.

The example graph seen through a lens whose target is PAYMENT. The shape of the logo comes from this idea: a vertical stem of ancestors down to the target, and a V of context spreading around it.

From the command line, a lens is one command:

ig-tool lens build -g graph.json -t PAYMENT -b 30 -o lens.yaml

Specification: lens specification; guide: navigation primer.

4. Epistemic state

Every node says how much is known about it. This is the idea borrowed from social science: a finding without its context and acknowledged uncertainty is not worth much, yet code carries neither. The field is free text; these are the common starting words:

Common epistemic states and what to do about each
State	Meaning	Typical next step
known	Well understood and stable.	Build on it.
undecided	Several options, no decision yet.	Present the options to a human, or research.
risky	Decided, with identified risks.	Flag it in reviews and add validation.
speculative	A best guess with low confidence.	Validate before building on it.
inherited	Assumed from the parent, not checked independently.	Check it if the node becomes critical.
observed	Extracted from existing code.	Confirm it still matches the code.

Issues can be appended, for example undecided: three strategies proposed | unvalidated: no test coverage data. A node may also be marked deferred when a decision is left open on purpose. The first rule for every agent is never invent intent: an honest “undecided” is better than false certainty. The graph may be temporarily messy, but it must never be silently wrong.

Guide: semantics primer.

5. Projections

A projection is anything generated from the graph through a lens: code in a chosen language and design style, a spec, a README, an executive summary, behavioural scenarios, tests, or a visual rendering. Each audience gets the view it needs, all derived from the same truth.

How a projection is produced is itself intent, and it is kept apart from the product. A ProjectionIG is a full intent graph about one rendering: a code ProjectionIG holds paradigm, naming and error handling; a documentation one holds audience, tone and emphasis. Swap the ProjectionIG and the same product intent yields object-oriented or functional code, an executive summary or a technical spec. A simple test sorts content between the two: if a statement would break when you switch to another language, it belongs in the ProjectionIG.

Product intent and rendering intent are separate graphs. A lens picks a slice of each; projections are generated from the slice and reconciled back when someone edits them.

Projections are not read-only. When a developer changes the code or a product manager rewrites a spec, the change can be reconciled back into the graph, so specs, docs and code stay maintained views of one source rather than parallel artefacts that drift. This is why IntentGraph aims to subsume spec-driven workflows instead of replacing them.

Guide: philosophy primer (the five axioms and the dual-graph model).

6. Agents

A graph with no tooling would be an inert design document. Agents bring it to life. They are configurations of foundation models, not trained models: each role is a set of instructions kept in the repository, under .claude/agents/. Each agent works through a lens it is given, never on the whole graph, and edits go through validated ig-tool commands rather than raw files.

Agent roles
Role	Job
Elicitor	Conducts a structured dialogue with a human to draw out intent.
Critic	Finds graph quality issues: vagueness, contradictions, gaps.
Extractor	Extracts intent from existing code, iteratively.
Designer	Designs the code architecture from the intent.
Generator	Generates code from the intent.
Verifier	Creates tests from the intent, to check that the code is faithful to it.
Steward	Enforces structure and propagates changes.
Navigator	Recommends what to work on next.

The agents are still work in progress; see where the project stands. Entry point: agent primers. How the roles combine into the three workflows: workflows primer.

Try it yourself