Universal Agent Engineering Core
Relevant source files
The following files were used as context for generating this wiki page:
The Universal Agent Engineering Core represents the governing framework and foundational logic for AI agent conduct, configuration management, and technical standards within the flext-dbt-oracle project. It establishes ~/.agents as the sole universal authority, ensuring that AI Hub configurations distribute but never compete with project-specific laws.
The core mandate is centered on "Truth with evidence" and "Root cause" solutions, prohibiting temporary workarounds, bypasses, or shims. It strictly enforces that tests, documentation, and executable snippets remain valid during configuration changes by deriving expectations from a Typed Single Source of Truth (SSOT).
Sources: AGENTS.md:5-15, README.md:21-25
Engineering Governance and Law
Engineering conduct is bound by two primary sets of rules: the Universal Agent Engineering Core (governing project-specific operations) and the Universal Agent Law (a portable core binding all AI agents).
Universal Principles
The core operates under a zero-tolerance policy for technical debt. This includes mandatory root-cause fixes, the immediate removal of superseded code, and loud failures when authoritative sources are missing.
The diagram illustrates the hierarchy of authority and the mandatory execution cycle for any agent intervention.
Sources: AGENTS.md:12-45, AGENTS.md:162-185
Prohibited Conduct
- No Workarounds: Suppression directives like
# type: ignoreor escape hatches likeAnyare forbidden without explicit documentation. - No Blame: Concurrent work is integrated through "fix forward" logic rather than reverting shared working trees.
- Minimal Scope: Agents must perform only requested actions; unrequested refactors are prohibited.
Sources: AGENTS.md:165-180, AGENTS.md:196-200
Configuration and SSOT Management
Configuration is strictly managed through a typed SSOT architecture. The system ensures that config/*.yaml or specific settings classes are the canonical owners of all configurable facts.
Settings and Profiles
The FlextDbtOracleSettings class manages the runtime environment, utilizing Pydantic for validation and environment variable mapping (prefix FLEXT_DBT_ORACLE_).
| Component | Purpose | Authority Source |
|---|---|---|
| Database Config | Host, Port, Service Name, SID | rules.json, settings.py |
| Performance | Pool sizes, timeouts, fetch sizes | rules.json |
| DBT Logic | Materialization, Schema mapping | rules.json, models.py |
Sources: rules.json:20-35, src/flext_dbt_oracle/settings.py:16-30
P0 Validation Requirement
Tests must validate configuration changes by construction. Hardcoding expectations in tests is prohibited; instead, tests must read expected values from the same typed SSOT used by production code.
Sources: AGENTS.md:10-25
Architectural Components
The architecture integrates DBT adapter logic with Oracle database operations using a modular domain namespace.
Data Model Hierarchy
The project uses a composed model structure where FlextDbtOracleModels inherits from FlextMeltanoModels and Oracle-specific base models.
This class diagram depicts the relationship between core model metadata and connection configurations.
Sources: src/flext_dbt_oracle/models.py:16-45
Module Governance Rules
Automated checks ensure structural integrity. The system prohibits:
- Module-level loggers:
loggeror_loggerassignments at the top level are defects. - Top-level functions: Logic must be encapsulated within classes or specific namespaces.
Sources: tests/unit/test_module_governance.py:60-95
Technical Execution Standards
The core mandates specific tools and sequences for project interaction to maintain "Continuous Green" status.
Quality Gates and Tooling
Standardized make verbs (e.g., make check, make test) are the only permitted routes for validation. The project requires rigorous linting and typing across all directories, including tests/ and examples/.
| Tool | Scope | Requirement |
|---|---|---|
| Ruff / Pyrefly | Linting & Logic | Zero violations in src, tests, scripts |
| Pyright / Mypy | Static Typing | Strict mode, no Any escape hatches |
| Pytest | Execution | Coverage thresholds and construction validation |
Sources: pyproject.toml:285-350, AGENTS.md:55-65
Coordination via Beads
The "Beads" system owns the execution truth, including work plans, status, and evidence. Workers implement one Bead in one branch and must land work immediately upon validation.
The sequence shows the coordination flow between agents and the centralized state tracking.
Sources: AGENTS.md:75-80, AGENTS.md:225-230
Conclusion
The Universal Agent Engineering Core serves as the constitutional framework for flext-dbt-oracle. By enforcing a Typed SSOT, prohibiting technical shortcuts, and requiring objective evidence for all changes, it ensures that the project maintains a high degree of architectural integrity and stability even when managed by multiple autonomous agents.