From 9855c6bb0af324854883255bd76e0a0fb48fbcce Mon Sep 17 00:00:00 2001 From: Mike Swanson Date: Tue, 12 May 2026 08:41:28 -0700 Subject: [PATCH] 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 | 87 ++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 86 insertions(+), 1 deletion(-) diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 337e53c..ac3a0c8 100644 --- a/.claude/CLAUDE.md +++ b/.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=&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=" +``` + +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//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/?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/` | `(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)