diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index aa0e9ed..4948d50 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -150,7 +150,7 @@ Never ask "What did we do last time?" or "What's the server IP?" — read the CO **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` +- Roadmap: `projects/msp-tools/guru-rmm/docs/FEATURE_ROADMAP.md` (also `docs/UI_GAPS.md`) --- diff --git a/.claude/FILE_PLACEMENT_GUIDE.md b/.claude/FILE_PLACEMENT_GUIDE.md index 38e0cfa..5487de4 100644 --- a/.claude/FILE_PLACEMENT_GUIDE.md +++ b/.claude/FILE_PLACEMENT_GUIDE.md @@ -16,7 +16,7 @@ | Client Info | Client details | `clients/[client-name]/CLIENT_INFO.md` | | Client Session Logs | Support notes | `clients/[client-name]/session-logs/` | | ClaudeTools API Code | `*.py`, migrations | `api/`, `migrations/` (keep existing structure) | -| ClaudeTools API Logs | Session notes | `projects/claudetools-api/session-logs/` | +| ClaudeTools API Logs | Session notes | `session-logs/` (root) | | General Session Logs | Mixed work | `session-logs/YYYY-MM-DD-session.md` | | Credentials | All credentials | `credentials.md` (root - shared) | @@ -28,7 +28,7 @@ **Ask yourself:** What project or client is this related to? - Dataforth DOS → `projects/dataforth-dos/` -- ClaudeTools API → `projects/claudetools-api/` or root API folders +- ClaudeTools API → root `api/`, `migrations/` folders; session logs to root `session-logs/` - Specific Client → `clients/[client-name]/` - Multiple projects → Root or `session-logs/` @@ -96,8 +96,8 @@ clients/[client-name]/ **Files Created:** - New router → `api/routers/new_endpoint.py` (existing structure) - Migration → `migrations/versions/xxx_add_table.py` (existing structure) -- Session log → `projects/claudetools-api/session-logs/2026-01-20-session.md` -- API docs → `projects/claudetools-api/documentation/NEW_ENDPOINT.md` +- Session log → `session-logs/2026-01-20-session.md` (root) +- API docs → `api/` or root `docs/` if cross-cutting ### Scenario 4: Mixed Work (Multiple Projects) diff --git a/CONTEXT.md b/CONTEXT.md index 84a44ad..a0e7ca0 100644 --- a/CONTEXT.md +++ b/CONTEXT.md @@ -1,264 +1,264 @@ -# ClaudeTools - Project Context - -**Last Updated:** 2026-04-14 -**Status:** Active - Production Stable - -## Quick Start - Infrastructure Overview - -| Component | Location | Access | Notes | -|-----------|----------|--------|-------| -| **Production API** | http://172.16.3.30:8001 | Public access | ClaudeTools work tracking API | -| **Production DB** | MariaDB @ 172.16.3.30:3306/claudetools | Vault credentials | 38 tables, AES-256-GCM encryption | -| **Vault (SOPS)** | D:\vault\ | age-encrypted YAML | Primary credential store | -| **1Password** | Service account | Fallback | op://Projects/ClaudeTools * | -| **Gitea Repo** | git.azcomputerguru.com/azcomputerguru/claudetools | Active development | Main codebase | - -**Get DB credentials:** -```bash -bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password -``` - -## Current State (READ THIS FIRST) - -### Project Status -- **API:** 95+ endpoints, production-stable -- **Database:** 38 tables, fully encrypted sensitive fields -- **Authentication:** JWT-based, AES-256-GCM for API keys -- **Deployment:** Auto-deploy via Gitea webhooks (planned) - -### Active Subprojects -1. **GuruRMM** - Remote monitoring system (see projects/msp-tools/guru-rmm/CONTEXT.md) -2. **Dataforth DOS** - Test datasheet pipeline (see projects/dataforth-dos/CONTEXT.md) - -### Session Logs -- **Project-specific:** projects/*/session-logs/ -- **Client work:** clients/*/session-logs/ -- **General:** session-logs/ (root) - -## Anti-Patterns (DON'T DO THIS) - -❌ **DO NOT query database directly** - Use Database Agent for ALL operations - -❌ **DO NOT write production code yourself** - Delegate to Coding Agent, coordinate as needed - -❌ **DO NOT use emojis** - ASCII markers only: [OK], [ERROR], [WARNING], [SUCCESS], [INFO] - -❌ **DO NOT hardcode credentials** - Always use SOPS vault (primary) or 1Password (fallback) - -❌ **DO NOT skip Code Review Agent** - MANDATORY after any code changes - -❌ **DO NOT execute >500 token operations directly** - Delegate to appropriate agent - -## Where to Find Things - -### Repository Structure -``` -ClaudeTools/ -├── .claude/ -│ ├── CLAUDE.md # Project instructions (directives) -│ ├── REFERENCE.md # Technical reference -│ ├── CODING_GUIDELINES.md # Code standards -│ ├── FILE_PLACEMENT_GUIDE.md # Where to save files -│ ├── agents/ # Agent definitions -│ └── memory/ # Persistent facts (syncs via Git) -├── credentials.md # Infrastructure reference (migrating to vault) -├── session-logs/ # General session logs -├── projects/ -│ ├── msp-tools/guru-rmm/ # GuruRMM (CONTEXT.md there) -│ ├── dataforth-dos/ # Dataforth (CONTEXT.md there) -│ └── claudetools-api/ # API codebase (legacy) -├── clients/ -│ └── [client-name]/ # Client-specific work -└── D:\vault\ # SOPS encrypted credentials (separate repo) -``` - -### Credential Locations - -**Primary: SOPS Vault (D:\vault\)** -```bash -# Search for keywords (no decryption needed) -bash D:/vault/scripts/vault.sh search "claudetools" - -# Get specific field -bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password - -# List all entries -bash D:/vault/scripts/vault.sh list -``` - -**Structure:** -- infrastructure/ - Servers, network gear -- clients/ - Client-specific credentials -- services/ - External services (GitHub, APIs) -- projects/ - Project databases, APIs -- msp-tools/ - MSP application credentials - -**Fallback: 1Password** -```bash -# ClaudeTools database credentials -op read "op://Projects/ClaudeTools Database/password" - -# ClaudeTools API auth -op read "op://Projects/ClaudeTools API Auth/credential" -``` - -## Common Operations - -### Start Work on Subproject -``` -User: "Let's work on GuruRMM tunnel Phase 2" - -Claude should: -1. Read projects/msp-tools/guru-rmm/CONTEXT.md (this file) -2. Check recent session logs referenced in CONTEXT.md -3. Understand current state, infrastructure, anti-patterns -4. Proceed without asking user for context - -DO NOT: -- Ask user "what's the server IP?" -- Ask user "where is the database?" -- Ask user "what credentials should I use?" -All of this is in CONTEXT.md -``` - -### Database Operations -```bash -# WRONG: Direct query -ssh user@172.16.3.30 "mysql -u claudetools -p claudetools -e 'SELECT * FROM ...'" - -# RIGHT: Delegate to Database Agent -"Use Database Agent to query work_logs table for entries from last 7 days" -``` - -### Deploy Code Changes -```bash -# WRONG: Deploy yourself -scp file.js user@172.16.3.30:/path/ - -# RIGHT: Follow project deployment process -# (See project-specific CONTEXT.md for deployment steps) -``` - -## Project-Specific Context Files - -**When user says "work on [project]", read that project's CONTEXT.md FIRST:** - -| Project | CONTEXT.md Location | What It Contains | -|---------|---------------------|------------------| -| GuruRMM | projects/msp-tools/guru-rmm/CONTEXT.md | Server IPs, deployment, tunnel architecture, agent status | -| Dataforth DOS | projects/dataforth-dos/CONTEXT.md | AD2/AD1 infrastructure, testdatadb service, log formats | -| ClaudeTools API | (This file) | Main project overview, credential locations | - -## Coordination Rules (My Role) - -I am a **Coordinator**, NOT an executor: - -| Operation | Delegate To | -|-----------|-------------| -| Database queries/updates | Database Agent | -| Production code generation | Coding Agent | -| Code review (MANDATORY) | Code Review Agent | -| Test execution | Testing Agent | -| Git commit/push | Gitea Agent | -| Backups/restore | Backup Agent | -| File exploration | Explore Agent | -| Semantic code search | deep-explore Agent (GrepAI) | -| Complex reasoning | General-purpose + Sequential Thinking | - -**I do myself:** Simple responses, reading 1-2 files, presenting results, planning, decisions - -**Rule:** >500 tokens of work = delegate - -## Memory System - -**Location:** `.claude/memory/` (syncs across machines via Git) - -**Structure:** -- MEMORY.md - Index of all facts -- [topic]-context.md - Topic-specific persistent facts - -**IMPORTANT:** Always write to `.claude/memory/` (repo-relative), NOT `~/.claude/projects/*/memory/` - -## Session Log Locations - -**Follow these rules:** - -| Work Type | Save To | -|-----------|---------| -| Dataforth DOS work | projects/dataforth-dos/session-logs/ | -| ClaudeTools API code | projects/claudetools-api/session-logs/ | -| GuruRMM work | projects/msp-tools/guru-rmm/session-logs/ | -| Client work | clients/[client-name]/session-logs/ | -| General/mixed work | session-logs/ (root) | - -**See:** .claude/FILE_PLACEMENT_GUIDE.md for full rules - -## Auto-Invoke Skills - -**Frontend Design:** Auto-invoke `/frontend-design` skill after ANY UI change (HTML/CSS/JSX/styling) - -**Sequential Thinking:** Use for genuine complexity only: -- Rejection loops (3+ failed attempts) -- Critical architectural decisions -- Multi-step debugging with unclear root cause -- NOT for every task - -## Key Commands - -| Command | Purpose | When | -|---------|---------|------| -| `/checkpoint` | Git commit + database context save | After code changes | -| `/save` | Comprehensive session log | End of session | -| `/context` | Search session logs + credentials | User references previous work | -| `/1password` | 1Password operations | Manage secrets | -| `/sync` | Sync from Gitea | Update local config | -| `/refresh-directives` | Re-read CLAUDE.md | After summarization, large tasks | - -## Reference Documents (Read On-Demand) - -- **Project instructions:** .claude/CLAUDE.md (my role, agent delegation rules) -- **Technical reference:** .claude/REFERENCE.md (endpoints, database, workflows) -- **Coding standards:** .claude/CODING_GUIDELINES.md (agents read, not every session) -- **File placement:** .claude/FILE_PLACEMENT_GUIDE.md (where to save files) -- **MCP servers:** MCP_SERVERS.md (available integrations) -- **Agent definitions:** .claude/agents/*.md (agent capabilities) - -## Troubleshooting - -### "I don't know the database password" -- **Check:** D:\vault\ (SOPS encrypted) -- **Command:** `bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password` -- **Fallback:** credentials.md (has 1Password references) - -### "Where is the GuruRMM server?" -- **Check:** projects/msp-tools/guru-rmm/CONTEXT.md -- **Answer:** 172.16.3.30 (listed in first table) - -### "How do I deploy Dataforth changes?" -- **Check:** projects/dataforth-dos/CONTEXT.md -- **Section:** "Common Operations → Deploy Code to AD2" - -### "I forgot my role as Coordinator" -- **Read:** .claude/CLAUDE.md -- **Command:** `/refresh-directives` - -## Quick Links - -- **Credentials (vault):** D:\vault\ (SOPS encrypted YAML) -- **Credentials (legacy):** credentials.md (migrating to vault) -- **Gitea:** http://172.16.3.20:3000/azcomputerguru/claudetools -- **API Docs:** http://172.16.3.30:8001/api/docs - ---- - -**When user says "work on [project]":** -1. Read [project]/CONTEXT.md FIRST (don't ask user for context) -2. Check recent session logs mentioned in CONTEXT.md -3. Understand infrastructure, anti-patterns, current state -4. Proceed with work - -**This eliminates:** -- "What's the server IP?" → In CONTEXT.md -- "Where's the database?" → In CONTEXT.md -- "What credentials?" → In CONTEXT.md -- "What did we do last time?" → In session logs referenced by CONTEXT.md +# ClaudeTools - Project Context + +**Last Updated:** 2026-04-14 +**Status:** Active - Production Stable + +## Quick Start - Infrastructure Overview + +| Component | Location | Access | Notes | +|-----------|----------|--------|-------| +| **Production API** | http://172.16.3.30:8001 | Public access | ClaudeTools work tracking API | +| **Production DB** | MariaDB @ 172.16.3.30:3306/claudetools | Vault credentials | 38 tables, AES-256-GCM encryption | +| **Vault (SOPS)** | D:\vault\ | age-encrypted YAML | Primary credential store | +| **1Password** | Service account | Fallback | op://Projects/ClaudeTools * | +| **Gitea Repo** | git.azcomputerguru.com/azcomputerguru/claudetools | Active development | Main codebase | + +**Get DB credentials:** +```bash +bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password +``` + +## Current State (READ THIS FIRST) + +### Project Status +- **API:** 95+ endpoints, production-stable +- **Database:** 38 tables, fully encrypted sensitive fields +- **Authentication:** JWT-based, AES-256-GCM for API keys +- **Deployment:** Auto-deploy via Gitea webhooks (planned) + +### Active Subprojects +1. **GuruRMM** - Remote monitoring system (see projects/msp-tools/guru-rmm/CONTEXT.md) +2. **Dataforth DOS** - Test datasheet pipeline (see projects/dataforth-dos/CONTEXT.md) + +### Session Logs +- **Project-specific:** projects/*/session-logs/ +- **Client work:** clients/*/session-logs/ +- **General:** session-logs/ (root) + +## Anti-Patterns (DON'T DO THIS) + +❌ **DO NOT query database directly** - Use Database Agent for ALL operations + +❌ **DO NOT write production code yourself** - Delegate to Coding Agent, coordinate as needed + +❌ **DO NOT use emojis** - ASCII markers only: [OK], [ERROR], [WARNING], [SUCCESS], [INFO] + +❌ **DO NOT hardcode credentials** - Always use SOPS vault (primary) or 1Password (fallback) + +❌ **DO NOT skip Code Review Agent** - MANDATORY after any code changes + +❌ **DO NOT execute >500 token operations directly** - Delegate to appropriate agent + +## Where to Find Things + +### Repository Structure +``` +ClaudeTools/ +├── .claude/ +│ ├── CLAUDE.md # Project instructions (directives) +│ ├── REFERENCE.md # Technical reference +│ ├── CODING_GUIDELINES.md # Code standards +│ ├── FILE_PLACEMENT_GUIDE.md # Where to save files +│ ├── agents/ # Agent definitions +│ └── memory/ # Persistent facts (syncs via Git) +├── credentials.md # Infrastructure reference (migrating to vault) +├── session-logs/ # General session logs +├── projects/ +│ ├── msp-tools/guru-rmm/ # GuruRMM (CONTEXT.md there) +│ ├── dataforth-dos/ # Dataforth (CONTEXT.md there) +│ └── (API code is at root: api/, migrations/) +├── clients/ +│ └── [client-name]/ # Client-specific work +└── D:\vault\ # SOPS encrypted credentials (separate repo) +``` + +### Credential Locations + +**Primary: SOPS Vault (D:\vault\)** +```bash +# Search for keywords (no decryption needed) +bash D:/vault/scripts/vault.sh search "claudetools" + +# Get specific field +bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password + +# List all entries +bash D:/vault/scripts/vault.sh list +``` + +**Structure:** +- infrastructure/ - Servers, network gear +- clients/ - Client-specific credentials +- services/ - External services (GitHub, APIs) +- projects/ - Project databases, APIs +- msp-tools/ - MSP application credentials + +**Fallback: 1Password** +```bash +# ClaudeTools database credentials +op read "op://Projects/ClaudeTools Database/password" + +# ClaudeTools API auth +op read "op://Projects/ClaudeTools API Auth/credential" +``` + +## Common Operations + +### Start Work on Subproject +``` +User: "Let's work on GuruRMM tunnel Phase 2" + +Claude should: +1. Read projects/msp-tools/guru-rmm/CONTEXT.md (this file) +2. Check recent session logs referenced in CONTEXT.md +3. Understand current state, infrastructure, anti-patterns +4. Proceed without asking user for context + +DO NOT: +- Ask user "what's the server IP?" +- Ask user "where is the database?" +- Ask user "what credentials should I use?" +All of this is in CONTEXT.md +``` + +### Database Operations +```bash +# WRONG: Direct query +ssh user@172.16.3.30 "mysql -u claudetools -p claudetools -e 'SELECT * FROM ...'" + +# RIGHT: Delegate to Database Agent +"Use Database Agent to query work_logs table for entries from last 7 days" +``` + +### Deploy Code Changes +```bash +# WRONG: Deploy yourself +scp file.js user@172.16.3.30:/path/ + +# RIGHT: Follow project deployment process +# (See project-specific CONTEXT.md for deployment steps) +``` + +## Project-Specific Context Files + +**When user says "work on [project]", read that project's CONTEXT.md FIRST:** + +| Project | CONTEXT.md Location | What It Contains | +|---------|---------------------|------------------| +| GuruRMM | projects/msp-tools/guru-rmm/CONTEXT.md | Server IPs, deployment, tunnel architecture, agent status | +| Dataforth DOS | projects/dataforth-dos/CONTEXT.md | AD2/AD1 infrastructure, testdatadb service, log formats | +| ClaudeTools API | (This file) | Main project overview, credential locations | + +## Coordination Rules (My Role) + +I am a **Coordinator**, NOT an executor: + +| Operation | Delegate To | +|-----------|-------------| +| Database queries/updates | Database Agent | +| Production code generation | Coding Agent | +| Code review (MANDATORY) | Code Review Agent | +| Test execution | Testing Agent | +| Git commit/push | Gitea Agent | +| Backups/restore | Backup Agent | +| File exploration | Explore Agent | +| Semantic code search | deep-explore Agent (GrepAI) | +| Complex reasoning | General-purpose + Sequential Thinking | + +**I do myself:** Simple responses, reading 1-2 files, presenting results, planning, decisions + +**Rule:** >500 tokens of work = delegate + +## Memory System + +**Location:** `.claude/memory/` (syncs across machines via Git) + +**Structure:** +- MEMORY.md - Index of all facts +- [topic]-context.md - Topic-specific persistent facts + +**IMPORTANT:** Always write to `.claude/memory/` (repo-relative), NOT `~/.claude/projects/*/memory/` + +## Session Log Locations + +**Follow these rules:** + +| Work Type | Save To | +|-----------|---------| +| Dataforth DOS work | projects/dataforth-dos/session-logs/ | +| ClaudeTools API code | projects/claudetools-api/session-logs/ | +| GuruRMM work | projects/msp-tools/guru-rmm/session-logs/ | +| Client work | clients/[client-name]/session-logs/ | +| General/mixed work | session-logs/ (root) | + +**See:** .claude/FILE_PLACEMENT_GUIDE.md for full rules + +## Auto-Invoke Skills + +**Frontend Design:** Auto-invoke `/frontend-design` skill after ANY UI change (HTML/CSS/JSX/styling) + +**Sequential Thinking:** Use for genuine complexity only: +- Rejection loops (3+ failed attempts) +- Critical architectural decisions +- Multi-step debugging with unclear root cause +- NOT for every task + +## Key Commands + +| Command | Purpose | When | +|---------|---------|------| +| `/checkpoint` | Git commit + database context save | After code changes | +| `/save` | Comprehensive session log | End of session | +| `/context` | Search session logs + credentials | User references previous work | +| `/1password` | 1Password operations | Manage secrets | +| `/sync` | Sync from Gitea | Update local config | +| `/refresh-directives` | Re-read CLAUDE.md | After summarization, large tasks | + +## Reference Documents (Read On-Demand) + +- **Project instructions:** .claude/CLAUDE.md (my role, agent delegation rules) +- **Technical reference:** .claude/REFERENCE.md (endpoints, database, workflows) +- **Coding standards:** .claude/CODING_GUIDELINES.md (agents read, not every session) +- **File placement:** .claude/FILE_PLACEMENT_GUIDE.md (where to save files) +- **MCP servers:** MCP_SERVERS.md (available integrations) +- **Agent definitions:** .claude/agents/*.md (agent capabilities) + +## Troubleshooting + +### "I don't know the database password" +- **Check:** D:\vault\ (SOPS encrypted) +- **Command:** `bash D:/vault/scripts/vault.sh get-field projects/claudetools/database.sops.yaml credentials.password` +- **Fallback:** credentials.md (has 1Password references) + +### "Where is the GuruRMM server?" +- **Check:** projects/msp-tools/guru-rmm/CONTEXT.md +- **Answer:** 172.16.3.30 (listed in first table) + +### "How do I deploy Dataforth changes?" +- **Check:** projects/dataforth-dos/CONTEXT.md +- **Section:** "Common Operations → Deploy Code to AD2" + +### "I forgot my role as Coordinator" +- **Read:** .claude/CLAUDE.md +- **Command:** `/refresh-directives` + +## Quick Links + +- **Credentials (vault):** D:\vault\ (SOPS encrypted YAML) +- **Credentials (legacy):** credentials.md (migrating to vault) +- **Gitea:** http://172.16.3.20:3000/azcomputerguru/claudetools +- **API Docs:** http://172.16.3.30:8001/api/docs + +--- + +**When user says "work on [project]":** +1. Read [project]/CONTEXT.md FIRST (don't ask user for context) +2. Check recent session logs mentioned in CONTEXT.md +3. Understand infrastructure, anti-patterns, current state +4. Proceed with work + +**This eliminates:** +- "What's the server IP?" → In CONTEXT.md +- "Where's the database?" → In CONTEXT.md +- "What credentials?" → In CONTEXT.md +- "What did we do last time?" → In session logs referenced by CONTEXT.md