Universal Agent Engineering Core

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• CLAUDE.md
• codex.md
• README.md
• pyproject.toml
• examples/advanced_processing_example.py
• examples/complete_workflow_example.py

The Universal Agent Engineering Core represents the canonical governing authority and architectural baseline for all autonomous agents operating within the FLEXT ecosystem. It establishes an "Engineering Law" that ensures absolute truth, technical rigor, and continuous validation. The core is anchored by the ~/.agents configuration, which acts as the supreme authority for AI Hub distribution and project-specific governance.

This framework is designed to enforce a "Continuous Green" state, where every change must be validated by evidence and every implementation must adhere to strictly typed, fallible paths using the r[T] (Result) pattern. The scope covers the entire platform, including core integration packages like flext-core and domain-specific connectors.

Sources: AGENTS.md:7-14, README.md:16-22

Core Governance and Engineering Laws

The core is built upon a hierarchy of "Supreme Laws" and rules that govern agent behavior, ranging from absolute honesty to strict technical constraints. These rules ensure that agents do not just perform tasks but stabilize the environment through evidence-backed actions.

The Supreme Rules

• Supreme Rule (Absolute Truth): Agents must provide 100% honesty backed by real evidence (command exit codes and output).
• Supreme Law (Resolve, Never Hide): Every defect must be fixed at the root in the source/GitOps layer; workarounds and suppressions are prohibited.
• Continuous Green: No task is complete if the environment is broken or missing real-use QA.

Sources: AGENTS.md:166-174, AGENTS.md:46-55

Implementation Directives

Rule ID	Directive	Description
P0	Test Validation	Tests must validate config changes by construction, never hardcoding expected values.
R0	Zero Tolerance	Prohibits bypass, fallbacks, or stubs. Fixes must be generic at the root.
R6	Strict Typing	Prohibits the use of Any or bare object. Requires Pydantic models.
R18	Continuous Green	Tree must be importable/collectable at every instant; batch edits must be smoke-tested.
R20	Operator Supremacy	The newest explicit operator instruction overrides all lower authorities and plan injections.

Sources: AGENTS.md:12-25, AGENTS.md:176-200, AGENTS.md:105-115

Architectural Patterns

The FLEXT architecture enforces specific patterns to maintain enterprise-grade reliability and performance.

The Railway Pattern

All fallible application paths must use the r[T] result pattern. This functional approach ensures that errors are handled as data rather than through standard exception propagation, allowing for robust, fail-fast pipelines.

Parallel Batch Processing

The core supports parallel execution using ThreadPoolExecutor for high-throughput data operations while maintaining memory efficiency through batching.

Bead System and Work Ledger

Work is managed through Beads (bd), which act as the mandatory execution truth for all agents. Beads track plans, memory, status, and evidence.

• Execution Truth: Beads own the status and evidence of every task. GitHub acts only as an external CI/PR mirror.
• Ownership: The orchestrator owns the semantic state, while workers implement specific Beads in isolated branches.
• Landing Work: A task is only "Done" when evidence is recorded, a commit is pushed, and the SHA is stored in the Bead.

Sources: AGENTS.md:57-60, AGENTS.md:62-72, AGENTS.md:133-138

Validation and Quality Gates

The core mandates a rigorous validation chain that must be cleared before any code is landed. This is managed through a canonical command surface.

Canonical Commands

Agents must use the project's Make verbs rather than direct tool invocations.

• make check: Runs linting, formatting, and type-checking (Ruff, Pyright, Mypy).
• make test: Executes scoped unit and integration tests.
• make val: Workspace-wide validation.
• make mod: Regenerates managed sections in pyproject.toml.

Sources: AGENTS.md:92-103, pyproject.toml:1-5, scripts/maintenance/README.md:20-25

Quality Enforcement

Gate	Tooling	Enforcement Level
Linting	Ruff	Error on any violation; no per-file-ignores to hide defects.
Typing	Pyright/Mypy	Strict mode; no Any allowed.
Dependency	Deptry	Enforces known first-party boundaries.
Logic	Pyrefly	Custom project-specific smell detection and refactor gates.

Sources: pyproject.toml:115-135, pyproject.toml:500-515, AGENTS.md:52-55

Conclusion

The Universal Agent Engineering Core serves as the bedrock of the FLEXT platform, ensuring that agents operate with the same rigor as human architects. By centralizing authority in AGENTS.md, enforcing the Railway Pattern for error handling, and mandating evidence-backed completion via the Bead system, the project maintains a "Continuous Green" state suitable for enterprise data integration.

Sources: AGENTS.md:7-14, README.md:7-12