AI Race Condition Testing

A lightweight multi-agent coordination testbed that simulates parallel AI agents working on the same codebase using isolated git worktrees.

Architecture

Claude (Orchestrator)       DeepSeek Agents (Workers)
─────────────────────       ──────────────────────────
Designs interfaces           Implement against contracts
Writes task specs            Claim and execute tasks
Reviews completed work        Log issues, never redesign

• Git worktrees isolate each agent at the filesystem level — no conflicts until human merge time
• File-level lock registry (.agent-locks.json) prevents concurrent edits on the same file
• @agent-contract: interface-only headers let workers reference stable interfaces while implementation is in progress
• Pre-commit hook enforces lock rules at the git level

Quick Start

# Create a worktree for an agent
./agent-worktree.sh create agent-a

# Enter the worktree
cd ../<project>-agent-a

# Install lock-enforcing pre-commit hooks
./install-hooks.sh

# Agent identifies itself
export AGENT_ID="deepseek-agent-a"

# Read task queue, claim a task, implement, commit

# When done, from main repo:
./agent-worktree.sh done agent-a

Directory

.
├── AGENTS.md                  # Coordination protocol (read-only reference)
├── .agent-locks.json          # Live lock registry
├── AGENTS/
│   ├── task-queue.md          # Available / In Progress / Blocked tasks
│   ├── completed.md           # Finished task log
│   └── discoveries.md         # Bugs found outside agent scope
├── docs/                      # Workflow guides
├── src/                       # Source code (agents edit these)
│   └── types/                 # Shared interfaces (high-impact, lock carefully)
├── agent-worktree.sh          # Worktree lifecycle manager
├── lock.sh                    # Lock acquire/release/heartbeat/cleanup
├── master-watch.sh            # tmux-based lock watcher
├── start-session.sh           # Bootstrap full agent session in tmux
├── plan-mode.sh               # Toggle plan mode across agent panes
├── pre-commit                 # Git pre-commit hook (lock enforcement)
├── install-hooks.sh           # Install hooks into all worktrees
└── tsconfig.json              # TypeScript config (strict mode)

Scripts

Script	Purpose
agent-worktree.sh	Create, merge, abandon, or list agent worktrees
lock.sh	Acquire, release, check, heartbeat, cleanup locks
master-watch.sh	Poll .agent-locks.json and auto-resume waiting agents in tmux
start-session.sh	Create a tmux session with agent panes + master watcher
plan-mode.sh	Send Ctrl+I to all agent panes (toggle plan mode)
pre-commit	Git hook — blocks commits to files locked by another agent
install-hooks.sh	Install pre-commit hook into all worktrees

Key Rules

1. One task = one file ownership. No two agents touch the same file.
2. Read .agent-locks.json before every edit.
3. Never read past --- IMPLEMENTATION --- in contract-protected files.
4. Never push your branch. A human squash-merges everything to main.