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

refactor: Consolidate directives into CLAUDE.md, delete redundant files

Browse Source 
Deleted:
- directives.md (9-line redirect, obsolete)
- DIRECTIVES_ENFORCEMENT.md (408 lines of enforcement theater)
- AGENT_COORDINATION_RULES.md (merged into CLAUDE.md)
- refresh-directives command (no longer needed)

Updated:
- CLAUDE.md: Added coordination flow, GuruRMM project, removed hardcoded
  DB password, trimmed Ollama section, updated project description
- CODING_GUIDELINES.md: Cut from 428 to ~90 lines, project-specific only

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Mike Swanson
2026-04-02 19:19:06 -07:00
parent 3d363e481d
commit 6e4ebc2db9
6 changed files with 78 additions and 1262 deletions
Download Patch File Download Diff File Expand all files Collapse all files

152
.claude/CLAUDE.md
View File

@@ -23,16 +23,28 @@ You are NOT an executor. You coordinate specialized agents and preserve your con
**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.
### Coordination Flow
```
User request -> Main Claude (coordinator) -> Launches agent(s) -> Agent returns summary -> Main Claude presents to user
```
- Independent operations run in parallel
- Skills (Skill tool) enhance/validate. Agents (Agent tool) execute/operate.
---
## Project Overview
## Projects
**Type:** MSP Work Tracking System | **Status:** Production-Ready (Phase 5 Complete)
**Database:** MariaDB 10.6.22 @ 172.16.3.30:3306 | **API:** http://172.16.3.30:8001
**Stats:** 95+ endpoints, 38 tables, JWT auth, AES-256-GCM encryption
**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`
**DB Connection:** Host: 172.16.3.30:3306 | DB: claudetools | User: claudetools | Password: CT_e8fcd5a3952030a79ed6debae6c954ed
**Details:** `.claude/agents/DATABASE_CONNECTION_INFO.md`
**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`
---
@@ -42,7 +54,7 @@ You are NOT an executor. You coordinate specialized agents and preserve your con
- **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.
- **Full coding standards:** `.claude/CODING_GUIDELINES.md` (agents read on-demand, not every session)
- **Coding standards:** `.claude/CODING_GUIDELINES.md` (agents read on-demand, not every session)
---
@@ -70,33 +82,19 @@ Credentials are stored in SOPS+age encrypted YAML files in a dedicated Gitea rep
**To read credentials:**
```bash
# Search by keyword (no decryption needed - metadata is plaintext)
bash D:/vault/scripts/vault.sh search "172.16.3.30"
# Get a specific field
bash D:/vault/scripts/vault.sh get-field infrastructure/gururmm-server.sops.yaml credentials.password
# Decrypt full entry
bash D:/vault/scripts/vault.sh get infrastructure/gururmm-server.sops.yaml
# List all entries
bash D:/vault/scripts/vault.sh list
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 (kind, name, host, tags) stays plaintext for searchability. Only `credentials`, `notes`, and secret fields are encrypted.
**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)
**Setup on new machines:**
1. Install: `winget install Mozilla.sops FiloSottile.age MikeFarah.yq` (or brew/pacman)
2. Generate key: `age-keygen -o ~/.config/sops/age/keys.txt`
3. Clone: `git clone git@git.azcomputerguru.com:azcomputerguru/vault.git`
4. Add public key to `keys/recipients.txt`, push, then run `vault rotate` from existing machine
### 1Password (Fallback)
1Password remains available for browser autofill and as fallback. Service account token is in the vault:
`bash D:/vault/scripts/vault.sh get-field infrastructure/1password-service-account.sops.yaml credentials.token`
Service account token in vault: `infrastructure/1password-service-account.sops.yaml`
---
@@ -118,6 +116,7 @@ bash D:/vault/scripts/vault.sh list
- **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)
@@ -126,103 +125,46 @@ bash D:/vault/scripts/vault.sh list
## Local AI (Ollama)
Ollama runs locally with GPU acceleration. Use it for tasks that don't need Claude-level reasoning.
### Available Models
Ollama runs locally with GPU acceleration for tasks that don't need Claude-level reasoning.
| Model | Size | Use For |
|-------|------|---------|
| `qwen3:14b` | 9.3 GB | General sub-tasks: summarization, classification, data extraction, drafting |
| `codestral:22b` | 12 GB | Code-specific sub-tasks: code generation, refactoring suggestions, docstring generation |
| `nomic-embed-text` | 274 MB | Embeddings only (used by GrepAI, not for direct use) |
| `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) |
```bash
# Simple prompt
curl -s http://localhost:11434/api/generate -d '{"model":"qwen3:14b","prompt":"...","stream":false}' | jq -r '.response'
```
**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)
GrepAI indexes the codebase using `nomic-embed-text` embeddings and provides semantic search via MCP server.
**When to use GrepAI instead of Grep/Glob:**
- Finding code by intent ("how does authentication work") rather than exact text
- Exploring unfamiliar areas of the codebase
- Finding related implementations across files
- Context recovery — searching session logs and credentials by meaning
**How to use:**
- **MCP tool:** Use the `grepai` MCP server tools directly (available after MCP loads)
- **deep-explore agent:** Delegate to the `deep-explore` agent for thorough semantic exploration
- **CLI fallback:** `grepai search "your query" --json --compact`
**Maintenance:** The watcher daemon runs in the background and auto-indexes file changes. If search results seem stale, run `grepai watch --stop && grepai watch --background` to restart it.
### Using Ollama for Sub-Tasks
For bulk or repetitive work that doesn't require Claude's full reasoning, offload to local models via Ollama's API:
**When to use Ollama:**
- Processing many items in a loop (e.g., summarizing 50 session logs)
- Generating boilerplate or repetitive code patterns
- Data extraction/classification from structured text
- Draft content that Claude will review/refine
- Any task where speed > quality and results will be verified
**When NOT to use Ollama (use Claude instead):**
- Architectural decisions or complex reasoning
- Security-sensitive code review
- Tasks requiring tool use or multi-step planning
- Final output that goes directly to production
**How to call Ollama:**
```bash
# Simple prompt
curl -s http://localhost:11434/api/generate -d '{"model":"qwen3:14b","prompt":"Summarize this: ...","stream":false}' | jq -r '.response'
# Chat format
curl -s http://localhost:11434/api/chat -d '{"model":"codestral:22b","messages":[{"role":"user","content":"Refactor this function: ..."}],"stream":false}' | jq -r '.message.content'
```
### Ollama Output Review Policy
The coordinator (Claude) must review Ollama outputs based on impact level. Local models are useful but unreliable — they hallucinate, miss edge cases, and produce subtly wrong code.
**Impact levels and review requirements:**
| Level | Review | Examples |
|-------|--------|----------|
| **Critical** | ALWAYS review, verify against source | Code touching auth/security/encryption, credential handling, database migrations, production config, anything user-facing |
| **High** | Review for correctness, spot-check details | API endpoint logic, business rules, infrastructure scripts, client-specific work |
| **Medium** | Skim for obvious errors, trust if reasonable | Internal documentation drafts, session log summaries, data extraction from structured input, boilerplate code |
| **Low** | Trust without review | Classification/tagging of items, reformatting text, generating placeholder content for later editing |
**Review process for Critical/High:**
1. Read Ollama's full output — don't just check if it "looks right"
2. Verify claims against actual files/data (e.g., if it says a function exists, confirm it does)
3. Check for: hallucinated function names, wrong parameter types, missing error handling, security gaps
4. If output is wrong or uncertain, redo the task yourself rather than patching Ollama's attempt
**Batch processing pattern:**
When using Ollama for bulk tasks (e.g., processing N items), review the first 2-3 results fully before trusting the rest. If any are wrong, switch to doing it yourself or fix the prompt and reprocess.
**Flag to user:** If Ollama produces output for a Critical task and you are not confident in your review, tell the user explicitly: "This was generated by a local model and I'm not fully confident in [specific concern]."
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)
Claude Code's auto-memory is stored **in-repo** at `.claude/memory/` so it syncs via Gitea to all workstations.
Stored in-repo at `.claude/memory/` -- syncs via Gitea to all workstations.
Index: `.claude/memory/MEMORY.md`
**IMPORTANT for all machines:** Configure Claude Code to use the repo memory path, NOT the default `~/.claude/projects/` path. When the auto-memory system prompts you to write to `~/.claude/projects/-home-guru-ClaudeTools/memory/`, write to `.claude/memory/` (repo-relative) instead. The index file is `.claude/memory/MEMORY.md`.
This ensures memory created on one workstation (CachyOS, Mac, Windows) is available on all others after a git pull/sync.
**IMPORTANT:** Always write to `.claude/memory/` (repo-relative), NOT `~/.claude/projects/*/memory/`.
---
## Reference (read on-demand, not every session)
## Reference (read on-demand)
- **Project structure, endpoints, workflows, troubleshooting:** `.claude/REFERENCE.md`
- **Project structure, endpoints, workflows:** `.claude/REFERENCE.md`
- **Agent definitions:** `.claude/agents/*.md`
- **MCP servers:** `MCP_SERVERS.md`
- **Coding standards:** `.claude/CODING_GUIDELINES.md`
- **Shared memory:** `.claude/memory/MEMORY.md` (index) + `.claude/memory/*.md` (individual memories)
---
**Last Updated:** 2026-03-22
**Last Updated:** 2026-04-02