minions-ai-agents/docs/AI_AGENT_PROTOCOL.md

# 🤖 AI Agent Protocol

**READ THIS BEFORE WORKING ON THE CODEBASE**

This document defines the mandatory protocols for AI agents working on the Antigravity Brain project.

---

## 🎯 Prime Directives

1. **READ KNOWLEDGE FIRST** - Before writing ANY code, read relevant `src/knowledge/standards/*.md`
2. **NEVER HARDCODE SECRETS** - Use `Config` class and environment variables
3. **TOOLS MUST NOT RAISE** - Always return error strings, never raise exceptions
4. **TEST BEFORE COMMIT** - Verify changes with `docker-compose restart app`

---

## 📖 Required Reading by Task Type

| Task | Must Read First |
|------|-----------------|
| Python tools | `python_tool_standards.md` |
| Docker changes | `docker_standards.md` |
| New agents | `DEVELOPER_GUIDE.md#adding-new-agents` |
| Database | `database_standards.md` |
| Security | `security_standards.md` |
| Git operations | `git_standards.md` |
| UI changes | `ui_ux_standards.md` |

---

## ✅ Code Change Checklist

Before making any change:

- [ ] Read relevant standards file
- [ ] Check if pattern already exists in codebase
- [ ] Plan change with minimal impact
- [ ] Add error handling
- [ ] Test locally

After making change:

- [ ] Restart container: `docker-compose restart app`
- [ ] Check logs for errors: `docker logs antigravity_brain --tail 50`
- [ ] Verify functionality works
- [ ] Commit with proper message format

---

## 📝 Commit Message Format

```
<type>: <short description>

<optional body>
```

Types:
- `feat:` New feature
- `fix:` Bug fix
- `docs:` Documentation
- `refactor:` Code cleanup
- `test:` Tests
- `chore:` Maintenance

Example:
```
feat: Add new DevOps agent persona

- Created persona-devops-dan.md
- Added to Infrastructure crew
- Assigned Docker tools
```

---

## 🔧 Tool Development Protocol

```python
class MyTool(BaseTool):
    name: str = "Descriptive Name"  # Agent reads this
    description: str = (
        "DETAILED description of when to use this tool. "
        "Include example inputs and expected outputs."
    )
    args_schema: type = MyToolInput  # Pydantic model with Field descriptions

    def _run(self, **kwargs) -> str:
        try:
            # Your logic
            return "Success: ..."
        except SpecificError as e:
            return f"Error: Specific handling for {e}"
        except Exception as e:
            return f"Error: Unexpected - {str(e)[:100]}"
```

**NEVER:**
- Use `input()` for user interaction
- Raise exceptions
- Return raw JSON (use narrative text)
- Use `Any` type hints

---

## 🤖 Agent Development Protocol

### Persona Files

1. Use YAML frontmatter for metadata
2. Include `**Role:**` and `**Goal:**` fields
3. Write backstory in character voice
4. Define clear protocols/procedures

### Tool Assignment

- Only assign tools the agent actually needs
- Consider `model_tier`: tools requiring reasoning → `smart`
- Memory tools are auto-assigned to all agents

---

## 📁 File Placement Rules

| Content Type | Location |
|--------------|----------|
| Agent personas | `src/agents/personas/persona-*.md` |
| Tools | `src/tools/*.py` |
| Knowledge standards | `src/knowledge/standards/*.md` |
| Dynamic knowledge | `src/knowledge/dynamic/*/*.md` |
| Crew definitions | `src/crews/definitions.py` |
| Configuration | `src/config.py` |

---

## ⚠️ Common Mistakes to Avoid

### 1. Variable Names in Standards

❌ BAD:
```python
return f"Error: File '{path}' not found"  # {path} interpreted as template
```

✅ GOOD:
```python
return f"Error: File 'PATH_VAR' not found"  # Escaped
```

### 2. Missing Rate Limiting

❌ BAD:
```python
while True:
    api.call()  # Burns quota instantly
```

✅ GOOD:
```python
for attempt in range(MAX_RETRIES):
    result = api.call()
    if success: break
    time.sleep(DELAY * (2 ** attempt))
```

### 3. Hardcoded Configuration

❌ BAD:
```python
model = "gpt-4"
api_key = "sk-xxx"
```

✅ GOOD:
```python
config = Config.get_llm_config(mode="smart")
```

---

## 🧪 Testing Protocol

1. **Local test:**
   ```bash
   docker-compose restart app
   docker logs antigravity_brain --tail 50
   ```

2. **Verify no errors:**
   ```bash
   docker logs antigravity_brain 2>&1 | findstr "Error ERROR Exception"
   ```

3. **Interactive test:**
   - Open http://localhost:8000
   - Send test message
   - Verify correct crew routing
   - Check agent response

---

## 🚀 Deployment Protocol

1. **Commit changes:**
   ```bash
   git add .
   git commit -m "feat: Description"
   git push
   ```

2. **On production server:**
   ```bash
   git pull
   docker-compose build --no-cache app
   docker-compose up -d
   ```

---

**Remember:** Quality over speed. Read the standards. Test your changes.