Skip to content

Getting started

From nothing to a supervised repository. Every command below exists in the CLI reference; nothing here is a target.

Majordomus is a directory in your repository plus a portable-shell CLI. There is no server to run and no account to create. The steps below are the ones the tool's own tests exercise.

  1. 1 Install the CLI

    once per machine 
    curl -fsSL https://majordomus.dev/install.sh | sh

    One archive for your machine, its digest verified before anything is unpacked, into $HOME/.local/bin. Pinning a version, choosing where it goes, and the security model →

  2. 2 Add it to a repository

    in your project 
    majordomus init
majordomus update
majordomus doctor

    init writes .ai/ and refuses to overwrite one that exists. update generates AGENTS.md, CLAUDE.md, GEMINI.md from the policy. doctor prints the 2 hook lines still missing; add them and run it again until it reports zero failures.

  3. 3 Start a scoped task

    per task 
    majordomus start "fix OAuth callback" --scope lib/auth --profile debugging

    Scope is the set of paths the worker may touch. Profile defaults to implementation. Identity fields are computed from git; a worker never writes them.

  4. 4 Work, checkpoint, check

    during the task 
    majordomus check --checkpoint
majordomus check --explain   # the effective policy and profile

    A file outside the scope is a failure, not a warning. A stale checkpoint is a warning and never blocks.

  5. 5 Hand over or finish

    end of session 
    printf '# Objective\
…\
# Current State\
…\
# Next Action\
…\
' | majordomus handover
# or
majordomus finish --outcome completed --verify-command "make test"

    Required handover sections: # Objective, # Current State, # Next Action. finish evaluates scope_respected, verification_ran, state_updated, no_open_blockers, note_present and writes nothing when any line fails.

Task lifecyclefrom lib/finish.sh outcome vocabulary
stateDiagram-v2
    [*] --> active: start
    active --> active: check --checkpoint
    active --> handed_over: handover --close
    handed_over --> [*]: next start archives the record
    active --> completed: finish --outcome completed
    completed --> [*]
    active --> partial: finish --outcome partial
    partial --> [*]
    active --> blocked: finish --outcome blocked
    blocked --> [*]
    active --> no_match: finish --outcome no_match
    no_match --> [*]
    active --> failed: finish --outcome failed
    failed --> [*]