The homepage says what Majordomus is and proves it in a page. This is the argument that page was distilled from, in full: the problem as a repository experiences it, the model it argues for, and — stage by stage — how much of that model runs here today and how much is still only the argument.
The full argument
The long form behind the homepage: why prompt-driven development does not scale with a repository, what an intent is, the execution model with an honest mark of what exists, why governance has to be executable, and the doctrine.
01 / the problem
Prompt-driven development does not scale with the repository
A developer says: edit this file, add this endpoint, write these tests, update this component. The model follows the immediate instruction. Sometimes it works.
- It builds a second implementation of something that already exists.
- It ignores an ADR nobody put in front of it.
- Documentation claims one thing while the runtime does another.
- Tests pass while a whole integration surface is broken.
- The change merges, and nobody can answer a fairly basic question later.
What user intent was this change actually supposed to satisfy?
Context is fragmented across
- source code
- tests
- git history
- issues
- milestones
- ADRs
- rules
- doctrines
- policies
- session contexts
- handovers
- knowledge
- generated documentation
- runtime state
- API schemas
- deployment state
- other agents working on the same system
Giving a model a larger context window does not solve this. A larger pile of unstructured information is still a pile.
Agents are fast. Trust is slow.
- re-explained the same context to a brand-new session
- found two agents fixing the same bug in two branches
- watched the strongest model, at maximum effort, rename a variable
- accepted "done" because the model said so, and paid for it the next morning
- opened CLAUDE.md and AGENTS.md and found two different rulebooks for one repository
- watched a session undo last week's decision, for the reason it was made
- found a task "in progress" that nobody had touched for three weeks
- asked what the workers did last night and had only transcripts to grep
- found the rule for that directory in a README no session ever loaded
- read three roadmaps for one project and believed none of them
All 38, by who you are and by what part of operations they fall under →
Majordomus fixes all three in the one place every agent already works: your repository.
02 / the core idea
Describe the desired state, not the edit
An intent is a statement about reality: what must become true, what must stay true, and what evidence would settle it. It is deliberately not a list of files to open.
Every coding agent entering this repository must automatically discover the runtime, load the relevant governance and session context, join the active peer environment, and be ready to cooperate without manual bootstrap.
Modify .envrc. Add a bootstrap. Create a peer registry. Add a route. Update the Cockpit.Those may be right. They may be incomplete. They may already exist. They may contradict the architecture. The first question is the other one.
Given the current repository, what must change for the intent to become true?
Intent is the primary artifact
A prompt is not the source of truth. It is one way to communicate an intent to a worker. Neither is an issue, a milestone, a commit, a pull request, an ADR or a test: those are projections, constraints, evidence or consequences around it.
context before code
Context is compiled, not merely retrieved
The goal is not to pour the repository into the model. It is to compile the smallest useful representation of reality the work needs. It would be ordered by authority, carry its provenance, fit a line budget that names every exclusion, leave out what a worker already holds, and say where two sources disagree.
Dumping twenty Markdown files into a context window is not architecture. It is littering with GPUs.
What a worker is actually handed when it opens this repository →
03 / the execution model
Intent → Context → Plan → Execute → Verify → Proof
Development as a transformation from the current reality of the repository to the desired one. Every stage has an input it did not invent and an output the next stage can check. Under each stage are the claims that cover it, each with the status the claims matrix declares.
flowchart TD
capture["INTENT CAPTURE"]
context["CONTEXT"]
plan["PLAN"]
execute["EXECUTE"]
verify["VERIFY"]
proof["PROOF"]
capture --> context
context --> plan
plan --> execute
execute --> verify
verify --> proof
verify -- "not satisfied" --> plan-
1 / 6 · capture
Intent capture
The statement, and what would settle it.desired outcomes · constraints · invariants · acceptance criteria · provenance
- guaranteedintent-links-resolve
- guaranteedintent-stage-derived
-
2 / 6 · discover
Context
Governance preflight, then discovery, then compilation — not retrieval.rules, doctrines, policies, ADRs · session contexts and handovers · decisions, knowledge, open questions · issues, milestones, worktree and branch state · authority order and provenance · a line budget that names its exclusions
- guaranteedcontext-assembly
- guaranteedcontext-selection-budget
- guaranteedintent-in-session-context
-
3 / 6 · resolve
Plan
Ambiguity named, impact derived, strategy chosen against the architecture.ambiguity detection · impact analysis · architectural constraints · capability mapping · source, tests, docs, schemas · integration surfaces and deployment
- guaranteedintent-criteria-covered
- guaranteedintent-plan-reviewed
- guaranteedintent-refused-at-plan-start
-
4 / 6 · execute
Execute
Several workers, different responsibilities, one coordination object.implementation · opposition · review · testing · verification
- guaranteedscoped-task
- guaranteedscope-enforcement
- guaranteedmcp-peers
- guaranteedworktree-topology-derived
-
5 / 6 · verify
Verify
Against the acceptance criteria, not against the diff.acceptance criteria · invariants · regression checks · claims against implementation · runtime evidence
- guaranteedfinish-contract
- guaranteedevidence-gates-done
- guaranteedintent-realization-held-to-evidence
-
6 / 6 · prove
Proof
An inspectable bundle, not the word success.requirements and changed code · tests and runtime checks · governance that applied · commits, artifacts, API and deployment state · remaining limitations
- guaranteedevidence-proof-is-an-execution
- plannedintent-command-deployment-evidence
- plannedintent-closes-github-milestones
a control loop
An agent does not get to declare success because its patch applied
Close the same stages and you have a control system rather than an assistant: context would observe, the plan would compute the difference, execution would act, verification would measure, and the result would be compared against the intent rather than against the diff — replanning until it is satisfied. Majordomus never invokes a model and never writes the code; it decides what a worker is told and whether its claim of being done can be believed.
The repository, the tests, the runtime, governance and evidence all get a vote. Evidence gets the final one.
04 / governance is executable
A blocking rule stops the command; anything less is documentation
Rules and doctrines are not inspirational prose; they participate in execution. The rules that apply to a piece of work are resolved before it starts, from the policy and the profile, and a blocking rule stops the command rather than advising it. The model would resolve them against an intent as well.
Intent plus repository governance is what produces the effective requirements for a change. The rules below are not a selection somebody made for this page — they are the ones the public features rest on, resolved by the executable.
- rules that stop the command
- 68
- rules that report and let it pass
- 15
- resolved for the public features
- 83
Every one of them, by name — 83 rules, resolved and deduplicated by the executable
- blocking Architecture decision integrity
- blocking AI layer integrity
- blocking Blocker resolution
- blocking Bootstrap integrity
- blocking Catalogue integrity
- advisory Checkpoint freshness
- blocking Context budget
- blocking Context integrity
- blocking Dependency graph integrity
- advisory Decision records
- blocking The decision threshold
- advisory Define done before executing
- blocking Doctrine wiring integrity
- blocking Enforcement wiring
- advisory Externalise decisions and durable state
- blocking Handover integrity
- advisory Handovers transfer state, not transcripts
- advisory Parallel work requires isolation
- advisory Layout integrity
- blocking Ledger integrity
- advisory Load minimum sufficient context
- blocking Note integrity
- advisory One worker, one clear scope
- blocking Policy completeness
- blocking Policy integrity
- blocking Profile requirements
- blocking Project model integrity
- blocking Projection integrity
- blocking Prompt capture is proven, or reported unavailable
- blocking Retention caps
- blocking The roadmap is a projection, never a document
- blocking Rule package integrity
- blocking Scope integrity
- blocking The episode boundary is drawn below the model, and its working context is local
- blocking Session records are shared objects with a closed field set
- blocking Skill integrity
- blocking State consistency
- advisory Task continuity
- blocking Use-case coverage
- blocking Verification integrity
- advisory Verify outcomes, not activity
- blocking A personal layer changes nothing shared
- blocking Advisors are optional; reasoning, governance and CI never depend on one
- advisory Every public command is benchmarkable from the registry
- blocking Blocking checks are deterministic and cheap
- blocking Context locality
- blocking A commit message is a value this repository judges, not a convention it hopes for
- blocking Derived files are regenerated, never edited
- advisory Derived state is computed once per state version
- blocking Distribution has one canonical model
- blocking English only
- blocking Every finding carries a reproduce command
- blocking A generated artifact declares its document, its encoding, its contract and its source
- advisory A command reads each canonical file at most once
- blocking External interfaces are projections of one capability definition
- blocking Mesh cooperation is admitted per link, replicated through one journal, and projected by every surface alike
- blocking The mesh observes nodes; it authorizes nothing and holds one registry
- blocking A native command line command exists only with its documentation and its executable examples
- blocking Never author identity fields
- blocking Never store or summarise transcripts
- blocking New and changed executable code is covered by a test; legacy debt may only shrink
- blocking No claim without a test
- blocking Nothing this repository commits names a path of the machine it was written on
- blocking No network, no telemetry, no eval, no silent overwrite, no recursive deletion
- advisory A performance claim carries its measurement
- blocking Portable shell
- blocking Independent review is a recorded fact, weighed by evidence, never claimed and never counted
- blocking A new enforced rule is a doctrine, not an inline check
- blocking No endpoint of the Rust executable without a benchmark, and no number without evidence
- blocking One canonical declaration; modules compose capabilities; the root composes modules
- blocking The Rust executable carries its evidence with it
- blocking A command asserts in the file that declares it that it is what it claims, and is composed rather than registered
- blocking A request never rebuilds canonical state, and a cache is never trusted without an equivalence test
- blocking What a worker reads is declared once, and nothing outside it is read or served
- blocking Nothing a client leaves behind locks another client out
- blocking Tests run in disposable repositories
- blocking An interface shows only what is derived, and unknown is never drawn as healthy
- blocking Unknown configuration keys are errors
- blocking A use case is proved by execution, and a capability is covered by a use case
- blocking A web surface is declared once and every web projection is derived from it
- blocking A web surface is discovered from its producer, never registered twice
- blocking An operational failure mode is a catalogue object, never a page
- blocking A branch's worktree is at <repo>-wt/<branch>, derived from git, never registered
Every rule, with the validator that decides it and the test that proves it →
the doctrine
Implementation is subordinate to intent
A change is not complete because code was written, tests passed, a pull request merged or a deployment succeeded. It is complete when all of this holds.
- the originating intent is known
- relevant context has been considered
- applicable governance holds
- the required implementation exists
- affected surfaces are synchronized
- acceptance criteria pass
- claims match implementation
- runtime behaviour is verified where it applies
- evidence enough to demonstrate the outcome exists
The rest of the argument
Every significant change should be explainable
An intent should carry its origin, its governance, its constraints, its realisation, its verification and the interfaces it reached. That is what turns development history into something you can ask a question of.
Instead of “Why does this code exist?” — “fix stuff”, an answerable history says
This subsystem exists because an intent required automatic worker bootstrap. It was introduced in these commits, under this doctrine, verified by this test, exposed on these interfaces, and its verification status is current.
What this repository already records, and what reads it back →
The tracker stops pretending to be the semantic model
Issues stay useful. Milestones stay useful. In this model they become projections of intent rather than the place intent is kept, and the questions below become findings rather than investigations.
- implementation with no active intent behind it
- intent with no implementation
- an issue marked complete while its acceptance criteria fail
- a commit not linked to the intent it serves
- a milestone claiming completion while dependent intents are unresolved
None of these are questions a tracker can answer, because a tracker holds the work and not what the work was for.
The work graph this repository keeps, issue by issue and milestone by milestone →
Automatic. Supported. Enforced. Generated. Tested.
Repositories accumulate words like these, and they are surprisingly dangerous. A claim is worth having only when something connects it to evidence. Here every claim names the source, the implementation and the test that settle it, and a claim whose evidence no longer resolves fails the build.
Then either the implementation changes or the claim does. Reality wins — an unusual policy for software documentation, admittedly.
This repository's index holds 247 of them, each naming the source, the implementation and the test that settle it. A claim whose evidence no longer resolves fails the build before the site can be published; comparing a claim's wording to the behaviour it describes is still a person's job here.
Every claim, with its evidence and the command that verifies it →
Completion means intent satisfaction
Code written, tests green, PR merged: all useful, none of them proof of the outcome. A merged pull request whose intent remains false is unfinished work, and the git server is not an oracle.
The contract as the repository's own README shows it: a recorded run from the challenge, redacted and otherwise untouched, which the build refuses to publish if it stops matching. One line per check, each naming what it proved; a failing line carries the command that reproduces it, and nothing is written until every line passes.
- 1scope
- 2verification
- 3state
- 4blockers
- 5note
Work leaves as completed only when every line passes. Anything else gets a name, not a shrug.
Disagreement is cheap before deployment and expensive after
Before an implementation is accepted, another pass should try to disprove it. It is the discipline the model asks for, and these are the questions that actually catch the failures.
- Did we misunderstand the intent?
- Does an existing implementation already solve this?
- Is this duplicating another subsystem?
- Which decision constrains it?
- Which edge cases and which surfaces were forgotten?
- Do the tests match the requirement, or only the implementation?
- Can this regress silently later?
Where the design stands, claim by claim
The argument above is a doctrine and a design. How much of it exists is not written on this page: the feature matrix answers feature by feature and interface by interface, the claims under each stage of the pipeline carry the status the claims matrix declares, and the limitations page names what the tool does not do.
The commands, each declared once
Each command is declared once, and that declaration is what the command line, the HTTP API, the MCP tools and this site are all projections of.
initupdatedoctorwatchstartcontextcheckpointhandovercheckfinishhistorydecisionquestionpromptevidenceskillscapturesearchdoctrineplanversionsessionknowledgeadrusecaserulesmigraterecoverbencharchive
Write once. Surface everywhere.
A rule, a skill, a decision, a use case, an operational moment, a feature: each is one file under the layer with a schema. Discovery finds it, the schema validates it, the index holds it, and every interface reads the index. Nothing registers anything.
adr117application5area9audience8claim247command31context39critique4deployment1derive-offload1distribution-model1document347domain6feature29gap4implementation52intent5issue424knowledge4mesh-declaration1milestone41moment38policy1profile4prompt4release-record29rule187scope1session90skill8taxonomy10test527use-case49workspace1
Every one of them is discovered by a declared source class, validated against a published schema, held in one index and read by every interface. Nothing registers anything. The schemas, one per kind →
Discover once. Reason once. Derive everywhere. Verify against intent.
A repository stops being a collection of partially synchronized artifacts and becomes an inspectable model of what we wanted, what we knew, what we decided, what changed, why it changed, what constrains it, whether it works, and how we know.
Humans define intent. Majordomus keeps the system honest.
This page is a projection of the repository it describes. Every feature, count, provider, interface and moment on it came out of the same executable that answers agents, and a stale page fails the build before it can be deployed.
Every feature Read the guarantees How this page is derived View on GitHub