diff --git a/.claude/AGENT_COORDINATION_RULES.md b/.claude/AGENT_COORDINATION_RULES.md deleted file mode 100644 index f22aa60..0000000 --- a/.claude/AGENT_COORDINATION_RULES.md +++ /dev/null @@ -1,38 +0,0 @@ -# Agent Coordination Rules - -**Purpose:** Reference for agents about their responsibilities and coordination patterns. -**Main Claude behavioral rules are in CLAUDE.md - this file is for agent reference only.** - ---- - -## Agent Responsibilities - -| Agent | Authority | Examples | -|-------|-----------|----------| -| Database Agent | ALL data operations | Queries, inserts, updates, deletes, API calls | -| Coding Agent | Production code | Python, PowerShell, Bash; new code and modifications | -| Testing Agent | Test execution | pytest, validation scripts, performance tests | -| Code Review Agent | Code quality (MANDATORY) | Security, standards, quality checks before commits | -| Gitea Agent | Git/version control | Commits, pushes, branches, tags | -| Backup Agent | Backup/restore | Create backups, restore data, verify integrity | - -## Coordination Flow - -``` -User request -> Main Claude (coordinator) -> Launches agent(s) -> Agent returns summary -> Main Claude presents to user -``` - -- Main Claude NEVER queries databases, writes production code, runs tests, or commits directly -- Agents return concise summaries, not raw data -- Independent operations run in parallel -- Use Sequential Thinking MCP for genuinely complex problems - -## Skills vs Agents - -- **Skills** (Skill tool): Specialized enhancements - frontend-design validation, design patterns -- **Agents** (Task tool): Core operations - database, code, testing, git, backups -- **Rule:** Skills enhance/validate. Agents execute/operate. - ---- - -**Last Updated:** 2026-02-17 diff --git a/.claude/CLAUDE.md b/.claude/CLAUDE.md index 9b31c24..2a6dfd0 100644 --- a/.claude/CLAUDE.md +++ b/.claude/CLAUDE.md @@ -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 `) 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 # Get specific field +bash D:/vault/scripts/vault.sh get # 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 diff --git a/.claude/CODING_GUIDELINES.md b/.claude/CODING_GUIDELINES.md index e0ec217..6525cb5 100644 --- a/.claude/CODING_GUIDELINES.md +++ b/.claude/CODING_GUIDELINES.md @@ -1,364 +1,57 @@ # ClaudeTools - Coding Guidelines -## General Principles - -These guidelines ensure code quality, consistency, and maintainability across the ClaudeTools project. +Project-specific standards. Generic language conventions (PEP 8, etc.) are assumed knowledge. --- -## Character Encoding and Text +## Character Encoding ### NO EMOJIS - EVER -**Rule:** Never use emojis in any code files, including: -- Python scripts (.py) -- PowerShell scripts (.ps1) -- Bash scripts (.sh) -- Configuration files -- Documentation within code -- Log messages -- Output strings +Never use emojis in code, scripts, config files, log messages, or output strings. -**Rationale:** -- Emojis cause encoding issues (UTF-8 vs ASCII) -- PowerShell parsing errors with special Unicode characters -- Cross-platform compatibility problems -- Terminal rendering inconsistencies -- Version control diff issues +**Rationale:** Causes PowerShell parsing errors, encoding issues, terminal rendering problems. -**Instead of emojis, use:** -```powershell -# BAD - causes parsing errors -Write-Host "✓ Success!" -Write-Host "⚠ Warning!" - -# GOOD - ASCII text markers -Write-Host "[OK] Success!" -Write-Host "[SUCCESS] Task completed!" -Write-Host "[WARNING] Check settings!" -Write-Host "[ERROR] Failed to connect!" +**Use instead:** +``` +[OK] [SUCCESS] [INFO] [WARNING] [ERROR] [CRITICAL] ``` -**Allowed in:** -- User-facing web UI (where Unicode is properly handled) -- Database content (with proper UTF-8 encoding) -- Markdown documentation (README.md, etc.) - use sparingly +**Exception:** User-facing web UI with proper UTF-8 handling. --- -## Python Code Standards +## Naming Conventions -### Style -- Follow PEP 8 style guide -- Use 4 spaces for indentation (no tabs) -- Maximum line length: 100 characters (relaxed from 79) -- Use type hints for function parameters and return values - -### Imports -```python -# Standard library imports -import os -import sys -from datetime import datetime - -# Third-party imports -from fastapi import FastAPI -from sqlalchemy import Column - -# Local imports -from api.models import User -from api.utils import encrypt_data -``` - -### Naming Conventions -- Classes: `PascalCase` (e.g., `UserService`, `CredentialModel`) -- Functions/methods: `snake_case` (e.g., `get_user`, `create_session`) -- Constants: `UPPER_SNAKE_CASE` (e.g., `API_BASE_URL`, `MAX_RETRIES`) -- Private methods: `_leading_underscore` (e.g., `_internal_helper`) +- **Python:** snake_case functions, PascalCase classes, UPPER_SNAKE constants +- **PowerShell:** PascalCase variables ($TaskName), approved verbs (Get-/Set-/New-) +- **Bash:** lowercase_underscore functions, quote all variables +- **DB tables:** lowercase plural (users, user_sessions), FK as {table}_id +- **DB columns:** created_at/updated_at timestamps, is_/has_ boolean prefixes --- -## PowerShell Code Standards +## Security -### Style -- Use 4 spaces for indentation -- Use PascalCase for variables: `$TaskName`, `$PythonPath` -- Use approved verbs for functions: `Get-`, `Set-`, `New-`, `Remove-` - -### Error Handling -```powershell -# Always use -ErrorAction for cmdlets that might fail -$Task = Get-ScheduledTask -TaskName $TaskName -ErrorAction SilentlyContinue -if (-not $Task) { - Write-Host "[ERROR] Task not found" - exit 1 -} -``` - -### Output -```powershell -# Use clear status markers -Write-Host "[INFO] Starting process..." -Write-Host "[SUCCESS] Task completed" -Write-Host "[ERROR] Failed to connect" -Write-Host "[WARNING] Configuration missing" -``` +- Never hardcode credentials -- use SOPS vault or environment variables +- JWT tokens for API auth, Argon2 for password hashing +- Log all authentication attempts and sensitive operations +- `.env` files are gitignored, never committed --- -## Bash Script Standards +## API Standards -### Style -- Use 2 spaces for indentation -- Always use `#!/bin/bash` shebang -- Quote all variables: `"$variable"` not `$variable` -- Use `set -e` for error handling (exit on error) - -### Functions -```bash -# Use lowercase with underscores -function check_connection() { - local host="$1" - echo "[INFO] Checking connection to $host" -} -``` +- RESTful with plural nouns: `/api/users` +- Consistent error format: `{"detail": "...", "error_code": "...", "status_code": N}` +- Paginate large result sets +- Document with OpenAPI (automatic with FastAPI) --- -## API Development Standards +## Output Markers -### Endpoints -- Use RESTful conventions -- Use plural nouns: `/api/users` not `/api/user` -- Use HTTP methods appropriately: GET, POST, PUT, DELETE -- Version APIs if breaking changes: `/api/v2/users` - -### Error Responses -```python -# Return consistent error format -{ - "detail": "User not found", - "error_code": "USER_NOT_FOUND", - "status_code": 404 -} -``` - -### Documentation -- Every endpoint must have a docstring -- Use Pydantic schemas for request/response validation -- Document in OpenAPI (automatic with FastAPI) - ---- - -## Database Standards - -### Table Naming -- Use lowercase with underscores: `user_sessions`, `billable_time` -- Use plural nouns: `users` not `user` -- Use consistent prefixes for related tables - -### Columns -- Primary key: `id` (UUID) -- Timestamps: `created_at`, `updated_at` -- Foreign keys: `{table}_id` (e.g., `user_id`, `project_id`) -- Boolean: `is_active`, `has_access` (prefix with is_/has_) - -### Indexes -```python -# Add indexes for frequently queried fields -Index('idx_users_email', 'email') -Index('idx_sessions_project_id', 'project_id') -``` - ---- - -## Security Standards - -### Credentials -- Never hardcode credentials in code -- Use environment variables for sensitive data -- Use `.env` files (gitignored) for local development -- Encrypt passwords with AES-256-GCM (Fernet) - -### Authentication -- Use JWT tokens for API authentication -- Hash passwords with Argon2 -- Include token expiration -- Log all authentication attempts - -### Audit Logging -```python -# Log all sensitive operations -audit_log = CredentialAuditLog( - credential_id=credential.id, - action="password_updated", - user_id=current_user.id, - details="Password updated via API" -) -``` - ---- - -## Testing Standards - -### Test Files -- Name: `test_{module_name}.py` -- Location: Same directory as code being tested -- Use pytest framework - -### Test Structure -```python -def test_create_user(): - """Test user creation with valid data.""" - # Arrange - user_data = {"email": "test@example.com", "name": "Test"} - - # Act - result = create_user(user_data) - - # Assert - assert result.email == "test@example.com" - assert result.id is not None -``` - -### Coverage -- Aim for 80%+ code coverage -- Test happy path and error cases -- Mock external dependencies (database, APIs) - ---- - -## Git Commit Standards - -### Commit Messages -``` -[Type] Brief description (50 chars max) - -Detailed explanation if needed (wrap at 72 chars) - -- Change 1 -- Change 2 -- Change 3 -``` - -### Types -- `[Feature]` - New feature -- `[Fix]` - Bug fix -- `[Refactor]` - Code refactoring -- `[Docs]` - Documentation only -- `[Test]` - Test updates -- `[Config]` - Configuration changes - ---- - -## File Organization - -### Directory Structure -``` -project/ -├── api/ # API application code -│ ├── models/ # Database models -│ ├── routers/ # API endpoints -│ ├── schemas/ # Pydantic schemas -│ ├── services/ # Business logic -│ └── utils/ # Helper functions -├── .claude/ # Claude Code configuration -│ ├── hooks/ # Git-style hooks -│ └── agents/ # Agent instructions -├── scripts/ # Utility scripts -└── migrations/ # Database migrations -``` - -### File Naming -- Python: `snake_case.py` -- Classes: Match class name (e.g., `UserService` in `user_service.py`) -- Scripts: Descriptive names (e.g., `setup_database.sh`, `test_api.py`) - ---- - -## Documentation Standards - -### Code Comments -```python -# Use comments for WHY, not WHAT -# Good: "Retry 3 times to handle transient network errors" -# Bad: "Set retry count to 3" - -def fetch_data(url: str) -> dict: - """ - Fetch data from API endpoint. - - Args: - url: Full URL to fetch from - - Returns: - Parsed JSON response - - Raises: - ConnectionError: If API is unreachable - ValueError: If response is invalid JSON - """ -``` - -### README Files -- Include quick start guide -- Document prerequisites -- Provide examples -- Keep up to date - ---- - -## Error Handling - -### Python -```python -# Use specific exceptions -try: - result = api_call() -except ConnectionError as e: - logger.error(f"[ERROR] Connection failed: {e}") - raise -except ValueError as e: - logger.warning(f"[WARNING] Invalid data: {e}") - return None -``` - -### PowerShell -```powershell -# Use try/catch for error handling -try { - $Result = Invoke-RestMethod -Uri $Url -} catch { - Write-Host "[ERROR] Request failed: $_" - exit 1 -} -``` - ---- - -## Logging Standards - -### Log Levels -- `DEBUG` - Detailed diagnostic info (development only) -- `INFO` - General informational messages -- `WARNING` - Warning messages (non-critical issues) -- `ERROR` - Error messages (failures) -- `CRITICAL` - Critical errors (system failures) - -### Log Format -```python -# Use structured logging -logger.info( - "[INFO] User login", - extra={ - "user_id": user.id, - "ip_address": request.client.host, - "timestamp": datetime.utcnow() - } -) -``` - -### Output Markers +All scripts and tools use ASCII status markers: ``` [INFO] Starting process [SUCCESS] Task completed @@ -369,60 +62,12 @@ logger.info( --- -## Performance Guidelines +## Git -### Database Queries -- Use indexes for frequently queried fields -- Avoid N+1 queries (use joins or eager loading) -- Paginate large result sets -- Use connection pooling - -### API Responses -- Return only necessary fields -- Use pagination for lists -- Compress large payloads -- Cache frequently accessed data - -### File Operations -- Use context managers (`with` statements) -- Stream large files (don't load into memory) -- Clean up temporary files +- Commit types: feat, fix, refactor, docs, test, config +- Always include `Co-Authored-By` line for Claude commits +- Never commit .env, credentials, venv, __pycache__, *.log --- -## Version Control - -### .gitignore -Always exclude: -- `.env` files (credentials) -- `__pycache__/` (Python cache) -- `*.pyc` (compiled Python) -- `.venv/`, `venv/` (virtual environments) -- `.claude/*.json` (local state) -- `*.log` (log files) - -### Branching -- `main` - Production-ready code -- `develop` - Integration branch -- `feature/*` - New features -- `fix/*` - Bug fixes -- `hotfix/*` - Urgent production fixes - ---- - -## Review Checklist - -Before committing code, verify: -- [ ] No emojis or special Unicode characters -- [ ] All variables and functions have descriptive names -- [ ] No hardcoded credentials or sensitive data -- [ ] Error handling is implemented -- [ ] Code is formatted consistently -- [ ] Tests pass (if applicable) -- [ ] Documentation is updated -- [ ] No debugging print statements left in code - ---- - -**Last Updated:** 2026-01-17 -**Status:** Active +**Last Updated:** 2026-04-02 diff --git a/.claude/DIRECTIVES_ENFORCEMENT.md b/.claude/DIRECTIVES_ENFORCEMENT.md deleted file mode 100644 index 431acd5..0000000 --- a/.claude/DIRECTIVES_ENFORCEMENT.md +++ /dev/null @@ -1,418 +0,0 @@ -# Directives Enforcement Mechanism - -**Created:** 2026-01-19 -**Purpose:** Ensure Claude consistently follows operational directives and stops taking shortcuts - ---- - -## The Problem - -Claude (Main Instance) has a tendency to: -- Take shortcuts by querying database directly instead of using Database Agent -- Use emojis despite explicit prohibition (causes PowerShell errors) -- Execute operations directly instead of coordinating via agents -- Forget directives after conversation compaction or long sessions - -**Result:** Violated architecture, broken scripts, inconsistent behavior - ---- - -## The Solution: Multi-Layered Enforcement - -### Layer 1: Prominent Directive Reference in claude.md - -**File:** `.claude/claude.md` (line 3-15) - -```markdown -**FIRST: READ YOUR DIRECTIVES** - -Before doing ANYTHING in this project, read and internalize `directives.md` in the project root. - -This file defines: -- Your identity (Coordinator, not Executor) -- What you DO and DO NOT do -- Agent coordination rules (NEVER query database directly) -- Enforcement checklist (NO EMOJIS, ASCII markers only) - -**If you haven't read directives.md in this session, STOP and read it now.** - -Command: `Read directives.md` (in project root: D:\ClaudeTools\directives.md) -``` - -**Effect:** First thing Claude sees when loading project context - ---- - -### Layer 2: /refresh-directives Command - -**File:** `.claude/commands/refresh-directives.md` - -**Purpose:** Command to re-read and internalize directives - -**User invocation:** -``` -/refresh-directives -``` - -**Auto-invocation points:** -- After `/checkpoint` command -- After `/save` command -- After conversation compaction (detected automatically) -- After large task completion (3+ agents) -- Every 50 tool uses (optional counter-based) - -**What it does:** -1. Reads `directives.md` completely -2. Performs self-assessment for violations -3. Commits to following directives -4. Reports status to user - -**Output:** -```markdown -## Directives Refreshed - -I've re-read my operational directives. - -**Key commitments:** -- [OK] Coordinate via agents, not execute -- [OK] Database Agent for ALL data operations -- [OK] ASCII markers only (no emojis) -- [OK] Preserve context by delegating - -**Self-assessment:** Clean - no violations detected - -**Status:** Ready to coordinate effectively. -``` - ---- - -### Layer 3: Integration with /checkpoint Command - -**File:** `.claude/commands/checkpoint.md` (step 8) - -**After git + database checkpoint:** -```markdown -8. **Refresh directives** (MANDATORY): - - After checkpoint completion, auto-invoke `/refresh-directives` - - Re-read `directives.md` to prevent shortcut-taking - - Perform self-assessment for any violations - - Confirm commitment to agent coordination rules - - Report directives refreshed to user -``` - -**Effect:** Every checkpoint automatically refreshes directives - ---- - -### Layer 4: Integration with /save Command - -**File:** `.claude/commands/save.md` (step 4) - -**After saving session log:** -```markdown -4. **Refresh directives** (MANDATORY): - - Auto-invoke `/refresh-directives` - - Re-read `directives.md` to prevent shortcut-taking - - Perform self-assessment for violations - - Confirm commitment to coordination rules - - Report directives refreshed -``` - -**Effect:** Every session save automatically refreshes directives - ---- - -### Layer 5: directives.md (The Source of Truth) - -**File:** `directives.md` (project root) - -**Contains:** -- Identity definition (Coordinator, not Executor) -- What Claude DOES and DOES NOT do -- Complete agent coordination rules -- Coding standards (NO EMOJIS - ASCII only) -- Enforcement checklist -- Pre-action verification questions - -**Key sections:** -1. My Identity -2. Core Operating Principle -3. What I DO [OK] -4. What I DO NOT DO [ERROR] -5. Agent Coordination Rules -6. Skills vs Agents -7. Automatic Behaviors -8. Coding Standards (NO EMOJIS) -9. Enforcement Checklist - ---- - -## Automatic Trigger Points - -### Session Start -``` -Claude loads project → Sees claude.md → "READ DIRECTIVES FIRST" -→ Reads directives.md → Internalizes rules → Ready to work -``` - -### After Checkpoint -``` -User: /checkpoint -→ Claude creates git commit + database context -→ Verifies both succeeded -→ AUTO-INVOKES /refresh-directives -→ Re-reads directives.md -→ Confirms ready to proceed -``` - -### After Save -``` -User: /save -→ Claude creates/updates session log -→ Commits to repository -→ AUTO-INVOKES /refresh-directives -→ Re-reads directives.md -→ Confirms ready to proceed -``` - -### After Conversation Compaction -``` -System: [Conversation compacted due to length] -→ Claude detects compaction (system message) -→ AUTO-INVOKES /refresh-directives -→ Re-reads directives.md -→ Restores operational mode -→ Continues with proper coordination -``` - -### After Large Task -``` -Claude completes task using 3+ agents -→ Recognizes major work completed -→ AUTO-INVOKES /refresh-directives -→ Re-reads directives.md -→ Resets to coordination mode -→ Ready for next task -``` - ---- - -## Violation Detection - -### Self-Assessment Process - -**During /refresh-directives, Claude checks:** - -**Database Operations:** -- [ ] Did I query database directly via ssh/mysql/curl? → VIOLATION -- [ ] Did I call ClaudeTools API directly? → VIOLATION -- [ ] Did I use Database Agent for data operations? → CORRECT - -**Code Generation:** -- [ ] Did I write production code myself? → VIOLATION -- [ ] Did I delegate to Coding Agent? → CORRECT - -**Emoji Usage:** -- [ ] Did I use [OK][ERROR][WARNING] or other emojis? → VIOLATION -- [ ] Did I use [OK]/[ERROR]/[WARNING]? → CORRECT - -**Agent Coordination:** -- [ ] Did I execute operations directly? → VIOLATION -- [ ] Did I coordinate via agents? → CORRECT - -**If violations detected:** -```markdown -[WARNING] Detected 2 directive violations: -- Direct database query at timestamp X -- Emoji usage in output at timestamp Y - -[OK] Corrective actions committed: -- Will use Database Agent for all database operations -- Will use ASCII markers [OK]/[ERROR] instead of emojis - -[SUCCESS] Directives re-internalized. Proper coordination restored. -``` - ---- - -## Benefits - -### Prevents Shortcut-Taking -- Regular reminders not to query database directly -- Reinforces agent coordination model -- Stops emoji usage before it causes errors - -### Context Recovery -- Restores operational mode after compaction -- Ensures consistency across sessions -- Maintains proper coordination principles - -### Self-Correction -- Detects violations automatically -- Commits to corrective behavior -- Provides accountability to user - -### User Visibility -- User sees when directives refreshed -- Transparent operational changes -- Builds trust in coordination model - ---- - -## Enforcement Checklist - -### For Claude (Self-Check Before Any Action) - -**Before database operation:** -- [ ] Read directives.md this session? If no → STOP and read -- [ ] Am I about to query database? → Use Database Agent instead -- [ ] Am I about to use curl/API? → Use Database Agent instead - -**Before writing code:** -- [ ] Am I writing production code? → Delegate to Coding Agent -- [ ] Am I using emojis? → STOP, use [OK]/[ERROR]/[WARNING] - -**Before git operations:** -- [ ] Am I about to commit? → Delegate to Gitea Agent -- [ ] Am I about to push? → Delegate to Gitea Agent - -**After major operations:** -- [ ] Completed checkpoint/save? → Auto-invoke /refresh-directives -- [ ] Completed large task? → Auto-invoke /refresh-directives -- [ ] Conversation compacted? → Auto-invoke /refresh-directives - ---- - -## User Commands - -### Manual Refresh -``` -/refresh-directives -``` -Manually trigger directive re-reading and self-assessment - -### Checkpoint (Auto-refresh) -``` -/checkpoint -``` -Creates git commit + database context, then auto-refreshes directives - -### Save (Auto-refresh) -``` -/save -``` -Creates session log, then auto-refreshes directives - -### Sync -``` -/sync -``` -Pulls latest from Gitea (directives.md included if updated) - ---- - -## Monitoring - -### User Can Monitor Compliance - -**Check for violations:** -- Look for direct `ssh`, `mysql`, or `curl` commands to database -- Look for emoji characters ([OK][ERROR][WARNING]) in output -- Look for direct code generation (should delegate to Coding Agent) - -**If violations detected:** -``` -User: /refresh-directives -``` -Forces Claude to re-read and commit to directives - ---- - -## Maintenance - -### Updating directives.md - -**When to update:** -- New agent added to system -- New restriction discovered -- Behavior patterns change -- New shortcut tendencies identified - -**Process:** -1. Edit `directives.md` with new rules -2. Commit changes to repository -3. Push to Gitea -4. Invoke `/sync` on other machines -5. Invoke `/refresh-directives` to apply immediately - ---- - -## Summary - -**Five-layer enforcement:** -1. **claude.md** - Prominent reference at top (first thing Claude sees) -2. **/refresh-directives command** - Explicit directive re-reading -3. **/checkpoint integration** - Auto-refresh after checkpoints -4. **/save integration** - Auto-refresh after session saves -5. **directives.md** - Complete operational ruleset - -**Automatic triggers:** -- Session start -- After /checkpoint -- After /save -- After conversation compaction -- After large tasks - -**Result:** Claude consistently follows directives, stops taking shortcuts, maintains proper agent coordination architecture. - ---- - -## Example: Full Enforcement Flow - -``` -Session Start: -→ Claude loads .claude/claude.md -→ Sees "READ YOUR DIRECTIVES FIRST" -→ Reads directives.md completely -→ Internalizes rules -→ Ready to coordinate (not execute) - -User Request: -→ "How many projects in database?" -→ Claude recognizes database operation -→ Checks directives: "Database Agent handles ALL database operations" -→ Launches Database Agent with task -→ Receives count from agent -→ Presents to user - -After /checkpoint: -→ Git commit created -→ Database context saved -→ AUTO-INVOKES /refresh-directives -→ Re-reads directives.md -→ Self-assessment: Clean -→ Confirms: "Directives refreshed. Ready to coordinate." - -Conversation Compacted: -→ System compacts conversation -→ Claude detects compaction -→ AUTO-INVOKES /refresh-directives -→ Re-reads directives.md -→ Restores coordination mode -→ Continues properly -``` - ---- - -**This enforcement mechanism ensures Claude maintains proper operational behavior throughout the entire session lifecycle.** - ---- - -**Created:** 2026-01-19 -**Files Modified:** -- `.claude/claude.md` - Added directive reference at top -- `.claude/commands/checkpoint.md` - Added step 8 (refresh directives) -- `.claude/commands/save.md` - Added step 4 (refresh directives) -- `.claude/commands/refresh-directives.md` - New command definition - -**Status:** Active enforcement system diff --git a/.claude/commands/refresh-directives.md b/.claude/commands/refresh-directives.md deleted file mode 100644 index f3c2da5..0000000 --- a/.claude/commands/refresh-directives.md +++ /dev/null @@ -1,306 +0,0 @@ -# /refresh-directives Command - -**Purpose:** Re-read and internalize operational directives to prevent shortcut-taking and ensure proper agent coordination. - ---- - -## When to Use - -**Automatic triggers (I should invoke this):** -- After conversation compaction/summarization -- After completing a large task -- When detecting directive violations (database queries, emoji use, etc.) -- At start of new work session -- After extended conversation (>100 exchanges) - -**Manual invocation:** -- User types: `/refresh-directives` -- User says: "refresh your directives" or "read your rules again" - ---- - -## What This Command Does - -1. **Reads directives.md** - Full file from project root -2. **Self-assessment** - Checks recent actions for violations -3. **Commitment** - Explicitly commits to following directives -4. **Reports to user** - Confirms directives internalized - ---- - -## Execution Steps - -### Step 1: Read Directives File -``` -Read tool → D:\ClaudeTools\directives.md -``` - -**Must read entire file** - All sections are mandatory: -- My Identity -- Core Operating Principle -- What I DO / DO NOT DO -- Agent Coordination Rules -- Coding Standards (NO EMOJIS) -- Enforcement Checklist - -### Step 2: Self-Assessment - -**Check recent conversation for violations:** - -**Database Operations:** -- [ ] Did I query database directly? (Violation) -- [ ] Did I use ssh/mysql/curl to ClaudeTools API? (Violation) -- [ ] Did I delegate to Database Agent? (Correct) - -**Code Generation:** -- [ ] Did I write production code myself? (Violation) -- [ ] Did I delegate to Coding Agent? (Correct) - -**Emoji Usage:** -- [ ] Did I use emojis in code/output? (Violation) -- [ ] Did I use ASCII markers [OK]/[ERROR]? (Correct) - -**Agent Coordination:** -- [ ] Did I execute operations directly? (Violation) -- [ ] Did I coordinate via agents? (Correct) - -### Step 3: Commit to Directives - -**Explicit commitment statement:** - -"I have read and internalized directives.md. I commit to: -- Coordinating via agents, not executing directly -- Using Database Agent for ALL database operations -- Using ASCII markers, NEVER emojis -- Preserving my context by delegating -- Following the enforcement checklist before every action" - -### Step 4: Report to User - -**Format:** -```markdown -## Directives Refreshed - -I've re-read and internalized my operational directives from `directives.md`. - -**Key commitments:** -- [OK] Coordinate via agents (not execute directly) -- [OK] Database Agent handles ALL database operations -- [OK] ASCII markers only (no emojis: [OK], [ERROR], [WARNING]) -- [OK] Preserve context by delegating operations >500 tokens -- [OK] Auto-invoke frontend-design skill for UI changes - -**Self-assessment:** [Clean / X violations detected] - -**Status:** Ready to coordinate effectively. -``` - ---- - -## Integration Points - -### With /checkpoint Command - -**After git commit + database save:** -``` -1. Execute checkpoint (git + database) -2. Verify both succeeded -3. Auto-invoke /refresh-directives -4. Confirm directives refreshed -``` - -### With /save Command - -**After creating session log:** -``` -1. Create/append session log -2. Commit to repository -3. Auto-invoke /refresh-directives -4. Confirm directives refreshed -``` - -### With Session Start - -**When conversation begins:** -``` -1. If directives.md exists → Read it immediately -2. If starting new project → Create directives.md first -3. Confirm directives internalized before proceeding -``` - -### After Large Tasks - -**When completing major work:** -- Multi-agent coordination (3+ agents) -- Complex problem-solving with Sequential Thinking -- Database migrations or schema changes -- Large code refactoring - -**Trigger:** Auto-invoke /refresh-directives - ---- - -## Violation Detection - -**If I detect violations during self-assessment:** - -1. **Acknowledge violations:** - ``` - [WARNING] Detected X directive violations in recent conversation: - - Violation 1: Direct database query at [timestamp] - - Violation 2: Emoji usage in output at [timestamp] - ``` - -2. **Commit to correction:** - ``` - [OK] Corrective actions: - - Will use Database Agent for all future database operations - - Will use ASCII markers [OK]/[ERROR] instead of emojis - ``` - -3. **Reset behavior:** - ``` - [SUCCESS] Directives re-internalized. Proceeding with proper coordination. - ``` - ---- - -## Example Usage - -### User-Invoked -``` -User: /refresh-directives - -Claude: -[Reads directives.md] -[Performs self-assessment] -[Commits to directives] - -## Directives Refreshed - -I've re-read my operational directives. - -**Key commitments:** -- [OK] Coordinate via agents, not execute -- [OK] Database Agent for ALL data operations -- [OK] ASCII markers only (no emojis) -- [OK] Preserve context by delegating - -**Self-assessment:** Clean - no violations detected - -**Status:** Ready to coordinate effectively. -``` - -### Auto-Invoked After Checkpoint -``` -Claude: [Completes /checkpoint command] -Claude: [Auto-invokes /refresh-directives] -Claude: [Reads directives.md] -Claude: [Confirms directives internalized] - -Checkpoint complete. Directives refreshed. Ready for next task. -``` - -### Auto-Invoked After Conversation Compaction -``` -System: [Conversation compacted] -Claude: [Detects compaction occurred] -Claude: [Auto-invokes /refresh-directives] -Claude: [Reads directives.md] -Claude: [Confirms ready to proceed] - -Context compacted. Directives re-internalized. Continuing coordination. -``` - ---- - -## Technical Implementation - -### Hook Integration - -**Create hook:** `.claude/hooks/refresh-directives` - -```bash -#!/bin/bash -# Hook: Refresh Directives -# Triggers: session-start, post-checkpoint, post-compaction - -echo "[INFO] Triggering directives refresh..." -echo "Reading: D:/ClaudeTools/directives.md" -echo "[OK] Directives file available for refresh" -``` - -### Command Recognition - -**User input patterns:** -- `/refresh-directives` -- `/refresh` -- "refresh your directives" -- "read your rules again" -- "re-read directives" - -**Auto-trigger patterns:** -- After `/checkpoint` success -- After `/save` success -- After conversation compaction (detect via system messages) -- Every 50 tool uses (counter-based) - ---- - -## Benefits - -### Prevents Shortcut-Taking -- Reminds me not to query database directly -- Reinforces agent coordination model -- Stops emoji usage before it happens - -### Context Recovery -- Restores operational mode after compaction -- Ensures consistency across sessions -- Maintains coordination principles - -### Self-Correction -- Detects violations automatically -- Commits to corrective behavior -- Provides accountability - -### User Visibility -- User sees when directives refreshed -- Transparency in operational changes -- Builds trust in coordination model - ---- - -## Enforcement - -**Mandatory refresh points:** -1. [OK] Session start (if directives.md exists) -2. [OK] After conversation compaction -3. [OK] After /checkpoint command -4. [OK] After /save command -5. [OK] When user requests: /refresh-directives -6. [OK] After completing large tasks (3+ agents) - -**Optional refresh points:** -- Every 50 tool uses (counter-based) -- When detecting potential violations -- Before critical operations (migrations, deployments) - ---- - -## Summary - -**This command ensures I:** -- Never forget my role as Coordinator -- Always delegate to appropriate agents -- Use ASCII markers, never emojis -- Follow enforcement checklist -- Maintain proper agent architecture - -**Result:** Consistent, rule-following behavior across all sessions and contexts. - ---- - -**Created:** 2026-01-19 -**Purpose:** Enforce directives.md compliance throughout session lifecycle -**Status:** Active - auto-invoke at trigger points diff --git a/directives.md b/directives.md deleted file mode 100644 index 5944901..0000000 --- a/directives.md +++ /dev/null @@ -1,9 +0,0 @@ -# Claude Code Directives - -**All behavioral directives are now in `.claude/CLAUDE.md`** (auto-loaded every session). - -This file exists for backward compatibility. No need to read it separately. - -See `.claude/CLAUDE.md` for: identity, delegation rules, key rules, automatic behaviors, context recovery. - -**Last Updated:** 2026-02-17