Engineering Agent Laws
Relevant source files
The following files were used as context for generating this wiki page:
The Engineering Agent Laws constitute the Universal Agent Law, an inviolable and agent-agnostic core of conduct for all AI agents (including Claude, Codex, Cursor, and others) and users operating within the FLEXT Meltano repository. These laws establish a strict framework for engineering behavior, ensuring that every session maintains a zero-debt baseline and adheres to enterprise-grade standards regardless of project type or configuration access.
The scope of these laws covers root-cause analysis, state management, technical debt prevention, and rigorous validation. They serve as the foundational governance for the project's Quality Gates and Integration Architecture, binding all contributors to a "Fix-Forward-Only" and "Zero-Tolerance" technical philosophy.
Sources: AGENTS.md:3-13, README.md:21-25
Core Mandates and Zero-Tolerance Policy
The laws enforce a strict adherence to canonical code and single sources of truth. Agents are prohibited from using workarounds, stubs, or legacy branch fallbacks to bypass system gates.
Strict Total Conduct
- Root Cause Resolution: Every fix must address the root cause generically and cleanly. Validation must occur in the same turn, confirmed by exit codes and specific output lines.
- Dead Code Removal: Superseded code must be removed in the same cycle as its replacement.
- SSOT (Single Source of Truth): Operations must fail loud if the authoritative source for identity, configuration, or contract is absent.
- Bypass Prohibition: No usage of
TODO,FIXME, hardcodes, or suppression directives (e.g.,# type: ignore) unless accompanied by documented justification.
Sources: AGENTS.md:15-32, AGENTS.md:52-58
Fix-Forward-Only Strategy
To maintain integrity in shared working trees, reverting to past states via git commands like reset, restore, or stash is strictly forbidden as it may destroy the in-flight work of other agents. Agents must accept the current state and apply new changes to correct issues.
Sources: AGENTS.md:34-40
Operational Protocol and Validation
The project utilizes a specific protocol for handling blocked operations and validating completed work. "Done" is defined only when the complete chain of execution is validated with objective evidence.
Blocked-Operation Protocol
When a tool or command is blocked by security hooks or sandboxes, the agent must follow a specific sequence:
- Stop execution immediately.
- Diagnose the blockage in a single sentence.
- Hand the exact command to the user for manual execution.
- Wait for user output before proceeding.
Sources: AGENTS.md:67-77
Evidence and Reporting
Reporting honesty is 100% mandatory. Agents must explicitly state when a step was skipped or if a result was reached via a workaround. Speculative results are never presented as verified.
Sources: AGENTS.md:52-58
Technical Principles and Coordination
The laws integrate standard software engineering principles (SOLID, YAGNI, DI) with multi-agent coordination requirements.
Universal Engineering Principles
| Principle | Requirement |
|---|---|
| SSOT | One authoritative source per fact; reference only, never duplicate. |
| SOLID | Respect SRP, OCP, LSP, ISP, and DIP. Avoid fat interfaces and god-objects. |
| YAGNI | No speculative parameters or dead branches. Build only for current needs. |
| DI / DIP | Depend on abstractions; inject collaborators; no hidden globals. |
Sources: AGENTS.md:86-98
Multi-Agent Coordination Flow
Agents coordinate through a committed task board located at <repo>/.agents/coordination/tasks.md.
The diagram represents the lifecycle of a task under the Engineering Agent Laws, emphasizing validation and coordination.
Sources: AGENTS.md:100-111, src/flext_meltano/README.md:95-103
Quality Gates and Standards Compliance
Engineering Agent Laws are enforced through canonical make verbs and automated scanning tools defined in the project's configuration.
Enforcement Mechanisms
- Type Safety: strict-mode MyPy compliance and most-restrictive typing.
- Quality Gates: Mandatory execution of
make test,make check, andmake val. - Git Landing: Scoped work must be landed immediately after validation using explicit pathspecs. Commits must not contain agent/bot attribution or trailers.
Sources: README.md:34-36, AGENTS.md:80-84, AGENTS.md:100-107, pyproject.toml:161-182
Minimum Thresholds
The project configuration sets specific failure thresholds to ensure compliance with the Engineering Agent Laws.
| Category | Requirement | Source |
|---|---|---|
| Coverage | 90% minimum (enterprise target) | tests/README.md:104 |
| Type Errors | 0 allowed | src/flext_meltano/README.md:100 |
| Python Version | 3.13+ | pyproject.toml:44 |
| Linting | Ruff (comprehensive rule set) | pyproject.toml:500 |
Conclusion
The Engineering Agent Laws provide a non-negotiable framework for maintaining the technical integrity of the FLEXT Meltano platform. By enforcing root-cause fixes, prohibiting workarounds, and requiring objective evidence for validation, these laws ensure that the project remains enterprise-ready and scalable across multi-agent development environments.
Sources: AGENTS.md:5-13, src/flext_meltano/README.md:131-136