azcomputerguru
565b6458ba
Replaced 50+ emoji types with ASCII text markers for consistent rendering across all terminals, editors, and operating systems: - Checkmarks/status: [OK], [DONE], [SUCCESS], [PASS] - Errors/warnings: [ERROR], [FAIL], [WARNING], [CRITICAL] - Actions: [DO], [DO NOT], [REQUIRED], [OPTIONAL] - Navigation: [NEXT], [PREVIOUS], [TIP], [NOTE] - Progress: [IN PROGRESS], [PENDING], [BLOCKED] Additional changes: - Made paths cross-platform (~/ClaudeTools for Mac/Linux) - Fixed database host references to 172.16.3.30 - Updated START_HERE.md and CONTEXT_RECOVERY_PROMPT.md for multi-OS use Files updated: 58 markdown files across: - .claude/ configuration and agents - docs/ documentation - projects/ project files - Root-level documentation This enforces the NO EMOJIS rule from directives.md and ensures documentation renders correctly on all systems. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
401 lines
10 KiB
Markdown
401 lines
10 KiB
Markdown
# 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)
|
|
|
|
```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 ...
|
|
```
|
|
|
|
### [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
|
|
```bash
|
|
ssh guru@172.16.3.30 "mysql ... SELECT COUNT(*) FROM conversation_contexts"
|
|
```
|
|
**Should have been:** Database Agent task
|
|
|
|
### [ERROR] Violation 2: Direct API Calls
|
|
```bash
|
|
curl -X POST http://172.16.3.30:8001/api/conversation-contexts ...
|
|
```
|
|
**Should have been:** Database Agent task
|
|
|
|
### [ERROR] 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. [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
|