[Config] Add coding guidelines and code-fixer agent
Major additions: - Add CODING_GUIDELINES.md with "NO EMOJIS" rule - Create code-fixer agent for automated violation fixes - Add offline mode v2 hooks with local caching/queue - Add periodic context save with invisible Task Scheduler setup - Add agent coordination rules and database connection docs Infrastructure: - Update hooks: task-complete-v2, user-prompt-submit-v2 - Add periodic_save_check.py for auto-save every 5min - Add PowerShell scripts: setup_periodic_save.ps1, update_to_invisible.ps1 - Add sync-contexts script for queue synchronization Documentation: - OFFLINE_MODE.md, PERIODIC_SAVE_INVISIBLE_SETUP.md - Migration procedures and verification docs - Fix flashing window guide Updates: - Update agent configs (backup, code-review, coding, database, gitea, testing) - Update claude.md with coding guidelines reference - Update .gitignore for new cache/queue directories Status: Pre-automated-fixer baseline commit Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
272
.claude/AGENT_COORDINATION_RULES.md
Normal file
272
.claude/AGENT_COORDINATION_RULES.md
Normal file
@@ -0,0 +1,272 @@
|
||||
# Agent Coordination Rules
|
||||
|
||||
**CRITICAL: Main Claude is a COORDINATOR, not an executor**
|
||||
|
||||
---
|
||||
|
||||
## Core Principle
|
||||
|
||||
**Main Claude Instance:**
|
||||
- Coordinates work between user and agents
|
||||
- Makes decisions and plans
|
||||
- Presents concise results to user
|
||||
- **NEVER performs database operations directly**
|
||||
- **NEVER makes direct API calls to ClaudeTools API**
|
||||
|
||||
**Agents:**
|
||||
- Execute specific tasks (database, coding, testing, etc.)
|
||||
- Return concise summaries
|
||||
- Preserve Main Claude's context space
|
||||
|
||||
---
|
||||
|
||||
## Database Operations - ALWAYS Use Database Agent
|
||||
|
||||
### ❌ WRONG (What I Was Doing)
|
||||
|
||||
```bash
|
||||
# Main Claude making direct queries
|
||||
ssh guru@172.16.3.30 "mysql -u claudetools ... SELECT ..."
|
||||
curl http://172.16.3.30:8001/api/conversation-contexts ...
|
||||
```
|
||||
|
||||
### ✅ CORRECT (What Should Happen)
|
||||
|
||||
```
|
||||
Main Claude → Task tool → Database Agent → Returns summary
|
||||
```
|
||||
|
||||
**Example:**
|
||||
```
|
||||
User: "How many contexts are saved?"
|
||||
|
||||
Main Claude: "Let me check the database"
|
||||
↓
|
||||
Launches Database Agent with task: "Count conversation_contexts in database"
|
||||
↓
|
||||
Database Agent: Queries database, returns: "7 contexts found"
|
||||
↓
|
||||
Main Claude to User: "There are 7 contexts saved in the database"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Agent Responsibilities
|
||||
|
||||
### Database Agent (`.claude/agents/database.md`)
|
||||
**ONLY agent authorized for database operations**
|
||||
|
||||
**Handles:**
|
||||
- All SELECT, INSERT, UPDATE, DELETE queries
|
||||
- Context storage and retrieval
|
||||
- Data validation and integrity
|
||||
- Transaction management
|
||||
- Query optimization
|
||||
|
||||
**Returns:** Concise summaries, not raw SQL results
|
||||
|
||||
**When to use:**
|
||||
- Saving contexts to database
|
||||
- Retrieving contexts from database
|
||||
- Checking record counts
|
||||
- Any database operation
|
||||
|
||||
### Coding Agent (`.claude/agents/coding.md`)
|
||||
**Handles code writing and modifications**
|
||||
|
||||
**When to use:**
|
||||
- Writing new code
|
||||
- Modifying existing code
|
||||
- Creating scripts
|
||||
|
||||
### Testing Agent (`.claude/agents/testing.md`)
|
||||
**Handles test execution**
|
||||
|
||||
**When to use:**
|
||||
- Running tests
|
||||
- Executing validation scripts
|
||||
- Performance testing
|
||||
|
||||
### Code Review Agent (`.claude/agents/code-review.md`)
|
||||
**Reviews code quality**
|
||||
|
||||
**When to use:**
|
||||
- After significant code changes
|
||||
- Before committing
|
||||
|
||||
### Gitea Agent (`.claude/agents/gitea.md`)
|
||||
**Handles Git operations**
|
||||
|
||||
**When to use:**
|
||||
- Git commits
|
||||
- Push to remote
|
||||
- Branch management
|
||||
|
||||
### Backup Agent (`.claude/agents/backup.md`)
|
||||
**Manages backups**
|
||||
|
||||
**When to use:**
|
||||
- Creating backups
|
||||
- Restoring data
|
||||
- Backup verification
|
||||
|
||||
---
|
||||
|
||||
## Violation Examples from This Session
|
||||
|
||||
### ❌ Violation 1: Direct Database Queries
|
||||
```bash
|
||||
ssh guru@172.16.3.30 "mysql ... SELECT COUNT(*) FROM conversation_contexts"
|
||||
```
|
||||
**Should have been:** Database Agent task
|
||||
|
||||
### ❌ Violation 2: Direct API Calls
|
||||
```bash
|
||||
curl -X POST http://172.16.3.30:8001/api/conversation-contexts ...
|
||||
```
|
||||
**Should have been:** Database Agent task
|
||||
|
||||
### ❌ Violation 3: Direct Context Creation
|
||||
```bash
|
||||
curl ... -d '{"context_type": "session_summary", ...}'
|
||||
```
|
||||
**Should have been:** Database Agent task
|
||||
|
||||
---
|
||||
|
||||
## Correct Coordination Flow
|
||||
|
||||
### Example: Save Context to Database
|
||||
|
||||
**User Request:** "Save the current context"
|
||||
|
||||
**Main Claude Actions:**
|
||||
1. ✅ Summarize what needs to be saved
|
||||
2. ✅ Launch Database Agent with task:
|
||||
```
|
||||
"Save session context to database:
|
||||
- Title: [summary]
|
||||
- Dense summary: [compressed context]
|
||||
- Tags: [relevant tags]
|
||||
- Score: 8.5"
|
||||
```
|
||||
3. ✅ Receive agent response: "Context saved with ID abc-123"
|
||||
4. ✅ Tell user: "Context saved successfully"
|
||||
|
||||
**What Main Claude Does NOT Do:**
|
||||
- ❌ Make direct curl calls
|
||||
- ❌ Make direct SQL queries
|
||||
- ❌ Return raw database results to user
|
||||
|
||||
---
|
||||
|
||||
## Example: Retrieve Contexts
|
||||
|
||||
**User Request:** "What contexts do we have about offline mode?"
|
||||
|
||||
**Main Claude Actions:**
|
||||
1. ✅ Launch Database Agent with task:
|
||||
```
|
||||
"Search conversation_contexts for entries related to 'offline mode'.
|
||||
Return: titles, scores, and brief summaries of top 5 results"
|
||||
```
|
||||
2. ✅ Receive agent summary:
|
||||
```
|
||||
Found 3 contexts:
|
||||
1. "Offline Mode Implementation" (score 9.5)
|
||||
2. "Offline Mode Testing" (score 8.0)
|
||||
3. "Offline Mode Documentation" (score 7.5)
|
||||
```
|
||||
3. ✅ Present to user in conversational format
|
||||
|
||||
**What Main Claude Does NOT Do:**
|
||||
- ❌ Query API directly
|
||||
- ❌ Show raw JSON responses
|
||||
- ❌ Execute SQL
|
||||
|
||||
---
|
||||
|
||||
## Benefits of Agent Architecture
|
||||
|
||||
### Context Preservation
|
||||
- Main Claude's context not polluted with raw data
|
||||
- Can handle longer conversations
|
||||
- Focus on coordination, not execution
|
||||
|
||||
### Separation of Concerns
|
||||
- Database Agent handles data integrity
|
||||
- Coding Agent handles code quality
|
||||
- Main Claude handles user interaction
|
||||
|
||||
### Scalability
|
||||
- Agents can run in parallel
|
||||
- Each has full context window for their task
|
||||
- Complex operations don't bloat main context
|
||||
|
||||
---
|
||||
|
||||
## Enforcement
|
||||
|
||||
### Before Making ANY Database Operation:
|
||||
|
||||
**Ask yourself:**
|
||||
1. Am I about to query the database directly? → ❌ STOP
|
||||
2. Am I about to call the ClaudeTools API? → ❌ STOP
|
||||
3. Should the Database Agent handle this? → ✅ USE AGENT
|
||||
|
||||
### When to Launch Database Agent:
|
||||
- Saving any data (contexts, tasks, sessions, etc.)
|
||||
- Retrieving any data from database
|
||||
- Counting records
|
||||
- Searching contexts
|
||||
- Updating existing records
|
||||
- Deleting records
|
||||
- Any SQL operation
|
||||
|
||||
---
|
||||
|
||||
## Going Forward
|
||||
|
||||
**Main Claude Responsibilities:**
|
||||
- ✅ Coordinate with user
|
||||
- ✅ Make decisions about what to do
|
||||
- ✅ Launch appropriate agents
|
||||
- ✅ Synthesize agent results for user
|
||||
- ✅ Plan and design solutions
|
||||
|
||||
**Main Claude Does NOT:**
|
||||
- ❌ Query database directly
|
||||
- ❌ Make API calls to ClaudeTools API
|
||||
- ❌ Execute code (unless simple demonstration)
|
||||
- ❌ Run tests (use Testing Agent)
|
||||
- ❌ Commit to git (use Gitea Agent)
|
||||
|
||||
---
|
||||
|
||||
## Quick Reference
|
||||
|
||||
| Operation | Handler |
|
||||
|-----------|---------|
|
||||
| Save context | Database Agent |
|
||||
| Retrieve contexts | Database Agent |
|
||||
| Count records | Database Agent |
|
||||
| Write code | Coding Agent |
|
||||
| Run tests | Testing Agent |
|
||||
| Review code | Code Review Agent |
|
||||
| Git operations | Gitea Agent |
|
||||
| Backups | Backup Agent |
|
||||
| **User interaction** | **Main Claude** |
|
||||
| **Coordination** | **Main Claude** |
|
||||
| **Decision making** | **Main Claude** |
|
||||
|
||||
---
|
||||
|
||||
**Remember: Main Claude = Coordinator, not Executor**
|
||||
|
||||
**When in doubt, use an agent!**
|
||||
|
||||
---
|
||||
|
||||
**Created:** 2026-01-17
|
||||
**Purpose:** Ensure proper agent-based architecture
|
||||
**Status:** Mandatory guideline for all future operations
|
||||
Reference in New Issue
Block a user