Spec v0.1 · Open convention · MIT · By BRTHLS
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.]Create your NORTH with your agent
Your agent reads the repository first, asks you one question at a time, drafts the seven sections, tests the draft against three decisions from your project and links it from the files your agents already read.
If your agent supports skills
npx skills add berthelius/north --skill north-adoptionIf it does not
Copy the prompt and paste it into the chat: the same interview, in one message.
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)