diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index b66fb52..337e53c 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -111,14 +111,14 @@ If user mentions **GuruRMM**, **Dataforth**, **tunnel**, **VASLOG**, **AD2**, ** - GuruRMM keywords → `projects/msp-tools/guru-rmm/CONTEXT.md` - Dataforth keywords → `projects/dataforth-dos/CONTEXT.md` - General → `CONTEXT.md` (root) -2. If `PROJECT_STATE.md` exists alongside CONTEXT.md, read it **and** `.claude/PROJECT_STATE_PROTOCOL.md`. +2. Query the coordination API for current state: `GET http://172.16.3.30:8001/api/coord/status` (no auth needed for status) and `GET /api/coord/components?project_key=`. 3. THEN respond with full context. ### Trigger 2: Continuation/Resume Words If user says "continue", "let's work on", "back to", "resume", "finish": 1. Detect project from message, read project CONTEXT.md. -2. If PROJECT_STATE.md exists, read it and `.claude/PROJECT_STATE_PROTOCOL.md`. -3. Check "Current State" and "Recent Session Logs" sections, then proceed. +2. Query coordination API: `GET /api/coord/status` for active locks and in-progress workflows; `GET /api/coord/messages/unread-count?session_id=` for pending messages. +3. Check for unread messages and display them before proceeding. ### Trigger 3: Infrastructure/Deployment Questions If user asks about **servers**, **databases**, **credentials**, **deploy**, **IP**, **password**: @@ -163,23 +163,25 @@ Never ask "What did we do last time?" or "What's the server IP?" — read the CO - **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-User Messages (MANDATORY) +### Cross-Session Messages (MANDATORY) -After every `/sync` — and whenever reading any session log from another user — scan for sections named `## Note for ` or `## Message for `. If found: +At session start and after every `/sync`, check for unread messages: +``` +GET http://172.16.3.30:8001/api/coord/messages?to_session=&unread_only=true +``` +If unread messages exist, display each one prominently before any other work: +``` +============================================================ +MESSAGE FROM — +============================================================ + +============================================================ +``` +Mark as read via `PUT /api/coord/messages/{id}/read` after displaying. -1. Display the full note content **prominently at the top of the response**, before sync status or anything else, formatted as: - ``` - ============================================================ - MESSAGE FROM () - ============================================================ - - ============================================================ - ``` -2. Explicitly address each action item or question in the note before moving on. -3. Do not bury these in the sync summary or skip them because other work is in progress. - -This applies to ALL session logs pulled during sync, not just the most recent one. +Also scan session logs pulled during `/sync` for legacy `## Note for ` sections (transitional — older sessions still use markdown). --- @@ -188,7 +190,8 @@ This applies to ALL session logs pulled during sync, not just the most recent on When user references previous work, use `/context` command. Never ask for info in: - `credentials.md` — Infrastructure reference (being migrated to SOPS vault) - `session-logs/` — Daily work logs (also in `projects/*/session-logs/` and `clients/*/session-logs/`) -- `projects/*/PROJECT_STATE.md` and `clients/*/PROJECT_STATE.md` — per-project state (active locks, current state, recent changes). Loaded automatically per Trigger 2 above; protocol at `.claude/PROJECT_STATE_PROTOCOL.md` +- **Coordination API** — current locks, component states, workflows, messages: `GET http://172.16.3.30:8001/api/coord/status` +- `projects/*/PROJECT_STATE.md` — ARCHIVED. Read-only historical reference. Do not edit. Use coordination API for live state. ### Credential Access (SOPS Vault) diff --git a/.claude/COORDINATION_PROTOCOL.md b/.claude/COORDINATION_PROTOCOL.md new file mode 100644 index 0000000..e3f4c47 --- /dev/null +++ b/.claude/COORDINATION_PROTOCOL.md @@ -0,0 +1,192 @@ +# Coordination Protocol + +Cross-session coordination uses the ClaudeTools API at `http://172.16.3.30:8001/api/coord/`. This replaces PROJECT_STATE.md files. + +All endpoints require a `session_id` string identifying the current session (e.g., `DESKTOP-0O8A1RL/claude-main`). No auth token required for coordination endpoints. + +--- + +## When a Lock Is Required + +- 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 + +Reading files, planning, and answering questions do NOT require a lock. + +--- + +## Lock Lifecycle + +**Step 1 — Check for conflicts** +``` +GET /api/coord/locks?project_key=&resource= +``` +- Active lock present: stop, report to user, ask how to proceed. +- Lock `acquired_at` > 2 hours ago: note it, release it (Step 2 below), proceed. + +**Step 2 — Claim your lock** +``` +POST /api/coord/locks +{ + "project_key": "gururmm", + "session_id": "DESKTOP-0O8A1RL/claude-main", + "resource": "server/src/api/credentials.rs", + "description": "Adding credential endpoints", + "ttl_hours": 2 +} +``` +Response: `{ "id": "", ... }` — save the `id` for release. + +`ttl_hours`: use 2 for normal work; 0 for no expiry (use sparingly). + +**Step 3 — Do the work** + +**Step 4 — Release the lock** +``` +DELETE /api/coord/locks/?session_id= +``` +Release on completion AND on failure. Only the claiming session may release. + +**Stale lock rule:** A lock with `acquired_at` older than 2 hours and no activity update is abandoned. Release it, then proceed. + +--- + +## Component States + +Record the current status of named system components so all sessions share a live view. + +**Upsert a component state:** +``` +PUT /api/coord/components +{ + "project_key": "gururmm", + "component": "server", + "state": "deployed", + "version": "0.3.0", + "notes": "Deployed 2026-05-12; credential store live", + "updated_by": "DESKTOP-0O8A1RL/claude-main" +} +``` + +Valid states (convention — not enforced): `building`, `built`, `deploying`, `deployed`, `degraded`, `unknown` + +**Read all component states for a project:** +``` +GET /api/coord/components?project_key=gururmm +``` + +--- + +## Workflows and Work Items + +Use workflows to track multi-step initiatives that span sessions or days. + +**Create a workflow:** +``` +POST /api/coord/workflows +{ + "project_key": "gururmm", + "name": "Network Discovery Phase 1", + "description": "TCP probe scanner + DB layer + API + dashboard", + "status": "planning", + "created_by": "DESKTOP-0O8A1RL/claude-main" +} +``` + +**Add work items to a workflow:** +``` +POST /api/coord/work-items +{ + "workflow_id": "", + "project_key": "gururmm", + "title": "Write migrations 017-019 for discovery tables", + "status": "pending", + "priority": 10 +} +``` + +**Update work item status:** +``` +PATCH /api/coord/work-items/ +{ "status": "completed" } +``` + +Workflow statuses: `planning`, `active`, `blocked`, `completed`, `cancelled` +Work item statuses: `pending`, `in_progress`, `blocked`, `completed`, `cancelled` + +--- + +## Inter-Session Messages + +Send targeted messages between sessions or broadcast to a project. + +**Send a message:** +``` +POST /api/coord/messages +{ + "from_session": "DESKTOP-0O8A1RL/claude-main", + "to_session": "HOWARD-HOME/claude-main", // omit for broadcast + "project_key": "gururmm", + "subject": "macOS build pipeline ready for wiring", + "body": "build-agents.sh updated. Section marked TODO-MACOS. Wire in from your end." +} +``` + +**Check for unread messages (do this at session start):** +``` +GET /api/coord/messages?to_session=&unread_only=true +``` + +Display each unread message prominently: +``` +============================================================ +MESSAGE FROM — +============================================================ + +============================================================ +``` + +**Mark as read:** +``` +PUT /api/coord/messages//read +``` + +--- + +## Status Overview + +Quick snapshot of everything active: +``` +GET /api/coord/status +``` +Returns: active locks, recent component state changes, active workflows, unread message count. + +--- + +## Session Cleanup + +When a session ends cleanly, release all its locks: +``` +DELETE /api/coord/locks?session_id=&release_all=true +``` + +--- + +## project_key Slugs + +| Slug | Project | +|------|---------| +| `gururmm` | GuruRMM server + dashboard | +| `claudetools` | ClaudeTools API + coordination system | +| `dataforth-dos` | Dataforth DOS project | + +Free-form — add new slugs as needed. Does NOT foreign-key to the projects table. + +--- + +## Migration Note + +`projects/*/PROJECT_STATE.md` files are ARCHIVED — read-only historical reference. Do not edit them. Use this API for all live coordination going forward. diff --git a/projects/msp-tools/guru-rmm b/projects/msp-tools/guru-rmm index f6a9a5d..23e0ad1 160000 --- a/projects/msp-tools/guru-rmm +++ b/projects/msp-tools/guru-rmm @@ -1 +1 @@ -Subproject commit f6a9a5d0e0b7d13c1c14830f1bbe309267b9e544 +Subproject commit 23e0ad1b0228a2912137a77a931d2e54aa3b529f