claudetools/.claude/AGENT_COORDINATION_RULES.md

# 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