azcomputerguru/claudetools
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: apply vix-inspired token efficiency optimizations

Browse Source 
- CLAUDE.md: trim ~45 lines — compress Live State Tracking, Automatic
  Context Loading, File Placement, Ollama sections; add single-agent
  guidance for coupled explore→implement tasks
- CODING_GUIDELINES.md: add GrepAI-first rule with token cost rationale;
  add GuruRMM platform parity matrix and cross-platform coding standards
- OLLAMA.md: expand tier-0 scope to include diff summarization, error
  categorization, agent phase handoff summaries, client email drafts,
  ticket classification with priority

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-05-15 15:50:29 -07:00
parent c5441ade3e
commit 5da286e18f
3 changed files with 147 additions and 97 deletions
Download Patch File Download Diff File Expand all files Collapse all files

129
.claude/CLAUDE.md
View File

@@ -92,6 +92,8 @@ You are NOT an executor. You coordinate specialized agents and preserve your con
**DO NOT** query databases directly. **DO NOT** write production code. **DO NOT** run tests. **DO NOT** commit/push.
**Single-agent for coupled tasks:** For explore → implement or explore → implement → review flows where the context is the same throughout, use one agent across all phases rather than spawning three. Each agent boundary is a cache miss and a context-handoff cost. Spawn separate agents only when tasks are genuinely independent or run in parallel.
### Model Routing (Complexity-Based)
| Tier | Model | When |
@@ -109,34 +111,16 @@ Pass `model: "haiku"` or `model: "opus"` explicitly. Omit for Tier 2. Tier 0 is
## Automatic Context Loading (CRITICAL)
**BEFORE responding to the first message or when switching projects, AUTOMATICALLY load context:**
Load context **before responding** when any trigger fires. Never ask for info that's already in CONTEXT.md.
### Trigger 1: Project Keywords Detected
If user mentions **GuruRMM**, **Dataforth**, **tunnel**, **VASLOG**, **AD2**, **testdatadb**, etc:
1. Read the matching project CONTEXT.md:
- GuruRMM keywords → `projects/msp-tools/guru-rmm/CONTEXT.md`
- Dataforth keywords → `projects/dataforth-dos/CONTEXT.md`
- General → `CONTEXT.md` (root)
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 | Action |
|---------|--------|
| GuruRMM / Dataforth / project keywords | Read `projects/<project>/CONTEXT.md`, query coord API status + components |
| "continue", "resume", "back to", "finish" | Read project CONTEXT.md, check coord API for locks + unread messages |
| Servers, IPs, credentials, deploy questions | Read CONTEXT.md — answer from it, never ask |
| Uncertainty >5% about infra or recent work | Read CONTEXT.md before asking the user |
### 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. 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**:
1. Check current directory for CONTEXT.md, then `projects/*/CONTEXT.md`.
2. Answer from CONTEXT.md — never ask for info that's already there.
### Trigger 4: Uncertainty >5%
If you're <95% certain about infrastructure, recent work, or next steps: read CONTEXT.md before asking the user.
### Anti-Pattern
Never ask "What did we do last time?" or "What's the server IP?" — read the CONTEXT.md first. If it's not there, then ask.
CONTEXT.md locations: `projects/msp-tools/guru-rmm/CONTEXT.md`, `projects/dataforth-dos/CONTEXT.md`, `CONTEXT.md` (root).
---
@@ -167,53 +151,34 @@ 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:
**Coord API is the live source of truth.** API base: `http://172.16.3.30:8001/api/coord` (no auth).
### Session start
```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 unread messages before any work. Mark read: `PUT /api/coord/messages/<id>/read`
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:
### Before significant work — claim a lock
```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
-d '{"project_key":"gururmm","session_id":"DESKTOP-0O8A1RL/claude-main","resource":"server/src","description":"...","ttl_hours":2}'
```
### After Work Completes (or Fails) — MANDATORY
### After work — release lock + update component
```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 DELETE "http://172.16.3.30:8001/api/coord/locks/<id>?session_id=<SESSION_ID>"
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"}'
-d '{"state":"deployed","version":"0.3.0","notes":"...","updated_by":"DESKTOP-0O8A1RL/claude-main"}'
```
### Project Keys and Components to Track
**Softfail:** If API unreachable, continue work and log failed calls to `.claude/coord-queue.jsonl`. Drain on next `/sync`.
### Project keys
| project_key | Components | States |
|-------------|------------|--------|
@@ -222,32 +187,7 @@ curl -s -X PUT "http://172.16.3.30:8001/api/coord/components/gururmm/server" \
| `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`
Full protocol + inter-session messaging: `.claude/COORDINATION_PROTOCOL.md`
---
@@ -313,25 +253,24 @@ Vault structure: `infrastructure/`, `clients/`, `services/`, `projects/`, `msp-t
## File Placement
- **Dataforth DOS work** → `projects/dataforth-dos/`
- **ClaudeTools API code** → `api/`, `migrations/`
- **GuruRMM work** → `projects/msp-tools/guru-rmm/` (code reference only — submodule, stale copy of `azcomputerguru/gururmm`)
- **GuruRMM session logs** → `session-logs/` (root, in claudetools — NOT committed to the gururmm submodule)
- **Client work** → `clients/[client-name]/`
- **Session logs** → project or client `session-logs/` subfolder; general → root `session-logs/`
- **Full guide:** `.claude/FILE_PLACEMENT_GUIDE.md`
- GuruRMM work → `projects/msp-tools/guru-rmm/` (submodule, stale reference copy of `azcomputerguru/gururmm`)
- GuruRMM session logs → root `session-logs/` (NOT the submodule)
- Client work → `clients/[client-name]/`
- Session logs → project/client `session-logs/` subfolder; general work → root `session-logs/`
- Full guide: `.claude/FILE_PLACEMENT_GUIDE.md`
---
## Local AI (Ollama)
Tier 0 — **Ollama is the documentation engine.** Route prose generation through it: commit messages, ticket comments, client notes, code docs. Claude reviews output, owns credentials/facts/execution. Session log narratives are written directly by Claude (Ollama too slow for /save).
Tier 0 — **Ollama is the documentation and classification engine.** Route prose, summaries, and classification through it; Claude reviews before writing or posting.
- **DESKTOP-0O8A1RL:** `http://localhost:11434`
- **Other machines:** `http://100.92.127.64:11434` (Tailscale required)
- **Models:** `qwen3:14b` (all documentation/prose), `codestral:22b` (code suggestions — always review)
- **Warm-start:** GrepAI keeps the Ollama service running; qwen3 VRAM swap is ~5s worst case, not 50s
- **Full reference:** `.claude/OLLAMA.md` (documentation engine scope, model selection, review policy)
| Machine | Endpoint |
|---------|----------|
| DESKTOP-0O8A1RL | `http://localhost:11434` |
| Other | `http://100.92.127.64:11434` (Tailscale) |
Models: `qwen3:14b` (docs, prose, classification, summarization), `codestral:22b` (code suggestions — always review). Full reference: `.claude/OLLAMA.md`
### GrepAI (Semantic Code Search)