Engineering Law (AGENTS.md)
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
The Engineering Law, primarily codified in AGENTS.md, establishes the "Universal Agent Law"—a set of inviolable rules governing code conduct, architectural integrity, and developer/AI interactions within the flext-grpc repository. Its purpose is to maintain a zero-debt baseline, ensuring that all agents (AI or human) follow a strict, predictable protocol for modifications, error handling, and coordination.
This governance model acts as the project's constitutional framework, dictating how technical debt is avoided, how failures are surfaced, and how multi-agent coordination is managed in a shared working tree. It is tightly integrated with the project's Clean Architecture and Quality Gates.
Sources: AGENTS.md:5-15, README.md:32-37
Core Mandates of Universal Agent Law
Zero-Tolerance and Root Cause Analysis
The project enforces a "Strict-Total" policy regarding code quality and bug fixing. Agents are prohibited from using workarounds, temporary stubs, or compatibility wrappers. Every fix must address the root cause generically and be validated within the same execution cycle.
Sources: AGENTS.md:18-28, src/README.md:120-125
Fix-Forward-Only Protocol
In environments where multiple agents share a working tree, reverting to previous states is strictly forbidden to prevent the destruction of concurrent work. If a conflict arises, agents must "fix forward" by incorporating the current state and building upon it. Unilateral reverts using git reset or git stash are classified as violations.
Sources: AGENTS.md:30-36
Engineering Governance Workflow
The following diagram illustrates the decision flow when an agent encounters a problem or completes a task under the Engineering Law:
The diagram shows the mandatory requirement for objective evidence (command + exit code + output) before a task is considered "Done".
Sources: AGENTS.md:56-72, AGENTS.md:89-95
Technical Implementation Standards
Strict Typing and Architecture Compliance
The project mandates "Most-Restrictive Typing." The use of Any, object, or type suppression (e.g., # type: ignore) is forbidden unless accompanied by documented justification. This supports the Clean Architecture requirement where dependency direction must always flow from Infrastructure to Application to Domain.
Sources: AGENTS.md:97-101, src/README.md:46-52
Universal Engineering Principles
All code must adhere to four foundational principles:
- SSOT (Single Source of Truth): One authoritative source per fact; fail loud if absent.
- SOLID: Respect for SRP, OCP, LSP, ISP, and DIP.
- YAGNI: No speculative parameters or dead branches.
- DI/DIP: Depend on abstractions and inject collaborators.
Sources: AGENTS.md:103-112
Coordination and Task Management
Multi-agent coordination is managed via a committed task board (.agents/coordination/tasks.md). Agents must lease tasks and commit small, frequent changes to allow others to rebuild state from the git log.
Sources: AGENTS.md:122-128
Protocol Summary Table
| Protocol | Requirement | Violation Examples |
|---|---|---|
| Success Validation | Evidence = Command + Exit Code + Output | "Conclusion-by-sample", assuming results. |
| Typing | Most restrictive types that compile | Using Any, unchecked casts, # noqa. |
| Git Operations | Fast-forward push only; No reverts | git reset --hard, git clean, git stash. |
| Bypass Prevention | Stop if tool is blocked | Wrapping in bash -c, using eval or exec. |
| Data Retention | Archive don't destroy (.bak files) | Deleting files, sudo without confirmation. |
Sources: AGENTS.md:74-87, AGENTS.md:114-120, AGENTS.md:130-137
Quality Standards and Validation
The Engineering Law is enforced through canonical make verbs that act as quality gates. Every change must pass the full validation pipeline before landing.
Conclusion
Engineering Law (AGENTS.md) represents a rigid framework for maintainability in the flext-grpc project. By mandating root-cause resolution, strictly typed interfaces, and objective validation, it prevents the accumulation of technical debt and ensures that both human and AI agents operate within a consistent, high-integrity development environment. Consistency is maintained through the leasing of tasks and a strict "fix-forward" approach to shared working trees.
Sources: AGENTS.md:143-150, src/flext_grpc/README.md:180-185