Universal Agent Laws
Relevant source files
The following files were used as context for generating this wiki page:
The Universal Agent Laws constitute an inviolable core of engineering conduct governing all AI agents and users interacting with the flext-dbt-ldif repository. These laws establish a strict-total framework designed to ensure architectural integrity, maintain a single source of truth (SSOT), and prevent the accumulation of technical debt during automated or human-led development sessions.
The laws bind various AI agents—including Claude, Codex, Gemini, and GitHub Copilot—requiring them to adhere to specific protocols for error handling, code modification, and multi-agent coordination. They prioritize root-cause fixes and strict typing over temporary workarounds or compatibility wrappers.
Sources: AGENTS.md:4-12, README.md:16-18
Core Engineering Conduct
The framework operates on a "Zero-Tolerance" basis, requiring that all agents fix root causes generically using canonical code. This ensures that the system remains maintainable across its different layers, from the FlextDbtLdifCore logic to service-level transformations.
Mandatory Protocols
- Root Cause Resolution: Agents must always address the underlying issue and validate the fix with actual commands and exit codes.
- Dead Code Elimination: Superseded code must be removed in the same cycle as the replacement.
- Failure Protocol: The system must "fail loud" if identity, config, or contract information is missing.
- Scope Compliance: Agents must perform only the requested task, avoiding unrequested refactors or adjacent fixes.
Sources: AGENTS.md:15-39, tests/unit/test_core.py:17-45
Fix-Forward and Modification Rules
To prevent the destruction of in-flight work in multi-agent environments, the laws forbid reverting shared work through commands like git reset or git stash. Instead, all participants must "fix forward," accepting the current state of the repository as the baseline for the next set of changes.
The diagram shows the required linear progression of repository changes and the specific Git operations that are prohibited to maintain environment stability.
Sources: AGENTS.md:30-38
Technical Quality Gates
The laws mandate strict engineering principles to be applied during the development of dbt models for LDIF transformations. This includes adherence to SOLID principles and the maintenance of a Single Source of Truth (SSOT).
Engineering Standards
| Principle | Requirement |
|---|---|
| SSOT | One authoritative source per fact; reference only, never duplicate. |
| SOLID | Respect SRP, OCP, LSP, ISP, and DIP; avoid god-objects. |
| YAGNI | Build only what is needed now; no speculative parameters or dead branches. |
| Strict Typing | Use the most restrictive types; no Any or bare object without justification. |
Sources: AGENTS.md:73-86, pyproject.toml:104-126
Evidence and Validation
"Done" is defined strictly by the validation of the complete chain with objective evidence. This process is exemplified in the project's test suite, which ensures that services like FlextDbtLdifServiceMixin handle workflows from parsing to dbt transformation correctly.
The sequence diagram illustrates the mandatory validation flow before any work is considered "Done" and committed.
Sources: AGENTS.md:41-47, tests/unit/test_services.py:126-170
Blocked-Operation and Security Protocol
When an operation is blocked by security hooks or sandbox restrictions, agents are strictly forbidden from seeking bypasses (e.g., using eval, exec, or sudo). The protocol requires immediate stoppage, a one-sentence diagnosis, and handing the command to the user for manual execution.
Forbidden Bypass Techniques
- Subshell wrapping (
bash -c,sh -c) - Environment manipulation (
env <blocked>) - Command chaining or pipes into blocked commands
- Absolute-path swaps to dodge prefix rules
Sources: AGENTS.md:54-68, AGENTS.md:104-109
Multi-Agent Coordination
Coordination is managed through a committed task board located at <repo>/.agents/coordination/tasks.md. Agents must claim tasks with a lease and heartbeat to prevent concurrent conflicting edits. All landings must be fast-forward pushes using explicit pathspecs.
Sources: AGENTS.md:88-102
The Universal Agent Laws serve as the governing constitution for the flext-dbt-ldif project, ensuring that every modification—whether automated or manual—adheres to high standards of technical accuracy, honesty, and architectural cleanliness. By enforcing root-cause fixes and forbidding temporary workarounds, these laws maintain the project's integrity across its LDAP transformation and dbt modeling components.
Sources: AGENTS.md:1-115, README.md:27-31