Multi-agent single repo (MASR) workflow

masr.md

Multi-Agent Git Branch + Worktree Workflow

Assumptions:

main branch has normal project code only.
agent/codex branch has main + AGENTS.md.
agent/claude branch has main + CLAUDE.md.
main should not keep AGENTS.md or CLAUDE.md.
task details are passed as URLs in the agent prompt.

---

Initial setup

# new machine / new Git setup
git --version

git config --global user.name "Ronald Petty"
git config --global user.email "ronald.petty@rx-m.com"
git config --global init.defaultBranch main
git config --global pull.rebase false

# clone repo
mkdir -p ~/github.com/rx-m
cd ~/github.com/rx-m

git clone git@github.com:rx-m/example-repo.git repo
cd repo

git switch main
git pull
git status

# create agent worktrees from main
git worktree add ../repo-codex -b agent/codex main
git worktree add ../repo-claude -b agent/claude main

# create committed Codex-only instructions on agent/codex
cd ../repo-codex

cat > AGENTS.md <<'EOF'
# Codex Instructions

You are Codex.

Rules:
- Read AGENTS.md first.
- Do not read or use CLAUDE.md.
- Follow the task URL passed in the prompt.
- Do not modify unrelated files.
- Commit only your task changes.
EOF

git add AGENTS.md
git commit -m "Add Codex-only instructions"
git push -u origin agent/codex

# create committed Claude-only instructions on agent/claude
cd ../repo-claude

cat > CLAUDE.md <<'EOF'
# Claude Instructions

You are Claude.

Rules:
- Read CLAUDE.md first.
- Do not read or use AGENTS.md.
- Follow the task URL passed in the prompt.
- Do not modify unrelated files.
- Commit only your task changes.
EOF

git add CLAUDE.md
git commit -m "Add Claude-only instructions"
git push -u origin agent/claude

---

Task example with no conflicts

# update main
cd ../repo

git switch main
git pull

# update Codex worktree branch
cd ../repo-codex

git switch agent/codex
git pull
git merge main

# update Claude worktree branch
cd ../repo-claude

git switch agent/claude
git pull
git merge main

# launch Codex for task-1
cd ../repo-codex

codex "
Read AGENTS.md first.

Then complete this task:
https://example.com/tasks/task-1

Rules:
- Complete only task-1.
- Do not read or use CLAUDE.md.
- Do not modify unrelated files.
"

# launch Claude for task-2
cd ../repo-claude

claude "
Read CLAUDE.md first.

Then complete this task:
https://example.com/tasks/task-2

Rules:
- Complete only task-2.
- Do not read or use AGENTS.md.
- Do not modify unrelated files.
"

# commit Codex task result
cd ../repo-codex

git status
git add .
git restore --staged AGENTS.md 2>/dev/null || true
git commit -m "Complete task-1"
git push origin agent/codex

# commit Claude task result
cd ../repo-claude

git status
git add .
git restore --staged CLAUDE.md 2>/dev/null || true
git commit -m "Complete task-2"
git push origin agent/claude

# merge task code into main without keeping agent instruction files
cd ../repo

git switch main
git pull
git fetch origin

git merge --no-ff --no-commit origin/agent/codex
git rm --cached AGENTS.md 2>/dev/null || true
rm -f AGENTS.md
git commit -m "Merge task-1"

git merge --no-ff --no-commit origin/agent/claude
git rm --cached CLAUDE.md 2>/dev/null || true
rm -f CLAUDE.md
git commit -m "Merge task-2"

git push origin main

---

Task example where both agents touch the same file

# update main
cd ../repo

git switch main
git pull

# create new task branches/worktrees from current main
git worktree add ../repo-codex-conflict -b agent/codex-conflict main
git worktree add ../repo-claude-conflict -b agent/claude-conflict main

# add Codex-only instructions to conflict branch
cd ../repo-codex-conflict

cat > AGENTS.md <<'EOF'
# Codex Instructions

You are Codex.

Rules:
- Read AGENTS.md first.
- Do not read or use CLAUDE.md.
- Follow the task URL passed in the prompt.
- Do not modify unrelated files.
- Commit only your task changes.
EOF

git add AGENTS.md
git commit -m "Add Codex-only instructions"

# add Claude-only instructions to conflict branch
cd ../repo-claude-conflict

cat > CLAUDE.md <<'EOF'
# Claude Instructions

You are Claude.

Rules:
- Read CLAUDE.md first.
- Do not read or use AGENTS.md.
- Follow the task URL passed in the prompt.
- Do not modify unrelated files.
- Commit only your task changes.
EOF

git add CLAUDE.md
git commit -m "Add Claude-only instructions"

# launch Codex for conflicting task-1
cd ../repo-codex-conflict

codex "
Read AGENTS.md first.

Then complete this task:
https://example.com/tasks/task-1-conflict

Rules:
- Complete only task-1.
- This task may edit shared-file.txt.
- Do not read or use CLAUDE.md.
- Do not modify unrelated files.
"

# launch Claude for conflicting task-2
cd ../repo-claude-conflict

claude "
Read CLAUDE.md first.

Then complete this task:
https://example.com/tasks/task-2-conflict

Rules:
- Complete only task-2.
- This task may edit shared-file.txt.
- Do not read or use AGENTS.md.
- Do not modify unrelated files.
"

# commit Codex conflicting task result
cd ../repo-codex-conflict

git status
git add .
git restore --staged AGENTS.md 2>/dev/null || true
git commit -m "Complete conflict task-1"
git push -u origin agent/codex-conflict

# commit Claude conflicting task result
cd ../repo-claude-conflict

git status
git add .
git restore --staged CLAUDE.md 2>/dev/null || true
git commit -m "Complete conflict task-2"
git push -u origin agent/claude-conflict

# merge Codex result into main
cd ../repo

git switch main
git pull
git fetch origin

git merge --no-ff --no-commit origin/agent/codex-conflict
git rm --cached AGENTS.md 2>/dev/null || true
rm -f AGENTS.md
git commit -m "Merge conflict task-1"

# merge Claude result into main; conflict expected
git merge --no-ff --no-commit origin/agent/claude-conflict

# inspect conflict
git status
git diff

# manually resolve shared-file.txt
code shared-file.txt

# after removing conflict markers and keeping desired final content
git add shared-file.txt

git rm --cached CLAUDE.md 2>/dev/null || true
rm -f CLAUDE.md

git commit -m "Merge conflict task-2"
git push origin main

---

Cleanup

cd ~/github.com/rx-m/repo

git worktree remove ../repo-codex
git worktree remove ../repo-claude
git worktree remove ../repo-codex-conflict
git worktree remove ../repo-claude-conflict

git branch -d agent/codex
git branch -d agent/claude
git branch -d agent/codex-conflict
git branch -d agent/claude-conflict

git push origin --delete agent/codex
git push origin --delete agent/claude
git push origin --delete agent/codex-conflict
git push origin --delete agent/claude-conflict