Skip to content

Repository contract

The operating contract for this repository, itself generated by majordomus update.

Rendered from AGENTS.md — the same Markdown GitHub shows.

This file is a bootstrap, not the rulebook. Read README.md for what this repository is. The provider-neutral AI context and governance layer lives under .ai/, and everything normative is there.

Before substantive planning, implementation, review or repository mutation:

  1. read .ai/README.md and follow its discovery protocol,
  2. load the effective rules under .ai/repo/rules/ and resolve their dependencies,
  3. load only the skills, workflows and knowledge the task is about,
  4. never load .ai/local/ implicitly; it is this checkout's own state and not context.

This repository is supervised by Majordomus. Run majordomus context before working, take the task lifecycle from .ai/repo/workflows/task-lifecycle.md, and expect check and finish to refuse work outside the task's scope. The default profile is implementation; the checkpoint interval it sets is 15m.

Before working under a path, run majordomus context resolve <path> (or read the README.md chain from .ai/ down to that directory): each document adds to its ancestors and the nearest one does not replace them. A provider's own nested-file loading is an optimisation; the Majordomus resolution is what applies.

This repository serves its .ai/ layer over MCP. The client configurations at the root (.mcp.json for Claude Code, .gemini/settings.json for Gemini CLI, .codex/config.toml for Codex) start bin/majordomus-mcp, which builds the Rust executable when it must and runs majordomus mcp: one shared server per repository, Swagger UI at the URL it logs on stderr, and every attached client visible to the others. Prefer its majordomus_* tools to reading .ai/ by hand, and call majordomus_announce with your intent and the paths you expect to touch, so that the other clients (Claude, Codex, Gemini, ...) can avoid colliding with you. The surface is docs/MCP.md; just lists the recipes a person runs.

Never add or change an operation of the Rust executable by editing a transport registry, an OpenAPI or Swagger definition, a benchmark inventory or a documentation table: change the canonical capability! or module declaration under apps/majordomus-cli/src/capability/builtin/ and run majordomus generate; a repeated semantic definition across projections is a design defect (docs/CAPABILITIES.md, ADR 0004).

A capability you add or change has use cases: run majordomus usecase impact and the scenarios it names, and close a coverage gap (majordomus usecase coverage) with a use case that executes (.ai/repo/workflows/use-cases.md); finish refuses a required gap.

You are probably not alone. One shared server serves this repository, and every worker attached to it is visible to every other through majordomus_peers. Announce what you are doing and the paths you expect to touch, with majordomus_announce, before you start — and again whenever the connection is re-established, because an announcement belongs to a connection and a worker that reconnects keeps its work while losing its place on the board. Read the board before you open a mandate and before you fan work out: two workers built the same subsystem in one afternoon because neither looked first. A scope announced there is a claim, not a lock; the task's own scope and check --overlap are what refuse a commit.

Push what you have, early. A branch whose commits reach no remote is invisible to every other worker, cannot be integrated by anyone but you, and is one disk away from being lost; majordomus doctor names those branches.

Before implementing something new — a module, a command group, a document kind, a generated artifact — run scripts/collision-check --new <paths> to see which other branches already carry those paths, not only who the peer board says is working now: a branch pushed before this session started carries no announcement and no less of a claim. Announce with majordomus_announce once the paths are clear, and announce the identifier you are about to allocate — an ADR number, a case number, an issue id — not only the paths: a branch scan sees what was pushed, and the board is the only thing that sees a number two sessions are taking in the same minute. The rule is project.work-is-claimed-before-it-is-built.

Linked git worktrees of this repository live at <repository>-wt/<branch> — the primary checkout's sibling named with -wt, then the branch name with its hierarchy kept — derived from git and never chosen or registered; the primary checkout hosts the trunk. Before implementing, run majordomus worktree to see which branch and worktree you are in and whether that is where the branch belongs; start new work with majordomus worktree create <branch> and continue in the path it prints; bring a misplaced worktree home with majordomus worktree migrate rather than continuing where you are. The pre-commit hook refuses a feature branch committed from anywhere but its canonical worktree. The rule is project.worktree-topology; the mechanism is docs/WORKTREES.md.

A .majordomus/ directory, if one exists, is an optional installation of the tool and not repository context. Do not duplicate shared rules into this file: it is generated, and a rule that exists here and nowhere else is a bug.