Shared State

"Single-writer principle prevents race conditions. Use Edit tool for atomic updates."

Core Principle

Each file has a primary owner to avoid conflicts. Only the owner may write to that file.

File Ownership Matrix (v2.0 - Per-Agent State Files)

State Files

Session Files

Key Changes in v2.0

OLD (v1.x):

• Workers read prd.json (110KB) for status
• Workers updated prd.json.agents.{role} directly

NEW (v2.0):

• Workers read ONLY their ~1KB state file
• Workers update ONLY their state file
• PM reads all state files and syncs to prd.json
• Workers NEVER read prd.json (saves 109KB per worker read)

What Each Agent CAN Write To

PM Coordinator

Developer Worker

QA Worker

Game Designer Worker

Tech Artist Worker

Commit Permissions

ALL agents MUST commit their file changes.

Commit Format (from shared-core):

[ralph] [{AGENT}] {TASK_ID}: {Brief description}

- Change 1
- Change 2

PRD: {TASK_ID} | Agent: {AGENT} | Iteration: {N}

No Commit Exceptions:

• Heartbeat updates (prd.json.agents.{agent}.lastSeen timestamps)
• Temporary message files (deleted after processing)

Atomic Updates Using Edit Tool

The Edit tool handles atomic writes automatically. No manual temp file pattern needed.

Using Edit Tool

Step 1: Read the file

Read: prd.json

Step 2: Use Edit tool to make changes

Edit: prd.json
  Replace: "status": "pending"
  With: "status": "assigned"

The Edit tool internally:

1. Reads the file
2. Applies your changes
3. Writes atomically (temp file + rename)

Edit Tool vs Manual Pattern

❌ DO NOT use manual temp file pattern:

# Don't do this anymore
echo "$NEW_STATE" > file.json.tmp && mv file.json.tmp file.json

✅ DO use Edit tool instead:

Read: file.json
Edit: file.json

Master Branch Coordination (Worktree System)

When working in a git worktree, ALL coordination files must be updated in the master branch.

Worktree system uses isolated branches for code/assets, but ALL state coordination must happen in master branch to ensure:

• PM sees worker status immediately
• Watchdog monitors heartbeats
• Message queue works for all agents

What Goes to Master Branch:

What Goes to Worktree Branch:

From worktree, access master branch:

Read: ../agentic-threejs/prd.json
Edit: ../agentic-threejs/prd.json

Concurrency Rules

1. Read-modify-write atomically — Use Edit tool
2. Only update fields you own — Never overwrite another agent's data
3. Append-only for logs — Never delete or reorder entries
4. Retry on conflict — If write fails, re-read and retry once
5. Use per-agent files for frequently updated data

Conflict Resolution

If you encounter a write conflict:

1. Re-read the file — Get latest state
2. Re-apply your changes — On top of new state
3. Write again — Using Edit tool
4. If still conflicts — Log issue, wait 30 seconds

When Atomic Updates Matter Most

• High-contention files — prd.json (session state, agent status, task items)
• Shared log files — Use append-only instead
• PRD file — Multiple agents may update different fields

When Atomic Updates Don't Apply

• Agent-specific files — {agent}-progress.txt (only one writer)
• Append-only logs — Don't need atomic pattern
• New file creation — No existing content to protect

Logging Best Practices

• Use structured logs — JSON format where possible
• Include timestamps — ISO 8601 format
• Include agent identifier — Who made the change
• Append only — Never rewrite log files
• Archive, don't delete — PM may archive old logs

Anti-Patterns

References

• shared-core — Commit format, session structure
• shared-messaging — Message queue ownership
• shared-worktree — Git worktree setup