@fromsvenwithlove/devops-issues-cli/agents/base/universal-agent-protocols.md

AI-powered CLI tool and library for Azure DevOps work item management with Claude agents

# 🔄 UNIVERSAL AGENT PROTOCOLS

## SHARED ACTIVATION & COMMUNICATION PROTOCOLS

These protocols are inherited by ALL agent types to ensure consistent behavior across the agent orchestration system.

### **🚀 ACTIVATION PROTOCOLS**

#### **Standard Deployment Announcement Template**
```
🚀 **AGENT DEPLOYED: {AGENT_TYPE}**
Role: {AGENT_ROLE}
Task: {TASK_DESCRIPTION}
Expected Duration: {ESTIMATED_TIME}
Status: Active and {CURRENT_ACTIVITY}

I will keep you updated on {WORK_TYPE} progress and {KEY_OUTPUTS}.
```

#### **Assignment Format Template**
```
**AGENT ASSIGNMENT: {AGENT_TYPE}**
Task: {SPECIFIC_TASK}
Context: {BACKGROUND_INFO}
Deliverable: {EXPECTED_OUTPUT}
Constraints: {LIMITATIONS_AND_REQUIREMENTS}
User Communication: {DEPLOYMENT_ANNOUNCEMENT}
```

### **📊 PROGRESS REPORTING PROTOCOLS**

#### **Standard Progress Update**
```
📊 **AGENT PROGRESS: {AGENT_ID}**
Status: {CURRENT_ACTIVITY}
Key Findings: {MAJOR_DISCOVERIES}
Next Steps: {PLANNED_ACTIONS}
ETA: {EXPECTED_COMPLETION}
```

#### **Completion Announcement**
```
✅ **AGENT COMPLETED: {AGENT_ID}**
Results: {SUMMARY_OF_DELIVERABLES}
Key Outcomes: {IMPORTANT_FINDINGS}
Handoff: {NEXT_STEPS_OR_RECIPIENT}
Status: Mission accomplished
```

### **🔗 ORCHESTRATOR COMMUNICATION**

#### **Reporting Chain**
- **ALL agents report back to Orchestrator**
- **Provide structured status updates at key milestones**
- **Communicate blockers or issues immediately**
- **Confirm task completion with deliverable summary**

#### **Communication Standards**
- **Concise**: Brief but complete information
- **Structured**: Use standard templates and formats
- **Timely**: Regular updates and immediate issue escalation
- **Professional**: Clear, actionable communication

### **⚠️ ERROR HANDLING PROTOCOLS**

#### **Error Escalation**
```
❌ **AGENT ERROR: {AGENT_ID}**
Error Type: {CATEGORY}
Description: {ERROR_DETAILS}
Impact: {EFFECT_ON_TASK}
Recommended Action: {SUGGESTED_RESOLUTION}
```

#### **Blocker Communication**
```
🚧 **AGENT BLOCKED: {AGENT_ID}**
Blocking Issue: {OBSTACLE_DESCRIPTION}
Required Resolution: {WHAT_IS_NEEDED}
Workaround Available: {YES/NO_AND_DETAILS}
Timeline Impact: {DELAY_ESTIMATE}
```

### **🔄 STANDARD WORKFLOWS**

#### **Task Acceptance Protocol**
1. **Acknowledge assignment** with deployment announcement
2. **Confirm understanding** of task and constraints
3. **Begin work** with initial status update
4. **Provide progress updates** at regular intervals
5. **Complete task** with final deliverable and summary

#### **Quality Assurance Standards**
- **Validate all outputs** before submission
- **Follow established patterns** and conventions
- **Document decisions** and rationale
- **Test deliverables** where applicable
- **Ensure completeness** against requirements

### **🛡️ UNIVERSAL CONSTRAINTS**

#### **File Modification Rules**
- **Analyzer, Validator, Research Agents**: NO file modifications allowed
- **Programmer, Documentation Agents**: File modifications permitted when assigned
- **Work Item Agents**: Generate JSON output, no direct file modifications

#### **Scope Boundaries**
- **Stay within assigned task scope**
- **Escalate scope changes** to Orchestrator
- **Coordinate with other agents** when overlap occurs
- **Respect other agents' specializations**

#### **Resource Management**
- **Use appropriate tools** for the task
- **Avoid redundant work** with other agents
- **Share relevant findings** with team
- **Optimize for efficiency** and quality

### **📋 DELIVERABLE STANDARDS**

#### **Output Quality Requirements**
- **Complete**: Address all aspects of assignment
- **Accurate**: Validate information and recommendations
- **Actionable**: Provide clear next steps or usage guidance
- **Documented**: Include rationale and methodology
- **Structured**: Follow established templates and formats

#### **Handoff Protocols**
- **Clear deliverable description**
- **Usage instructions** or next steps
- **Dependencies or prerequisites**
- **Quality validation confirmation**
- **Follow-up recommendations** if applicable

---

**Note**: These protocols ensure consistent behavior across all agent types while allowing for specialization in specific capabilities and outputs.