intent-graph
Skill0 starsChanged 4 months agoMITView on GitHub
Read or write the repo's intent graph under intent/ — the mission, bets, goals, problems, projects and stories that say why this code exists. Use when the user asks what something is for, why a decision was made, or what to work on next; when starting work whose purpose is not obvious from the diff; or when they want to record a decision, plan, problem, or piece of scope. Also use before writing code if no artifact is in focus.
In this repository3 other files it gives its agents.
- autopilotSkill
- coherence-checkSkill
- ship-checkSkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 0 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈0
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 13
Run coherence graph to see it.
- Very specific: line 21
Check what is in focus with coherence focus.
- Very specific: line 71
A bet that cannot be killed is not a bet: Every bet needs a "what would kill it" section with an observation that would make you stop.
- Very specific: line 88
When work teaches you something, edit the parent.
- Very specific: line 91
After any edit to intent/, run coherence check.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
The intent graph
intent/ holds small markdown files describing why this repo exists and what is
currently being built. Every file has frontmatter and hangs off a parent, forming
one chain: mission → bet → goal → project → story. user and problem sit off
to the side as the facts about the world that the chain answers to.
Run coherence graph to see it. Run coherence focus <id> to see one
artifact's chain up to the mission.
(Commands assume coherence on PATH; a repo may vendor it at bin/coherence
instead. Use whichever exists.)
Before writing code
Check what is in focus with coherence focus. If nothing is, find the artifact
this work serves and focus it. If no artifact covers the work, that is the real
finding, so say so before writing anything. Work with no stated intent is exactly
what this repo exists to catch.
The types
| type | one per | says |
mission | repo | why this exists at all |
bet | several | "I believe X, so I'm doing Y instead of Z", falsifiable |
goal | per bet | how you'd know the bet paid off; carries a measure: |
user | few | a specific person in a specific situation |
problem | per user | what goes wrong, told as a moment rather than a category |
architecture | per bet | a structural decision and what it forecloses |
project | per goal | a chunk of work big enough to matter, small enough to finish |
story | per project | one observable change, with acceptance criteria |
domain | repo | the nouns, if the vocabulary is contested |
Frontmatter
---
id: story-magic-link # primary key, matches the filename by convention
type: story
title: Magic-link sign-in
status: draft # draft | active | done | dropped
parent: project-auth # the one artifact above this
serves: [problem-signup-friction] # the problem/user this actually helps
priority: p1 # p0..p3, optional
measure: ... # goals only, the number that moves
code: [src/auth/**] # globs this artifact owns
---Bodies use ## Acceptance with - [ ] checkboxes on stories and projects. Those
checkboxes are what the ship gate judges a diff against, so write them as things a
reader could verify without asking the author.
Templates for every type live in intent/_templates/ (written by coherence
init). Copy one instead of writing frontmatter from memory.
Writing artifacts well
The graph is only worth maintaining if reading it is faster than rederiving the answer. That means:
- Write the reasoning, not the summary. "Use SQLite" is worthless in three months. "Use SQLite because the write pattern is single-writer and Postgres would add an ops surface I won't maintain" survives.
- A bet that cannot be killed is not a bet. Every
betneeds a "what would kill it" section with an observation that would make you stop. - Name what you gave up. Bets and architecture decisions both foreclose something. Recording it is how you recognise the pain later instead of rediscovering it as a mystery.
- Decompose, don't restate. A child that rephrases its parent adds nothing, and
the
copy-pastecheck will flag it. Each level down should contain a decision the level above did not make. - Delete freely. An artifact nobody reads makes the ones that matter harder to
find.
status: droppedkeeps the record, and deleting the file is fine too.
Maintaining it
- Finishing work means ticking criteria and setting
status: done. The checks flag done artifacts with open criteria or live children. - Abandoning work means
status: droppedrather than deleting silently. Anything hanging off it gets flagged as standing on a stale premise, which is the point. - When work teaches you something, edit the parent. A plan that never changes while
its children churn has stopped tracking reality, and
plan-stalenesscatches it.
After any edit to intent/, run coherence check.
Related: coherence-check for the checks, ship-check for the gate.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

