claudetools/.claude/CLAUDE.md

# ClaudeTools — Core Operating Rules

> 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`.

## 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`).

## How you work — act directly, delegate deliberately
You are the main operator. **ACT DIRECTLY by default.** Delegate to a sub-agent ONLY when:
(a) the task produces high-volume tool output, (b) blast radius >3 files across layers,
(c) a genuine domain shift needs a specialized agent, or (d) independent work can run in
parallel. Do NOT delegate one-shot work (a single API call, a ticket comment, a 1–2 file
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,
use ONE agent across all phases. Agent defs: `.claude/agents/`.

## 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`.

## Key rules (always)
- **NO EMOJIS.** Use ASCII markers: `[OK]` `[ERROR]` `[WARNING]` `[INFO]` `[CRITICAL]`.
- **Skill-first — if a skill/command covers the task, USE IT; never hand-roll the API.**
  When a request maps to an installed skill or slash-command, INVOKE THAT SKILL instead of
  improvising raw `curl`/API calls from memory. The skill encodes the correct payload shape,
  validation, attribution, and preview gates; free-handing the API is exactly how malformed
  records (e.g. Syncro tickets/invoices) reach a human for cleanup. **Syncro billing/invoicing
  ALWAYS runs through `/syncro` (or `/syncro-emergency-billing`) — no exceptions.** Same for
  other covered domains: credentials → `vault`, RMM actions → `/rmm` (+ `rmm-search` to find a
  host), M365 → `remediation-tool`, etc. Knowing the API is NOT a reason to bypass the skill —
  the memory rules (e.g. [[feedback_syncro_billing]]) describe what the SKILL does, not a license
  to free-hand it. Reach for raw API ONLY when no skill fits or the skill genuinely cannot do it
  — and say so explicitly when you do. Mistakes here go to `errorlog.md` (`--correction`).
- **Definition of Done — route the REQUEST to a doing-skill, then GATE the result with the
  matching check-skill(s) before calling work done — automatically, without being asked.**
  You map the request to skills from the conversation + expected end result; the user should not
  have to name skill A/B/C. Standing gates (run the check-skill BEFORE declaring done): code edits
  → `/code-review` + `/simplify` (+ `/security-review` if it touches auth/creds/security); anything
  outbound/client-facing → `impeccable` / `stop-slop`; Syncro/vendor work → its skill's own
  preview+verify gate; wiki/memory writes → their lint (`wiki-lint`/`memory-dream`). **Calibrate to
  stakes** (a typo fix doesn't need a full review) and **use Ollama Tier-0** for the cheap
  classify/prose passes so this stays low-token. The full request→doing-skill→check-skill map is
  `.claude/SKILL_ROUTING.md` — read it on demand when a request maps to a skill or work nears done.
- **Credentials — capture, vault, document (ALWAYS).** ANY credential that surfaces in a
  session — one the user pastes, one you create/rotate, one you discover in a log/config — you
  MUST immediately store it in the SOPS vault **via the `vault` skill** (the canonical path —
  this is why the vault exists; do not improvise raw `sops`/`vault.sh`) AND document it
  thoroughly in the entry: what it is, what it's for, and exactly how it's used (auth method,
  endpoint, gotchas). Read with the skill too; `vault.sh get-field <path> <field>` is the
  underlying read (1Password fallback). Never commit plaintext secrets (pre-commit
  `harness-guard.sh` warns). Losing/forgetting infra credentials wastes real time — capturing
  them is not optional.
- **SSH:** system OpenSSH (`C:\Windows\System32\OpenSSH\ssh.exe`), never Git-for-Windows SSH.
- **Data integrity:** never placeholder/fake data — check vault, wiki, or ask.
- **Hard-to-reverse or outward-facing actions:** confirm first (per-action, per-session).
- **Error logging (mandatory, all skills):** when a task or skill hits a GENUINE functional error during execution (failed command, API/auth failure, unexpected API response, tool call), record it to `errorlog.md` (repo root) via the canonical helper — never hand-format: `bash .claude/scripts/log-skill-error.sh "<skill/command>" "<brief error>" [--context "k=v ..."]`. It stamps UTC date + machine (from `identity.json`) and inserts in the standard `YYYY-MM-DD | MACHINE | skill | error` format (newest on top) for later skill **linting**, and soft-fails so it never breaks the caller. **Every skill MUST call it at its failure branches**; you (main loop) call it after any skill/command genuinely fails. Do NOT log expected/handled conditions (no search matches, no unread messages, a user declining a prompt) — only real failures worth spotting a pattern. Python skills shell out to the same helper.
- **Log user corrections too (`--correction`):** when the user CORRECTS an improper assumption or wrong approach you took (e.g. "don't use INKY unless onboarded", "EXO already has Mail.Send", "I don't need an exact match"), log it: `bash .claude/scripts/log-skill-error.sh "<skill/context>" "assumed X; correct is Y" --correction`. These are the highest-value entries — they surface recurring bad assumptions so we can train them out of the system. If the correction is a durable preference, ALSO save it as a `feedback` memory (the two are complementary: memory fixes future behavior, errorlog tracks the pattern for linting).
- **Log preventable friction too (`--friction`):** any time you waste tokens on a preventable, repeatable self-inflicted error — harness/env/tool misuse (Git-Bash `/tmp` path mismatch, shell env not persisting between Bash calls, passing huge args on the command line, PowerShell var case-collisions, etc.) — log it: `bash .claude/scripts/log-skill-error.sh "<context e.g. bash/env>" "what wasted tokens + the fix" --friction [--context "ref=<memory-or-rule>"]`. **If it repeats something already in memory or CLAUDE.md, that's the highest-value entry** — it means a rule/memory isn't working; cite the ref. This log is the corpus we lint to build better CLAUDE.md rules and to clean stale/misleading memory. Goal: stop paying twice for the same mistake.
- **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). **Never write API/scratch JSON to `/tmp`** — Git-Bash `/tmp` and the Write/Python tools
  resolve it to different places (read-back fails); use a repo-relative path (`./.x.json`). **Never
  embed `"` in `curl.exe`/`plink` args from PowerShell** — `CommandLineToArgvW` strips them and
  silently mangles the payload; single-quote bodies, build `$` from `[char]36`, or use SSH key auth.
  These two recur fleet-wide (errorlog) — treat as hard rules. Detail + fixes: EXTENDED,
  memories `feedback_tmp_path_windows` + `feedback_windows_quote_stripping`.

## 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).

## 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.

## Work modes
Auto-detect mode (remediation / client / infra / dev / general) from each message. On
change: announce `[MODE -> x]`, tell the user to run `/color <c>`, and write the mode to
`.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,
GrepAI, and every detailed workflow: **`.claude/CLAUDE_EXTENDED.md`**.