Universal Agent Law
Relevant source files
The following files were used as context for generating this wiki page:
The Universal Agent Law is a portable, agent-agnostic core of engineering conduct governing all development activity within the flext-target-oracle-oic repository. It establishes a set of inviolable rules that bind AI agents—including Claude, Codex, Gemini, Cursor, and others—as well as human users. The law ensures consistent engineering standards, prevents code degradation, and facilitates multi-agent collaboration by enforcing strict-total discipline and root-cause resolution.
Sources: AGENTS.md:4-10, README.md:21-22
Core Engineering Directives
The law is built on a "Zero-Tolerance" and "Strict-Total" philosophy. It mandates that any failure surfaced during a task must be owned and resolved by the acting agent, regardless of whether the issue is perceived as "pre-existing" or "unrelated."
Strict Engineering Standards
- Root Cause Resolution: Agents must always fix the root cause of an issue generically and cleanly. Workarounds, stubs, fakes, or "temporary" fixes are strictly forbidden.
- Dead Code Elimination: Superseded code must be removed in the same cycle as the replacement. No dead code is permitted "for later."
- No Suppressions: Use of suppression directives like
# type: ignore,eslint-disable, or escape-hatch typing such asAnyis prohibited unless accompanied by a one-line justification. - Loud Failure: The system must fail loudly when the single source of truth (identity, config, contract, version) is absent. Substituting guesses or local alternatives is not allowed.
Sources: AGENTS.md:14-26, AGENTS.md:36-41
Fix-Forward and Scope Integrity
The environment supports multi-agent concurrency. To prevent the destruction of in-flight work by other agents, a "Fix-Forward-Only" policy is enforced. Directives like git reset --hard, git restore, or git clean are forbidden for shared work. Additionally, agents must stay strictly within the user-provided scope, avoiding unrequested refactors or "obvious improvements."
Sources: AGENTS.md:28-34, AGENTS.md:43-46
Operational Protocols
The following flow represents how an agent must process a task under the Universal Agent Law, focusing on validation and honest reporting.
This diagram illustrates the mandatory stopping points when a clean solution is not immediately achievable or when validation fails.
Sources: AGENTS.md:48-60, AGENTS.md:79-82
Blocked-Operation Protocol
When a tool, command, or edit is blocked by security hooks or sandbox restrictions, agents must not attempt bypasses such as bash -c wrapping, eval, or absolute-path swaps. Instead, the agent must diagnose the block in one sentence, hand the exact command to the user, and wait for the output.
Sources: AGENTS.md:62-72
Multi-Agent Coordination
Multi-agent coordination is managed through a committed task board and strict Git conduct. This ensures that multiple agents can work on the same tree without collision.
Coordination Mechanism
| Component | Description |
|---|---|
| Task Board | Located at <repo>/.agents/coordination/tasks.md. Used for claiming tasks with ownership and lease entries. |
| Lease Heartbeat | Active agents must heartbeat their lease to maintain ownership of a task. |
| Git Commits | Commits must be small, frequent, and written as the user without bot attribution (no Co-Authored-By). |
| Pathspecs | Explicit pathspecs must be used during git add and git commit to ensure only scoped work is landed. |
Sources: AGENTS.md:84-90, AGENTS.md:79-82
Governance and Quality Gates
The project enforces specific module governance rules to maintain the integrity of the architecture. For instance, package modules are forbidden from defining module-level loggers or unapproved top-level functions.
The diagram shows the relationship between active test governance and the foundational law.
Sources: tests/unit/test_module_governance.py:46-81, AGENTS.md:4-12
Universal Engineering Principles
The law incorporates four foundational principles that must be respected at all times:
- SSOT (Single Source of Truth): One authoritative source per fact.
- SOLID: Full adherence to object-oriented design principles.
- YAGNI (You Ain't Gonna Need It): No speculative parameters or dead branches.
- DI / DIP (Dependency Injection/Inversion): Depend on abstractions; no hidden globals.
Sources: AGENTS.md:74-77
Conclusion
The Universal Agent Law serves as the constitutional framework for the flext-target-oracle-oic project. By mandating root-cause fixes, fix-forward operations, and objective evidence, it ensures that both human and AI contributors maintain a high-integrity, zero-debt codebase. Any deviation from these rules requires explicit user escalation, preserving the project's long-term maintainability and technical excellence.
Sources: AGENTS.md:12-13, README.md:21-23