Ralph Loop Workflow
Relevant source files
The following files were used as context for generating this wiki page:
The Ralph Loop Workflow is a specialized execution cycle within the FLEXT Quality ecosystem designed for AI agents and automated tooling. It orchestrates iterative code generation, project-specific quality checks, and verification loops to ensure that all changes adhere to the repository's strict engineering standards.
This workflow serves as a primary automation path for Claude Code and other agent-based tools. It integrates core quality gates—including Ruff, basedpyright, Bandit, and pytest—into a unified verification loop that must pass before any phase closure or code promotion.
Sources: AGENTS.md:12-14, README.md:15-18, .claude/commands/ralph-loop.md
Workflow Architecture and Execution
The Ralph Loop operates as an orchestration layer over the flext_quality facade and the underlying command surface. It coordinates the execution of quality hooks and the verification of results through a standardized input/output protocol.
Execution Phases
The workflow follows a strict sequential process to validate changes:
- Orchestration Initiation: The agent triggers the loop, often via the
ralph-loopcommand or theFlextQualityfacade. - Environment Preflight: The system verifies agent execution prerequisites, including parent FLEXT chain status and skill loading.
- Command Execution: The loop runs declared orchestration contracts, such as
make checkandmake test. - Verification & Feedback: The system parses the output of these tools. If failures occur, the loop provides diagnostic feedback for the agent to correct the code.
- Phase Closure: Once all gates pass, the loop allows the agent to finalize the session.
Sources: AGENTS.md:25-29, README.md:43-45, AGENTS.md:65-72
Workflow Logic Diagram
The following diagram illustrates the iterative nature of the Ralph Loop Workflow and its interaction with quality gates.
This diagram shows the feedback loop where failures lead to automated correction cycles before final closure.
Sources: AGENTS.md:25-29, tests/README.md:162-175
Integration with Quality Gates
The Ralph Loop leverages the FlextQualityCli to assemble and execute a suite of native quality tools. This ensure that all changes meet the project's zero-debt baseline.
Core Quality Components
| Tool | Role in Workflow | Implementation |
|---|---|---|
| Ruff | Linter and Formatter | FlextQualityCli assembly |
| basedpyright | Static Type Analysis | FlextQualityCli assembly |
| Bandit | Security Scanning | FlextQualityCli assembly |
| pytest | Functional Testing | make test |
| Coverage | Code Coverage Validation | tool.coverage in pyproject.toml |
Sources: AGENTS.md:25-27, README.md:47-48, tests/README.md:38-42
Hook Execution Protocol
The workflow uses standardized utility functions to handle communication between the agent and the quality tools. The FlextQualityUtilities class provides methods to manage these interactions.
# src/flext_quality/utilities.py:97-114
@staticmethod
def format_hook_output(
*,
continue_exec: bool = True,
message: str | None = None,
blocked_reason: str | None = None,
) -> str:
"""Format hook output JSON for the Ralph Loop."""
output: t.MutableOptionalFeatureFlagMapping = {"continue": continue_exec}
if message:
output["systemMessage"] = message
if blocked_reason:
output["blockedReason"] = blocked_reason
# ... serialization logic ...
return decoded_output
Sources: src/flext_quality/utilities.py:97-114
Execution Requirements and Prerequisites
The Ralph Loop enforces strict engineering laws defined in the AGENTS.md governance capsule. These policies are non-optional and must be satisfied for the loop to complete successfully.
- Zero-Debt Baseline: Changes must not introduce new linting or typing errors.
- Strict Execution: The workflow applies "fail loud" and "no fallback" policies. If a gate fails, the process stops and reports the traceback immediately.
- Runtime Evidence: Implementation success is proven only through runtime behavior and successful gate completion.
- SSOT (Single Source of Truth): The workflow respects generated projections and avoids altering correct adjacent owners for invalid consumers.
Sources: AGENTS.md:65-85, README.md:23-28
Verification Sequence
The verification sequence ensures that external token validation and internal logic checks are performed correctly.
This sequence shows the synchronous communication between the agent and the orchestration platform.
Sources: src/flext_quality/utilities.py:145-155, AGENTS.md:25-29
Conclusion
The Ralph Loop Workflow is the fundamental mechanism for ensuring professional integrity and technical accuracy in automated code changes. By wrapping quality gates in a strict, iterative orchestration layer, it prevents the introduction of defects and ensures that all agent-driven implementations conform to the project's high standards. Success in the loop is determined by clear runtime evidence and the total satisfaction of all declared quality gates.
Sources: AGENTS.md:95-98, examples/basic/simple_analysis/README.md:15-20