claudetools/.claude/DIRECTIVES_ENFORCEMENT.md

# 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