Project Governance & AI Agents
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Project governance within the FLEXT-LDIF repository is defined by a rigorous set of "Universal Agent Laws" and "Agent Engineering Cores" that bind both human developers and AI agents (such as Claude, Codex, or GitHub Copilot). The primary purpose of this governance framework is to ensure architectural integrity, absolute single-source-of-truth (SSOT) compliance, and continuous validation across all development activities.
The system relies on a decentralized yet highly coordinated execution model where "Beads" represent units of work and specific roles—Orchestrators and Workers—maintain clear separation of concerns. This approach ensures that technical debt is prevented at the root and that all code, including tests and examples, adheres to the same strict quality gates.
Sources: AGENTS.md:16-30, AGENTS.md:275-283, src/README.md:94-98
Agent Roles and Hierarchy
The governance model distinguishes between different agent roles to ensure serialized, validated progress without implementation conflicts.
Orchestrators vs. Workers
The architecture enforces a strict separation between coordination and implementation.
- Orchestrators: These agents own the semantic state of "Beads" (work units). They coordinate, validate, and approve merges but do not perform direct implementation. They are responsible for heartbeat reporting every five minutes.
- Workers: These agents directly implement a specific Bead in a dedicated branch. They are prohibited from merging or closing tasks, deferring that authority to the Orchestrator.
- Standing Documenter: Continuously audits and updates documentation, ADRs, and docstrings under the same PR flow as code.
Sources: AGENTS.md:65-76, AGENTS.md:214-220
Coordination Workflow
Multi-agent coordination is managed through a committed task board (e.g., .agents/coordination/tasks.md) to prevent overwriting shared work.
The diagram above illustrates the delegation flow from operator intent to the separation of worker implementation and orchestrator validation.
Sources: AGENTS.md:65-76, AGENTS.md:347-353
Universal Agent Laws
The repository enforces "Universal Agent Law," which is an inviolable core of engineering conduct.
Zero-Tolerance and Fix-Forward
Governance prohibits reverts of shared work. Instead, agents must "fix forward" by accepting the current state of the tree and correcting root causes. Fallbacks, stubs, and legacy workarounds are strictly forbidden; any failure surfaced during a task must be owned and fixed by the agent currently executing.
Sources: AGENTS.md:285-312
P0 Principle: Validation by Construction
A core requirement is that tests and documentation must not hardcode values owned by configuration or settings. If a configuration change breaks a test, it is considered a test defect rather than a configuration error. Tests must read from the same Typed SSOT that production code uses.
Sources: AGENTS.md:16-30
Quality Gates and Standards
Project governance enforces uniform rigor across production code (src/), examples, and tests.
Required Quality Checks
All code must pass through the following gates before completion can be claimed:
- Linting: Ruff with strict rules.
- Type Safety: MyPy (strict mode), Pyrefly, and Pyright.
- Testing: Pytest with coverage requirements (target >90%).
- Security: Bandit and pip-audit for dependency verification.
Sources: pyproject.toml:79-200, tests/README.md:210-220, AGENTS.md:52-64
Table of Validation Thresholds
| Component | Metric | Threshold | Source |
|---|---|---|---|
| Overall Code | Test Coverage | 90% Minimum | tests/README.md:214 |
| Domain/App Layers | Unit Test Coverage | 95% Minimum | tests/README.md:215 |
| Public API | Type Safety | 95%+ Coverage | src/README.md:90 |
| Performance | Parsing Speed | >1000 entries/sec | tests/README.md:237 |
Execution Truth: The "Beads" System
In this framework, the "Bead" is the unit of execution truth. It encapsulates the plan, memory, dependencies, and evidence of work.
- Truth with Evidence: No claim of completion is valid without exact commands, exit statuses, and decisive output logs.
- Small Batches: Work must be delivered in reviewable units that can be integrated within a single session (hours, not days).
- No Stall by Reporting: Status reports are non-blocking and occur in parallel with execution.
Sources: AGENTS.md:31-41, AGENTS.md:77-80, AGENTS.md:188-196
Configuration and SSOT
The governance model mandates that config/*.yaml or typed settings serve as the sole authority for business rules and environmental parameters.
- Managed Binaries: All binaries are provisioned by
ai-hubwith no product-specific hardcoding. - Generators: Derived surfaces must be produced by generators; manual edits of projections are prohibited.
- Helm Serialization: Helm operations (build, lint, package) are strictly serialized to prevent concurrency violations.
Sources: AGENTS.md:129-152
Conclusion
Project Governance in FLEXT-LDIF is an automated, high-trust environment where AI agents are treated as first-class engineering citizens bound by strict protocols. By enforcing the "Fix Forward" and "SSOT" rules, the project ensures that multiple agents can operate concurrently without degrading the codebase or introducing hidden debt. Every change is evidenced, validated, and documented in real-time, maintaining a "continuous green" state.