feat: retire PROJECT_STATE.md — add real-time coordination API protocol
- CLAUDE.md: triggers now query coordination API (/api/coord/status, /api/coord/components, /api/coord/messages) instead of reading PROJECT_STATE.md files - COORDINATION_PROTOCOL.md: new doc covering locks, component states, workflows, work items, and inter-session messages via ClaudeTools API - guru-rmm/PROJECT_STATE.md: marked ARCHIVED, redirects to COORDINATION_PROTOCOL.md for live state Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
@@ -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=<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=<this-session>` 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 <user>` or `## Message for <user>`. 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=<this-session>&unread_only=true
|
||||
```
|
||||
If unread messages exist, display each one prominently before any other work:
|
||||
```
|
||||
============================================================
|
||||
MESSAGE FROM <from_session> — <subject>
|
||||
============================================================
|
||||
<body>
|
||||
============================================================
|
||||
```
|
||||
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 <AUTHOR> (<date>)
|
||||
============================================================
|
||||
<full note content>
|
||||
============================================================
|
||||
```
|
||||
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 <user>` 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)
|
||||
|
||||
|
||||
192
.claude/COORDINATION_PROTOCOL.md
Normal file
192
.claude/COORDINATION_PROTOCOL.md
Normal file
@@ -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=<key>&resource=<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": "<uuid>", ... }` — 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/<id>?session_id=<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": "<uuid>",
|
||||
"project_key": "gururmm",
|
||||
"title": "Write migrations 017-019 for discovery tables",
|
||||
"status": "pending",
|
||||
"priority": 10
|
||||
}
|
||||
```
|
||||
|
||||
**Update work item status:**
|
||||
```
|
||||
PATCH /api/coord/work-items/<id>
|
||||
{ "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=<session_id>&unread_only=true
|
||||
```
|
||||
|
||||
Display each unread message prominently:
|
||||
```
|
||||
============================================================
|
||||
MESSAGE FROM <from_session> — <subject>
|
||||
============================================================
|
||||
<body>
|
||||
============================================================
|
||||
```
|
||||
|
||||
**Mark as read:**
|
||||
```
|
||||
PUT /api/coord/messages/<id>/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=<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.
|
||||
Submodule projects/msp-tools/guru-rmm updated: f6a9a5d0e0...23e0ad1b02
Reference in New Issue
Block a user