Agent Law & Execution Contracts
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The "Agent Law & Execution Contracts" system within the flext-api project defines an inviolable framework for AI agent conduct and technical execution. This framework, primarily governed by the Universal Agent Law, serves as the core engineering conduct bond for any AI agent interacting with the repository. It ensures consistency, reliability, and technical integrity across multi-agent environments by enforcing strict protocols for root-cause analysis, state management, and scope adherence.
At its core, the system establishes a "Zero-Tolerance/Strict-Total" policy where agents are mandated to fix root causes rather than symptoms and are forbidden from using workarounds, stubs, or legacy bypasses. This is complemented by "Execution Contracts" that define how tasks are planned, validated with objective evidence, and coordinated through shared state structures like task boards and git history.
Sources: AGENTS.md:1-12, README.md:15-18
Universal Agent Law (Portable Core)
The Universal Agent Law is the engineering constitution of the repository. It binds all AI agents (e.g., Claude, Codex, Gemini, Cursor) and users to a strict set of rules that cannot be relaxed for convenience.
Fundamental Pillars
- Zero-Tolerance Policy: Agents must resolve root causes using canonical code and remove superseded code immediately. No dead code or "TODOs" are permitted.
- Fix-Forward-Only: In shared working trees, reverting history is forbidden to avoid destroying other agents' in-flight work.
- Strict Typing: Use of
Anyor bareobjectis considered a defect unless justified. Restrictive typing is enforced at the source. - Evidence-Based Validation: A task is only "Done" when the complete chain is validated with objective command output and exit codes.
Sources: AGENTS.md:15-46, AGENTS.md:79-81
Agent Decision Logic
The following diagram illustrates the decision flow an agent must follow when encountering issues or deviations from the execution plan.
This flowchart represents the "Execute As Planned, Else Stop And Ask" and "Evidence Before Done" protocols.
Sources: AGENTS.md:54-68, AGENTS.md:83-85
Execution Contracts & Coordination
When multiple agents operate on the same codebase, coordination is managed through durable contracts and shared state files.
Multi-Agent Coordination Protocol
Agents must coordinate through a committed task board, typically located at <repo>/.agents/coordination/tasks.md. The protocol requires:
- Ownership Lease: Claiming a task before editing.
- Heartbeat: Maintaining the lease during execution.
- State Recovery: Rebuilding state from
git logif an agent is fresh. - No Destruction: Preferring moves to
.bakfiles rather than deletion.
Sources: AGENTS.md:92-101, AGENTS.md:108-112
Coordination State Flow
The sequence diagram below shows how an agent interacts with the coordination board and the repository.
Sources: AGENTS.md:83-85, AGENTS.md:92-101
Technical Execution Principles
The project mandates specific software architecture patterns to be followed by agents during code generation or refactoring.
| Principle | Requirement | Source |
|---|---|---|
| SSOT | Single Source of Truth; fail loud if absent. | AGENTS.md:83 |
| SOLID | Respect SRP, OCP, LSP, ISP, and DIP. | AGENTS.md:84 |
| YAGNI | No speculative parameters or future-hooks. | AGENTS.md:86 |
| DI / DIP | Depend on abstractions; inject collaborators. | AGENTS.md:87 |
| Restrictive Typing | Use Python 3.13+ StrEnum and strict Literal types. | history.json:constants.py:15-25 |
Data Normalization & Validation Contract
Execution requires strict adherence to public facades for request construction and model validation, as demonstrated in the basic usage patterns.
# Example of following the Execution Contract for request building
# Sources: [examples/01_basic_usage.py:24-40]
payload_result = u.Api.RequestUtils.build_request_payload(
method=c.Api.Method.GET,
url=f"{self.settings.base_url.rstrip('/')}/resources",
headers={"accept": c.Api.ContentType.JSON.value},
request_kwargs={"params": {"page": 1, "active": True}},
timeout=timeout_result.value,
)
Blocked-Operation Protocol
If a tool or command is restricted (e.g., sandbox limits, missing permissions), agents must follow the Blocked-Operation Protocol:
- Immediate Stop: Do not attempt variations or subshell wrapping (e.g.,
bash -c). - Diagnosis: Provide a one-sentence explanation of the blockage.
- Handover: Give the exact command to the user to run manually.
- Sync: Wait for user output before proceeding.
Sources: AGENTS.md:70-77
Summary
The Agent Law & Execution Contracts provide a robust governance layer for the flext-api project. By defining strict engineering conduct, prohibiting workarounds, and mandating evidence-based validation, the system ensures that AI-driven development maintains the high-performance and high-integrity standards required by the FastAPI platform. All agents must prioritize the Universal Agent Law over convenience to ensure the long-term health of the codebase.
Sources: AGENTS.md:10-14, README.md:15-20