Skip to content

majordomus init

Create the .ai/ layer in this repository, and refuse to overwrite an existing one.

Create the .ai/ layer in this repository, and refuse to overwrite an existing one.

  • generated-output-mutating
  • system
  • runs before init

The only command that runs before the .ai/ layer exists. It refuses an existing layer; --extend adds only what is missing and overwrites nothing.

Syntax

majordomus init [--extend]

Lifecycle

  1. Set up
  2. Begin
  3. Work
  4. Verify
  5. Conclude
  6. Inspect

Other commands at this stage:update, migrate.

Reads

  • share/skeleton/ai

Writes

  • .ai/manifest.yaml
  • .ai/README.md
  • .ai/repo/
  • .ai/local/state/
  • .gitignore

Exit codes

Only the codes this command can produce. The full contract is on the commands index.

  • 0 ok
  • 2 usage
  • 13 internal error
  • 15 refused

Setting up, and refusing to overwrite

init is the only command that runs before the .ai/ layer exists. It seeds the manifest, the policy, the profiles, the vendored rule baseline and the empty sections from the skeleton, and it never touches .ai/local/.

A repository with no AI layer

--extend
no
already installed
no

Given this repository

# An empty git repository: no AI layer at all.
git commit -q --allow-empty -m base 2>/dev/null || true

Run

$ majordomus init

Output contains

  • ^created$
  • .ai/repo/policy.yaml
  • next: majordomus update

exit 0

The skeleton is copied in, the ignore line for .ai/local/ is added, and the two hook lines the policy needs are printed together with the command that will verify they were added. init does not install hooks itself.

A repository that already has one

--extend
no
already installed
yes

Given this repository

# A repository with Majordomus installed and projections generated, and one commit of work.
"$MJ" init >/dev/null
"$MJ" update >/dev/null
mkdir -p lib docs
echo a > lib/a
echo d > docs/d
git add . && git commit -qm base

Run

$ majordomus init

Output contains

  • already exists

exit 15

Exit 15 is REFUSED, not an error. Overwriting a policy someone has edited is the kind of silent loss this tool exists to prevent, so it stops and names the flag that adds without overwriting.

Adding what is missing with --extend

--extend
yes
already installed
yes

Given this repository

# A repository with Majordomus installed and projections generated, and one commit of work.
"$MJ" init >/dev/null
"$MJ" update >/dev/null
mkdir -p lib docs
echo a > lib/a
echo d > docs/d
git add . && git commit -qm base

Run

$ majordomus init --extend

Output contains

  • nothing to add

exit 0

--extend seeds only the files the layer lacks and rewrites nothing. On a complete layer it says so; the files under .ai/repo/ belong to the repository from the moment they were created.

Reference

Create the repository's AI layer, .ai/, from the tool's skeleton. It installs nothing: the tool stays wherever it was run from, no hook and no shell file is touched, and .majordomus/ is never created.

Reads: the skeleton under share/skeleton/ and the standard rule package under share/standard/majordomus/. Writes: .ai/README.md (the protocol, readable without the tool) and .ai/manifest.yaml (the section registry, ai-repository/v1); under .ai/repo/, the tracked half: its README.md, policy.yaml, profiles/, prompts/, rules/ with its README.md, the vendored baseline rules/vendor/majordomus/ (manifest and rule files, byte for byte the package the tool ships) and an empty rules/project/, knowledge/sources.yaml beside an empty knowledge/curated/, workflows/, skills/, adrs/, project/; under .ai/local/, the checkout's own half: state/ seeded with decisions.md and open-questions.md and the empty state/handovers/ and state/checkpoints/, plus cache/, prompts/ and session-contexts/; and one .ai/local/ line in .gitignore, added once. Everything under .ai/repo/ belongs to the repository from that moment; a newer tool does not rewrite it.

Refuses (15) when .ai/ already exists, unless --extend, which adds every file the skeleton ships and the repository lacks and overwrites nothing; (15) when .ai/ exists without a manifest, naming the choice between moving it aside and --extend; and (15) when project data still lives under .majordomus/, the pre-.ai layout, naming majordomus migrate.

Does not install git hooks. It prints the two lines a hook needs and the command majordomus doctor that will verify they were added.

$ majordomus init
created
  .ai/README.md
  .ai/manifest.yaml
  .ai/repo/README.md
  .ai/repo/policy.yaml
  .ai/repo/profiles/
  .ai/repo/prompts/
  .ai/repo/rules/README.md
  .ai/repo/rules/vendor/majordomus/
  .ai/repo/knowledge/
  .ai/repo/workflows/
  .ai/repo/skills/
  .ai/repo/adrs/
  .gitignore:.ai/local/
local state: .ai/local/state/ (ignored by git; this checkout's own)
next: majordomus update      # generate the provider instruction files named in the policy
next: majordomus doctor      # verify nothing is declared that is not wired

$ majordomus init
majordomus: .ai/ already exists in … (use --extend to add what is missing; nothing is overwritten)
$ echo $?
15

Evidence

Every case below runs in CI on Linux and macOS. The site refuses to build if a public command has no behavioural case, no negative case, or no demonstration.

Behaviour

Failure modes

Implementation

Demonstration

Guarantees this command carries