Straight answers

No. Each file answers a different question. AGENTS.md and CLAUDE.md say how to work in the repository; SOUL.md says who the agent is; DESIGN.md covers the look; a CONSTITUTION.md sets the limits. NORTH.md says why the project exists and how far to push. They are meant to live in the same repository. Where two overlap (a constitution that already records trade-offs, say), point from one file to the other instead of repeating it.

It is written to decide, not to inspire. Vision docs and mission statements are written for stakeholders and rarely change. OKRs are quarterly and measured on a cycle. A NORTH.md is working context for the agents and people inside the codebase: it changes rarely and deliberately, and it puts clear trade-offs ahead of inspiration. The test is simple: does it change what an agent decides when it has two reasonable options?

Because without them an agent has to guess seven things: where the project is going, what counts as done, where effort pays off, what is refused, which trade-offs are settled, when to push for more, and which decisions are hard to undo. Fewer sections would leave one of those open; more would make the file harder to keep current. Seven is a design choice for v0.1, and the spec allows extra sections after them.

Because the file has to carry reasons, and prose carries reasons better than fields do. A rule without its reason covers only the cases its author imagined; the reason lets an agent apply it to the next one. Plain text at a known path is also easy to read, version and find, as CLAUDE.md, AGENTS.md and llms.txt show. A schema or validator may come later, once real use has shaped the spec. The format will stay markdown.

Two named lists: where you invest 10x, and where you deliberately accept 1.1x. A legal-tech product might go 10x on document accuracy and accept 1.1x on its admin screens. Naming both sides prevents two failures at once: over-investing in commodity work and under-investing in the work that compounds. ‘We care about everything’ is not an asymmetric bet.

An Anti-Goal is decided once, for a whole class of requests, with a reason that survives pushback. ‘We don’t do that’ is improvised, one request at a time. From the Arkwell example: ‘We do not build a CRM. Mature CRMs exist; we sync customers and orders through the API instead of rebuilding contact management.’ That line ends the conversation before it starts, for humans and agents alike.

It tells the agent that the safe, incremental reading is too small for this task. Examples: ‘Is there a 10x version of this?’ or ‘What would [reference team] ship here?’ One property matters: a trigger must allow the answer ‘what we have is already the 10x version’. Otherwise it is not a trigger. It is pressure.

Point them at it. In Claude Code, add the line @NORTH.md to CLAUDE.md: Claude Code loads CLAUDE.md at the start of every session, and the import brings NORTH.md with it. In AGENTS.md or any other rules file, add a one-line pointer such as ‘See NORTH.md for project purpose and ambition’; whether the agent then opens the file depends on the tool, so prefer an import wherever one exists. For a single task, paste the relevant sections into the prompt.

Keep the heading and say why. The spec lets you omit any section, but recommends keeping the heading with a short note so people and tools can still read the file predictably. ‘No asymmetric bets at this scale; everything gets the same effort’ is still useful information.

Public where you can. Agents read a private NORTH.md exactly as they read a public one; public adds discoverability for contributors, evaluators and LLMs. If parts of your strategy are confidential, write the NORTH.md at the level of abstraction you can publish, and keep the detail in private notes.

Rarely, and on purpose. The North Star should hold for years. The Bar may rise as the team gets better. Trade-off Defaults and Anti-Goals change only when the strategy does. If you are editing it every sprint, the roadmap has crept in, and the roadmap belongs in your tracker. Review it at major versions and real pivots.

Yes. Each product with its own ambition can have a NORTH.md in its package root; the root file then describes the umbrella ambition the whole repository serves. Where ambitions genuinely differ, separate files beat one file vague enough to cover everything.

Draft it yourself, then review it with the people who make architectural and prioritisation calls. Expect the draft to surface assumptions the team shares but has never written down; that is the point. Once it is agreed, link it from CLAUDE.md or AGENTS.md, add the badge if you like, and let everyday use build the habit. Put it where people and agents already look, rather than mandating it through process.

Possibly, though it was designed for code repositories. The underlying problem, collaborators taking the smallest reading of a task, is not specific to software. A design system, a research project or an open dataset could use the same seven sections: The Bar becomes the quality criteria for the output, and Reversibility maps the editorial or structural decisions that are hard to undo. If you try it, tell us how it went.

Not measured yet. NORTH.md v0.1 rests on a hypothesis: that agents choose better between valid options when the project’s direction is written down. We have not published an evaluation, and the only NORTH.md we can point to in use is this site’s own. If you test it, with and without a NORTH.md, we want the results, including the unflattering ones.

Not at v0.1, deliberately. Tooling now would lock in a file shape before real use has shown what matters; this project’s own NORTH.md lists a premature linter as an Anti-Goal. Once the spec settles and common patterns emerge, a validator is the natural next step.

Add what you need after them, and propose changes by RFC. The spec allows extra sections after the canonical seven. If one keeps proving essential, open an issue on GitHub. The seven names are stable at v0.1, but the spec is built to evolve, and every section has to earn its place by changing what an agent or a team decides.

Viktor Berthelius (BRTHLS). NORTH.md is an independent open-source project: MIT-licensed, vendor-neutral and not tied to any commercial product.

Its shape is; the detail can still move. The current version is v0.1. The seven section names are treated as one-way doors: they will not be renamed without a major version and a migration path for anyone using them. Section guidance, examples and propagation advice may change in minor versions. Versions follow semver, and v1.0 will mark stability.

There is nothing to pay for: no paid tier, no commercial product. The most useful support is to use it, tell us where it breaks, contribute a real NORTH.md to the examples, or write about it.

Open an issue at github.com/berthelius/north for questions, bugs, discussion or example submissions. The specification is the single source of truth: if it is unclear, that is a documentation bug, and we want to know.