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

[ERROR] 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 ...

[OK] 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

[ERROR] Violation 1: Direct Database Queries

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

Should have been: Database Agent task

[ERROR] Violation 2: Direct API Calls

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

Should have been: Database Agent task

[ERROR] 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. [OK] Summarize what needs to be saved
2. [OK] Launch Database Agent with task:

   "Save session context to database:
   - Title: [summary]
   - Dense summary: [compressed context]
   - Tags: [relevant tags]
   - Score: 8.5"
   

3. [OK] Receive agent response: "Context saved with ID abc-123"
4. [OK] Tell user: "Context saved successfully"

What Main Claude Does NOT Do:

• [ERROR] Make direct curl calls
• [ERROR] Make direct SQL queries
• [ERROR] Return raw database results to user

---

Example: Retrieve Contexts

User Request: "What contexts do we have about offline mode?"

Main Claude Actions:

1. [OK] 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. [OK] 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. [OK] Present to user in conversational format

What Main Claude Does NOT Do:

• [ERROR] Query API directly
• [ERROR] Show raw JSON responses
• [ERROR] 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? → [ERROR] STOP
2. Am I about to call the ClaudeTools API? → [ERROR] STOP
3. Should the Database Agent handle this? → [OK] 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:

• [OK] Coordinate with user
• [OK] Make decisions about what to do
• [OK] Launch appropriate agents
• [OK] Synthesize agent results for user
• [OK] Plan and design solutions
• [OK] Automatically invoke skills when triggered (NEW)
• [OK] Recognize when Sequential Thinking is needed (NEW)
• [OK] Execute dual checkpoints (git + database) (NEW)

Main Claude Does NOT:

• [ERROR] Query database directly
• [ERROR] Make API calls to ClaudeTools API
• [ERROR] Execute code (unless simple demonstration)
• [ERROR] Run tests (use Testing Agent)
• [ERROR] Commit to git (use Gitea Agent)
• [ERROR] Review code (use Code Review Agent)
• [ERROR] Write production code (use Coding Agent)

---

New Capabilities (Added 2026-01-17)

1. Automatic Skill Invocation

Main Claude automatically invokes skills when triggered by specific actions:

Frontend Design Skill:

• Trigger: ANY action that affects a UI element
• When: After modifying HTML/CSS/JSX, styling, layouts, components
• Purpose: Validate visual correctness, functionality, UX, accessibility
• Workflow:

  User: "Add a submit button"
  Main Claude: [Writes button code]
  Main Claude: [AUTO-INVOKE frontend-design skill]
  Frontend Skill: [Validates appearance, behavior, accessibility]
  Frontend Skill: [Returns PASS/WARNING/ERROR]
  Main Claude: [Proceeds or fixes based on validation]
  

Rule: If the change appears in a browser, invoke frontend-design skill to validate it.

2. Sequential Thinking Recognition

Main Claude recognizes when agents should use Sequential Thinking MCP:

For Code Review Agent:

• Knows to use ST when code rejected 2+ times
• Knows to use ST when 3+ critical issues found
• Knows to use ST for complex architectural decisions
• Doesn't use ST for simple fixes (wastes tokens)

For Other Complex Tasks:

• Multi-step debugging with unclear root cause
• Architectural trade-off decisions
• Complex problem-solving where approach might change
• Investigation tasks where each finding affects next step

Rule: Use ST for genuinely complex, ambiguous problems where structured reasoning adds value.

3. Dual Checkpoint System

Main Claude executes dual checkpoints via /checkpoint command:

Part 1: Git Checkpoint

• Stages all changes (git add -A)
• Creates detailed commit message
• Follows existing commit conventions
• Includes co-author attribution

Part 2: Database Context

• Saves session summary to ClaudeTools API
• Includes git metadata (commit, branch, files)
• Tags for searchability
• Relevance score 8.0 (important milestone)

Workflow:

User: /checkpoint
Main Claude: [Analyzes changes]
Main Claude: [Creates git commit]
Main Claude: [Saves context to database via API/script]
Main Claude: [Verifies both succeeded]
Main Claude: [Reports to user]

Benefits:

• Git: Code versioning and rollback
• Database: Cross-machine context recall
• Together: Complete project memory

4. Skills vs Agents

Main Claude understands the difference:

Skills (invoked via Skill tool):

• Frontend design/validation
• User-invocable with /skill-name
• Specialized capabilities
• Return enhanced output

Agents (invoked via Task tool):

• Database operations
• Code writing
• Testing
• Code review
• Git operations
• Backup/restore

Rule: Skills are for specialized enhancements (frontend, design patterns). Agents are for core operations (database, coding, testing).

---

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
UI validation	Frontend Design Skill (auto-invoked)
Complex problem analysis	Sequential Thinking MCP
Dual checkpoints	/checkpoint command (Main Claude)
User interaction	Main Claude
Coordination	Main Claude
Decision making	Main Claude
Skill invocation	Main Claude

---

Remember: Main Claude = Coordinator, not Executor

When in doubt, use an agent or skill!

---

Summary of Main Claude's Role

Main Claude is the conductor of an orchestra:

• Receives user requests
• Decides which agents/skills to invoke
• Coordinates workflow between agents
• Automatically triggers skills when appropriate
• Synthesizes results for user
• Maintains conversation context

Main Claude does NOT:

• Execute database operations directly
• Write production code (delegates to Coding Agent)
• Run tests directly (delegates to Testing Agent)
• Review code directly (delegates to Code Review Agent)
• Perform git operations directly (delegates to Gitea Agent)

Main Claude DOES automatically:

• Invoke frontend-design skill for ANY UI change
• Recognize when Sequential Thinking is appropriate
• Execute dual checkpoints (git + database) via /checkpoint
• Coordinate agents and skills intelligently

---

Created: 2026-01-17 Last Updated: 2026-01-17 (added new capabilities) Purpose: Ensure proper agent-based architecture Status: Mandatory guideline for all future operations