feat: Add directives system and DOS management utilities
Implemented comprehensive directives system for agent coordination: - Created directives.md (590 lines) - Core operational rules defining coordinator vs executor roles, agent delegation patterns, and coding standards (NO EMOJIS, ASCII markers only) - Added DIRECTIVES_ENFORCEMENT.md - Documentation of enforcement mechanisms and checklist for validating compliance - Created refresh-directives command - Allows reloading directives after Gitea updates without restarting Claude Code - Updated checkpoint and save commands to verify directives compliance - Updated .claude/claude.md to mandate reading directives.md first Added DOS system management PowerShell utilities: - check-bat-on-nas.ps1 - Verify BAT files on NAS match source - check-latest-errors.ps1 - Scan DOS error logs for recent issues - check-plink-references.ps1 - Find plink.exe usage in scripts - check-scp-errors.ps1 - Analyze SCP transfer errors - check-sync-log.ps1 (modified) - Enhanced sync log analysis - check-sync-status.ps1 - Monitor sync process status - copy-to-nas-now.ps1 - Manual NAS file deployment - find-error-logging.ps1 - Locate error logging patterns - fix-copy-tonas-logging.ps1 - Repair logging in copy scripts - fix-dos-files.ps1 - Batch DOS file corrections - fix-line-break.ps1 - Fix line ending issues - fix-plink-usage.ps1 - Modernize plink.exe to WinRM - push-fixed-bat-files.ps1 - Deploy corrected BAT files - run-sync-direct.ps1 - Direct sync execution - test-error-logging.ps1 - Validate error logging functionality - trigger-sync-push.ps1 - Initiate sync push operations - verify-error-logging.ps1 - Confirm error logging working - scripts/fix-ad2-error-logging.ps1 - Fix AD2 error logging Added Gitea password management scripts: - Reset-GiteaPassword.ps1 - Windows PowerShell password reset - reset-gitea-password.sh - Unix shell password reset Key architectural decisions: - Directives system establishes clear separation between Main Claude (coordinator) and specialized agents (executors) - DOS utilities modernize legacy plink.exe usage to WinRM - Error logging enhancements improve troubleshooting capabilities - All scripts follow PSScriptAnalyzer standards Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
418
.claude/DIRECTIVES_ENFORCEMENT.md
Normal file
418
.claude/DIRECTIVES_ENFORCEMENT.md
Normal file
@@ -0,0 +1,418 @@
|
||||
# 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 ✅
|
||||
4. What I DO NOT DO ❌
|
||||
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 ✅❌⚠️ 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 (✅❌⚠️) 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
|
||||
Reference in New Issue
Block a user