Introducing Intentset

Intentset is a way of writing down what a product promises, and keeping that record true while coding agents change the code. The first half of this deck needs no technical background. The second half shows the files, the checks and the tools.

Both boxes are one pull request, of a size agent-written changes reach every day, and many run larger. Nobody can review thousands of lines of generated code properly, every day. But the same change, described as what it does to the product, is short enough to read. That gap is what Intentset fills.

This is the risk in one sentence. If nobody wrote down what the product is supposed to do, nobody can tell whether a change kept it. Review turns into trusting the agent. Each change shifts a little behavior nobody chose; over months the shortcuts pile up out of sight; and when a customer or a colleague asks what the product does, the only answer is in the code.

This is the whole idea on one slide. Take one thing the product does, here scheduling an assessment in Lantern, and write down five things about it: why it exists and how you would know it worked; what it does, including what it refuses; which part of the code is accountable for it; the tests that check it, and whether they pass right now; and what each audience is told about it. They live in the repository as short, linked files, so they change in the same commit as the code, and when the code changes and the promise does not, that shows up at review. Agents do the writing. People decide what the promises are. Because the files are linked, a product reviewer can start at why and drill down, an engineer can start from the code they are changing, and both arrive at the same promise.

Everything in Intentset is organized around behaviors. "Student assessments" is a heading in a roadmap, not a promise: there is nothing in it to test. "Schedule a student assessment for a future time" is one. A behavior is small enough to recognize and to test, and it always says what happens when things go wrong, not only when they go right. The example comes from Lantern, an invented education product used throughout the Intentset site.

Lantern is the invented product the Intentset site uses as its worked example. Here one behavior sits in the middle, and every other record points at it: the intent that explains why it exists, the rule it must keep, the part of the code that delivers it, the checks that prove it, and the guide that explains it to teachers. Ask about any one of them and you can reach all the others.

The division of labor is the point. Agents do the writing: they draft records, change the code and keep the records in step. People do the deciding: only a person moves a record from draft to approved, and passing every automated check never counts as approval. Step five is the next slide: the pull request's reviewer reads it as a change to the product, not as a diff. Step six is where the same records reach people outside the team, as help articles for customers, tips beside the controls in the product, and guides for the people who support it.

The story of this change in one line: the rule about when an assessment may open was tightened so teachers cannot schedule past the end of term, and the scheduling behavior now refuses those times. That is what a reviewer reads instead of, or before, nearly seven thousand lines of code: which promise changed, which rule moved, which checks ran, which customer explanation now needs another look, and whether any code changed without its records. One honest gap is visible too: one of the two checks has not run yet.

Each of these questions needs the links between records to answer. A wiki page or a ticket cannot tell you which promises have no passing check on this release, or which customer explanations a rule change made stale. The last column matters as much as the others: agents also need to know where their authority ends.

In this example every one of twelve promises has a test, so a dashboard that counts links would show all twelve green. Only seven have a test that passed on the code as it stands now. The other five might be fine, but nobody can say so: a test that passed last month, on code that has changed since, proves nothing about today. Intentset keeps the two numbers apart and shows both.

From here on the deck is for the people who will set Intentset up and live with it day to day: engineers, technical product managers and anyone configuring agents.

This is the behavior from Lantern as a file, slightly abridged. The part between the dashes is what the tools read. The part below is what people read. Because it is just a file in the repository, it is reviewed in the same pull request as the code, reads on GitHub with nothing installed, and needs no database or hosted service.

Two of these carry most of the weight day to day: behaviors and rules. When parts of a behavior would be released, owned or reviewed separately, they become separate behaviors. Capabilities group behaviors into what users can do. Decisions can be existing architecture decision records, given frontmatter rather than copied.

A measure names its metric, baseline, target, window and evidence source before anyone collects data. Intentset does not collect telemetry or compute the metric; the systems named as sources do that, and the reading can come back to the record later as outcome evidence.

Relationships are frontmatter fields on the record that points. The tools derive every inverse, so there is no second copy to fall out of step. Every diagnostic names the file, the field and how to fix it.

Agents follow the shape of the code they are shown. If every behavior has one owning slice, an agent handed that slice's context makes a change that stays inside it. A product can even be modelled before it is built: while a slice is a draft, missing files are warnings, and approving it makes them errors. The reference profile maps this onto TypeScript and AWS Amplify Gen 2.

A verification record is a definition, not evidence: it says how to check, not that anyone did. Evidence is a run record produced by CI. Run records are never committed, because a record in the commit it assesses is stale the moment it lands. intentset evidence stale lists which checks need a run.

Point your agents at the guide with one line in CLAUDE.md or AGENTS.md. The drift check is what keeps the model honest over time: code cannot change quietly underneath a promise, because either the records change too, or the commit says explicitly that behavior did not.

Everything except the files is derived. Impact helps a reviewer see what a change could touch. The Atlas is for reviewing the model as a whole. Context and the read-only MCP server give agents what they need and no more. The export is the one contract other tools build against, so importing the same snapshot twice changes nothing.

Customer-facing tools read only this publication, never the engineering graph. Every published document carries its provenance: the source IDs and revisions, the snapshot and the reviewer. The documents are written in Markset, which Intentset adds meaning to without adding any syntax.

intentset validate --level L3 runs every check up to that level. Most teams start at L1 on one capability, add ownership and evidence as they go, and widen the scope from there.

Coral Reef Ventures is adopting Intentset in two of its own products and recording what it catches, what it costs and what it changes, friction included. The adoption log on the site has the details and what it changed in the specifications.

The example command sets up Lantern, the invented product from this deck, so you can run validate and impact before touching your own repository. The start page on intentset.org walks through modelling your first real capability.