Use cases
What people do with it: a task, the commands that answer it, and what you are left holding, each one proved against the tool. Every step is a real invocation, every rule and promise a real object, and every example below was executed to make this page.
- use cases
- 49
- categories
- 10
- executable
- 2
- guaranteed
- 45
- verified
- 2
- coverage
- 148 of 360 targets
Filtering runs in the browser. Without JavaScript every use case below is still listed, by category.
Getting started and adoption 5
Bringing Majordomus into a repository, new or old, without losing what people already wrote.
-
guaranteed basic
Adopt a repository that already has its own rules
Install the supervisory layer into a repository with a hand-written CLAUDE.md, without the tool taking ownership of a file somebody else wrote.
init · update · doctor -
guaranteed basic
Install the tool in one command, on a machine with no toolchain
Paste one line, get a verified binary for this machine, and run majordomus init — no git, no Rust, no Node, no Python, no root, and no way to install an archive whose digest does not match.
version · init · doctor -
guaranteed basic
Check the version before trusting a diagnosis
Print the version every other surface derives from, and see the argument it refuses.
version -
guaranteed basic
Move a repository from the pre-.ai layout to the layer
See what a migration would move, move it with a backup, and prove the result is a layer the tool reads.
migrate · doctor -
guaranteed basic
Use the tool as your own in a shared repository, and propose it to the team when it has made its case
One flag installs the same layer as yours alone: no tracked file changes, nothing is added to .gitignore, git status reads the same — the command checks it — and one more command hands the layer to the team.
init · update · doctor
Sessions and handover 11
Stopping and resuming work across sessions and workers from durable state, never a transcript.
-
guaranteed basic
Keep the prompts that started the work, below the model rather than around it
Wire the provider hook, prove it by running a payload through it, and see that a prompt the tool could not parse is reported rather than silently dropped.
capture -
guaranteed intermediate
Hand work over with a question still open, and keep it blocking
Close a task into a handover while a question is unresolved, start the follow-up task, and see the same question still refuse acceptance there.
handover · start · check · question · finish -
guaranteed basic
Checkpoint long work so a stop costs minutes, not the day
Record compact progress inside the active task at the profile interval, so a session that ends without warning leaves the next one a place to start.
checkpoint · check · context -
verified basic
Hand unfinished work to the next session
Stop mid-task and leave the next worker something to act on that is not a transcript.
checkpoint · handover · context · check -
guaranteed basic
Record a decision so the next worker can find it
Write down what was decided and why as state, then find it again without reading a conversation.
decision · search · history -
guaranteed basic
Have the session opened and closed without anybody remembering to
Wire the provider's own session events, and the episode opens when the sitting begins, hands the worker what the last one left, records what a compaction is about to discard, and closes with a continuation record beside its envelope.
capture · session · doctor · start · checkpoint · handover -
guaranteed basic
Record what one worker did in one sitting
Open a session, do the work under whatever tasks it touches, and close it into an envelope that references what it produced and copies nothing.
session · history · knowledge -
guaranteed intermediate
Read only the context that fits the budget, and know what was dropped
Assemble the context a worker needs now in authority order, cut it to a line budget, and see every dropped section named with its reason.
context · check -
guaranteed intermediate
Close an episode whose client never came back
A killed provider sends no end event. Close the episode it left open by evidence, exactly once, without claiming work it did not do.
recover -
verified basic
Start a session from a rendered framing, not a pasted transcript
List the prompt assets the repository ships, render one against the durable state, and read the context it embeds.
prompt · context -
guaranteed intermediate
Resume in the right worktree, never against somebody else’s task
Find the handover that belongs to this worktree and branch, and see a task record from another checkout reported as foreign rather than enforced here.
handover · check · context
Parallel workers 3
Several agents or people on one repository: claimed scopes, overlap, and who touched what.
-
guaranteed intermediate
Deliver issues in waves the graph computes, and take the next one
Validate the plan, read the execution waves the dependency graph yields, see which issues are ready and which are blocked on what, and take the one issue a worker should do now.
plan · start -
guaranteed intermediate
Run several workers in one repository without them colliding
Give each worker a declared scope, and find out immediately when two of them claim the same paths.
start · check · finish -
guaranteed intermediate
Work on a branch in the one worktree it belongs to
Start a branch without choosing a path, find every checkout of the repository from any of them, and bring a stray one home with its uncommitted work intact.
doctor · context
Policy and enforcement 5
Declaring rules, proving they are wired, and reproducing a finding.
-
guaranteed basic
Gate CI on the tool itself, with an exit code that is a contract
Run the checks CI runs, read every finding with the command that reproduces it, and rely on exit codes that mean one thing each: no code means warn and continue.
doctor · watch · doctrine · check -
executable intermediate
Divide a working tree into commits, and hold every message to a policy
Ask what this tree would commit and why, learn the scope vocabulary from the history rather than a table, and get a verdict on one message or on a whole range before a reviewer has to give one.
doctrine -
guaranteed intermediate
Prove a rule is actually enforced, not merely written down
Answer "is this rule real?" with a command rather than a reading of the source.
doctrine · doctor · check -
guaranteed basic
See which rules apply here and what enforces them
List the effective rule set, read one rule as the tool reads it, and see which of them the tool enforces and from where.
rules · doctrine -
guaranteed basic
Trust the policy and the profiles only after they are validated
Prove that the canonical policy parses with every key it needs declared, that every profile parses and the default exists, and that what the policy declares as enforced is what actually runs.
doctor · check
Completion and quality gates 7
Deciding whether work is finished, with a contract every line of which passes or fails.
-
guaranteed intermediate
Decide whether finished work is actually finished
Evaluate a contract line by line instead of accepting a sentence that says the work is done.
finish · question · check -
guaranteed intermediate
Block acceptance on a question nobody has answered
Open a question against the task, watch finish refuse completion while it is unresolved, resolve it with the answer, and only then complete.
question · finish · check -
guaranteed basic
Catch an agent that says it is done when it is not
One task, start to finish: a worker strays outside its scope, claims it is finished, hands over, and is accepted only once the repository's own verification passes.
start · check · finish · handover · context -
guaranteed intermediate
Complete an issue only when its evidence exists
See an issue refuse completion while a required piece of evidence is missing, read the roadmap the milestone state derives, and keep the GitHub projection a projection.
plan -
executable basic
Know whether the work in this checkout is finished
Ask the repository you are standing in, and be told what is still owed by name.
check · watch -
guaranteed basic
Prove what a task owed before calling it done
A task declares what it owes, records evidence against each obligation, and is refused when that evidence no longer describes the tree it was taken over.
start · evidence · check · finish -
guaranteed basic
Say what reached the remote and what did not
The obligations that reach past the working tree are settled by asking git and the published site, so a report cannot call uncommitted work committed or unpushed work pushed.
evidence · check · finish
Drift and reconciliation 2
Detecting that policy, projections, state and git disagree, and putting them back in step.
-
guaranteed basic
Find out what has drifted since anyone last looked
Ask what has moved, rather than whether anything is wrong.
watch · update · history -
guaranteed basic
Keep every provider bootstrap thin, generated and within budget
Regenerate AGENTS.md, CLAUDE.md and the other provider files from one policy and prove they are stamped, point at the layer, stay under the line budget and resolve every reference.
update · doctor · watch
Repository knowledge 8
What the repository declares about itself: sources, nodes, edges, the plan, and searching them.
-
guaranteed intermediate
Decide what belongs in the AI context, as data
Read the repository’s declared scope policy, see which paths are in and out of the index, and let doctor and the knowledge index apply it rather than a hardcoded list.
knowledge · doctor -
guaranteed intermediate
Refuse a directory of the layer that documents nothing
A directory added under the layer without a context document fails validation by name, nothing resolves against the tree until it says what it is for, and the same hierarchy is readable over MCP and the API without running the gate.
context · doctor -
guaranteed basic
Hand the repository to someone who cannot clone it
Take a snapshot that a model can read or a gate can run in, without sending anything untracked and without losing the file modes on the way.
archive -
guaranteed basic
Keep what an episode learned, without a model and without a conversation
Record a decision inside an episode, derive it into a candidate knowledge record from the ledger, read the evidence that the derivation ran, and watch a second derivation change nothing.
start · decision · knowledge · history -
guaranteed intermediate
Keep the plan as milestones and issues the tool can validate
Declare milestones as outcomes and issues as execution contracts, and let the tool say what is ready and what is blocked.
plan -
guaranteed basic
Read back what happened, and keep the ledger within its cap
Read the append-only ledger as operational history, filtered by task and event, validate every line, and rotate the oldest lines into an archive rather than deleting them.
history · search · watch -
guaranteed basic
Record a decision as data, and prove the tool cannot accept it for you
Read the decisions a repository holds, validate the whole set in one command, and watch the tool refuse to write the one status only a person may write.
adr · knowledge -
guaranteed intermediate
Trace a change to the context documents it affects
List the scoped context documents, resolve which apply to a path and why, and find out which documents a change set touches before it lands.
context · doctor
Serving the layer to AI clients 3
One shared server per repository, every client a peer, the same layer over MCP, HTTP and the command line.
-
guaranteed basic
Find an object of the layer without reading everything
Search durable records literally across kinds from the shell, and ask the shared server the same question over MCP with majordomus_search and majordomus_get.
search · knowledge · prompt -
guaranteed basic
See what the repository holds, and run one of its capabilities, without reading a file
Open the shared server in a browser and get the whole layer as pages: what exists, where each thing came from, what depends on what, what is failing, and a form that runs any capability.
doctor · knowledge -
guaranteed basic
Serve the repository's AI layer to every AI client through one shared server
Open the repository in any client the tool declares a provider for (docs/generated/providers.md) and have each of them read the same rules, prompts and knowledge over MCP from one process, seeing each other.
init · doctor
Performance 1
Benchmarks derived from the registry, baselines that are data, and budgets doctor reports against.
Extension 4
Adding a kind, a rule, a command or a use case as data, with the checks that follow from it.
-
guaranteed intermediate
Add a use case and let the tool prove it
Scaffold a draft for an uncovered command, validate it, run its scenario against the real tool, and see the coverage move.
usecase · doctor -
guaranteed advanced
Extend what the executable serves by adding a file, never by rebuilding it
Add a rule, a prompt or a knowledge node to .ai/ and have it appear as an MCP resource, an HTTP route and a reference entry, with the same binary.
init · update · doctor · knowledge -
guaranteed basic
Follow a procedure the repository defines, and add another one
Read the repository's skills, take one as it is written, and add a new one by writing its file — no registry, no code, and a check that says what it examined.
skills -
guaranteed intermediate
Say what your work is for, once, and have every surface say it
Record an operational failure mode as one file and have the command line, the API, MCP and the website answer it without registering it anywhere.
init · context · knowledge · doctor
What a use case is here
One file under .ai/repo/use-cases/: the commands, rules and promises it names, and a scenario the tool executes against itself. The maturity shown on each card is observed, not written: a use case is guaranteed only when its scenario passed and every claim it names is guaranteed. The coverage page says which capabilities still have no use case.
A why page is a moment you recognise. A use case is a task you perform. An application is a context it suits. A command page is one command's surface.