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
- 42
- categories
- 10
- described
- 42
- coverage
- 138 of 188 targets
Filtering runs in the browser. Without JavaScript every use case below is still listed, by category.
Getting started and adoption 4
Bringing Majordomus into a repository, new or old, without losing what people already wrote.
-
describedbasic
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 -
describedbasic
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 -
describedbasic
Check the version before trusting a diagnosis
Print the version every other surface derives from, and see the argument it refuses.
version -
describedbasic
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
Sessions and handover 10
Stopping and resuming work across sessions and workers from durable state, never a transcript.
-
describedbasic
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 -
describedintermediate
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 -
describedbasic
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 -
describedbasic
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 -
describedbasic
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 -
describedbasic
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 -
describedbasic
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 -
describedintermediate
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 -
describedbasic
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 -
describedintermediate
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.
-
describedintermediate
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 -
describedintermediate
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 -
describedintermediate
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 4
Declaring rules, proving they are wired, and reproducing a finding.
-
describedbasic
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 -
describedintermediate
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 -
describedbasic
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 -
describedbasic
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 5
Deciding whether work is finished, with a contract every line of which passes or fails.
-
describedintermediate
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 -
describedintermediate
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 -
describedintermediate
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 -
describedbasic
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 -
describedbasic
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.
-
describedbasic
Find out what has drifted since anyone last looked
Ask what has moved, rather than whether anything is wrong.
watch · update · history -
describedbasic
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 6
What the repository declares about itself: sources, nodes, edges, the plan, and searching them.
-
describedintermediate
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 -
describedintermediate
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 -
describedintermediate
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 -
describedbasic
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 -
describedbasic
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 -
describedintermediate
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.
-
describedbasic
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 -
describedbasic
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 -
describedbasic
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.
-
describedintermediate
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 -
describedadvanced
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 -
describedbasic
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 -
describedintermediate
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.