Multi-Agent Coordination Protocol
Relevant source files
The following files were used as context for generating this wiki page:
The Multi-Agent Coordination Protocol is an autonomous development framework designed for the Sweepbot project. It organizes development into four specialized domains to ensure parallel progress with zero file conflicts. By defining exclusive territories and strict communication rules, the system allows independent agents to work simultaneously on complex features across the monorepo stack.
Sources: README_AGENTS.md:5-15, AGENT_COORDINATION.md:1-5
Agent Roles and Domain Territories
The system divides the Sweepbot codebase into four distinct domains, each owned by a specific agent. Ownership is absolute, meaning only the assigned agent has write access to their files, while others maintain read-only access.
Domain Assignments
| Agent | Domain Focus | Primary Responsibilities | Key File Paths |
|---|---|---|---|
| Agent 1 | Backend & Database | APIs, microservices, database schemas, and server-side security. | apps/api/**, services/** |
| Agent 2 | Frontend & UI | User interface, React components, styling, and web animations. | apps/web/** |
| Agent 3 | Extension & Shared | Browser extension, shared types, and cross-app utilities. | apps/extension/**, packages/types/**, packages/utils/** |
| Agent 4 | DevOps & Docs | CI/CD, testing infrastructure, and documentation. | .github/**, docs/**, packages/flows/** |
Sources: AGENT_COORDINATION.md:8-15, AGENT_QUICK_START.md:5-15, README_AGENTS.md:20-55
Domain Ownership Visualized
The following diagram illustrates the structural separation of the Sweepbot monorepo among the four agents.
Coordination and Communication Rules
To maintain system integrity, agents follow strict coordination rules when features span across multiple domains.
Core Protocol Rules
- File Ownership is Absolute: Only the owner agent writes to their assigned directory.
- Shared Packages First: Changes to
packages/types/orpackages/utils/must be coordinated as they affect all agents. - No Code Imports Across Boundaries: Frontend code cannot directly import backend code and vice-versa. Agents must use shared types from Agent 3.
- Type Contracts are Sacred: Type definitions are the formal contracts between agents; breaking changes require prior notification.
- Test Gate: Agent 4 manages the CI/CD pipeline. No code is merged unless all tests pass.
Sources: AGENT_COORDINATION.md:148-175, AGENT_QUICK_START.md:110-125, README_AGENTS.md:140-160
Multi-Agent Feature Workflow
The typical lifecycle of a feature involves sequential and parallel phases among agents.
Dependency Matrix
Each agent acts as both a provider and a receiver within the system ecosystem.
| Agent | Provides | Receives |
|---|---|---|
| Agent 1 | API endpoints, business logic, DB schemas | Type definitions (from Agent 3) |
| Agent 2 | UI implementation, user flows | API types, endpoints (from 1 & 3) |
| Agent 3 | Types, utilities, API client abstractions | API specifications (from Agent 1) |
| Agent 4 | Testing, CI/CD, documentation | Source code and features to verify |
Sources: AGENT_COORDINATION.md:180-193, AGENT_QUICK_START.md:130-145
Conflict Prevention and Safety Guardrails
The protocol includes a specific "Never Touches" list for each agent to prevent accidental overlaps. For instance, Agent 1 never touches frontend code, and Agent 4 never modifies application source code directly, only tests and configurations.
Escalation Protocol
If a conflict arises during development, the involved agents must:
- Identify the conflicting files.
- Review the domain assignment rules.
- Request Agent 4 to mediate if the domain boundary is unclear.
- Document the resolution to prevent recurrence.
Sources: AGENT_COORDINATION.md:265-275, AGENT_4_DEVOPS_DOCS.md:15-25
Conclusion
The Multi-Agent Coordination Protocol ensures Sweepbot development is scalable and conflict-free. By treating type definitions as sacred contracts and enforcing domain isolation, the project maintains high code quality and clear accountability. Agent 4 serves as the final quality gate, ensuring that despite independent development, the integrated system remains robust and well-documented.
Sources: AGENT_COORDINATION.md:280-285, README_AGENTS.md:235-245