sync: auto-sync from DESKTOP-0O8A1RL at 2026-05-12 08:41:28

Author: Mike Swanson
Machine: DESKTOP-0O8A1RL
Timestamp: 2026-05-12 08:41:28

.claude/CLAUDE.md

@@ -158,12 +158,97 @@ Never ask "What did we do last time?" or "What's the server IP?" — read the CO
 
 ---
 
+## Live State Tracking (ALL Projects)
+
+**The ClaudeTools coordination API is the live source of truth for ALL projects.** Every agent session MUST use it — not PROJECT_STATE.md files (those are archived).
+
+API base: `http://172.16.3.30:8001/api/coord` | No auth required for coord endpoints.
+
+### Session Start Protocol (MANDATORY)
+
+Run these at the beginning of every session:
+
+```bash
+# 1. Check for messages addressed to this session or broadcast
+curl -s "http://172.16.3.30:8001/api/coord/messages?to_session=<SESSION_ID>&unread_only=true"
+
+# 2. Check overall live status
+curl -s "http://172.16.3.30:8001/api/coord/status"
+
+# 3. Check active locks on any project you plan to touch
+curl -s "http://172.16.3.30:8001/api/coord/locks?project_key=<KEY>"
+```
+
+Display any unread messages prominently before any other work. Mark them read:
+```bash
+curl -s -X PUT "http://172.16.3.30:8001/api/coord/messages/<id>/read"
+```
+
+### Before Significant Work (MANDATORY)
+
+Claim a lock before editing code, running migrations, deploying, or touching shared resources:
+```bash
+curl -s -X POST http://172.16.3.30:8001/api/coord/locks \
+  -H "Content-Type: application/json" \
+  -d '{"project_key":"gururmm","session_id":"DESKTOP-0O8A1RL/claude-main","resource":"server/src","description":"Adding credential endpoints","ttl_hours":2}'
+# Save the returned "id" for release
+```
+
+### After Work Completes (or Fails) — MANDATORY
+
+```bash
+# Release lock
+curl -s -X DELETE "http://172.16.3.30:8001/api/coord/locks/<lock_id>?session_id=<SESSION_ID>"
+
+# Update component state
+curl -s -X PUT "http://172.16.3.30:8001/api/coord/components/gururmm/server" \
+  -H "Content-Type: application/json" \
+  -d '{"state":"deployed","version":"0.3.0","notes":"Credential store live","updated_by":"DESKTOP-0O8A1RL/claude-main"}'
+```
+
+### Project Keys and Components to Track
+
+| project_key | Components | States |
+|-------------|------------|--------|
+| `gururmm` | `server`, `agents`, `dashboard`, `db_migrations` | `building`, `built`, `deploying`, `deployed`, `degraded` |
+| `claudetools` | `api`, `db_migrations`, `coord_api` | `deploying`, `deployed`, `degraded` |
+| `dataforth-dos` | `app`, `db` | `active`, `idle`, `degraded` |
+| `clients/<name>` | `(free-form)` | `(free-form)` |
+
+### Softfail When Coordination API Is Unavailable
+
+If the coord API is unreachable (connection refused, timeout, or 5xx):
+1. **Do not block work.** Continue with the task.
+2. Log the failed call to `.claude/coord-queue.jsonl` (one JSON object per line):
+   ```json
+   {"ts":"2026-05-12T15:30:00Z","method":"PUT","path":"/api/coord/components/gururmm/server","body":{...}}
+   ```
+3. On the next session start or `/sync`, drain the queue:
+   ```bash
+   # For each line in coord-queue.jsonl, replay the call, then remove the file if all succeed
+   ```
+
+If coord API returns 503 with `Retry-After`, wait that many seconds and retry once before queuing locally.
+
+### Inter-Session Messages
+
+Send messages to specific sessions or broadcast to a project:
+```bash
+curl -s -X POST http://172.16.3.30:8001/api/coord/messages \
+  -H "Content-Type: application/json" \
+  -d '{"from_session":"DESKTOP-0O8A1RL/claude-main","to_session":"HOWARD-HOME/claude-main","project_key":"gururmm","subject":"macOS build ready","body":"build-agents.sh marked TODO-MACOS."}'
+# Omit to_session for a broadcast to everyone watching the project
+```
+
+Full protocol reference: `.claude/COORDINATION_PROTOCOL.md`
+
+---
+
 ## Automatic Behaviors
 
 - **Frontend Design:** Auto-invoke `/frontend-design` skill after ANY UI change (HTML/CSS/JSX/styling)
 - **Sequential Thinking:** Use for genuine complexity — rejection loops, 3+ critical issues, architectural decisions
 - **Task Management:** Complex work (>3 steps) → TaskCreate. Persist to `.claude/active-tasks.json`.
-- **Coordination:** Before touching shared resources (server code, migrations, build pipeline) → claim a lock via `POST /api/coord/locks`. Release on completion via `DELETE /api/coord/locks/{id}`. See `.claude/COORDINATION_PROTOCOL.md`.
 
 ### Cross-Session Messages (MANDATORY)