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

38
.claude/AGENT_COORDINATION_RULES.md
View File

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

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

417
.claude/CODING_GUIDELINES.md
View File

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

418
.claude/DIRECTIVES_ENFORCEMENT.md
View File

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

306
.claude/commands/refresh-directives.md
View File

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

9
directives.md
View File

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