Agent Execution & Universal Core

Relevant source files

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

• AGENTS.md
• README.md
• src/README.md
• pyproject.toml
• src/flext_oracle_wms/README.md

Introduction

The Agent Execution & Universal Core represents the governing framework and foundational logic for all AI agents and automated processes within the flext-oracle-wms repository. It is centered around the ~/.agents directory, which serves as the sole universal authority for agent behavior, configuration, and state management. This system ensures that AI agents operate under a strict, version-controlled set of laws (Universal Agent Law) that prioritize root-cause resolution, zero-debt baselines, and consistent validation through execution truth.

The primary scope of this module is to provide a "Universal Core" that binds any AI agent—regardless of the specific platform (Claude, Gemini, Cursor, etc.)—to the same engineering standards. Within the FLEXT ecosystem, this core governs how agents interact with Oracle WMS integration logic, enforcing that every configuration change is validated by construction and that all work is landed immediately upon successful verification.

Sources: AGENTS.md:7-15, AGENTS.md:270-280, README.md:16-19

Universal Governance & P0 Rules

The core operates on a hierarchy of authority where project-specific laws may be stricter than universal ones, but explicit operator instructions always prevail. A critical "P0" rule dictates that tests must validate configuration and settings changes by construction, preventing the hardcoding of expected values that might change over time.

Key Governance Principles

Principle	Description
Truth with Evidence	Every claim requires a command, exit status, and decisive output.
One Active Intent	Preserve goals and target "Beads" through delegation and continuation.
Root Cause Owner	Changes must occur at the canonical source (e.g., config/*.yaml), not projections.
Continuous Green	No task is considered done if the environment or project is broken or missing QA.
Beads is Truth	The "Beads" system owns work status, dependencies, and execution history.

Sources: AGENTS.md:17-45, AGENTS.md:112-115

Execution Flow and Validation

The execution flow for agents is strictly managed through canonical command surfaces, primarily using the project's make verbs (e.g., make check, make test, make val). Agents are prohibited from bypassing these guards with ad-hoc tool invocations.

Universal Agent Law (Portable Core)

The Portable Core is an inviolable set of rules that bind all AI agents. These rules ensure that agents do not use fallbacks, stubs, or "temporary" workarounds that hide underlying defects.

Core Mandates

1. Zero-Tolerance/Strict-Total: Agents must generically fix the root cause and remove superseded code in the same cycle. Bypassing gates with # type: ignore or TODO is strictly forbidden.
2. Fix-Forward-Only: Reverting shared work via git restore or git reset is prohibited to prevent destroying concurrent agent progress.
3. Strict, Most-Restrictive Typing: Adherence to the highest level of type safety (e.g., MyPy strict mode) is required.
4. SSOT (Single Source of Truth): Every fact has one authoritative source; agents must fail loud if it is missing.

Sources: AGENTS.md:285-300, AGENTS.md:302-308, AGENTS.md:347-350

Agent Roles and Multi-Agent Coordination

Agent execution is divided into separated roles to maintain integrity and prevent implementation bias in management.

Role Definitions

• Orchestrator: Coordinates semantic Bead states, validates outcomes, and approves merges. It does not implement code.
• Worker: Implements specific Beads in dedicated branches but never merges or closes tasks.
• Standing Documenter: Continuously audits and updates skills, ADRs, and docstrings under the same PR flow.

Sources: AGENTS.md:95-104

Multi-Agent Interaction

When multiple agents share a working tree, they coordinate through a committed task board located at <repo>/.agents/coordination/tasks.md.

Quality Gates and Technical Compliance

Agent execution is verified against a rigorous set of quality gates defined in the project's configuration. In flext-oracle-wms, these gates include:

• Type Safety: Strict MyPy adoption aiming for 95%+ coverage.
• Linting: Comprehensive Ruff rules with zero tolerance.
• Security: Scanning via Bandit and pip-audit.
• Testing: Minimum 90% test coverage for unit and integration tests.

Required Quality Verbs

Command	Action
make check	Run linter and type checker.
make test	Run the full test suite with coverage reporting.
make val	Combined validation: lint + type + security + test.
make mod	Regenerate managed pyproject.toml sections.

Sources: README.md:26-30, src/README.md:126-140, pyproject.toml:3-5, src/flext_oracle_wms/README.md:155-165

Conclusion

The Agent Execution & Universal Core provides the necessary discipline and technical infrastructure to allow multiple AI agents to collaborate on the flext-oracle-wms project safely. By enforcing the Universal Agent Law and the Bead execution system, the project ensures that all automated contributions maintain enterprise-grade quality, follow SOLID principles, and strictly adhere to the project's single source of truth.

Sources: AGENTS.md:270-280, AGENTS.md:352-360