Quality Gates & Onboarding

Relevant source files

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

• README.md
• AGENTS.md
• pyproject.toml
• examples/README.md
• examples/basic-plugin.md
• src/flext_plugin/models.py
• src/flext_plugin/_utilities/plugin_platform.py

Introduction

Quality Gates and Onboarding in the FLEXT Plugin system represent a set of mandatory technical standards and procedural checkpoints designed to ensure software integrity, type safety, and architectural consistency. The system enforces a "zero-debt baseline" where every contribution must pass through canonical make verbs—specifically check, test, val, and docs—to validate the codebase against predefined thresholds.

The onboarding process is governed by the Universal Agent Law, which binds both human developers and AI agents to strict engineering principles. This includes zero-tolerance for workarounds, mandatory root-cause fixes, and the requirement for objective evidence (exit codes and output) before a task is considered "Done." These gates ensure that all plugins integrated into the platform maintain the high standards required for enterprise-grade stability.

Sources: README.md:38-42, AGENTS.md:10-25, examples/README.md:330-345

Universal Agent Law & Governance

The project operates under a strict governance model defined in AGENTS.md. This "Universal Agent Law" is an inviolable core of engineering conduct that applies to every session and project type.

Core Engineering Principles

The onboarding process requires adherence to several critical principles:

• SSOT (Single Source of Truth): Reference authoritative sources and fail loud when they are absent.
• Zero-Tolerance: Never use fallbacks, compatibility wrappers, or suppression directives (like # type: ignore) to bypass a gate.
• Strict Typing: Use the most restrictive types possible to ensure compile-time safety.
• Fix-Forward-Only: In a shared environment, developers must accept the current state and fix forward rather than reverting shared work.

Sources: AGENTS.md:14-22, AGENTS.md:46-52, AGENTS.md:79-88

The "Done" Protocol

A task is only classified as "Done" when the complete validation chain is evidenced by objective command output and success exit codes. Speculative or partial results are forbidden.

This diagram illustrates the mandatory feedback loop required for passing quality gates during development.
Sources: AGENTS.md:55-60, AGENTS.md:90-95

Quality Gate Verbs & Standards

The flext-plugin system uses standardized make verbs to enforce quality. These are categorized into specific execution domains.

Verb	Scope	Target Standards
check	Linting & Formatting	ruff, black, isort
test	Functional Validation	pytest (85% coverage minimum)
val	Type Checking	mypy, pyright (strict mode)
docs	Documentation	mkdocs, API reference generation

Sources: README.md:38-42, examples/README.md:330-335, pyproject.toml:132-150

Validation Thresholds

The project configuration in pyproject.toml defines strict thresholds for the test gate:

• Coverage: A minimum of 25% is enforced globally, but example standards recommend 85% for production-grade plugins.
• Strict Typing: pyright is configured in strict mode, and mypy requires check_untyped_defs = true.
• Linting: ruff is configured with select = ["ALL"], ensuring exhaustive rule checking.

Sources: pyproject.toml:132-135, pyproject.toml:154-175, pyproject.toml:350-355, examples/README.md:330-335

Plugin Onboarding & Integration

Onboarding a new plugin into the platform requires passing through a structural and lifecycle validation gate. The FlextPluginPlatform enforces these rules through its register_plugin and discover_plugins methods.

Onboarding Flow for New Plugins

1. Metadata Definition: The plugin must define a PluginMetadata value object including name, version, and dependencies.
2. Business Rule Validation: Every plugin entity must pass the validate_business_rules() check, ensuring valid semantic versioning (X.Y.Z) and non-empty identifiers.
3. Lifecycle Registration: The plugin must be registered via the PluginPlatformService.

The sequence shows the internal validation steps required before a plugin is accepted by the platform.
Sources: src/flext_plugin/models.py:173-200, src/flext_plugin/_utilities/plugin_platform.py:348-364

Technical Requirements for Onboarding

Requirement	Specification	Source File
Python Version	3.13+	pyproject.toml:30
Naming Pattern	Regex validation for plugin ID	src/flext_plugin/models.py:44
Versioning	Semantic Version (X.Y.Z)	src/flext_plugin/models.py:102
Dependency Mgmt	poetry or hatchling	pyproject.toml:5-10

Onboarding Checklists for Agents

When an AI agent (or human developer) initializes a session, they must verify the following "Agent Execution Pre-requisites":

1. Parent MRO chain verification: Check pyproject.toml dependencies.
2. Scope bootstrap: Initialize the required platform environment.
3. Zero-debt baseline: Ensure existing tests pass before starting new work.
4. Slot registry verification: Verify that internal service registries are active.

Sources: README.md:28-32, AGENTS.md:97-105

Summary

Quality Gates and Onboarding in flext-plugin function as a rigorous filtration system. By combining strict architectural laws (Universal Agent Law) with automated validation tools (make gates and Pydantic-based business rules), the project ensures that every component—whether a basic utility or a complex Docker-integrated service—adheres to a high-reliability baseline. Success is defined not just by functional code, but by the presence of objective evidence, type safety, and strict compliance with the project's engineering governance.

Sources: AGENTS.md:55-60, src/flext_plugin/models.py:173-180