Source-available · early stage

Make intent, not code, the source of truth.

Code records how a system works. It does not record what the system is for, why it was built this way, or what was left undecided. IntentGraph keeps that in a structured graph you can zoom, and treats code, docs, specs and tests as views generated from it.

Try it in 5 minutes Read the concepts View the repository

The problem: code is the wrong place to keep intent

Purpose, constraints, trade-offs and rejected alternatives end up in meetings, tickets, comments and the heads of the people who wrote the code. Four things follow.

Intent is implicit

The “why” is not in the code, so understanding, maintaining or extending a system means reverse-engineering it. When the authors leave, the reasons leave with them.

Code is flat

There is no hierarchy of purpose and no zoom. To understand a part you read everything, or you read nothing.

Uncertainty is invisible

Code either does X or it does not. Nothing says “this is a workaround” or “we have not decided yet”.

Relevance is hard to bound

Changing one function can break behaviour elsewhere, and the dependencies are often invisible. In a large system nobody can hold the whole thing in mind.

AI coding assistants make this worse, not better: more code, written faster, with no more of the why attached to it.

The answer: one graph, many views

IntentGraph centres software development on a single intent graph: a tree of units of intent (“what is this part for, and why?”) with explicit relations between them. The graph is the canonical model. Everything else is a projection of it: code, documentation, specs, tests, visual views. Different audiences get different projections of the same truth, and edits to a projection flow back into the graph.

zoom

Zoom without losing meaning

Refining a node adds precision but never changes what it stands for. Parts of the system can stay coarse for as long as you like. A lens shows a slice of the graph at the detail you choose, so a person or an AI agent can work on one part with the rest in view at low resolution.

epistemic state

Say what you do not know

Every node records how sure we are: known, undecided, risky, speculative, observed from existing code. The graph never pretends to be complete, so gaps and open decisions are visible instead of buried.

projection

Intent apart from implementation

What the system does and why lives in the product graph. How one particular rendering is produced (language, style, audience, tone) lives in a separate graph. Swap the second and you get another language or another document from the same intent.

The concepts in detail, with diagrams →

How it works

Three workflows move between the graph and your code. Specialised AI agents do the heavy lifting; a command-line tool, ig-tool, gives them (and you) validated, atomic edits, so nobody edits raw graph files by hand.

Improve

Build and challenge intent

Refine the graph through dialogue and critique. Surface gaps, contradictions and unresolved decisions. Works from scratch or on an existing graph.

Distill

Extract intent from code

Reverse-engineer a graph from an existing codebase and its docs, layer by layer, not as one dump. Extracted claims are marked observed and re-checked against the code.

Project

Generate from intent

Derive code, documentation or tests from a refined graph, in a chosen language and design style. If the intent turns out to be insufficient, pause and improve the graph first.

A typical loop: define or update the graph through a lens, validate it, bundle the local neighbourhood for focused work, project it into artifacts, and when a projection is edited, reconcile the change back into the graph.

How it differs from prior approaches

The problem is recognised, and several families of tools attack part of it. This table is the project’s own reading of them; the full argument is in the positioning summary.

Four families of prior work, where each stops, and what IntentGraph does differently
Family	What it does	Where it stops	IntentGraph
Spec-driven development Tessl, Traycer, Kiro, GitHub Spec Kit	Structured text specs that guide AI code generation.	A spec describes behaviour, not the reasons behind it. It is flat text with implicit links and no way to express uncertainty.	Hierarchical, with typed relations and explicit epistemic state. A spec becomes one projection of the graph.
Formal methods and goal modelling KAOS, i*, TLA+, Alloy	Mathematical rigour: goal decomposition, state machines, constraints.	Another language to learn, and a demand for completeness up front. Records the result of a decision, not its reasoning.	Incompleteness is first-class. Readable by mixed-skill teams at the level of detail they need.
Projectional editing JetBrains MPS, Intentional Programming	Separate the model from its views.	Right architecture, wrong object: the model is still a syntax tree, a representation of code and not of intent.	Same principle (canonical model plus projections), applied to intent.
Intent-native runtimes Unison, Embabel, Darklang	Build intent into execution or storage.	They address runtime, not design. They cannot describe a system that does not exist yet or parts left deliberately open.	Works at design time and is language-agnostic: one graph, code in any language.

Where it stands

Early stage, built in the open. The foundations exist and run. The headline claim, that a real codebase can be rebuilt from its graph alone, is the project’s stated goal, not yet a published result.

Exists today

A written formalism: vocabulary, notation and invariants.
A Python core library: data model, lens operations, serialisation, two-way sync with Obsidian.
The ig-tool command line: validation, lens, node and link edits, batch changes.
A worked example graph (21 nodes) and a VS Code extension for viewing and editing.
Instruction files for the agent roles.

Not there yet

The agent workflows are work in progress.
The end-to-end validation (regenerate a popular third-party Python library from its graphs and have the result judged equivalent) is the roadmap’s definition of done, not an achieved result.

Details: roadmap and architecture.