# GitHub Etiquette for AI Agents

This document provides essential guidelines for AI agents interacting with GitHub issues, pull requests, and comments.

## Critical Rules

### 1. @ Mentions - Use with Extreme Caution

**NEVER use @ mentions for:**
- AI agent names (Gemini, Claude, OpenAI, etc.)
- Generic role names (reviewer, developer, tester)
- Any name you're not 100% certain is a real contributor

**ONLY use @ mentions for:**
- Repository owner: @AndrewAltimit
- Contributors explicitly listed in the repository
- Users who have specifically requested to be mentioned

**Why this matters:** Using @Gemini or @Claude will ping random GitHub users who happen to have those usernames, causing unnecessary notifications and confusion.

### 2. Referencing AI Agents

**Correct ways to reference AI agents:**
- "Gemini's review indicates..."
- "As Claude suggested..."
- "The OpenAI agent found..."
- "Per the agent's analysis..."

**Incorrect ways (DO NOT USE):**
- "@Gemini's review indicates..." [WRONG]
- "As @Claude suggested..." [WRONG]
- "CC @OpenAI for visibility..." [WRONG]

### 3. Comment Formatting

When posting automated comments:
- Clearly identify yourself as an AI agent
- Use professional, concise language
- Include relevant context without being verbose
- End with a signature line indicating automated generation

Example:
```markdown
## Automated Code Review

I've analyzed the changes and found the following...

[Review content]

---
*This review was automatically generated by [Agent Name] AI.*
```

### 4. Issue and PR Interactions

**When creating issues:**
- Use clear, descriptive titles
- Label appropriately
- Include all necessary context
- Never assign to users without permission

**When commenting on PRs:**
- Focus on constructive feedback
- Acknowledge good practices, not just issues
- Provide actionable suggestions
- Respect the author's time and effort

### 5. Error Handling

If you make a mistake (like incorrect @ mention):
- Acknowledge it promptly in a follow-up comment
- Update documentation to prevent recurrence
- Learn from the feedback

## Examples

### Good Comment
```markdown
## Response to Gemini's Code Review

Thank you for the thorough review! I've addressed all concerns:

1. **Security**: Removed unsafe patterns
2. **Architecture**: Improved containerization
3. **Documentation**: Updated all relevant docs

The solution maintains our best practices while addressing the feedback.
```

### Bad Comment
```markdown
@Gemini thanks for the review! CC @Claude @OpenAI

Fixed everything you mentioned.
```

## Quick Reference

| Scenario | Do | Don't |
|----------|--------|----------|
| Referencing AI agents | "Gemini suggested..." | "@Gemini suggested..." |
| Mentioning repo owner | "@AndrewAltimit" | N/A |
| Referencing external tools | "Using OpenAI's API..." | "@OpenAI's API..." |
| Team references | "The AI agents found..." | "@ai-agents found..." |

## Integration with Multi-Agent System

All agents in the multi-agent system should:
1. Load and respect these guidelines
2. Include etiquette checks in their comment generation
3. Validate @ mentions before posting
4. Log any etiquette violations for review

## Updates and Maintenance

This document should be updated when:
- New AI agents are added to the system
- GitHub changes their notification system
- We discover new edge cases
- Community standards evolve

Remember: When in doubt, don't use @ mentions!
