Skip to content

majordomus start

Begin one scoped task under a profile, and refuse while another is active.

Begin one scoped task under a profile, and refuse while another is active.

  • state-mutating
  • task

One active task per checkout. Scope paths are normalised, and overlap with other worktrees' active tasks is reported rather than refused.

Syntax

majordomus start "<task>" --scope <path>[,<path>...] [--profile <name>] [--owner <who>]

Lifecycle

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

Other commands at this stage:plan, session.

Reads

  • .ai/repo/policy.yaml
  • .ai/repo/profiles/
  • .ai/local/state/current.yaml
  • git worktree list

Writes

  • .ai/local/state/current.yaml
  • .ai/local/state/ledger.jsonl

Exit codes

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

  • 0 ok
  • 2 usage
  • 10 contract unmet
  • 12 missing artifact
  • 15 refused

One scoped task at a time

start records what you are about to do and which paths it may touch. The scope is a claim you will be held to by check and by finish.

Beginning a task

task already active
no

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 start narrow the parser --scope lib

Output contains

  • ^started t-
  • profile=implementation
  • scope=lib

exit 0

The identity fields — repository, branch, head, worktree — are computed from git and never authored. What you supply is the description, the scope and the profile.

Starting a second task while one is active

task already active
yes

Given this repository

# ... and an active task scoped to lib, with work done inside that scope.
. "$FIXTURE_SETUP/installed.sh"
"$MJ" start "narrow the parser" --scope lib >/dev/null
echo work >> lib/a

Run

$ majordomus start something else --scope lib

Output contains

  • is active

exit 15

One active task per checkout. Two open claims on the same working copy cannot both be enforced, so the second is refused and told what to do first.

Reference

Begin a scoped task.

Arguments: <task> one line. --scope <path>[,<path>...] required. --profile <name> default from policy.profiles.default. --owner <string> free-form, default $USER.

Reads: policy, profile, git state. Writes: state/current.yaml and one task.started line to state/ledger.jsonl.

Behaviour:

  • Refuses (15) if state/current.yaml exists and its outcome is not terminal. One active task per checkout: hand the existing task over (handover --close) or finish it first. No flag discards an active task.
  • Normalises each scope path: strips trailing /, canonicalises, refuses paths outside the repository. Records the normalised form.
  • Reads every other worktree from git worktree list and, where one has an active task, reports any scope that contains or is contained by this scope. Reported, not blocked: that is a coordination fact for the person, not a rule. Git is the registry; there is no sidecar file.
  • Records repository_id, branch, head, working_tree from git. Never from arguments.
$ majordomus start "fix OAuth callback" --scope lib/auth --profile debugging
started t-20260903-193012-a4f1  profile=debugging  scope=lib/auth
INFO overlap  ../wt-alice-oauth-refresh claims lib/auth/oauth — contained by your scope  [reproduce: majordomus check --overlap]
next: worker reads AGENTS.md; checkpoint every 15m; majordomus check

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