One policy, projected into every tool's instruction file

Every provider the tool declares — an agent, an orchestrator that runs agents, any tool that reads AGENTS.md — gets the same rules from the same place, because their instruction files are generated from one policy and never written by hand; the providers are the table in docs/generated/providers.md.

status

stable

exposed through

• ✓cli
• ·api
• ✓mcp
• ·cockpit
• ✓docs

area

governance

context

What it does

.ai/repo/policy.yaml names the projections: a provider and a target file for each. The templates ship with the tool and a repository may override one under its own layer; the Rust executable and the shell tool render the same bytes, stamp included, so both agree on every stamp. A bootstrap says how to find the policy and never what the policy is: it points at the layer and the rules, stays inside the line budget the policy sets, and carries no rule of its own, so a rule that exists for one provider and not another cannot happen.

Profiles set capability class, effort, verbosity, presentation, context toggles and verification as independent fields, and a task carries the profile it started with. Unknown keys anywhere are errors, so a typo fails loudly.

What it does not do

It never names a vendor model: capability classes are what the projection asks a worker to map onto the closest its environment offers. It does not edit a provider's own settings, and a hand edit of a generated file is detected and refused rather than merged.

The commands that run it

• majordomus init setup

  Create the .ai/ layer in this repository, and refuse to overwrite an existing one.

• majordomus update setup

  Regenerate every provider instruction file from the one policy, deterministically.

• majordomus doctor inspect · read-only

  Is Majordomus itself healthy, and is every enforcement it declares actually wired here?

The objects it is made of

Kinds of the layer. Each is a schema, a source class and a file on disk; the number beside it is what this repository holds today, counted at build time.

• policy1
• profile4

What it answers

Operational moments from the Why catalogue that name one of this feature's mechanisms. Nothing here was assigned: a moment appears because it names a rule, a command, a capability or a claim this feature also names.

• →watched the strongest model, at maximum effort, rename a variable
• →opened CLAUDE.md and AGENTS.md and found two different rulebooks for one repository
• →found the rule for that directory in a README no session ever loaded
• →read three roadmaps for one project and believed none of them
• →watched the always-loaded instruction file grow past a thousand lines
• →changed a policy in one place and found the old one still in force in three others
• →found a rule everyone believed was enforced and nothing ever invoked
• →found code that contradicted a decision the repository had written down
• →closed an issue whose acceptance criteria nothing had actually checked
• →was asked how far the milestone had got and had to go and ask four people
• →read a promise in the README that no test stood behind
• →shipped an interface change whose contract document still described the old one
• →pasted a command from the documentation and watched it fail
• →had a green pipeline over generated files that no longer matched their sources
• →let a fast, cheap session make a decision the whole codebase now lives with
• →could not say why one provider was used for that work and another for this
• →found the same thing explained three times, slightly differently
• →published a page that promised more than any test could support
• →spent the first hour in an unfamiliar repository working out what was normal here
• →was asked who made a change and under what policy, and had only a commit

The rules that hold it

• blockingPolicy integritymajordomus.policy-integrity
• blockingPolicy completenessmajordomus.policy-completeness
• blockingProjection integritymajordomus.projection-integrity
• blockingBootstrap integritymajordomus.bootstrap-integrity
• blockingProfile requirementsmajordomus.profile-requirements
• blockingContext budgetmajordomus.context-budget
• blockingUnknown configuration keys are errorsproject.unknown-keys-are-errors

What is guaranteed

• guaranteed The canonical policy is parsed and rejected if it contains an unknown key
• guaranteed Every profile is parsed, its unknown keys rejected, and the default profile proven to exist
• guaranteed Provider instruction files are generated from the one policy, deterministically
• guaranteed Every generated instruction file carries its own stamp, and a hand edit is detected
• guaranteed A projection can own only the region between its markers, leaving the rest of the file untouched
• guaranteed Provider instruction files are thin bootstraps that point at the AI layer and carry no rule of their own
• planned One policy will be shared across repositories and workers
• guaranteed The always-loaded instruction file has a line budget with a failing check
• advisory Capability class, reasoning effort, output verbosity, context and verification are five independent axes
• advisory A profile names a capability class rather than a vendor model
• advisory Escalating reasoning effort after repeated blocked attempts is recorded rather than assumed
• guaranteed The provider bootstraps the policy declares (AGENTS.md, CLAUDE.md, GEMINI.md, ...) are a target of majordomus generate, rendered from the policy and the provider templates byte for byte as the shell tool renders them, and generate --check refuses a hand-edited or stale one in CI
• guaranteed Installing into a repository that already has an installation is refused
• guaranteed A hand-edited instruction file is never silently overwritten

Executable use cases

• adoptionAdopt a repository that already has its own rules
• driftKeep every provider bootstrap thin, generated and within budget
• policyTrust the policy and the profiles only after they are validated