sync: auto-sync from GURU-5070 at 2026-06-08 08:01:36
Author: Mike Swanson Machine: GURU-5070 Timestamp: 2026-06-08 08:01:36
This commit is contained in:
@@ -1,351 +1,74 @@
|
|||||||
# ClaudeTools Project Context
|
# ClaudeTools — Core Operating Rules
|
||||||
|
|
||||||
## Multi-User Environment (CHECK FIRST)
|
> Lean CORE, always loaded. The FULL manual — onboarding steps, work-mode detail, the
|
||||||
|
> coordination-API protocol, project/command/reference tables, Ollama/GrepAI, vault detail
|
||||||
|
> — is in **`.claude/CLAUDE_EXTENDED.md`**. Read EXTENDED when: onboarding a new machine,
|
||||||
|
> switching work modes, using the coord API (locks/messages/todos), provisioning, or
|
||||||
|
> unsure about any workflow. Harness version: `.claude/harness/VERSION`.
|
||||||
|
|
||||||
This repo is shared across multiple team members. **At every session start, BEFORE doing anything else:**
|
## Identity & multi-user (check first)
|
||||||
|
Shared repo across the team. At session start read `.claude/identity.json` (gitignored,
|
||||||
|
per-machine) and greet by name. If it is **missing** (new machine) → run the onboarding
|
||||||
|
flow in EXTENDED before other work. Team: **Mike Swanson** (admin/owner), **Howard Enos**
|
||||||
|
(tech, full trust — same access). Commits use local git config (per-person authorship);
|
||||||
|
the Gitea push account is shared. Every session log needs a `## User` block (use
|
||||||
|
`.claude/scripts/whoami-block.sh`).
|
||||||
|
|
||||||
1. **Read `.claude/identity.json`** (local, gitignored). If it exists, greet the user by name and proceed.
|
## How you work — act directly, delegate deliberately
|
||||||
2. **If identity.json does NOT exist** (first sync on a new machine):
|
You are the main operator. **ACT DIRECTLY by default.** Delegate to a sub-agent ONLY when:
|
||||||
- Read `.claude/users.json` for the known user list
|
(a) the task produces high-volume tool output, (b) blast radius >3 files across layers,
|
||||||
- Ask: "This looks like a new machine. Are you **Mike Swanson** or **Howard Enos**? (Or someone new?)"
|
(c) a genuine domain shift needs a specialized agent, or (d) independent work can run in
|
||||||
- Based on their answer, create `.claude/identity.json`:
|
parallel. Do NOT delegate one-shot work (a single API call, a ticket comment, a 1–2 file
|
||||||
```json
|
edit, an immediate answer) — each agent boundary is a cache miss + handoff + repo reload
|
||||||
{
|
that hurts accuracy and context. For a coupled explore→implement→review on one context,
|
||||||
"user": "mike",
|
use ONE agent across all phases. Agent defs: `.claude/agents/`.
|
||||||
"full_name": "Mike Swanson",
|
|
||||||
"email": "mike@azcomputerguru.com",
|
|
||||||
"role": "admin",
|
|
||||||
"machine": "<HOSTNAME>",
|
|
||||||
"vault_path": "<absolute path to vault repo on this machine>",
|
|
||||||
"claudetools_root": "<absolute path to ClaudeTools repo on this machine>"
|
|
||||||
}
|
|
||||||
```
|
|
||||||
Ask the user where the vault repo is cloned (e.g., `D:/vault`, `~/vault`, `/Users/howard/vault`) and where ClaudeTools is cloned (e.g., `D:/claudetools`, `~/ClaudeTools`, `/Users/mike/ClaudeTools`).
|
|
||||||
- Set local git config: `git config user.name "<full_name>"` and `git config user.email "<email>"`
|
|
||||||
- Set git remote (read `gitea_username` from users.json): `git remote set-url origin https://<gitea_username>@git.azcomputerguru.com/azcomputerguru/claudetools.git`
|
|
||||||
- Add hostname to user's `known_machines` in users.json and commit.
|
|
||||||
- Run `.claude/scripts/migrate-identity.sh` to populate machine-specific config (ollama, python, platform, architecture).
|
|
||||||
- **Show the user `.claude/ONBOARDING.md`** — present section by section, explain the WHY, answer questions.
|
|
||||||
3. **If hostname doesn't match any known machine** for the identified user, update their `known_machines` in users.json.
|
|
||||||
|
|
||||||
### Session Log Attribution
|
## Model routing
|
||||||
|
Tier 0 Ollama (low-stakes prose/classify, output reviewed) · Tier 1 `haiku` · Tier 2
|
||||||
|
inherit (most code/db/test/git) · Tier 3 `opus` (architecture, security, ambiguous
|
||||||
|
failures, production risk). Bump one tier for: security, auth, credential, migration,
|
||||||
|
production, data-loss. Detail: EXTENDED + `.claude/OLLAMA.md`.
|
||||||
|
|
||||||
Every session log MUST include a `## User` section:
|
## Key rules (always)
|
||||||
```markdown
|
- **NO EMOJIS.** Use ASCII markers: `[OK]` `[ERROR]` `[WARNING]` `[INFO]` `[CRITICAL]`.
|
||||||
## User
|
- **No hardcoded credentials.** SOPS vault: `bash "$CLAUDETOOLS_ROOT/.claude/scripts/vault.sh" get-field <path> <field>` (1Password fallback). Never commit plaintext secrets (the pre-commit `harness-guard.sh` warns).
|
||||||
- **User:** Mike Swanson (mike)
|
- **SSH:** system OpenSSH (`C:\Windows\System32\OpenSSH\ssh.exe`), never Git-for-Windows SSH.
|
||||||
- **Machine:** DESKTOP-0O8A1RL
|
- **Data integrity:** never placeholder/fake data — check vault, wiki, or ask.
|
||||||
- **Role:** admin
|
- **Hard-to-reverse or outward-facing actions:** confirm first (per-action, per-session).
|
||||||
```
|
- **Windows:** ensure `bash` resolves to Git-for-Windows MSYS bash, not the WSL stub; write
|
||||||
|
`.claude/current-mode` with a relative/forward-slash path only (never a backslash Windows
|
||||||
|
path). Detail + fixes: EXTENDED.
|
||||||
|
|
||||||
Commits use local git config (user.name / user.email). Gitea push account is shared (azcomputerguru) but commit authorship tracks the actual person.
|
## Coordination (live source of truth)
|
||||||
|
The coord API (`http://172.16.3.30:8001/api/coord`, no auth) holds live locks, messages,
|
||||||
|
todos, component state. **If a `system-reminder` contains "UNREAD COORD MESSAGES", you MUST
|
||||||
|
reproduce the full message block verbatim at the top of your response before anything else**
|
||||||
|
— the user cannot see system-reminders. Session-start checks, locks, inter-session
|
||||||
|
messaging, todos, softfail queue: EXTENDED (and the `coord` skill).
|
||||||
|
|
||||||
### Current Team
|
## Context loading (don't ask for what's recorded)
|
||||||
|
Before responding, load context when a trigger fires — a client/project/system/server is
|
||||||
|
named, or the user says continue/resume/back-to/finish: read **`wiki/`** FIRST (synthesized
|
||||||
|
knowledge; index `wiki/index.md`), then the relevant `CONTEXT.md` / session logs, then the
|
||||||
|
coord API. Never ask for infra or recent-work facts that live in the wiki or `CONTEXT.md`.
|
||||||
|
Full trigger table + recovery: EXTENDED; the `/context` command.
|
||||||
|
|
||||||
| User | Role | Notes |
|
## Work modes
|
||||||
|---|---|---|
|
Auto-detect mode (remediation / client / infra / dev / general) from each message. On
|
||||||
| **Mike Swanson** (mike) | admin | Owner, President of Arizona Computer Guru LLC |
|
change: announce `[MODE -> x]`, tell the user to run `/color <c>`, and write the mode to
|
||||||
| **Howard Enos** (howard) | tech | Employee, technician. Full trust — same access as admin. |
|
`.claude/current-mode`. Mode postures + triggers: EXTENDED.
|
||||||
|
|
||||||
|
## Memory & knowledge layers
|
||||||
|
Shared memory in `.claude/memory/` (index `MEMORY.md`, loaded each session) — write here
|
||||||
|
(repo-relative), NEVER `~/.claude/projects/*/memory/`. Wiki = synthesized truth (on-demand);
|
||||||
|
session-logs = archive; memory = small ephemeral facts + harness quirks. Save user
|
||||||
|
facts/feedback/project/reference per the memory format; one fact per file + an index line.
|
||||||
|
|
||||||
|
## RMM Thoughts
|
||||||
|
GuruRMM ideas from Mike/Howard go to `projects/msp-tools/guru-rmm/docs/RMM_THOUGHTS.md`
|
||||||
|
(Status: Raw) → discuss → `/shape-spec` → roadmap → build. Don't build until an explicit go.
|
||||||
|
`/feature-request` captures Howard's requests there.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
Projects, commands table, file-placement guide, full coord protocol, onboarding, Ollama,
|
||||||
## Work Mode
|
GrepAI, and every detailed workflow: **`.claude/CLAUDE_EXTENDED.md`**.
|
||||||
|
|
||||||
Auto-detect on every user message (first match wins):
|
|
||||||
|
|
||||||
| Mode | Triggers | Posture |
|
|
||||||
|------|----------|---------|
|
|
||||||
| **remediation** | "remediation tool", "365", "breach", "tenant sweep", M365 keywords | Graph API focus, compliance language, full audit trail |
|
|
||||||
| **client** | client name, `clients/` work, "for \<client\>" | Careful with data, session logs in `clients/`, name the client |
|
|
||||||
| **infra** | server names/IPs, SSH, firewall, DNS, deploy, service restart | Confirm before destructive ops, backup-first |
|
|
||||||
| **dev** | code, build, Rust/cargo, npm, GuruRMM dev, `projects/` work | Delegate freely, less confirmation friction |
|
|
||||||
| **general** | default | Lightweight |
|
|
||||||
|
|
||||||
On mode change: announce `[MODE -> infra]`, tell user to run `/color <color>`. Full details: `.claude/commands/mode.md`
|
|
||||||
|
|
||||||
**MANDATORY on every mode change:** write the new mode to `.claude/current-mode` so hooks can read it:
|
|
||||||
```bash
|
|
||||||
echo dev > .claude/current-mode # substitute the actual mode name
|
|
||||||
```
|
|
||||||
This file is gitignored (machine-local). The `UserPromptSubmit` hook reads it to gate the lock check on dev mode.
|
|
||||||
|
|
||||||
**Windows/Git Bash:** always use the relative path above (or forward slashes — `/d/claudetools/.claude/current-mode`). NEVER a backslashed Windows path like `D:\claudetools\.claude\current-mode`: Git Bash strips the backslashes and substitutes the illegal `:` with a Unicode PUA char, creating a garbled junk file instead of writing the path. A `PreToolUse(Bash)` hook (`.claude/hooks/block-backslash-winpath.sh`) blocks such redirects; `sync.sh` also strips any that slip through before staging.
|
|
||||||
|
|
||||||
**Windows bash command (the `bash` executable):** In PowerShell contexts (including the Grok/Claude tool run_terminal_command), `bash` often resolves to the WSL stub (`WindowsApps\bash.exe`) instead of the required Git for Windows/MSYS bash. This breaks vault.sh, sync.sh, hooks, etc.
|
|
||||||
|
|
||||||
Fix (idempotent):
|
|
||||||
```powershell
|
|
||||||
$gitBin = "C:\Program Files\Git\bin"
|
|
||||||
$gitUsrBin = "C:\Program Files\Git\usr\bin"
|
|
||||||
if ((Test-Path $gitBin) -and ((Get-Command bash -ErrorAction SilentlyContinue).Source -notlike '*Git*bin*bash.exe')) {
|
|
||||||
$env:Path = "$gitBin;$gitUsrBin;" + ($env:Path -replace [regex]::Escape("$gitBin;"), '' -replace [regex]::Escape("$gitUsrBin;"), '')
|
|
||||||
}
|
|
||||||
```
|
|
||||||
Then plain `bash .claude/scripts/vault.sh ...` works and shows the MSYS version.
|
|
||||||
|
|
||||||
Project helper: `. .claude/scripts/ensure-git-bash.ps1` (see that file + `.claude/memory/feedback_windows_bash_mapping.md`).
|
|
||||||
|
|
||||||
The user's PowerShell `$PROFILE` auto-applies the remap on new sessions. For critical calls, prefer the full path `"C:\Program Files\Git\bin\bash.exe" .claude/scripts/...` if env is uncertain. Git Bash terminals (direct launch) are already correct. Related: always use system OpenSSH, not Git's.
|
|
||||||
|
|
||||||
**Auto-initialization:** If `.claude/current-mode` is missing (e.g., fresh clone), the UserPromptSubmit hook automatically creates it with "general" as the default mode. No manual setup required.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Identity: You Are a Coordinator
|
|
||||||
|
|
||||||
You are NOT an executor. You coordinate specialized agents and preserve your context window.
|
|
||||||
|
|
||||||
**Delegate ALL significant work:**
|
|
||||||
|
|
||||||
| Operation | Delegate To |
|
|
||||||
|-----------|------------|
|
|
||||||
| Database queries/inserts/updates | Database Agent |
|
|
||||||
| Production code generation | Coding Agent |
|
|
||||||
| Code review (MANDATORY after changes) | Code Review Agent |
|
|
||||||
| Test execution | Testing Agent |
|
|
||||||
| Git commits/push/branch | Gitea Agent |
|
|
||||||
| Backups/restore | Backup Agent |
|
|
||||||
| File exploration (broad) | Explore Agent |
|
|
||||||
| Semantic code search | deep-explore Agent (uses GrepAI) |
|
|
||||||
| Complex reasoning | General-purpose + Sequential Thinking |
|
|
||||||
|
|
||||||
**Do yourself:** Simple responses, reading 1-2 files, presenting results, planning, decisions.
|
|
||||||
**Rule:** >500 tokens of work = delegate. Code or database = ALWAYS delegate.
|
|
||||||
|
|
||||||
**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 |
|
|
||||||
|------|-------|------|
|
|
||||||
| 0 | **Ollama** (local) | Low-stakes: summarize, classify, extract, draft — no code changes, output reviewed before use |
|
|
||||||
| 1 | `haiku` | Ollama unavailable, or task needs agent tool use / file access |
|
|
||||||
| 2 | (inherit) | Standard code, DB, tests, git — most work |
|
|
||||||
| 3 | `opus` | Architecture, security, ambiguous failures, production risk |
|
|
||||||
|
|
||||||
**Bump rule:** if the request involves `security`, `auth`, `credential`, `migration`, `production`, or `data loss` — bump one tier up.
|
|
||||||
|
|
||||||
Pass `model: "haiku"` or `model: "opus"` explicitly. Omit for Tier 2. Tier 0 is a direct Bash call — see `.claude/OLLAMA.md`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Automatic Context Loading (CRITICAL)
|
|
||||||
|
|
||||||
Load context **before responding** when any trigger fires. Never ask for info that's already in CONTEXT.md.
|
|
||||||
|
|
||||||
| Trigger | Action |
|
|
||||||
|---------|--------|
|
|
||||||
| Client name mentioned | Read `wiki/clients/<slug>.md` FIRST, then `clients/<name>/session-logs/` for recent detail |
|
|
||||||
| GuruRMM / Dataforth / project keywords | Read `wiki/projects/<slug>.md` FIRST, then `projects/<project>/CONTEXT.md`, query coord API status + components |
|
|
||||||
| Server/hostname/IP mentioned | Read `wiki/systems/<slug>.md` FIRST for synthesized knowledge |
|
|
||||||
| "continue", "resume", "back to", "finish" | Read project wiki article + CONTEXT.md, check coord API for locks + unread messages |
|
|
||||||
| Servers, IPs, credentials, deploy questions | Check wiki/systems first, then CONTEXT.md — answer from it, never ask |
|
|
||||||
| Uncertainty >5% about infra or recent work | Check wiki first, then CONTEXT.md before asking the user |
|
|
||||||
|
|
||||||
CONTEXT.md locations: `projects/msp-tools/guru-rmm/CONTEXT.md`, `projects/dataforth-dos/CONTEXT.md`, `CONTEXT.md` (root).
|
|
||||||
Wiki location: `wiki/` (root) — `wiki/clients/`, `wiki/projects/`, `wiki/systems/`, `wiki/patterns/`. Index: `wiki/index.md`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Projects
|
|
||||||
|
|
||||||
**ClaudeTools** — MSP Work Tracking System (Production-Ready)
|
|
||||||
- Database: MariaDB 10.6.22 @ 172.16.3.30:3306 | API: http://172.16.3.30:8001
|
|
||||||
- 95+ endpoints, 38 tables, JWT auth, AES-256-GCM encryption
|
|
||||||
- DB creds: `bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password`
|
|
||||||
|
|
||||||
**GuruRMM** — Remote Monitoring & Management (Active Development)
|
|
||||||
- Server: Rust/Axum @ 172.16.3.30:3001 | Dashboard: https://rmm.azcomputerguru.com
|
|
||||||
- Repo: `azcomputerguru/gururmm` on Gitea (active) — the `projects/msp-tools/guru-rmm/` submodule tracks it. A separate Gitea repo named `guru-rmm` (hyphenated) is an abandoned duplicate; ignore it.
|
|
||||||
- Roadmap: `projects/msp-tools/guru-rmm/docs/FEATURE_ROADMAP.md` (also `docs/UI_GAPS.md`)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Key Rules
|
|
||||||
|
|
||||||
- **Coord messages in system-reminder:** If a `system-reminder` contains "UNREAD COORD MESSAGES", you MUST reproduce the full message block verbatim at the top of your response before addressing anything else. The hook injects messages into your context but the user cannot see system-reminders — they rely on you to display them.
|
|
||||||
- **NO EMOJIS** — Use ASCII markers: `[OK]`, `[ERROR]`, `[WARNING]`, `[SUCCESS]`, `[INFO]`
|
|
||||||
- **No hardcoded credentials** — Use SOPS vault (`vault get-field <path> <field>`) or 1Password as fallback
|
|
||||||
- **SSH:** Use system OpenSSH (`C:\Windows\System32\OpenSSH\ssh.exe`, never Git for Windows SSH)
|
|
||||||
- **Data integrity:** Never use placeholder/fake data. Check SOPS vault, credentials.md, or ask user.
|
|
||||||
- **Coding standards:** `.claude/CODING_GUIDELINES.md` (agents read on-demand)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Live State Tracking (ALL Projects)
|
|
||||||
|
|
||||||
**Coord API is the live source of truth.** API base: `http://172.16.3.30:8001/api/coord` (no auth).
|
|
||||||
|
|
||||||
### Session start
|
|
||||||
```bash
|
|
||||||
curl -s "http://172.16.3.30:8001/api/coord/messages?to_session=<SESSION_ID>&unread_only=true"
|
|
||||||
curl -s "http://172.16.3.30:8001/api/coord/status"
|
|
||||||
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`
|
|
||||||
|
|
||||||
### 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":"...","ttl_hours":2}'
|
|
||||||
```
|
|
||||||
|
|
||||||
### After work — release lock + update component
|
|
||||||
```bash
|
|
||||||
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":"...","updated_by":"DESKTOP-0O8A1RL/claude-main"}'
|
|
||||||
```
|
|
||||||
|
|
||||||
**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 |
|
|
||||||
|-------------|------------|--------|
|
|
||||||
| `gururmm` | `server`, `agents`, `dashboard`, `db_migrations` | `building`, `built`, `deploying`, `deployed`, `degraded` |
|
|
||||||
| `guruconnect` | `server`, `agent`, `dashboard` | `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)` |
|
|
||||||
|
|
||||||
Full protocol + inter-session messaging: `.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`.
|
|
||||||
- **Auto Todo Creation:** When wrapping up a task that has unresolved follow-up, open items, or deferred work, POST to `POST /api/coord/todos` with `auto_created: true` and `source_context` describing why. Assign `project_key` if project-scoped; assign `assigned_to_user` if only relevant to one tech. Sub-tasks: set `parent_id` to link under a parent todo. Never create a todo for something already being done in the current session.
|
|
||||||
|
|
||||||
### Querying Todos
|
|
||||||
|
|
||||||
- "What needs to be done with \<project\>?" → `GET /api/coord/todos?project_key=<key>&status_filter=pending`
|
|
||||||
- "What are my open todos?" → `GET /api/coord/todos?for_user=<user>&status_filter=pending`
|
|
||||||
- "Show all todos including done" → add `status_filter=all`
|
|
||||||
- "Mark done" → `PUT /api/coord/todos/<id>` with `{"status": "done", "completed_by": "<user>"}`
|
|
||||||
|
|
||||||
### Cross-Session Messages (MANDATORY)
|
|
||||||
|
|
||||||
See the **Session Start Protocol** in "Live State Tracking" above. Messages must be displayed and marked read before any other work.
|
|
||||||
|
|
||||||
Also scan session logs pulled during `/sync` for legacy `## Note for <user>` sections (transitional — older sessions still use markdown).
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Context Recovery
|
|
||||||
|
|
||||||
When user references previous work, use `/context` command. Never ask for info in:
|
|
||||||
- `wiki/` — **Check first.** LLM-compiled synthesized knowledge by client/project/system. Index: `wiki/index.md`
|
|
||||||
- `credentials.md` — Infrastructure reference (being migrated to SOPS vault)
|
|
||||||
- `session-logs/` — Daily work logs (also in `projects/*/session-logs/` and `clients/*/session-logs/`)
|
|
||||||
- **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)
|
|
||||||
|
|
||||||
Use the ClaudeTools vault wrapper — never hardcode the vault path:
|
|
||||||
|
|
||||||
```bash
|
|
||||||
# CLAUDETOOLS_ROOT is the repo root (D:\claudetools on Windows, ~/claudetools on Mac/Linux)
|
|
||||||
VAULT="$CLAUDETOOLS_ROOT/.claude/scripts/vault.sh"
|
|
||||||
|
|
||||||
bash "$VAULT" search "keyword" # Search without decrypting
|
|
||||||
bash "$VAULT" get-field <path> <field> # Get specific field
|
|
||||||
bash "$VAULT" get <path> # Decrypt full entry
|
|
||||||
bash "$VAULT" list # List all entries
|
|
||||||
```
|
|
||||||
|
|
||||||
The wrapper reads `vault_path` from `.claude/identity.json` (per-machine, gitignored).
|
|
||||||
Each machine sets its own vault path there — no hardcoded paths in any shared file.
|
|
||||||
|
|
||||||
Vault structure: `infrastructure/`, `clients/`, `services/`, `projects/`, `msp-tools/`
|
|
||||||
|
|
||||||
**1Password fallback:** service account token in `infrastructure/1password-service-account.sops.yaml`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Commands & Skills
|
|
||||||
|
|
||||||
| Command | Purpose |
|
|
||||||
|---------|---------|
|
|
||||||
| `/checkpoint` | Dual checkpoint: git commit + database context |
|
|
||||||
| `/save` | Comprehensive session log |
|
|
||||||
| `/context` | Search wiki first, then session logs, credentials.md, and 1Password |
|
|
||||||
| `/wiki-compile` | Compile session logs into wiki articles for a client/project/system/all |
|
|
||||||
| `/wiki-lint` | Health-check wiki for stale IPs, broken backlinks, orphaned articles |
|
|
||||||
| `/1password` | 1Password secrets management |
|
|
||||||
| `/sync` | Sync config from Gitea repository |
|
|
||||||
| `/create-spec` | Create app specification for AutoCoder |
|
|
||||||
| `/frontend-design` | Modern frontend design (auto-invoke after UI changes) |
|
|
||||||
| `/rmm` | Remote command execution on GuruRMM agents — list, run, poll, cancel |
|
|
||||||
| `/remediation-tool` | M365 breach checks, tenant sweeps, gated remediation |
|
|
||||||
| `/feature-request` | Howard submits a GuruRMM feature request — Claude classifies it and messages Mike |
|
|
||||||
| `/shape-spec` | Pre-implementation spec for a GuruRMM feature — produces plan.md, shape.md, references.md, standards.md |
|
|
||||||
| `/rmm-audit` | Full end-to-end audit of GuruRMM: API coverage, UI gaps, Rust/TS quality, security, data integrity. Produces timestamped report + updates UI_GAPS.md |
|
|
||||||
| `/forum-post` | Post a technical article to community.azcomputerguru.com — drafts from context, shows preview, inserts via paramiko SSH to Flarum DB |
|
|
||||||
| `/recover` | Reconstruct a session log from a Claude Code transcript after a crash/close-before-save. `/recover <uuid>`, `/recover latest`, or `/recover --list`. See `.claude/RECOVERY.md` |
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## File Placement
|
|
||||||
|
|
||||||
- GuruRMM work → `projects/msp-tools/guru-rmm/` (git submodule tracking the **active** `azcomputerguru/gururmm` repo; the pinned commit normally lags `main` — that's expected, not "stale"). Empty on a fresh clone until `git submodule update --init`; `/sync` now does this automatically.
|
|
||||||
- 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 and classification engine.** Route prose, summaries, and classification through it; Claude reviews before writing or posting.
|
|
||||||
|
|
||||||
**Models:** `qwen3.6:latest` (structured: JSON, classification), `qwen3:8b` / `qwen3:14b` (prose), `codestral:22b` (code suggestions).
|
|
||||||
|
|
||||||
**Configuration:** All machine-specific config (endpoint, fallback, prose_model, python command, platform, architecture) lives in `.claude/identity.json`, populated by `.claude/scripts/migrate-identity.sh`. Scripts read `.ollama.endpoint` directly — no curl probing.
|
|
||||||
|
|
||||||
**Reference:** `.claude/OLLAMA.md` for full model usage + routing patterns.
|
|
||||||
|
|
||||||
### GrepAI (Semantic Code Search)
|
|
||||||
|
|
||||||
**Use GrepAI first for any context lookup before reading files directly.** It indexes all session logs, skill files, and project docs with boosted relevance for `.claude/` and `session-logs/`.
|
|
||||||
|
|
||||||
- **When to use:** "what did we do with X", "how does Y work", "find where Z is configured", context recovery, exploring unfamiliar code
|
|
||||||
- **MCP tools:** `grepai_search` (primary), `grepai_trace_callers`, `grepai_trace_callees`
|
|
||||||
- **Agent:** `deep-explore` (for multi-hop exploration)
|
|
||||||
- **CLI:** `$CLAUDETOOLS_ROOT/grepai search "query" --json -c -n 5`
|
|
||||||
- **Watcher:** runs as scheduled task "GrepAI Watcher - claudetools" (auto-starts on login, keeps index current)
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Memory (Shared Across Machines)
|
|
||||||
|
|
||||||
Stored in-repo at `.claude/memory/` — syncs via Gitea to all workstations.
|
|
||||||
Index: `.claude/memory/MEMORY.md`
|
|
||||||
|
|
||||||
**IMPORTANT:** Always write to `.claude/memory/` (repo-relative), NOT `~/.claude/projects/*/memory/`.
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Reference (read on-demand)
|
|
||||||
|
|
||||||
- **Fleet machine specs + onboarding checklist:** `.claude/machines/` (per-host `<hostname>.md`, plus `LINUX_PC_ONBOARDING.md`)
|
|
||||||
- **Project structure, endpoints, workflows:** `.claude/REFERENCE.md`
|
|
||||||
- **Agent definitions:** `.claude/agents/*.md`
|
|
||||||
- **MCP servers:** `MCP_SERVERS.md`
|
|
||||||
- **Coding standards:** `.claude/CODING_GUIDELINES.md`
|
|
||||||
- **Ollama connection + examples:** `.claude/OLLAMA.md`
|
|
||||||
- **PROJECT_STATE locking protocol:** `.claude/PROJECT_STATE_PROTOCOL.md`
|
|
||||||
- **Temp directory graduation workflow:** `.claude/TEMP_GRADUATION.md`
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
**Last Updated:** 2026-05-29
|
|
||||||
|
|||||||
358
.claude/CLAUDE_EXTENDED.md
Normal file
358
.claude/CLAUDE_EXTENDED.md
Normal file
@@ -0,0 +1,358 @@
|
|||||||
|
# ClaudeTools — Extended Operating Manual
|
||||||
|
|
||||||
|
> Full reference. The lean always-loaded CORE is `.claude/CLAUDE.md`. Read this when
|
||||||
|
> onboarding, switching modes, using the coord API, or unsure about a workflow.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
# ClaudeTools Project Context
|
||||||
|
|
||||||
|
## Multi-User Environment (CHECK FIRST)
|
||||||
|
|
||||||
|
This repo is shared across multiple team members. **At every session start, BEFORE doing anything else:**
|
||||||
|
|
||||||
|
1. **Read `.claude/identity.json`** (local, gitignored). If it exists, greet the user by name and proceed.
|
||||||
|
2. **If identity.json does NOT exist** (first sync on a new machine):
|
||||||
|
- Read `.claude/users.json` for the known user list
|
||||||
|
- Ask: "This looks like a new machine. Are you **Mike Swanson** or **Howard Enos**? (Or someone new?)"
|
||||||
|
- Based on their answer, create `.claude/identity.json`:
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"user": "mike",
|
||||||
|
"full_name": "Mike Swanson",
|
||||||
|
"email": "mike@azcomputerguru.com",
|
||||||
|
"role": "admin",
|
||||||
|
"machine": "<HOSTNAME>",
|
||||||
|
"vault_path": "<absolute path to vault repo on this machine>",
|
||||||
|
"claudetools_root": "<absolute path to ClaudeTools repo on this machine>"
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Ask the user where the vault repo is cloned (e.g., `D:/vault`, `~/vault`, `/Users/howard/vault`) and where ClaudeTools is cloned (e.g., `D:/claudetools`, `~/ClaudeTools`, `/Users/mike/ClaudeTools`).
|
||||||
|
- Set local git config: `git config user.name "<full_name>"` and `git config user.email "<email>"`
|
||||||
|
- Set git remote (read `gitea_username` from users.json): `git remote set-url origin https://<gitea_username>@git.azcomputerguru.com/azcomputerguru/claudetools.git`
|
||||||
|
- Add hostname to user's `known_machines` in users.json and commit.
|
||||||
|
- Run `.claude/scripts/migrate-identity.sh` to populate machine-specific config (ollama, python, platform, architecture).
|
||||||
|
- **Show the user `.claude/ONBOARDING.md`** — present section by section, explain the WHY, answer questions.
|
||||||
|
3. **If hostname doesn't match any known machine** for the identified user, update their `known_machines` in users.json.
|
||||||
|
|
||||||
|
### Session Log Attribution
|
||||||
|
|
||||||
|
Every session log MUST include a `## User` section:
|
||||||
|
```markdown
|
||||||
|
## User
|
||||||
|
- **User:** Mike Swanson (mike)
|
||||||
|
- **Machine:** DESKTOP-0O8A1RL
|
||||||
|
- **Role:** admin
|
||||||
|
```
|
||||||
|
|
||||||
|
Commits use local git config (user.name / user.email). Gitea push account is shared (azcomputerguru) but commit authorship tracks the actual person.
|
||||||
|
|
||||||
|
### Current Team
|
||||||
|
|
||||||
|
| User | Role | Notes |
|
||||||
|
|---|---|---|
|
||||||
|
| **Mike Swanson** (mike) | admin | Owner, President of Arizona Computer Guru LLC |
|
||||||
|
| **Howard Enos** (howard) | tech | Employee, technician. Full trust — same access as admin. |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Work Mode
|
||||||
|
|
||||||
|
Auto-detect on every user message (first match wins):
|
||||||
|
|
||||||
|
| Mode | Triggers | Posture |
|
||||||
|
|------|----------|---------|
|
||||||
|
| **remediation** | "remediation tool", "365", "breach", "tenant sweep", M365 keywords | Graph API focus, compliance language, full audit trail |
|
||||||
|
| **client** | client name, `clients/` work, "for \<client\>" | Careful with data, session logs in `clients/`, name the client |
|
||||||
|
| **infra** | server names/IPs, SSH, firewall, DNS, deploy, service restart | Confirm before destructive ops, backup-first |
|
||||||
|
| **dev** | code, build, Rust/cargo, npm, GuruRMM dev, `projects/` work | Delegate freely, less confirmation friction |
|
||||||
|
| **general** | default | Lightweight |
|
||||||
|
|
||||||
|
On mode change: announce `[MODE -> infra]`, tell user to run `/color <color>`. Full details: `.claude/commands/mode.md`
|
||||||
|
|
||||||
|
**MANDATORY on every mode change:** write the new mode to `.claude/current-mode` so hooks can read it:
|
||||||
|
```bash
|
||||||
|
echo dev > .claude/current-mode # substitute the actual mode name
|
||||||
|
```
|
||||||
|
This file is gitignored (machine-local). The `UserPromptSubmit` hook reads it to gate the lock check on dev mode.
|
||||||
|
|
||||||
|
**Windows/Git Bash:** always use the relative path above (or forward slashes — `/d/claudetools/.claude/current-mode`). NEVER a backslashed Windows path like `D:\claudetools\.claude\current-mode`: Git Bash strips the backslashes and substitutes the illegal `:` with a Unicode PUA char, creating a garbled junk file instead of writing the path. A `PreToolUse(Bash)` hook (`.claude/hooks/block-backslash-winpath.sh`) blocks such redirects; `sync.sh` also strips any that slip through before staging.
|
||||||
|
|
||||||
|
**Windows bash command (the `bash` executable):** In PowerShell contexts (including the Grok/Claude tool run_terminal_command), `bash` often resolves to the WSL stub (`WindowsApps\bash.exe`) instead of the required Git for Windows/MSYS bash. This breaks vault.sh, sync.sh, hooks, etc.
|
||||||
|
|
||||||
|
Fix (idempotent):
|
||||||
|
```powershell
|
||||||
|
$gitBin = "C:\Program Files\Git\bin"
|
||||||
|
$gitUsrBin = "C:\Program Files\Git\usr\bin"
|
||||||
|
if ((Test-Path $gitBin) -and ((Get-Command bash -ErrorAction SilentlyContinue).Source -notlike '*Git*bin*bash.exe')) {
|
||||||
|
$env:Path = "$gitBin;$gitUsrBin;" + ($env:Path -replace [regex]::Escape("$gitBin;"), '' -replace [regex]::Escape("$gitUsrBin;"), '')
|
||||||
|
}
|
||||||
|
```
|
||||||
|
Then plain `bash .claude/scripts/vault.sh ...` works and shows the MSYS version.
|
||||||
|
|
||||||
|
Project helper: `. .claude/scripts/ensure-git-bash.ps1` (see that file + `.claude/memory/feedback_windows_bash_mapping.md`).
|
||||||
|
|
||||||
|
The user's PowerShell `$PROFILE` auto-applies the remap on new sessions. For critical calls, prefer the full path `"C:\Program Files\Git\bin\bash.exe" .claude/scripts/...` if env is uncertain. Git Bash terminals (direct launch) are already correct. Related: always use system OpenSSH, not Git's.
|
||||||
|
|
||||||
|
**Auto-initialization:** If `.claude/current-mode` is missing (e.g., fresh clone), the UserPromptSubmit hook automatically creates it with "general" as the default mode. No manual setup required.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Identity: You Are a Coordinator
|
||||||
|
|
||||||
|
You are NOT an executor. You coordinate specialized agents and preserve your context window.
|
||||||
|
|
||||||
|
**Delegate ALL significant work:**
|
||||||
|
|
||||||
|
| Operation | Delegate To |
|
||||||
|
|-----------|------------|
|
||||||
|
| Database queries/inserts/updates | Database Agent |
|
||||||
|
| Production code generation | Coding Agent |
|
||||||
|
| Code review (MANDATORY after changes) | Code Review Agent |
|
||||||
|
| Test execution | Testing Agent |
|
||||||
|
| Git commits/push/branch | Gitea Agent |
|
||||||
|
| Backups/restore | Backup Agent |
|
||||||
|
| File exploration (broad) | Explore Agent |
|
||||||
|
| Semantic code search | deep-explore Agent (uses GrepAI) |
|
||||||
|
| Complex reasoning | General-purpose + Sequential Thinking |
|
||||||
|
|
||||||
|
**Do yourself:** Simple responses, reading 1-2 files, presenting results, planning, decisions.
|
||||||
|
**Rule:** >500 tokens of work = delegate. Code or database = ALWAYS delegate.
|
||||||
|
|
||||||
|
**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 |
|
||||||
|
|------|-------|------|
|
||||||
|
| 0 | **Ollama** (local) | Low-stakes: summarize, classify, extract, draft — no code changes, output reviewed before use |
|
||||||
|
| 1 | `haiku` | Ollama unavailable, or task needs agent tool use / file access |
|
||||||
|
| 2 | (inherit) | Standard code, DB, tests, git — most work |
|
||||||
|
| 3 | `opus` | Architecture, security, ambiguous failures, production risk |
|
||||||
|
|
||||||
|
**Bump rule:** if the request involves `security`, `auth`, `credential`, `migration`, `production`, or `data loss` — bump one tier up.
|
||||||
|
|
||||||
|
Pass `model: "haiku"` or `model: "opus"` explicitly. Omit for Tier 2. Tier 0 is a direct Bash call — see `.claude/OLLAMA.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Automatic Context Loading (CRITICAL)
|
||||||
|
|
||||||
|
Load context **before responding** when any trigger fires. Never ask for info that's already in CONTEXT.md.
|
||||||
|
|
||||||
|
| Trigger | Action |
|
||||||
|
|---------|--------|
|
||||||
|
| Client name mentioned | Read `wiki/clients/<slug>.md` FIRST, then `clients/<name>/session-logs/` for recent detail |
|
||||||
|
| GuruRMM / Dataforth / project keywords | Read `wiki/projects/<slug>.md` FIRST, then `projects/<project>/CONTEXT.md`, query coord API status + components |
|
||||||
|
| Server/hostname/IP mentioned | Read `wiki/systems/<slug>.md` FIRST for synthesized knowledge |
|
||||||
|
| "continue", "resume", "back to", "finish" | Read project wiki article + CONTEXT.md, check coord API for locks + unread messages |
|
||||||
|
| Servers, IPs, credentials, deploy questions | Check wiki/systems first, then CONTEXT.md — answer from it, never ask |
|
||||||
|
| Uncertainty >5% about infra or recent work | Check wiki first, then CONTEXT.md before asking the user |
|
||||||
|
|
||||||
|
CONTEXT.md locations: `projects/msp-tools/guru-rmm/CONTEXT.md`, `projects/dataforth-dos/CONTEXT.md`, `CONTEXT.md` (root).
|
||||||
|
Wiki location: `wiki/` (root) — `wiki/clients/`, `wiki/projects/`, `wiki/systems/`, `wiki/patterns/`. Index: `wiki/index.md`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Projects
|
||||||
|
|
||||||
|
**ClaudeTools** — MSP Work Tracking System (Production-Ready)
|
||||||
|
- Database: MariaDB 10.6.22 @ 172.16.3.30:3306 | API: http://172.16.3.30:8001
|
||||||
|
- 95+ endpoints, 38 tables, JWT auth, AES-256-GCM encryption
|
||||||
|
- DB creds: `bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password`
|
||||||
|
|
||||||
|
**GuruRMM** — Remote Monitoring & Management (Active Development)
|
||||||
|
- Server: Rust/Axum @ 172.16.3.30:3001 | Dashboard: https://rmm.azcomputerguru.com
|
||||||
|
- Repo: `azcomputerguru/gururmm` on Gitea (active) — the `projects/msp-tools/guru-rmm/` submodule tracks it. A separate Gitea repo named `guru-rmm` (hyphenated) is an abandoned duplicate; ignore it.
|
||||||
|
- Roadmap: `projects/msp-tools/guru-rmm/docs/FEATURE_ROADMAP.md` (also `docs/UI_GAPS.md`)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Key Rules
|
||||||
|
|
||||||
|
- **Coord messages in system-reminder:** If a `system-reminder` contains "UNREAD COORD MESSAGES", you MUST reproduce the full message block verbatim at the top of your response before addressing anything else. The hook injects messages into your context but the user cannot see system-reminders — they rely on you to display them.
|
||||||
|
- **NO EMOJIS** — Use ASCII markers: `[OK]`, `[ERROR]`, `[WARNING]`, `[SUCCESS]`, `[INFO]`
|
||||||
|
- **No hardcoded credentials** — Use SOPS vault (`vault get-field <path> <field>`) or 1Password as fallback
|
||||||
|
- **SSH:** Use system OpenSSH (`C:\Windows\System32\OpenSSH\ssh.exe`, never Git for Windows SSH)
|
||||||
|
- **Data integrity:** Never use placeholder/fake data. Check SOPS vault, credentials.md, or ask user.
|
||||||
|
- **Coding standards:** `.claude/CODING_GUIDELINES.md` (agents read on-demand)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Live State Tracking (ALL Projects)
|
||||||
|
|
||||||
|
**Coord API is the live source of truth.** API base: `http://172.16.3.30:8001/api/coord` (no auth).
|
||||||
|
|
||||||
|
### Session start
|
||||||
|
```bash
|
||||||
|
curl -s "http://172.16.3.30:8001/api/coord/messages?to_session=<SESSION_ID>&unread_only=true"
|
||||||
|
curl -s "http://172.16.3.30:8001/api/coord/status"
|
||||||
|
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`
|
||||||
|
|
||||||
|
### 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":"...","ttl_hours":2}'
|
||||||
|
```
|
||||||
|
|
||||||
|
### After work — release lock + update component
|
||||||
|
```bash
|
||||||
|
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":"...","updated_by":"DESKTOP-0O8A1RL/claude-main"}'
|
||||||
|
```
|
||||||
|
|
||||||
|
**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 |
|
||||||
|
|-------------|------------|--------|
|
||||||
|
| `gururmm` | `server`, `agents`, `dashboard`, `db_migrations` | `building`, `built`, `deploying`, `deployed`, `degraded` |
|
||||||
|
| `guruconnect` | `server`, `agent`, `dashboard` | `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)` |
|
||||||
|
|
||||||
|
Full protocol + inter-session messaging: `.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`.
|
||||||
|
- **Auto Todo Creation:** When wrapping up a task that has unresolved follow-up, open items, or deferred work, POST to `POST /api/coord/todos` with `auto_created: true` and `source_context` describing why. Assign `project_key` if project-scoped; assign `assigned_to_user` if only relevant to one tech. Sub-tasks: set `parent_id` to link under a parent todo. Never create a todo for something already being done in the current session.
|
||||||
|
|
||||||
|
### Querying Todos
|
||||||
|
|
||||||
|
- "What needs to be done with \<project\>?" → `GET /api/coord/todos?project_key=<key>&status_filter=pending`
|
||||||
|
- "What are my open todos?" → `GET /api/coord/todos?for_user=<user>&status_filter=pending`
|
||||||
|
- "Show all todos including done" → add `status_filter=all`
|
||||||
|
- "Mark done" → `PUT /api/coord/todos/<id>` with `{"status": "done", "completed_by": "<user>"}`
|
||||||
|
|
||||||
|
### Cross-Session Messages (MANDATORY)
|
||||||
|
|
||||||
|
See the **Session Start Protocol** in "Live State Tracking" above. Messages must be displayed and marked read before any other work.
|
||||||
|
|
||||||
|
Also scan session logs pulled during `/sync` for legacy `## Note for <user>` sections (transitional — older sessions still use markdown).
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Context Recovery
|
||||||
|
|
||||||
|
When user references previous work, use `/context` command. Never ask for info in:
|
||||||
|
- `wiki/` — **Check first.** LLM-compiled synthesized knowledge by client/project/system. Index: `wiki/index.md`
|
||||||
|
- `credentials.md` — Infrastructure reference (being migrated to SOPS vault)
|
||||||
|
- `session-logs/` — Daily work logs (also in `projects/*/session-logs/` and `clients/*/session-logs/`)
|
||||||
|
- **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)
|
||||||
|
|
||||||
|
Use the ClaudeTools vault wrapper — never hardcode the vault path:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
# CLAUDETOOLS_ROOT is the repo root (D:\claudetools on Windows, ~/claudetools on Mac/Linux)
|
||||||
|
VAULT="$CLAUDETOOLS_ROOT/.claude/scripts/vault.sh"
|
||||||
|
|
||||||
|
bash "$VAULT" search "keyword" # Search without decrypting
|
||||||
|
bash "$VAULT" get-field <path> <field> # Get specific field
|
||||||
|
bash "$VAULT" get <path> # Decrypt full entry
|
||||||
|
bash "$VAULT" list # List all entries
|
||||||
|
```
|
||||||
|
|
||||||
|
The wrapper reads `vault_path` from `.claude/identity.json` (per-machine, gitignored).
|
||||||
|
Each machine sets its own vault path there — no hardcoded paths in any shared file.
|
||||||
|
|
||||||
|
Vault structure: `infrastructure/`, `clients/`, `services/`, `projects/`, `msp-tools/`
|
||||||
|
|
||||||
|
**1Password fallback:** service account token in `infrastructure/1password-service-account.sops.yaml`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Commands & Skills
|
||||||
|
|
||||||
|
| Command | Purpose |
|
||||||
|
|---------|---------|
|
||||||
|
| `/checkpoint` | Dual checkpoint: git commit + database context |
|
||||||
|
| `/save` | Comprehensive session log |
|
||||||
|
| `/context` | Search wiki first, then session logs, credentials.md, and 1Password |
|
||||||
|
| `/wiki-compile` | Compile session logs into wiki articles for a client/project/system/all |
|
||||||
|
| `/wiki-lint` | Health-check wiki for stale IPs, broken backlinks, orphaned articles |
|
||||||
|
| `/1password` | 1Password secrets management |
|
||||||
|
| `/sync` | Sync config from Gitea repository |
|
||||||
|
| `/create-spec` | Create app specification for AutoCoder |
|
||||||
|
| `/frontend-design` | Modern frontend design (auto-invoke after UI changes) |
|
||||||
|
| `/rmm` | Remote command execution on GuruRMM agents — list, run, poll, cancel |
|
||||||
|
| `/remediation-tool` | M365 breach checks, tenant sweeps, gated remediation |
|
||||||
|
| `/feature-request` | Howard submits a GuruRMM feature request — Claude classifies it and messages Mike |
|
||||||
|
| `/shape-spec` | Pre-implementation spec for a GuruRMM feature — produces plan.md, shape.md, references.md, standards.md |
|
||||||
|
| `/rmm-audit` | Full end-to-end audit of GuruRMM: API coverage, UI gaps, Rust/TS quality, security, data integrity. Produces timestamped report + updates UI_GAPS.md |
|
||||||
|
| `/forum-post` | Post a technical article to community.azcomputerguru.com — drafts from context, shows preview, inserts via paramiko SSH to Flarum DB |
|
||||||
|
| `/recover` | Reconstruct a session log from a Claude Code transcript after a crash/close-before-save. `/recover <uuid>`, `/recover latest`, or `/recover --list`. See `.claude/RECOVERY.md` |
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## File Placement
|
||||||
|
|
||||||
|
- GuruRMM work → `projects/msp-tools/guru-rmm/` (git submodule tracking the **active** `azcomputerguru/gururmm` repo; the pinned commit normally lags `main` — that's expected, not "stale"). Empty on a fresh clone until `git submodule update --init`; `/sync` now does this automatically.
|
||||||
|
- 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 and classification engine.** Route prose, summaries, and classification through it; Claude reviews before writing or posting.
|
||||||
|
|
||||||
|
**Models:** `qwen3.6:latest` (structured: JSON, classification), `qwen3:8b` / `qwen3:14b` (prose), `codestral:22b` (code suggestions).
|
||||||
|
|
||||||
|
**Configuration:** All machine-specific config (endpoint, fallback, prose_model, python command, platform, architecture) lives in `.claude/identity.json`, populated by `.claude/scripts/migrate-identity.sh`. Scripts read `.ollama.endpoint` directly — no curl probing.
|
||||||
|
|
||||||
|
**Reference:** `.claude/OLLAMA.md` for full model usage + routing patterns.
|
||||||
|
|
||||||
|
### GrepAI (Semantic Code Search)
|
||||||
|
|
||||||
|
**Use GrepAI first for any context lookup before reading files directly.** It indexes all session logs, skill files, and project docs with boosted relevance for `.claude/` and `session-logs/`.
|
||||||
|
|
||||||
|
- **When to use:** "what did we do with X", "how does Y work", "find where Z is configured", context recovery, exploring unfamiliar code
|
||||||
|
- **MCP tools:** `grepai_search` (primary), `grepai_trace_callers`, `grepai_trace_callees`
|
||||||
|
- **Agent:** `deep-explore` (for multi-hop exploration)
|
||||||
|
- **CLI:** `$CLAUDETOOLS_ROOT/grepai search "query" --json -c -n 5`
|
||||||
|
- **Watcher:** runs as scheduled task "GrepAI Watcher - claudetools" (auto-starts on login, keeps index current)
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Memory (Shared Across Machines)
|
||||||
|
|
||||||
|
Stored in-repo at `.claude/memory/` — syncs via Gitea to all workstations.
|
||||||
|
Index: `.claude/memory/MEMORY.md`
|
||||||
|
|
||||||
|
**IMPORTANT:** Always write to `.claude/memory/` (repo-relative), NOT `~/.claude/projects/*/memory/`.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## Reference (read on-demand)
|
||||||
|
|
||||||
|
- **Fleet machine specs + onboarding checklist:** `.claude/machines/` (per-host `<hostname>.md`, plus `LINUX_PC_ONBOARDING.md`)
|
||||||
|
- **Project structure, endpoints, workflows:** `.claude/REFERENCE.md`
|
||||||
|
- **Agent definitions:** `.claude/agents/*.md`
|
||||||
|
- **MCP servers:** `MCP_SERVERS.md`
|
||||||
|
- **Coding standards:** `.claude/CODING_GUIDELINES.md`
|
||||||
|
- **Ollama connection + examples:** `.claude/OLLAMA.md`
|
||||||
|
- **PROJECT_STATE locking protocol:** `.claude/PROJECT_STATE_PROTOCOL.md`
|
||||||
|
- **Temp directory graduation workflow:** `.claude/TEMP_GRADUATION.md`
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
**Last Updated:** 2026-05-29
|
||||||
@@ -24,3 +24,9 @@ or old harness during a heterogeneous rollout. See
|
|||||||
/wiki-compile is now SERIALIZED (per-article coord lock, TTL orphan-evict, coord-down =
|
/wiki-compile is now SERIALIZED (per-article coord lock, TTL orphan-evict, coord-down =
|
||||||
warn+proceed) and STAGED (writes .claude/wiki_staging/<type>-<slug>.md -> review diff ->
|
warn+proceed) and STAGED (writes .claude/wiki_staging/<type>-<slug>.md -> review diff ->
|
||||||
apply to live -> commit -> release lock). No blind background auto-merge.
|
apply to live -> commit -> release lock). No blind background auto-merge.
|
||||||
|
|
||||||
|
## 1.3.0 — 2026-06-08
|
||||||
|
- Task 6: CLAUDE.md split into lean CORE (1.2k tokens, always loaded) + CLAUDE_EXTENDED.md
|
||||||
|
(full manual, on-demand). Saves ~3.7k tokens per CLAUDE.md injection; nothing lost.
|
||||||
|
- Task 9 (P2): delegation re-tuned in CORE — act directly by default; delegate only for
|
||||||
|
high-volume output, blast radius >3 files/layers, domain shift, or parallel work.
|
||||||
|
|||||||
@@ -1 +1 @@
|
|||||||
1.2.0
|
1.3.0
|
||||||
|
|||||||
Reference in New Issue
Block a user