Multi-Agent Coordination
Relevant source files
The following files were used as context for generating this wiki page:
Multi-agent coordination in this project refers to the collaborative framework and governance laws that allow multiple AI agents (such as Claude, Codex, or GitHub Copilot) to operate within a single working tree without conflict. This system ensures that every agent follows a "Universal Agent Law" to maintain code integrity, strictly adhere to technical standards, and communicate progress via shared state indicators like git logs and task boards.
The coordination strategy is built upon a "Zero-Tolerance" and "Fix-Forward-Only" philosophy. Agents are required to fix root causes rather than implementing workarounds, and they must validate all changes through objective evidence (exit codes and command outputs) before claiming a task is complete.
Sources: AGENTS.md:10-15, AGENTS.md:99-105
The Universal Agent Law
The Universal Agent Law is an inviolable core of engineering conduct that binds any AI agent or user interacting with the repository. It defines strict rules for code modifications, failure handling, and operational scope.
Core Principles
- Zero-Tolerance / Strict-Total: Agents must fix root causes generically and remove superseded code immediately. Failures in the single source of truth (SSOT) must result in a "fail loud" response rather than a guess.
- Fix-Forward-Only: Agents are strictly forbidden from reverting the working tree to a past state (e.g., via
git reset --hardorgit restore) to avoid destroying the work of other agents. - Root Cause Resolution: Bypasses like
# type: ignoreorAnytypes are forbidden unless accompanied by documented justification.
Sources: AGENTS.md:18-40
Operational Governance Table
| Principle | Requirement | Forbidden Actions |
|---|---|---|
| Integrity | Fix root cause generically | Stubs, fakes, TODO/FIXME |
| Persistence | Accept current state and fix forward | git checkout, git restore, git stash |
| Validation | Command + Exit Code + Output | Conclusion-by-sample, assumed results |
| Typing | Most restrictive type that compiles | Any, bare object, unchecked casts |
Sources: AGENTS.md:21-72
Coordination Mechanisms
Agents share a single working tree and coordinate their efforts through specific structured communication channels and git-based workflows.
Task Board and Leases
Coordination is primarily achieved through a committed task board, typically located at <repo>/.agents/coordination/tasks.md. Agents must:
- Claim: Create an ownership and lease entry before editing.
- Heartbeat: Maintain the lease to show active work.
- Finish: Update the status to
doneorblocked. - Recover: Check git history to identify and recover stale tasks.
Sources: AGENTS.md:99-105
Git-Based State Management
To ensure visibility, agents are required to commit small changes frequently. This allows subsequent agents to rebuild the context of the working tree from the git log. All commits must be made as the user without bot/agent attribution trailers like Co-Authored-By.
Sources: AGENTS.md:92-97, AGENTS.md:104-105
Conflict Resolution Flow
This diagram illustrates how agents handle task execution and potential conflicts in a shared environment.
The diagram shows the lifecycle of an agent's interaction with the shared workspace, prioritizing the task board and git history to avoid overlapping work.
Sources: AGENTS.md:99-108
Engineering Standards for Agents
Agents must adhere to standard architectural principles to ensure that coordination results in a maintainable codebase.
- SSOT (Single Source of Truth): One authoritative source per fact.
- SOLID Principles: Emphasis on SRP (Single Responsibility) and DIP (Dependency Inversion). God-objects are classified as defects.
- YAGNI (You Aint Gonna Need It): No speculative parameters or dead branches.
- Module Governance: Package modules are monitored to ensure they do not define module-level loggers or unapproved top-level functions, ensuring a predictable structure for automated agents.
Sources: AGENTS.md:79-90, tests/unit/test_module_governance.py:65-98
Dependency and MRO Management
Agents must understand the Method Resolution Order (MRO) when extending classes. For instance, FlextTargetOracleOic inherits from FlextMeltanoTargetAbstractions, and model namespaces like FlextTargetOracleOicModels use composition inheritance to combine generic test models with domain-specific OIC models.
The class hierarchy ensures that coordination follows established inheritance patterns, reducing logic duplication across agent sessions.
Sources: src/flext_target_oracle_oic/target.py:15-80, tests/models.py:17-30
Conclusion
Multi-agent coordination in this repository is enforced through the Universal Agent Law, which mandates strict root-cause resolution, forward-only git operations, and rigorous validation. By using a centralized task board and leveraging git history as the primary state synchronization mechanism, multiple agents can safely collaborate on the Oracle OIC integration target while maintaining architectural purity and high-quality typing standards.