AI Prompts & Workflows
Relevant source files
The following files were used as context for generating this wiki page:
AI Prompts and Workflows in the FLEXT ecosystem represent a governed, highly structured approach to automated engineering and data integration. The system relies on a "Canonical Engineering Law" that dictates how AI agents interact with the codebase, ensuring that all automated tasks follow a "Railway Pattern" for fault tolerance and a "Continuous Green" policy for system stability.
Workflows are implemented as multi-stage, often parallel, pipelines that handle complex enterprise tasks such as data validation, ACL processing, and system refactoring. These workflows are orchestrated through defined roles (Orchestrators, Workers, and Documenters) and are strictly managed by a "Bead" system for ledgering progress and evidence.
Sources: AGENTS.md:1-55, README.md:1-10, examples/README.md:10-30
Agent Governance & Prompting Hierarchy
The FLEXT project uses a strict hierarchy of authoritative sources to guide AI agent behavior. This ensures that prompts and automated actions are consistent across different tools and environments.
Authoritative Hierarchy
- User Request: The highest authority for a specific session.
- Project AGENTS.md: Defines project-specific engineering laws.
- Global Agent Law: Universal laws (v4) governing cross-project behavior.
- Path-Scoped Skills: Specific guidance found in
.agents/skills/*/SKILL.md.
Sources: AGENTS.md:315-320, CLAUDE.md:1-10
Operational Roles
Agents are organized into specialized roles to maintain separation of concerns:
- Orchestrator: Coordinates tasks, manages semantic state, and approves merges.
- Worker: Implements specific "Beads" (tasks) in isolated branches.
- Standing Documenter: Audits and updates documentation, docstrings, and examples in real-time.
Sources: AGENTS.md:86-98
Workflow Architecture: The Railway Pattern
FLEXT workflows leverage the "Railway Pattern," a functional error-handling approach where operations return a result type r[T]. This ensures that a pipeline stops immediately upon the first failure without propagating raw exceptions, providing a type-safe path for both success and failure branches.
The diagram above shows the linear flow of the Railway Pattern, where any failure in a stage diverts the workflow to a terminal error state.
Sources: examples/README.md:74-80, examples/advanced_processing_example.py:100-115
Workflow Components
| Component | Description | Reference |
|---|---|---|
| WorkflowContext | Stores correlation IDs, start times, and performance metrics. | CompleteWorkflowExample.WorkflowContext |
| StageResult | Captures success/failure, timing, and items processed for a single stage. | CompleteWorkflowExample.WorkflowStageResult |
| Orchestrator | Manages the lifecycle and parallel execution of workflow stages. | CompleteWorkflowExample.WorkflowOrchestrator |
| Bead (bd) | Mandatory work ledger that tracks task ownership and evidence. | AGENTS.md:410-415 |
Sources: examples/complete_workflow_example.py:53-120, AGENTS.md:410-420
Parallel Processing and Execution
Workflows are designed for enterprise scale, utilizing ThreadPoolExecutor for parallel execution of stages while maintaining strict data integrity.
Parallel Execution Flow
The WorkflowOrchestrator manages the fan-out of tasks to worker threads and collects results into a consolidated WorkflowStageResult.
This sequence illustrates how the orchestrator manages concurrent workers while ensuring correlation tracking.
Sources: examples/complete_workflow_example.py:173-200, examples/advanced_processing_example.py:210-225
Data Handling Constraints
- Pydantic Integration: All workflow payloads use Pydantic models (v2) for validation.
- Typed Boundaries: Untrusted input is parsed into canonical types immediately.
- Zero Bypass: Manual key normalization is prohibited; Pydantic must own the payload.
Sources: codex.md:15-25, AGENTS.md:65-68
Engineering Laws & Constraints
All AI-driven workflows must adhere to the "Supreme Law": Resolve, Never Hide. This forbids the use of workarounds, TODOs, or fakes.
Core Rules for AI Workflows
- Continuous Green (R7): No workflow is complete if the project is broken or missing real-use QA.
- Beads is Truth (R8): Every action must be recorded in the Bead system with objective command evidence.
- Runtime Reality (R15): Official external contracts and real consumer behavior precede implementation and tests.
- Land Immediately (R25): Small, validated batches must be committed and pushed fast-forward to the integration branch.
Sources: AGENTS.md:70-120, AGENTS.md:158-180
Workflow Validation Gates
Workflows must pass through specific "gates" before being considered done:
lint: Code style validation.pyrefly: Advanced static analysis.mypy/pyright: Strict type checking.markdown: Documentation validation.
Sources: AGENTS.md:365-375, scripts/maintenance/README.md:10-20
Summary
AI Prompts and Workflows in FLEXT are not merely scripts but highly governed processes integrated into the project's architecture. By combining the Railway Pattern for error resilience with a strict Engineering Law for AI agents, the system ensures that automated refactors, data integrations, and maintenance tasks are performant, type-safe, and verifiable via the Bead ledger system.
Sources: AGENTS.md:1-15, examples/README.md:140-150