FLEXT AI Agent Skills

Relevant source files

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

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

FLEXT AI Agent Skills represent the codified engineering principles, operational guidelines, and technical constraints that govern all AI agent actions within the FLEXT workspace. These skills are structured as path-scoped, evidence-backed guidance designed to ensure that integrations are built using typed, validated, and reusable primitives while maintaining a "zero ad-hoc code" policy.

The governance framework for these skills is anchored in the Universal Agent Engineering Core, which mandates that runtime reality, configuration-driven testing, and strict type safety precede all implementation efforts. Agents operate under a hierarchy of authority where the Meta do FLEXT serves as the "North Star," enforcing a governance chain that prioritizes net-LOC reduction and 100% type coverage.

Sources: AGENTS.md:1-24, AGENTS.md:150-165, README.md:8-13, codex.md:15-18

Governance Hierarchy and Authority

Agent behavior is governed by a strict hierarchy of authoritative sources. The newest explicit operator instruction always maintains supreme authority, overriding all lower-level rules or plan-based reminders.

Tiers of Authority

Priority	Source	Description
1 (Highest)	Operator Instruction	Real-time commands from the human operator.
2	AGENTS.md	Project-specific canonical engineering law and "Meta do FLEXT".
3	Universal Core	Cross-project law found in ~/.agents/AGENTS.md.
4	Path-Scoped Skills	Specific logic located in .agents/skills/*/SKILL.md.

Sources: AGENTS.md:12-20, AGENTS.md:175-180, CLAUDE.md:1-10

The Bead Ledger System

Agents use the Bead Ledger (bd) as the mandatory system of record for all work. Beads own the state of plans, memory, dependencies, and evidence. Every state-changing stage requires an update to the active Bead, including the exact command evidence and commit SHAs.

Sources: AGENTS.md:52-54, AGENTS.md:139-142, AGENTS.md:238-245

Core Engineering Principles

FLEXT AI Agent Skills enforce a "Continuous Green" policy where the workspace must be importable and collectable at every instant.

Critical Engineering Mandates

• Railway Pattern: All fallible application paths must return a Result type r[T]. Raw exceptions for control flow are prohibited.
• P0 Config Validation: Tests must validate configuration changes by construction. Hardcoding expected values that are owned by config/*.yaml is a test defect.
• Type Rigor: Total rejection of Any, bare object, or bypass stubs.
• Facade Consistency: Use canonical aliases for project facades: c (core/context), m (models), t (types), p (protocols), u (utilities).

Sources: AGENTS.md:25-30, AGENTS.md:200-210, examples/advanced_processing_example.py:80-95

Implementation Flow Diagram

This diagram illustrates the mandatory sequence an AI agent follows for any task mutation.

Advanced Processing and Workflow Skills

AI agents are expected to implement complex processing patterns that leverage Python 3.13 features and Pydantic v2.

Parallel Execution Patterns

Agents utilize ThreadPoolExecutor for concurrent operations while maintaining resource safety through context managers.

# From examples/advanced_processing_example.py
with ThreadPoolExecutor(max_workers=4) as executor:
    future_to_item = {
        executor.submit(process_single_item, item): item
        for item in items_to_process
    }
    for future in as_completed(future_to_item):
        result = future.result()
        # Result handling using Railway Pattern

Sources: examples/advanced_processing_example.py:215-225, examples/complete_workflow_example.py:218-230

Declarative Pipeline Architecture

Agents build pipelines where stages are defined as sequential operations on a shared payload, typically involving validation, processing, and analysis.

Component	Responsibility	Data Structure
Orchestrator	Context lifecycle and correlation tracking.	WorkflowContext
Stage Function	Isolated logic for one transformation step.	Callable[[Data], Result[T]]
Result Aggregator	Performance metrics and efficiency scoring.	AggregatedMetrics

Sources: examples/advanced_processing_example.py:126-140, examples/complete_workflow_example.py:80-110

Workflow Sequence

The following sequence diagram represents the interaction between the Orchestrator and the parallel processing stages during a complete workflow execution.

Validation and Quality Gates

No task is considered "Done" until it passes the project's canonical validation surface. AI agents must never route around these guards.

Canonical Tooling

• Static Analysis: ruff and pyrefly are mandatory first gates for any touched file.
• Type Checking: pyright and mypy must be green across the workspace.
• Command Surface: All actions must run through make verbs (e.g., make check, make test). Direct tool invocation is prohibited if a Make target exists.

Sources: AGENTS.md:95-110, AGENTS.md:218-223, codex.md:20-25

Definition of "Done"

A task is complete only when:

1. Objective command evidence (exit code + output) is recorded.
2. Scoped commit and fast-forward push are performed.
3. SHA is recorded in the Bead.
4. No unresolved smells remain in the touched lane.

Sources: AGENTS.md:126-135, AGENTS.md:247-255

FLEXT AI Agent Skills ensure that technical debt is minimized by enforcing a "Fix Forward" policy and preventing the introduction of shims, stubs, or bypasses, thus maintaining the integrity of the typed enterprise integration platform.