The Intent Tree Model
An intent tree is a navigable hierarchy that lives on disk as a folder of small markdown files with YAML frontmatter. Three branches at the top — Purpose, User Context, Means — answer why, who, and how. Around them sit four operational siblings — rules, specs, execution, clarifications — that turn the tree into something agents can actually act on. Humans curate; humans and agents both read.
Three branches
Purpose
Why the system exists. Mission, vision, value, product goal.
User Context
Who uses it, in what situation. Primary actor, usage situation, session shape.
Means
How we want to solve it. Interaction style, system behavior, abstraction choice, technical strategy.
What it looks like on disk
An intent tree we run in production is a folder of small markdown files. The three branches sit under intent-tree/, and four operational siblings — rules/, specs/, execution/, clarifications/ — keep the agent loop honest. A 00-map.md at the root tells humans (and agents) where to start reading.
intents/<domain>/
intent-tree/
00-map.md # reading order; what each cluster owns
purpose/
01-mission.md
02-vision.md
03-value.md
04-product-goal.md
user-context/
01-primary-actor.md
02-usage-situation.md
03-session-shape.md
means/
01-queue-topology.md
02-tooling-strategy.md
03-persistence-strategy.md
...
rules/ # technical & operational guardrails
specs/ # downstream contracts
execution/ # issue-ready slicing & dispatch order
clarifications/ # open questions, AI-surfaced and human-answered
design/ # rationale and alternativesExamples: intent-cli itself, plus internal product domains (private today). The same shape works for product domains, infrastructure domains, and even meta domains like "how this team makes decisions."
Where do the first files come from? In the early phase of a product we run Intent Storming — structuring technology and intent as the product owner, either with the team or solo with the AI interviewing you. Answers are captured as Purpose / User Context / Means nodes directly into the tree. More on Intent Storming →
Each intent is a small file with frontmatter
Every node carries a stable ID, a state, a one-line summary, and links to the intents it depends on or supports. That is what makes the tree machine-navigable while still being a folder a human can grep.
--- intent_id: ICL.M.TOPOLOGY domain: intent-cli intent_type: means intent_state: canonical # inferred → clarified → canonical readiness: structured summary: Adopt a queue-aware supervisor with selective block, sliced per sub-issue. tags: - domain:intent-cli - intent:means - state:canonical parent_intents: [ICL.P.MISSION] related_intents: [ICL.M.TOOLING, ICL.M.WORKER] source_concepts: - intents/rules/nonblocking-agent-loop.md --- # Body in plain Japanese / English — the why and the chosen approach.
When an issue is later compiled from this intent, the relevant slice of the tree (this file plus everything it links to) becomes the issue's context. That is why writing a clear issue stops being painful — the context is already structured and ready to attach.
Promotion states
Confidence is a state, not a guess. An intent goes through:
inferred — agents proposed; awaiting human confirmation ↓ clarified — human confirmed; meaning is fixed ↓ canonical — adopted as a base point that constrains downstream specs
An intent that is canonical can be referenced from specs and code reviews as a binding constraint. An intent that is inferred cannot.
Promotion is driven by Clarification, not by manual editing. AI continuously reviews the tree and surfaces "what about this?" questions in batches, with a recommended answer for each. Humans accept the recommendation where they have no strong opinion (most cases), and write their own where they do (the parts where their judgment actually matters). Each accepted answer promotes an intent one level. The tree gets richer with every cycle, without an upfront spec marathon — and every issue cut from the tree afterwards inherits that richer context.
Bug reports as a clarification signal
Even with a strong intent tree, the implementation will not be perfect. Bugs and adjustments will surface after the change is shipped — and that is part of the loop, not an exception to it. Intent-System treats every bug report as a signal to inspect, classified into one of two kinds:
- Implementation bug. The intent was captured correctly, but the code did not honor it. Fix the code; the tree does not need to change.
- Intent gap surfaced as a bug. The intent did not say anything about this point, the implementer (human or agent) made a reasonable-looking local choice, and the result was not what the team actually wanted. This is not really a bug — it is a clarification request from reality. The fix is to add or sharpen the relevant intent so the same point does not get re-decided incorrectly the next time.
Drawing this line correctly is what makes the tree get stronger over time instead of just bigger. Mis-classifying a bug as "just a code fix" loses the chance to record what the team actually meant; mis-classifying a code defect as an intent gap pollutes the tree with rules that should never have needed to be written. Intent-System routes both flows: code fixes go through the normal review loop; clarifications promote the tree, and every issue cut afterwards inherits the sharper intent.
Operationally, each report is filed as an Intent-Bug issue and re-enters the agent fix loop on ai-develop, then promotes to main through the same review path. See Git-AI-Flow → Promotion path →
How it differs from
- Requirement specs. Specs become snapshots; intents accumulate.
- Architecture decision records (ADRs). ADRs record decisions; intent records the reasons that drive future decisions.
- User stories / Job stories. Stories are slices; intent is the tree they grow on.