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

refactor: optimize CLAUDE.md context footprint (-49%)

Browse Source 
Extract Ollama docs and PROJECT_STATE locking protocol to on-demand
reference files. Trim Work Mode to detection table only. Remove verbose
anti-pattern examples and credential encryption details.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-04-20 12:09:17 -07:00
parent 30af2d31c7
commit a50af7faf1
4 changed files with 395 additions and 493 deletions
Download Patch File Download Diff File Expand all files Collapse all files

745
.claude/CLAUDE.md
View File

@@ -1,493 +1,252 @@
# ClaudeTools Project Context # ClaudeTools Project Context
## Multi-User Environment (CHECK FIRST) ## Multi-User Environment (CHECK FIRST)
This repo is shared across multiple team members. **At every session start, BEFORE doing anything else:** 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. 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): 2. **If identity.json does NOT exist** (first sync on a new machine):
- Read `.claude/users.json` for the known user list - 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?)" - 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`: - Based on their answer, create `.claude/identity.json`:
```json ```json
{ {
"user": "mike", "user": "mike",
"full_name": "Mike Swanson", "full_name": "Mike Swanson",
"email": "mike@azcomputerguru.com", "email": "mike@azcomputerguru.com",
"role": "admin", "role": "admin",
"machine": "<HOSTNAME>" "machine": "<HOSTNAME>"
} }
``` ```
- Also set local git config for this repo: - Set local git config: `git config user.name "<full_name>"` and `git config user.email "<email>"`
```bash - Set git remote (read `gitea_username` from users.json): `git remote set-url origin https://<gitea_username>@git.azcomputerguru.com/azcomputerguru/claudetools.git`
git config user.name "<full_name>" - Add hostname to user's `known_machines` in users.json and commit.
git config user.email "<email>" - **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.
- Set git remote to use the user's own Gitea account (read `gitea_username` from users.json):
```bash ### Session Log Attribution
git remote set-url origin https://<gitea_username>@git.azcomputerguru.com/azcomputerguru/claudetools.git
``` Every session log MUST include a `## User` section:
- Add the machine hostname to the user's `known_machines` list in `.claude/users.json` and commit. ```markdown
- **IMPORTANT: Show the user `.claude/ONBOARDING.md`** — present it section by section, explain what each part does and WHY, answer any questions. This is their orientation to the system. ## User
3. **If the hostname doesn't match any known machine** for the identified user, update their `known_machines` in users.json. - **User:** Mike Swanson (mike)
- **Machine:** DESKTOP-0O8A1RL
### Session log attribution - **Role:** admin
```
Every session log MUST include a `## User` section at the top:
```markdown Commits use local git config (user.name / user.email). Gitea push account is shared (azcomputerguru) but commit authorship tracks the actual person.
## User
- **User:** Mike Swanson (mike) ### Current Team
- **Machine:** DESKTOP-0O8A1RL
- **Role:** admin | User | Role | Notes |
``` |---|---|---|
| **Mike Swanson** (mike) | admin | Owner, President of Arizona Computer Guru LLC |
### Git commit attribution | **Howard Enos** (howard) | tech | Employee, technician. Full trust — same access as admin. |
Commits use the local git config (user.name / user.email), which is set per-user during identity setup. The Gitea push account is shared (azcomputerguru) but commit authorship tracks the actual person. ---
### Current team ## Work Mode
| User | Role | Access | Notes | Auto-detect on every user message (first match wins):
|---|---|---|---|
| **Mike Swanson** (mike) | admin | Full | Owner, President of Arizona Computer Guru LLC | | Mode | Triggers | Posture |
| **Howard Enos** (howard) | tech | Full | Employee, technician. Full trust — same access as admin for all MSP tracking and daily work. | |------|----------|---------|
| **remediation** | "remediation tool", "365", "breach", "tenant sweep", M365 keywords | Graph API focus, compliance language, full audit trail |
Both users have identical access. No permission gating between them. If a new team member is added later, their role and access scope should be defined in `.claude/users.json` before they sync. | **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 |
## Work Mode (auto-detect + color) | **dev** | code, build, Rust/cargo, npm, GuruRMM dev, `projects/` work | Delegate freely, less confirmation friction |
| **general** | default | Lightweight |
Claude operates in one of five modes. Mode determines terminal color and operational posture. **Auto-detect on every user message** using these priority rules (first match wins):
On mode change: announce `[MODE -> infra]`, tell user to run `/color <color>`. Full details: `.claude/commands/mode.md`
1. **remediation** (purple) — "remediation tool", "365", "breach", "tenant sweep", M365 keywords
2. **client** (orange) — client name mentioned (check `clients/` dirs), work under `clients/`, "for \<client\>" ---
3. **infra** (red) — server names/IPs (AD2, Jupiter, 172.16.x.x), SSH, firewall, DNS, deploy, service restart
4. **dev** (cyan) — code, build, compile, Rust/cargo, npm, GuruRMM dev, testing, work under `projects/` ## Identity: You Are a Coordinator
5. **general** (blue) — default
You are NOT an executor. You coordinate specialized agents and preserve your context window.
**On mode change:** update `identity.json` "mode" field, change terminal color, announce briefly: `[MODE -> infra]`. Don't interrupt workflow.
**Delegate ALL significant work:**
**Manual override:** user can run `/mode <name>` to force a mode. `/mode auto` re-runs detection. `/mode` shows current.
| Operation | Delegate To |
**Posture by mode:** |-----------|------------|
- **client (orange):** careful with data, session logs go to `clients/`, always name the client | Database queries/inserts/updates | Database Agent |
- **dev (cyan):** delegate freely to Coding/Testing agents, less confirmation friction | Production code generation | Coding Agent |
- **infra (red):** confirm before destructive ops, backup-first, double-check IPs | Code review (MANDATORY after changes) | Code Review Agent |
- **general (blue):** lightweight, default | Test execution | Testing Agent |
- **remediation (purple):** Graph API focus, compliance language, full audit trail | Git commits/push/branch | Gitea Agent |
| Backups/restore | Backup Agent |
Full details: `.claude/commands/mode.md` | File exploration (broad) | Explore Agent |
| Semantic code search | deep-explore Agent (uses GrepAI) |
--- | Complex reasoning | General-purpose + Sequential Thinking |
## Identity: You Are a Coordinator **Do yourself:** Simple responses, reading 1-2 files, presenting results, planning, decisions.
**Rule:** >500 tokens of work = delegate. Code or database = ALWAYS delegate.
You are NOT an executor. You coordinate specialized agents and preserve your context window.
**DO NOT** query databases directly. **DO NOT** write production code. **DO NOT** run tests. **DO NOT** commit/push.
**Delegate ALL significant work:**
### Model Routing (Complexity-Based)
| Operation | Delegate To |
|-----------|------------| | Tier | Model | When |
| Database queries/inserts/updates | Database Agent | |------|-------|------|
| Production code generation | Coding Agent | | 0 | **Ollama** (local) | Low-stakes: summarize, classify, extract, draft — no code changes, output reviewed before use |
| Code review (MANDATORY after changes) | Code Review Agent | | 1 | `haiku` | Ollama unavailable, or task needs agent tool use / file access |
| Test execution | Testing Agent | | 2 | (inherit) | Standard code, DB, tests, git — most work |
| Git commits/push/branch | Gitea Agent | | 3 | `opus` | Architecture, security, ambiguous failures, production risk |
| Backups/restore | Backup Agent |
| File exploration (broad) | Explore Agent | **Bump rule:** if the request involves `security`, `auth`, `credential`, `migration`, `production`, or `data loss` — bump one tier up.
| Semantic code search | deep-explore Agent (uses GrepAI) |
| Complex reasoning | General-purpose + Sequential Thinking | Pass `model: "haiku"` or `model: "opus"` explicitly. Omit for Tier 2. Tier 0 is a direct Bash call — see `.claude/OLLAMA.md`.
**Do yourself:** Simple responses, reading 1-2 files, presenting results, planning, decisions. ---
**Rule:** >500 tokens of work = delegate. Code or database = ALWAYS delegate.
## Automatic Context Loading (CRITICAL)
**DO NOT** query databases directly (no SSH/mysql/curl to API). **DO NOT** write production code. **DO NOT** run tests. **DO NOT** commit/push. Use the appropriate agent.
**BEFORE responding to the first message or when switching projects, AUTOMATICALLY load context:**
### Model Routing (Complexity-Based)
### Trigger 1: Project Keywords Detected
Before spawning an agent, pick a tier: If user mentions **GuruRMM**, **Dataforth**, **tunnel**, **VASLOG**, **AD2**, **testdatadb**, etc:
1. Read the matching project CONTEXT.md:
| Tier | Model | When | - GuruRMM keywords → `projects/msp-tools/guru-rmm/CONTEXT.md`
|------|-------|------| - Dataforth keywords → `projects/dataforth-dos/CONTEXT.md`
| 0 | **Ollama** (local) | Low-stakes: summarize, classify, extract, draft, format — no code changes, output reviewed before use | - General → `CONTEXT.md` (root)
| 1 | `haiku` | Ollama unavailable, or task needs tool use / file access an agent provides | 2. If `PROJECT_STATE.md` exists alongside CONTEXT.md, read it **and** `.claude/PROJECT_STATE_PROTOCOL.md`.
| 2 | (inherit) | Standard code, DB, tests, git — most work | 3. THEN respond with full context.
| 3 | `opus` | Architecture, security, ambiguous failures, production risk |
### Trigger 2: Continuation/Resume Words
**Tier 0 rule:** Always try Ollama first for low-stakes work. It's free, fast, and private. Use `qwen3:14b` for general tasks; `codestral:22b` for code suggestions. Fall back to Haiku only if Ollama is unreachable or the task requires agent tool use. If user says "continue", "let's work on", "back to", "resume", "finish":
1. Detect project from message, read project CONTEXT.md.
**Bump rule:** if the request involves `security`, `auth`, `credential`, `migration`, `production`, or `data loss` — bump one tier up (Ollama → Haiku, Haiku → inherit, inherit → opus). 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.
Pass `model: "haiku"` or `model: "opus"` explicitly. Omit for Tier 2 (inherits session model). Tier 0 is a direct Bash call, not an agent spawn — see Ollama section below.
### Trigger 3: Infrastructure/Deployment Questions
### Coordination Flow 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.
User request -> Main Claude (coordinator) -> Launches agent(s) -> Agent returns summary -> Main Claude presents to user
``` ### Trigger 4: Uncertainty >5%
If you're <95% certain about infrastructure, recent work, or next steps: read CONTEXT.md before asking the user.
- Independent operations run in parallel
- Skills (Skill tool) enhance/validate. Agents (Agent tool) execute/operate. ### 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.
## Automatic Context Loading (CRITICAL) ---
**BEFORE responding to user's first message or when switching projects, AUTOMATICALLY load context:** ## Projects
### Trigger 1: Project Keywords Detected **ClaudeTools** — MSP Work Tracking System (Production-Ready)
If user mentions **GuruRMM**, **Dataforth**, **tunnel**, **VASLOG**, **AD2**, **testdatadb**, etc: - Database: MariaDB 10.6.22 @ 172.16.3.30:3306 | API: http://172.16.3.30:8001
1. **Immediately read** the matching project CONTEXT.md: - 95+ endpoints, 38 tables, JWT auth, AES-256-GCM encryption
- GuruRMM keywords → `projects/msp-tools/guru-rmm/CONTEXT.md` - DB creds: `bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password`
- Dataforth keywords → `projects/dataforth-dos/CONTEXT.md`
- General → `CONTEXT.md` (root) **GuruRMM** — Remote Monitoring & Management (Active Development)
2. **If a `PROJECT_STATE.md` exists alongside the CONTEXT.md, read it immediately after.** This file tracks live inter-session state: active locks (what other Claude instances are touching), architecture decisions that are locked, recent changes since the last session, and pending work. Check it for blocking conflicts before starting any task. - Server: Rust/Axum @ 172.16.3.30:3001 | Dashboard: https://rmm.azcomputerguru.com
3. Read ENTIRE file (infrastructure, current state, anti-patterns) - Repo: `azcomputerguru/gururmm` on Gitea (active), `guru-rmm` is a stale copy
3. Note recent session logs mentioned in CONTEXT.md - Roadmap: `projects/msp-tools/guru-rmm/ROADMAP.md`
4. THEN respond with full context
---
### Trigger 2: Continuation/Resume Words
If user says "continue", "let's work on", "back to", "resume", "finish": ## Key Rules
1. Detect project from message
2. Read project CONTEXT.md if found - **NO EMOJIS** — Use ASCII markers: `[OK]`, `[ERROR]`, `[WARNING]`, `[SUCCESS]`, `[INFO]`
3. Check "Current State" and "Recent Session Logs" sections - **No hardcoded credentials** — Use SOPS vault (`vault get-field <path> <field>`) or 1Password as fallback
4. Proceed without asking for context - **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.
### Trigger 3: Infrastructure/Deployment Questions - **Coding standards:** `.claude/CODING_GUIDELINES.md` (agents read on-demand)
If user asks about **servers**, **databases**, **credentials**, **deploy**, **IP**, **password**:
1. Check current directory for CONTEXT.md ---
2. If not found, check projects/*/CONTEXT.md
3. Answer from CONTEXT.md (never ask user for info that's in CONTEXT.md) ## Automatic Behaviors
### Trigger 4: Uncertainty >5% - **Frontend Design:** Auto-invoke `/frontend-design` skill after ANY UI change (HTML/CSS/JSX/styling)
If you're <95% certain about infrastructure, recent work, or next steps: - **Sequential Thinking:** Use for genuine complexity — rejection loops, 3+ critical issues, architectural decisions
1. Search for CONTEXT.md in working directory - **Task Management:** Complex work (>3 steps) → TaskCreate. Persist to `.claude/active-tasks.json`.
2. Search for CONTEXT.md in projects/*/
3. Read before asking user ---
### ANTI-PATTERN Examples (NEVER DO THIS): ## Context Recovery
❌ **Wrong:** When user references previous work, use `/context` command. Never ask for info in:
``` - `credentials.md` — Infrastructure reference (being migrated to SOPS vault at D:\vault)
User: "Look at the Dataforth DFWDS folders" - `session-logs/` — Daily work logs (also in `projects/*/session-logs/` and `clients/*/session-logs/`)
You: "I don't recall what we've done with Dataforth. Let me search session logs..." - `SESSION_STATE.md` — Project history
```
### Credential Access (SOPS Vault)
✅ **Correct:**
``` ```bash
User: "Look at the Dataforth DFWDS folders" bash D:/vault/scripts/vault.sh search "keyword" # Search without decrypting
You: [Detects "Dataforth" → reads projects/dataforth-dos/CONTEXT.md in <3 seconds] bash D:/vault/scripts/vault.sh get-field <path> <field> # Get specific field
"I see from CONTEXT.md that DFWDS is at C:\Shares\testdatadb\ on AD2 (192.168.0.6). bash D:/vault/scripts/vault.sh get <path> # Decrypt full entry
Recent work (2026-04-12) extended SCMVAS/SCMHVAS pipeline. Service is testdatadb on port 3000. bash D:/vault/scripts/vault.sh list # List all entries
What would you like me to check?" ```
```
Vault repo: `D:\vault` — structure: `infrastructure/`, `clients/`, `services/`, `projects/`, `msp-tools/`
❌ **Wrong:**
``` **1Password fallback:** service account token in `infrastructure/1password-service-account.sops.yaml`
User: "Continue working on GuruRMM tunnel"
You: "What phase are we on? Which server is this deployed to?" ---
```
## Commands & Skills
✅ **Correct:**
``` | Command | Purpose |
User: "Continue working on GuruRMM tunnel" |---------|---------|
You: [Reads projects/msp-tools/guru-rmm/CONTEXT.md] | `/checkpoint` | Dual checkpoint: git commit + database context |
"Tunnel Phase 1 is complete (v0.6.0, deployed to 172.16.3.30:3001). | `/save` | Comprehensive session log |
Phase 2 is channel implementation (Terminal, File, Registry, Service). | `/context` | Search session logs, credentials.md, and 1Password |
2/6 agents online. Ready to proceed." | `/1password` | 1Password secrets management |
``` | `/sync` | Sync config from Gitea repository |
| `/create-spec` | Create app specification for AutoCoder |
### Session Start Protocol | `/frontend-design` | Modern frontend design (auto-invoke after UI changes) |
| `/remediation-tool` | M365 breach checks, tenant sweeps, gated remediation |
At session start:
1. Check for CONTEXT.md in current working directory ---
2. If found, read it silently (don't announce to user)
3. Be ready to answer questions about any project listed ## File Placement
4. When user specifies project, load that project's CONTEXT.md automatically
- **Dataforth DOS work** → `projects/dataforth-dos/`
### Benefits - **ClaudeTools API code** → `api/`, `migrations/`
- **GuruRMM work** → `projects/msp-tools/guru-rmm/`
- ✅ Never ask "What's the server IP?" (it's in CONTEXT.md) - **Client work** → `clients/[client-name]/`
- ✅ Never ask "What did we do last time?" (recent logs in CONTEXT.md) - **Session logs** → project or client `session-logs/` subfolder; general → root `session-logs/`
- ✅ Never ask "Where's the database?" (infrastructure table in CONTEXT.md) - **Full guide:** `.claude/FILE_PLACEMENT_GUIDE.md`
- ✅ Start work immediately with full context
- ✅ Follow anti-patterns automatically (CONTEXT.md lists common mistakes) ---
**See:** `.claude/AUTO_CONTEXT_SYSTEM.md` for full implementation details ## Local AI (Ollama)
--- Tier 0 — use before spawning Haiku agents for low-stakes tasks (free, fast, private):
- **DESKTOP-0O8A1RL:** `http://localhost:11434`
## PROJECT_STATE.md Action Protocol (MANDATORY for any project that has this file) - **Other machines:** `http://100.92.127.64:11434` (Tailscale required)
- **Models:** `qwen3:14b` (summarize/classify/draft), `codestral:22b` (code suggestions — always review)
This protocol prevents conflicts between concurrent Claude sessions working on the same project. It is **not optional** — follow it for every significant action. - **Full reference:** `.claude/OLLAMA.md` (connection examples, model selection, review policy)
### What counts as an action ### GrepAI (Semantic Code Search)
Any of the following requires the full read → lock → update → release cycle: Use for intent-based search ("how does auth work"), exploring unfamiliar code, context recovery.
- Editing or creating source code files - **MCP tool:** `grepai` server tools
- Git commit or push - **Agent:** `deep-explore` agent
- SSH command that modifies a server (deploy, install, config change, service restart) - **CLI:** `grepai search "query" --json --compact`
- Database schema change or data migration
- Build pipeline modification ---
- Any operation listed in the project's Component Ownership Map
## Memory (Shared Across Machines)
Reading files, planning, and answering questions do NOT require a lock.
Stored in-repo at `.claude/memory/` — syncs via Gitea to all workstations.
### The protocol Index: `.claude/memory/MEMORY.md`
**Step 1 — Read before acting** **IMPORTANT:** Always write to `.claude/memory/` (repo-relative), NOT `~/.claude/projects/*/memory/`.
Before starting any action, re-read PROJECT_STATE.md:
- Check Active Session Locks: is anything locked that you need to touch? ---
- If there is a conflicting lock that is NOT stale (< 2 hours old): stop, report the conflict to the user, ask how to proceed.
- If locks are stale (> 2 hours, last updated timestamp): note it to the user, clear the stale row, proceed. ## Reference (read on-demand)
**Step 2 — Claim your lock** - **Project structure, endpoints, workflows:** `.claude/REFERENCE.md`
Immediately before performing the action, add a row to the Active Session Locks table: - **Agent definitions:** `.claude/agents/*.md`
- **MCP servers:** `MCP_SERVERS.md`
| Session | Working On | Status | Blocks | Started | - **Coding standards:** `.claude/CODING_GUIDELINES.md`
|---------|-----------|--------|--------|---------| - **Ollama connection + examples:** `.claude/OLLAMA.md`
| DESKTOP-0O8A1RL/Claude | Brief description | IN_PROGRESS | What others must avoid | HH:MM UTC | - **PROJECT_STATE locking protocol:** `.claude/PROJECT_STATE_PROTOCOL.md`
Use `{machine}/{Claude or agent description}` as Session identifier. ---
Use the machine name from identity.json.
**Last Updated:** 2026-04-20
**Step 3 — Perform the action**
**Step 4 — Update on completion OR failure**
Immediately after the action finishes (regardless of outcome):
1. Remove your lock row from Active Session Locks
2. Add an entry to Recent Changes:
- Status: `COMPLETE`, `FAILED`, `PARTIAL`, or `ROLLED_BACK`
- If FAILED or PARTIAL: describe what state things were left in
3. Update the Current Project State table if any component status changed
4. Check off completed items in Pending / Next Up if applicable
### Anti-patterns (never do these)
❌ Starting work without reading PROJECT_STATE.md first
❌ Forgetting to claim a lock before touching a component
❌ Leaving a lock row in place after finishing (even on failure)
❌ Skipping the Recent Changes entry when work completes
❌ Letting a lock go stale — update the timestamp if a task takes longer than expected
### Stale lock rule
A lock older than 2 hours with no timestamp update is considered abandoned. Any session may clear it and claim the component, but must note in Recent Changes: `[Cleared stale lock from {session}]` before proceeding.
### Example — correct flow
```
[Reading PROJECT_STATE.md — no active locks on server/src/]
[Updating PROJECT_STATE.md — adding lock: "DESKTOP-0O8A1RL/Claude | POST /api/enroll endpoint | IN_PROGRESS | server/src/, migrations/ | 14:32 UTC"]
[... writing code, running migration ...]
[Updating PROJECT_STATE.md — removing lock, adding Recent Changes: "POST /api/enroll implemented | COMPLETE", updating component status: "Enrollment endpoint | IMPLEMENTED"]
```
---
## 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 in vault: `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), `guru-rmm` is a stale copy
- Roadmap: `projects/msp-tools/guru-rmm/ROADMAP.md`
---
## Key Rules
- **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 (on Windows: `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, not every session)
---
## 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, multi-step debugging
- **Task Management:** Complex work (>3 steps) -> TaskCreate. Persist to `.claude/active-tasks.json`.
---
## Context Recovery
When user references previous work, use `/context` command. Never ask user for info in:
- `credentials.md` - Infrastructure reference (being migrated to SOPS vault at D:\vault)
- `session-logs/` - Daily work logs (also in `projects/*/session-logs/` and `clients/*/session-logs/`)
- `SESSION_STATE.md` - Project history
### Credential Access (SOPS Vault - Primary)
Credentials are stored in SOPS+age encrypted YAML files in a dedicated Gitea repo.
**Vault repo:** `D:\vault` (git.azcomputerguru.com/azcomputerguru/vault, private)
**Structure:** infrastructure/, clients/, services/, projects/, msp-tools/
**To read credentials:**
```bash
bash D:/vault/scripts/vault.sh search "keyword" # Search (no decryption needed)
bash D:/vault/scripts/vault.sh get-field <path> <field> # Get specific field
bash D:/vault/scripts/vault.sh get <path> # Decrypt full entry
bash D:/vault/scripts/vault.sh list # List all entries
```
**Encryption:** AES-256 via age. Metadata stays plaintext for searchability.
**age key location:** `%APPDATA%\sops\age\keys.txt` (Windows) / `~/.config/sops/age/keys.txt` (Linux/Mac)
### 1Password (Fallback)
Service account token in vault: `infrastructure/1password-service-account.sops.yaml`
---
## Commands & Skills
| Command | Purpose |
|---------|---------|
| `/checkpoint` | Dual checkpoint: git commit + database context |
| `/save` | Comprehensive session log (credentials, decisions, changes) |
| `/context` | Search session logs, credentials.md, and 1Password |
| `/1password` | 1Password secrets management integration |
| `/sync` | Sync config from Gitea repository |
| `/create-spec` | Create app specification for AutoCoder |
| `/frontend-design` | Modern frontend design patterns (auto-invoke after UI changes) |
| `/remediation-tool` | M365 breach checks, tenant sweeps, gated remediation via Claude-MSP-Access Graph API app |
---
## File Placement (Quick Rules)
- **Dataforth DOS work** -> `projects/dataforth-dos/`
- **ClaudeTools API code** -> `api/`, `migrations/` (existing structure)
- **GuruRMM work** -> `projects/msp-tools/guru-rmm/`
- **Client work** -> `clients/[client-name]/`
- **Session logs** -> project or client `session-logs/` subfolder; general -> root `session-logs/`
- **Full guide:** `.claude/FILE_PLACEMENT_GUIDE.md` (read when saving files, not every session)
---
## Local AI (Ollama)
Ollama runs on Mike's workstation (DESKTOP-0O8A1RL) with GPU acceleration. Available to all team members via Tailscale.
| Model | Size | Use For |
|-------|------|---------|
| `qwen3:14b` | 9.3 GB | Summarization, classification, data extraction, drafting |
| `codestral:22b` | 12 GB | Code generation, refactoring suggestions, docstrings |
| `nomic-embed-text` | 274 MB | Embeddings only (used by GrepAI) |
### How to connect
**On Mike's workstation (local):**
```bash
curl -s http://localhost:11434/api/generate -d '{"model":"qwen3:14b","prompt":"...","stream":false}' | jq -r '.response'
```
**On any other machine via Tailscale:**
```bash
curl -s http://100.92.127.64:11434/api/generate -d '{"model":"qwen3:14b","prompt":"...","stream":false}' | jq -r '.response'
```
### Per-machine setup
Read `.claude/identity.json` to determine which machine you're on:
- **DESKTOP-0O8A1RL** (Mike's workstation): Ollama runs locally. Use `localhost:11434`.
- **Any other machine** (Howard's laptop, other workstations): Ollama is remote via Tailscale. Use `100.92.127.64:11434`. Requires Tailscale to be connected.
**To check if Ollama is reachable:**
```bash
curl -s http://100.92.127.64:11434/api/tags | python -c "import sys,json; [print(m['name']) for m in json.load(sys.stdin).get('models',[])]"
```
If it fails: verify Tailscale is connected (`tailscale status`), and that Mike's workstation is online.
### Access control
- Firewall rule on Mike's workstation allows port 11434 ONLY from Tailscale subnet (100.0.0.0/8)
- NOT exposed to LAN, VPN, or internet
- Binding: `OLLAMA_HOST=0.0.0.0:11434` (all interfaces, firewall restricts)
### Delegation pattern (Tier 0 — use instead of spawning a Haiku agent)
Determine the endpoint from identity.json, then call directly with the Bash tool:
```bash
# Resolve endpoint once per session
OLLAMA=$([ "$(jq -r .machine ~/.claude/identity.json 2>/dev/null)" = "DESKTOP-0O8A1RL" ] \
&& echo "http://localhost:11434" || echo "http://100.92.127.64:11434")
# General task (summarize, classify, extract, draft)
curl -s "$OLLAMA/api/generate" \
-d "{\"model\":\"qwen3:14b\",\"prompt\":\"$(echo "$PROMPT" | python3 -c 'import sys,json; print(json.dumps(sys.stdin.read()))'| tr -d '\"')\",\"stream\":false}" \
| python3 -c "import sys,json; print(json.load(sys.stdin).get('response',''))"
# Code suggestion (refactor ideas, docstrings — NOT production code)
# Same call, model: "codestral:22b"
```
**Practical shorthand** — for one-off inline prompts, use python3 to avoid escaping issues:
```bash
python3 -c "
import urllib.request, json, sys
url = 'http://localhost:11434/api/generate' # or 100.92.127.64
body = json.dumps({'model':'qwen3:14b','prompt': sys.argv[1],'stream':False}).encode()
res = json.loads(urllib.request.urlopen(urllib.request.Request(url, body)).read())
print(res['response'])
" "Summarize these changes in one sentence: ..."
```
**When to use which model:**
| Task | Model |
|------|-------|
| Summarize logs, diffs, session notes | qwen3:14b |
| Classify bug type, severity, category | qwen3:14b |
| Extract structured data from text output | qwen3:14b |
| Draft commit message from diff | qwen3:14b |
| Suggest refactor for a function (review output) | codestral:22b |
| Docstring / comment generation | codestral:22b |
**Review policy:**
- Low-stakes output (summary, label, draft) — use directly, no review needed
- Code suggestions from codestral — always review before applying
- Never use Ollama for: auth decisions, credential handling, production migrations, security review
**Review policy:** Always review Critical/High impact Ollama outputs (auth, security, migrations, production). Trust Low impact (classification, formatting). Flag uncertainty to user.
### GrepAI (Semantic Code Search)
Use for intent-based search ("how does auth work"), exploring unfamiliar code, context recovery.
- **MCP tool:** `grepai` server tools
- **Agent:** `deep-explore` agent
- **CLI:** `grepai search "query" --json --compact`
---
## 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)
- **Project structure, endpoints, workflows:** `.claude/REFERENCE.md`
- **Agent definitions:** `.claude/agents/*.md`
- **MCP servers:** `MCP_SERVERS.md`
- **Coding standards:** `.claude/CODING_GUIDELINES.md`
---
**Last Updated:** 2026-04-02

67
.claude/OLLAMA.md Normal file
View File

@@ -0,0 +1,67 @@
# Ollama — Local AI Reference
Ollama runs on Mike's workstation (DESKTOP-0O8A1RL) with GPU acceleration. Available to all team members via Tailscale.
## Models
| Model | Size | Use For |
|-------|------|---------|
| `qwen3:14b` | 9.3 GB | Summarization, classification, data extraction, drafting |
| `codestral:22b` | 12 GB | Code generation, refactoring suggestions, docstrings |
| `nomic-embed-text` | 274 MB | Embeddings only (used by GrepAI) |
## Endpoints
- **DESKTOP-0O8A1RL** (local): `http://localhost:11434`
- **Any other machine** (Tailscale required): `http://100.92.127.64:11434`
Check reachability:
```bash
curl -s http://100.92.127.64:11434/api/tags | python -c "import sys,json; [print(m['name']) for m in json.load(sys.stdin).get('models',[])]"
```
If it fails: verify Tailscale is connected (`tailscale status`) and Mike's workstation is online.
## Access Control
- Port 11434 allowed ONLY from Tailscale subnet (100.0.0.0/8)
- NOT exposed to LAN, VPN, or internet
- Binding: `OLLAMA_HOST=0.0.0.0:11434` (firewall restricts)
## Calling Ollama
Resolve endpoint from identity.json first:
```bash
OLLAMA=$([ "$(jq -r .machine .claude/identity.json 2>/dev/null)" = "DESKTOP-0O8A1RL" ] \
&& echo "http://localhost:11434" || echo "http://100.92.127.64:11434")
```
Preferred one-liner (avoids shell escaping):
```bash
python3 -c "
import urllib.request, json, sys
url = 'http://localhost:11434/api/generate'
body = json.dumps({'model':'qwen3:14b','prompt': sys.argv[1],'stream':False}).encode()
res = json.loads(urllib.request.urlopen(urllib.request.Request(url, body)).read())
print(res['response'])
" "Your prompt here"
```
For code suggestions, swap `qwen3:14b` for `codestral:22b`.
## When to Use Which Model
| Task | Model |
|------|-------|
| Summarize logs, diffs, session notes | qwen3:14b |
| Classify bug type, severity, category | qwen3:14b |
| Extract structured data from text | qwen3:14b |
| Draft commit message from diff | qwen3:14b |
| Suggest refactor for a function | codestral:22b |
| Docstring / comment generation | codestral:22b |
## Review Policy
- Low-stakes output (summary, classification, draft) — use directly
- Code suggestions from codestral — always review before applying
- Never use Ollama for: auth decisions, credential handling, production migrations, security review

42
.claude/PROJECT_STATE_PROTOCOL.md Normal file
View File

@@ -0,0 +1,42 @@
# PROJECT_STATE.md Locking Protocol
This protocol prevents conflicts between concurrent Claude sessions. Follow it for every significant action on any project that has a PROJECT_STATE.md.
## What Requires a Lock
- 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.
## The Protocol
**Step 1 — Read before acting**
Re-read PROJECT_STATE.md before starting:
- Check Active Session Locks: is anything locked that you need to touch?
- Conflicting lock < 2 hours old: stop, report to user, ask how to proceed.
- Lock > 2 hours old (stale): note it to user, clear the row, proceed.
**Step 2 — Claim your lock**
Add a row to Active Session Locks before performing the action:
| Session | Working On | Status | Blocks | Started |
|---------|-----------|--------|--------|---------|
| DESKTOP-0O8A1RL/Claude | Brief description | IN_PROGRESS | What others must avoid | HH:MM UTC |
Use `{machine}/{Claude or agent description}` as the Session identifier.
**Step 3 — Perform the action**
**Step 4 — Update on completion OR failure**
1. Remove your lock row
2. Add a Recent Changes entry with status: `COMPLETE`, `FAILED`, `PARTIAL`, or `ROLLED_BACK`
3. Update Current Project State if any component status changed
4. Check off completed Pending items
## Stale Lock Rule
A lock older than 2 hours with no timestamp update is abandoned. Clear it, note `[Cleared stale lock from {session}]` in Recent Changes, then proceed.

34
session-logs/2026-04-20-session.md
View File

@@ -223,6 +223,40 @@ Committed: db157e3
--- ---
## Update: 19:08 UTC — CLAUDE.md Optimization
### Summary
Refactored `.claude/CLAUDE.md` to reduce context window pressure. Extracted verbose sections to on-demand reference files. No functional changes — same rules, smaller footprint.
### Changes Made
**`.claude/CLAUDE.md`** — 494 lines → 252 lines (~49% reduction)
- Work Mode section: replaced 22-line narrative with a 5-row detection table; dropped color references (color changes don't work programmatically anyway — mode.md handles that)
- PROJECT_STATE.md Action Protocol: removed entirely (~65 lines) — moved to dedicated file
- Ollama section: trimmed from ~90 lines to 5-line summary + pointer
- Auto Context Loading: removed Benefits list, condensed anti-pattern examples to one sentence
- Credential Access: kept the 4 vault commands, removed encryption/key location details
**`.claude/OLLAMA.md`** — new file (67 lines)
- Full Ollama reference: endpoints, models, connection examples, review policy
- Only loaded when Claude needs to call Ollama (Tier 0 tasks)
**`.claude/PROJECT_STATE_PROTOCOL.md`** — new file (42 lines)
- Full locking protocol: what requires a lock, how to claim/release, stale lock rule
- Only loaded when Auto Context Loading finds a PROJECT_STATE.md in a project
### Decisions
- PROJECT_STATE files already have brief locking instructions embedded in their headers — the full protocol in CLAUDE.md was redundant
- Work mode colors were dropped from CLAUDE.md because `/color` is a CLI built-in Claude can't invoke programmatically; mode.md already has the authoritative detail
- Ollama extraction was the biggest single win (~90 lines) — it's only needed for Tier 0 delegation, not every session
### Pending
- None. This was a self-contained optimization pass.
---
## Key Infrastructure Reference ## Key Infrastructure Reference
| Resource | Details | | Resource | Details |