NORTH.md
1. North Star
NORTH.md becomes the standard decision arbitration file in the modern AI agent stack, adopted by ambitious open-source and commercial engineering teams to scale autonomous agency without scaling architectural drift.
2. The Bar
Automated gates (CI, on main and every pull request):
- Zero broken internal links or missing anchor targets across all static surfaces.
- The machine-readable JSON specification (/api/spec/v0.1.json) is valid and lists the same seven sections as spec.md, in the same order, at the same version.
astro checkreports zero errors, zero warnings and zero hints.
Release checks (before every deploy):
- Specification is readable in five minutes and adoptable in ten.
- Landing scores 100/100/100/100 on Lighthouse and passes WCAG AA with zero axe-core violations, in light and dark.
Truth & Honesty Assertions:
- Every example in
src/content/examplesis a production-grade file we would defend in code review, not a placeholder. - Badges and UI metrics promise only verifiable truth; zero phantom states.
- Spec wording is load-bearing; no generic corporate filler.
3. Asymmetric Bets
Go 10x on:
- Specification clarity and arbitration utility. The wording of the seven sections must actively change model decisions under uncertainty.
- Editorial design, typography, and clean contrast. First impression sets adoption calibre.
- Proof of boundary enforcement in production over synthetic marketing claims.
Accept 1.1x on:
- Internal build tooling, custom CLI utilities, and complex lint parsers at early adoption stage.
- Multi-language landing translations at launch (English canonical; Spanish /es/ mirror).
- Bespoke CMS infrastructure (static Markdown + CDN is permanently correct).
4. Anti-Goals
- We do not build a bloated linter CLI before spec adoption matures. Tooling locks in shape prematurely.
- We do not track or identify users on the landing. Privacy-first hosting (no cookies, no trackers).
- We do not claim territorial monopoly over the agent stack. Modular composition with
CONSTITUTION.md,AGENTS.md,DESIGN.md, andSOUL.md. Generous cross-links. - We do not ship a paid tier or proprietary paywall. The specification and reference implementation are permanently free and MIT-licensed.
5. Trade-off Defaults
| Trade-off | Default | Flip when |
|---|---|---|
| Spec depth vs. breadth | Depth on the seven canonical sections | Community RFC establishes a new universal failure mode |
| Editorial restraint vs. maximalism | High-contrast brutalist editorial (Anton + Inter + JetBrains Mono) | Content readability requires interactive diagrams |
| Static delivery vs. dynamic runtime | Static pre-rendering (zero server-side runtime) | Interactive eval harness requires remote model invocation |
| Composition vs. territorialism | Cross-link generously with adjacent conventions | Adjacent convention actively contradicts decision arbitration principles |
| Quality calibre vs. launch speed | Ship rough on day one if calibre is set; never ship soft on launch day | Polish in week one; calibre in hour one |
6. Ambition Triggers
- “Does this change give agents judgment when the prompt runs out, or just more instructions?”
- “Would Vercel or Linear ship this surface?”
- “Can an AI agent arbitrate between two competing valid PRs using only this file?”
- “If we had three more days, what changes — and why aren’t we doing that now?”
- “Does this look written by an engineer who cares, or by LLM defaults?“
7. Reversibility
One-way doors (decide deliberately, move slowly):
- The seven canonical section names and their semantics.
- The canonical domain (
northfile.dev). - The MIT license on the specification text and schema.
Two-way doors (move fast, reverse cheaply):
- Landing page copy, typography scale, styling tokens.
- Reference examples and eval scenarios (add, refine, replace freely).
- Comparison matrix additions as new ecosystem conventions emerge.
When in doubt: treat as two-way and move.
NORTH.md spec: v0.1 · adopted by berthelius/north itself.