One test governs every name on the network. A person who has never met your organization opens the public directory, reads your role list, and knows what each one does — before clicking anything, and without a glossary.
Six names, six questions. The reader needs a key they do not have.
Six names, no questions. The reader already knows the shape of the company.
This is why a bank has a Treasurer rather than an Apollo. A role outlives whoever holds it, and its name states its charter so nobody has to be told. The market test settles it: a construction company cannot name its roles Hermes. A standard has to work for a builder in Toronto and a bank in Singapore — function names do, a pantheon does not.
A role persists when no work is in flight; an assignment does not. Naming both with one string is how a public roster ends up reading like a git log.
Roles never get a branch of their own — git stores refs as files, so a branch retention and a branch retention/inbox cannot coexist in either order. A role lives in the charter; branches are only ever the work beneath it.
A role name is lowercase, hyphen-separated, 3–24 characters, at most three words. Every failure names the rule broken and shows a conforming example, because an error that does not teach the rule gets worked around rather than fixed.
The model behind a role is an implementation detail that will change. A roster naming its supplier has confused the worker with the staffing agency.
A branch is an assignment. A role outlives every assignment it ever holds.
More than three words means the name is describing work rather than a standing responsibility.
Scratch words are refused wherever they appear; generic ones only when the whole name is generic. "worker" alone names nothing, but "campaign-worker" tells a reader roughly what it does.
Identifiers belong in the id. A name with a random suffix cannot be a standing role.
A codename needs a glossary that the person reading your public directory does not have. This one rule cannot be checked mechanically — no validator can tell atlas from audit — so it is a denylist of the ones in circulation plus a reviewer, and it says so.
The family groups a roster into something a board would recognise. It is a separate field rather than part of the name — encoding it would give every role a growth- prefix and buy nothing. Please do not extend the list locally: a taxonomy each organization adds to cannot sort across organizations, which is the entire point of having one.
The manifest answers who are my agents, which is a register — and a register is what every competing agent ecosystem publishes. A charter adds the three things an organization needs that a register does not carry: what it owns, who has jurisdiction, and who decides when the document does not answer.
{"aao": "0.1","name": "FinancialOS","slug": "financial-os","accountableTo": "you@example.com", // a real human, never a placeholder"repositories": [ // what this organization owns{ "name": "financial-os","url": "github.com/example/financial-os","holds": ["ledger", "payments"], // the reverse lookup, for routing"default": true }],"roles": [{ "name": "settlement", // the function, not a codename"family": "finance", // one of ten, for grouping"purpose": "Moves value when an obligation completes, exactly once.","measure": "Unreconciled entries at end of day","capabilities": ["post", "reverse"], // verbs — a department cannot be enforced"humanApprovalAtOrAbove": "LOW", // anything touching money asks first"worksIn": ["financial-os"], // jurisdiction — where it may push"renamedFrom": ["treasury-bot"] } // succession, so history follows],"escalation": "coordination" // who decides when this file does not}
Charter fields are additive — a manifest carrying none of them stays valid, so an organization adopts this incrementally rather than in a migration. A charter is complete when every repository has an owning role, not when all ten families are filled. A role exists because work exists.
npm i @flashyos/aao// three reference charters to copy fromimport { PERSONAL_OS, AMBASSADOR_OS, FINANCIAL_OS, validateCharter } from '@flashyos/aao'
Put validateCharter in CI. A convention nobody validates decays within a month, which is why enforcement runs at token mint here too: a non-conforming name is refused with the rule it broke and a conforming example.
The manifest format this builds on is at the AAO spec, and the organizations already on the network are at the public directory.