What Majordomus supervises

11 responsibilities, one layer. Each is a file under .ai/ and a subcommand that reads it.

Policy

one provider-neutral policy.yaml; unknown keys are errors

majordomus update
8 guarantees
6 enforced

update generates CLAUDE.md, AGENTS.md, GEMINI.md, or any target you name, deterministically, and stamps each with the policy hash and the hash of its own content; a hand edit is detected and never silently overwritten

majordomus update
12 guarantees
3 enforced

State

one active task per checkout in current.yaml, with branch, head, and working_tree computed from git, never authored

majordomus start
9 guarantees
5 enforced

Scope

start takes the paths a task may touch; check and finish fail on files outside them; other worktrees' overlapping claims are reported

majordomus check
7 guarantees
3 enforced

Profiles

one bundle per task class, each setting capability class, reasoning effort, verbosity, presentation, context toggles, verification, and checkpoint interval independently

majordomus check
8 guarantees
3 enforced

Handover

append-only records with computed front matter and required sections, created atomically, never staged; --resolve finds the right one for this worktree and branch and labels how far git has moved since

majordomus handover
3 guarantees
3 enforced

Finish

a typed outcome and a contract evaluated line by line; nothing written when any line fails

majordomus finish
6 guarantees
3 enforced

Doctor

proves the installation is real: policy parses, every declared enforcement is actually invoked by the hook it names without a swallowed exit code, every projection matches its own stamp, the always-loaded file is under budget

majordomus doctor
18 guarantees
12 enforced

Watch

reports drift between policy, projections, state, scope, and git, each finding with the command that reproduces it

majordomus watch
5 guarantees

Plan

milestones are outcome specifications and issues are execution contracts; status, execution waves and the next ready issue are derived from the dependency graph, never stored

majordomus plan
8 guarantees
3 enforced

Layer

one portable .ai/ directory, readable without the tool: .ai/repo/ is tracked and canonical, .ai/local/ is this checkout's own and ignored; doctor proves the manifest resolves, every section it names exists, and nothing under local/ is tracked

majordomus init
14 guarantees
5 enforced

The 10 sentences every worker reads

Projected into every generated instruction file from the same source; the responsibilities above are how the tool backs them.

1Sessions are workers, not memory
2Load minimum sufficient context
3Externalise decisions and durable state
4One worker, one clear scope
5Escalate capability and effort only when justified
6Execution depth is not output verbosity
7Define done before executing
8Verify outcomes, not activity
9Parallel work requires isolation
10Handovers transfer state, not transcripts