`docs/PRINCIPLES.md`

The engineering principles: the handful of things this repository refuses to trade away. The top of the altitude hierarchy, which means everything below answers to it - decisions, specs, conventions, code.

What it is for

So that a trade-off has something to be wrong against. Most engineering arguments are between two reasonable positions, and they are settled by whoever cares most that day unless something above them says which way this project leans.

A principle earns its place by making at least one attractive option unavailable. If it forbids nothing, it is a value statement, and value statements do not settle arguments.

What goes in here

Few, short, and each one costly. "Prefer boring technology" is a principle when it means you will accept a worse fit rather than a novel dependency. "Write good code" is not a principle, because nobody was going to argue for the opposite.

Each should be recognisable in a decision record that cites it. A principle nothing has ever been decided against is untested.

What does not go in here

Decisions. A principle is a standing preference; a decision applies it to one case. The record cites the principle, not the other way round.

Rules. How commits are formatted is a convention. Principles do not reach that far down.

Anything you would abandon under pressure. A principle you break the first time it costs something has taught everyone that the file is decorative, and that lesson generalises to the rest of the documents.

Where it sits

PRINCIPLES.md
  -> ADR / BDR (decisions)
    -> specs (behaviour) + ARCHITECTURE.md (structure)
      -> conventions
        -> code

Higher wins. Code disagreeing with an accepted decision is a stop-and-propose, and a decision disagreeing with a principle needs the principle changed first - openly, because that is a larger act than it looks.

Decisions behind it

Optional in the manifest, named by R1. A repository can operate without stated principles; it just resolves its trade-offs somewhere less visible.
Short by design. A long list is a list nobody holds in their head, and a principle nobody remembers cannot be applied at the moment it matters.

Reference

Status. Optional - part of the core profile.
How it arrives. fill-from-repo - scaffold the shell from the standard, then author the body from THIS repo's reality - never blind-copy the example prose (ARCHITECTURE, PRODUCT, specs)
Shipped form. read it in the standard's own tree

The rule that requires it

A repo MUST carry AGENTS.md at its root as the single entry point for

See it in the spec