Agent Engineering & Governance
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Agent Engineering & Governance within the flext-cli project establishes a rigorous, automated framework for AI agents to operate safely and effectively. It centers on the "Universal Agent Engineering Core," which dictates that ~/.agents is the sole universal authority for configuration. The governance model ensures that every action taken by an agent—whether manual or automated—is validated against "executable documentation" and strictly follows "Project Law" to maintain system integrity.
The primary purpose of this governance is to prevent configuration drift, ensure "continuous green" status across all test tiers, and mandate that all changes are rooted in single sources of truth (SSOT). This framework is designed to support multi-agent collaboration in a shared working tree without destructive interference.
Sources: AGENTS.md:1-12, README.md:21-31
Core Engineering Principles
The governance model is built on twenty-nine specific engineering principles and thirteen "Universal Agent Laws" that mandate strict technical conduct.
The P0 Mandate: Validation by Construction
The highest priority (P0) is that all tests, golden files, and executable documentation must remain valid during configuration or settings changes. Hardcoding values that are owned by configuration is considered a test defect.
Sources: AGENTS.md:14-23
Universal Conduct Laws
Agents must adhere to a "Zero-Tolerance" policy for technical debt and workarounds.
| Principle | Description |
|---|---|
| SSOT | Reference one authoritative source; fail loud if absent. |
| Fix-Forward | Never revert shared work; accept current state and move forward. |
| Stay In Scope | Do exactly what is asked; no unrequested refactors or improvements. |
| Evidence Before Done | "Done" requires objective evidence (command exit code + output). |
| Strict Typing | Use the most restrictive types; avoid Any or bare object. |
Sources: AGENTS.md:204-265, AGENTS.md:280-295
Operational Flow & Multi-Agent Coordination
Governance defines a strict hierarchy of roles and coordination mechanisms to manage complexity in automated environments.
Role Separation
Execution is divided between three distinct roles to ensure checks and balances:
- Orchestrator: Coordinates work, owns semantic state, validates progress, and handles merges/promotes.
- Worker: Implements a single "Bead" (unit of work) in a branch; never merges or closes.
- Documenter: Audits and updates documentation, ADRs, and examples under the same PR flow.
Sources: AGENTS.md:73-83
Coordination via "Beads"
Work is organized into "Beads," which represent the execution truth of plans, dependencies, and evidence.
The diagram shows the lifecycle of a task governed by the Bead system, emphasizing validation before landing work.
Sources: AGENTS.md:59-62, AGENTS.md:146-155
Synchronization Logic
Coordination occurs through a committed task board. Agents must lease a task before editing and provide continuous heartbeats. Heartbeats must be published by the orchestrator at least every five minutes, including agent tables and "epic evolution."
Sources: AGENTS.md:88-90, AGENTS.md:159-166
Quality Gates and Validation
All code, including examples and scripts, is treated as first-class production source and must pass identical quality gates.
Canonical Command Surface
Agents are forbidden from using ad-hoc tool invocations. All build, test, and generation actions must run through canonical make verbs or the documented CLI.
Sources: AGENTS.md:118-126, README.md:33-35
Validation Hierarchy
Governance mandates that runtime reality precedes implementation and tests.
- Establish behavior from official external contracts.
- Validate staged artifacts with the real consumer.
- Align canonical implementation and models.
- Encode observed behavior into tests.
Sources: AGENTS.md:95-107
This sequence demonstrates the governance requirement to validate against runtime reality and canonical authority before updating task status.
Sources: AGENTS.md:130-137, AGENTS.md:146-155
Integration and Implementation Examples
The governance principles are applied in the examples/ directory to demonstrate compliant CLI development.
Complete Integration Pattern
Compliant CLI applications use a "Public Facade" and "Railway Pattern" results (p.Result) to ensure fail-loud behavior.
class DataManagerCLI:
def add_entry(self) -> p.Result[t.JsonMapping]:
# Uses public facade for prompts
key_result = cli.prompt("Enter key:", default="sample_key")
if key_result.failure:
return r[t.JsonMapping].fail(f"Prompt failed: {key_result.error}")
# Returns typed Result contract
return r[t.JsonMapping].ok(t.Cli.JSON_MAPPING_ADAPTER.validate_python({key: value}))
Sources: examples/ex_11_complete_integration.py:40-58, examples/README.md:46-56
Dependency and Build Governance
The project's pyproject.toml uses a [MANAGED] system enforced by infra tools. Manual edits are prohibited for managed sections, ensuring that the project structure remains deterministic and aligned with the "Universal Core."
Sources: pyproject.toml:1-10
Conclusion
Agent Engineering & Governance in flext-cli moves beyond simple coding standards into a structured "Project Law." By treating agents as first-class citizens with specific roles, strict conducts (Universal Agent Law), and mandatory validation protocols (P0), the system ensures that automated development remains robust, traceable, and "continuously green."