# NORTH.md

> 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, coding agents tend to ship the safe, incremental version. A NORTH.md at the repository root writes down where the project is going and how far to push, in seven sections: North Star, The Bar, Asymmetric Bets, Anti-Goals, Trade-off Defaults, Ambition Triggers and Reversibility. Specification v0.1, first published 2026-10-11, MIT licence, by Viktor Berthelius (BRTHLS).

## Specification

- [Specification v0.1](https://northfile.dev/spec): the seven sections, with criteria and examples.
- [Specification, raw markdown](https://northfile.dev/spec.md): the same text as plain markdown.
- [Especificación en español](https://northfile.dev/es/spec): the Spanish translation of the specification.
- [Especificación en markdown](https://northfile.dev/es/spec.md): the Spanish translation as plain markdown.
- [Full text for LLMs](https://northfile.dev/llms-full.txt): the README, the full specification, this project's own NORTH.md and the example index, in one file.
- [Comparison](https://northfile.dev/compare): what AGENTS.md, CLAUDE.md, SOUL.md, DESIGN.md, CONSTITUTION.md and VISION.md each answer, and where NORTH.md fits.

## Reference

- [README](https://github.com/berthelius/north): repository introduction and the ten-minute adoption guide.
- [Examples](https://northfile.dev/examples): one real NORTH.md (this site's own) and five illustrative ones for fictional organisations: a B2B SaaS product, an open-source library, a creative studio, a side project and an internal platform.
- [Why](https://northfile.dev/why): the argument for writing a project's direction down.
- [FAQ](https://northfile.dev/faq): straight answers, including what is not proven yet.
- [Changelog](https://northfile.dev/changelog): specification version history and versioning policy.

## Machine-readable endpoints

- [Spec v0.1 (JSON)](https://northfile.dev/api/spec/v0.1.json): JSON representation of the v0.1 specification.
- [Spec v0.1 (markdown)](https://northfile.dev/api/spec/v0.1.md): raw markdown of the v0.1 specification.
- [LLM index (JSON)](https://northfile.dev/.well-known/llms.json): machine-readable pointer file for agents discovering the specification.

## Related conventions

The layer numbers refer to the five-layer model NORTH.md proposes. It is a model, not an established standard.

- [CONSTITUTION.md](https://agentconstitution.dev): project-level principles and boundaries for coding agents (Layer 1, limits).
- [AGENTS.md](https://agents.md): operational instructions for coding agents (Layer 2, how).
- [CLAUDE.md](https://code.claude.com/docs/en/memory): project instructions Claude Code loads at the start of each session; supports @path imports (Layer 2, how).
- [DESIGN.md](https://github.com/google-labs-code/design.md): design tokens and rationale for coding agents, from Google Labs (Layer 3, look).
- [SOUL.md](https://soul.md): the agent's persona, values and tone (Layer 4, who).
- [NORTH.md](https://northfile.dev): purpose, ambition and precomputed trade-offs (Layer 5, direction).
- [llms.txt](https://llmstxt.org): the convention this file follows, for helping LLMs use a website.