diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 804b166..a1194fe 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -213,6 +213,74 @@ At session start: --- +## PROJECT_STATE.md Action Protocol (MANDATORY for any project that has this file) + +This protocol prevents conflicts between concurrent Claude sessions working on the same project. It is **not optional** — follow it for every significant action. + +### What counts as an action + +Any of the following requires the full read → lock → update → release cycle: +- Editing or creating source code files +- Git commit or push +- SSH command that modifies a server (deploy, install, config change, service restart) +- Database schema change or data migration +- Build pipeline modification +- Any operation listed in the project's Component Ownership Map + +Reading files, planning, and answering questions do NOT require a lock. + +### The protocol + +**Step 1 — Read before acting** +Before starting any action, re-read PROJECT_STATE.md: +- Check Active Session Locks: is anything locked that you need to touch? +- If there is a conflicting lock that is NOT stale (< 2 hours old): stop, report the conflict to the user, ask how to proceed. +- If locks are stale (> 2 hours, last updated timestamp): note it to the user, clear the stale row, proceed. + +**Step 2 — Claim your lock** +Immediately before performing the action, add a row to the Active Session Locks table: + +| Session | Working On | Status | Blocks | Started | +|---------|-----------|--------|--------|---------| +| DESKTOP-0O8A1RL/Claude | Brief description | IN_PROGRESS | What others must avoid | HH:MM UTC | + +Use `{machine}/{Claude or agent description}` as Session identifier. +Use the machine name from identity.json. + +**Step 3 — Perform the action** + +**Step 4 — Update on completion OR failure** +Immediately after the action finishes (regardless of outcome): +1. Remove your lock row from Active Session Locks +2. Add an entry to Recent Changes: + - Status: `COMPLETE`, `FAILED`, `PARTIAL`, or `ROLLED_BACK` + - If FAILED or PARTIAL: describe what state things were left in +3. Update the Current Project State table if any component status changed +4. Check off completed items in Pending / Next Up if applicable + +### Anti-patterns (never do these) + +❌ Starting work without reading PROJECT_STATE.md first +❌ Forgetting to claim a lock before touching a component +❌ Leaving a lock row in place after finishing (even on failure) +❌ Skipping the Recent Changes entry when work completes +❌ Letting a lock go stale — update the timestamp if a task takes longer than expected + +### Stale lock rule + +A lock older than 2 hours with no timestamp update is considered abandoned. Any session may clear it and claim the component, but must note in Recent Changes: `[Cleared stale lock from {session}]` before proceeding. + +### Example — correct flow + +``` +[Reading PROJECT_STATE.md — no active locks on server/src/] +[Updating PROJECT_STATE.md — adding lock: "DESKTOP-0O8A1RL/Claude | POST /api/enroll endpoint | IN_PROGRESS | server/src/, migrations/ | 14:32 UTC"] +[... writing code, running migration ...] +[Updating PROJECT_STATE.md — removing lock, adding Recent Changes: "POST /api/enroll implemented | COMPLETE", updating component status: "Enrollment endpoint | IMPLEMENTED"] +``` + +--- + ## Projects **ClaudeTools** -- MSP Work Tracking System (Production-Ready)