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

fix: correct dead references — FEATURE_ROADMAP path, claudetools-api nonexistent dir

Browse Source
This commit is contained in:
Mike Swanson
2026-05-14 18:46:48 -07:00
parent d6fc1cf5be
commit 4f23608306
3 changed files with 269 additions and 269 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
.claude/CLAUDE.md
View File

@@ -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`)
---

8
.claude/FILE_PLACEMENT_GUIDE.md
View File

@@ -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)

528
CONTEXT.md
View File

@@ -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