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)

# 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

ssh guru@172.16.3.30 "mysql ... SELECT COUNT(*) FROM conversation_contexts"

Should have been: Database Agent task

❌ Violation 2: Direct API Calls

curl -X POST http://172.16.3.30:8001/api/conversation-contexts ...

Should have been: Database Agent task

❌ Violation 3: Direct Context Creation

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