Spec v0.1 · Open convention · MIT
Give your AI agents
judgment when the prompt runs out.
NORTH.md is an open convention: one markdown file that declares a project's purpose, ambition and precomputed trade-offs for humans and AI coding agents. Left to guess, agents tend to ship the safe, incremental version. This file tells them how far to go, and how to break a tie.
The direction layer in a five-layer model we propose, alongside CONSTITUTION.md (limits), AGENTS.md (how), DESIGN.md (look) and SOUL.md (who).
A proposed model
Five files. Five questions.
Agents already read several context files. We propose seeing them as five layers, from the limits a project never crosses to the direction it is heading. It is a model, not a standard, and most repositories will use only some of the layers.
- L1 Limits Boundaries Community · agentconstitution.dev
CONSTITUTION.md
Non-negotiable principles and boundaries.
- L2 How Execution agents.md
AGENTS.md
How to build, test and work in the repository.
- L3 Look Design Google Labs
DESIGN.md
Design tokens and the rationale behind them.
- L4 Who Persona soul.md
SOUL.md
The agent's persona, values and tone.
- L5 Why Direction Spec v0.1
NORTH.md
Purpose, ambition and precomputed trade-offs: why, and how far.
No layer replaces another. Limits (L1), execution (L2), look (L3) and persona (L4) each answer their own question. NORTH.md answers the one left open: why the project exists, and how far to push.
See the full comparison →Seven sections. One file.
Each one answers a question an agent would otherwise have to guess.
- North Star The destination, in one sentence. Not the roadmap. Not the next quarter.
- The Bar What counts as done: measurable, above the industry default, defended by gates.
- Asymmetric Bets Where the project goes 10x, and where 1.1x is the right call.
- Anti-Goals What the project refuses, even when it is easy or profitable. Decided once, with a reason.
- Trade-off Defaults Recurring trade-offs, decided in advance, each with the condition that flips it.
- Ambition Triggers Short questions, for humans and prompts, that escalate scope when the team is thinking too small.
- Reversibility Which decisions are one-way doors and which are two-way. Deliberate on the first; move fast through the second.
Adopt it in ten minutes
Copy the template, fill in the seven sections and link it from the files your agents already read. A first draft takes ten minutes. A good one takes longer, and that is where the value is.
- Save it at the repository root as
NORTH.md - Link it from
CLAUDE.mdor AGENTS.md. - Optional: add the badge to your README.
<!-- NORTH.md spec: v0.1 -->
# NORTH.md
## 1. North Star
[One sentence. The destination, not the roadmap.]
## 2. The Bar
[What quality threshold counts as "shipped".]
## 3. Asymmetric Bets
[Where we go 10x. Where we accept 1.1x.]
## 4. Anti-Goals
[What we refuse, even when easy or profitable.]
## 5. Trade-off Defaults
| Trade-off | Default | Flip when |
|---|---|---|
| Speed vs. safety | Safety on core logic; speed on internal tools | An internal tool starts writing core data |
| Build vs. buy | Buy infrastructure; build core product | Vendor breaks unit economics |
## 6. Ambition Triggers
[Phrases that escalate scope when we are thinking too small.]
## 7. Reversibility
[One-way doors flagged. Two-way doors = move fast.]Add the badge
One line in your README. It tells readers the repository has a NORTH.md and links them to the spec.
Links to northfile.dev [](https://northfile.dev)