/moai-workflow-loop

name: moai-workflow-loop
description: >
  Ralph Engine - Automated feedback loop with LSP diagnostics and AST-grep
  integration for continuous code quality improvement. Use when implementing
  error-driven development, automated fixing, or continuous quality validation
  workflows.
license: Apache-2.0
compatibility: Designed for Claude Code
allowed-tools: Read, Write, Edit, Bash, Grep, Glob
effort: low
user-invocable: false
metadata:
  version: "1.2.0"
  category: "workflow"
  status: "active"
  updated: "2026-01-11"
  tags: "lsp, ast-grep, feedback-loop, code-quality, automation, diagnostics, ralph"

Ralph Engine

Automated feedback loop system integrating LSP diagnostics, AST-grep security scanning, and test validation for continuous code quality improvement.

Preset Architecture — the Ralph Engine as a goal preset

The `/moai loop` skill (`~/.claude/skills/moai/workflows/loop.md`) re-expresses this Ralph engine as a **goal preset** built ON the goal engine: a scan stage builds a finite issue queue, and the iterate-until-done decision is delegated to the goal engine (`stop-goal`) with the pre-filled condition "queue drained + diagnostics clean". In this **preset architecture**, this SKILL.md documents the underlying LSP / AST-grep / test / coverage diagnostic machinery that the goal-preset sweep drives; the preset layers the goal-engine composition on top of that machinery WITHOUT changing it. The four loop quadrants (goal-based sweep, turn-based `/moai fix`, time-based cadence, proactive CI-watch) are presets on the one goal engine, not independent engines.

Quick Reference

Core Capabilities:

• LSP Integration: Real-time diagnostics from language servers
• AST-grep Scanning: Structural code analysis and security checks
• Feedback Loop: Iterative error correction until completion conditions met
• Hook System: PostToolUse and Stop hooks for seamless Claude Code integration

Key Components:

• .claude/hooks/moai/handle-post-tool.sh (PostToolUse): LSP diagnostics after Write/Edit operations
• .claude/hooks/moai/handle-stop.sh (Stop): Loop iteration control
• ralph.yaml: Configuration settings

Commands:

• /moai: One-click Plan-Run-Sync automation (default)
• /moai loop: Start feedback loop
• /moai fix: One-time auto-fix

When to Use:

• Implementing features with zero-error goal
• Automated code quality improvement
• Continuous integration workflows
• Error-driven development patterns

Implementation Guide

Architecture Overview

The Ralph Engine follows a layered architecture. User commands such as /moai:loop, /moai:fix, and /moai enter the Command Layer. The Command Layer invokes the Hook System, which contains the PostToolUse Hook for LSP diagnostics and the Stop Hook for loop control. The Hook System connects to Backend Services including the LSP Client (MoAILSPClient), AST-grep Scanner, and Test Runner. Backend Services feed into Completion Check which evaluates whether errors are zero, tests pass, and coverage is met. Based on the Completion Check result, the system either continues the loop or completes.

Configuration

The ralph.yaml configuration file contains the following sections and settings.

Under the ralph section, enabled controls whether Ralph is active (true by default).

Under the lsp section, auto_start controls automatic language server startup (true by default), timeout_seconds sets the connection timeout (30 seconds default), and graceful_degradation enables fallback to linters when LSP unavailable (true by default).

Under the ast_grep section, enabled controls AST-grep integration (true by default), security_scan enables security rule checking (true by default), and quality_scan enables code quality rule checking (true by default).

Under the loop section, max_iterations sets the maximum loop iterations (10 by default), auto_fix controls automatic fix application (false by default requiring confirmation), and require_confirmation requires user approval before fixes (true by default).

Under the completion subsection of loop, zero_errors requires no LSP or compiler errors (true by default), zero_warnings requires no warnings (false by default as optional), tests_pass requires all tests to pass (true by default), and coverage_threshold sets minimum coverage percentage (85 by default).

Under the hooks section, post_tool_lsp has enabled (true by default) and severity_threshold (error by default). The stop_loop_controller has enabled set to true by default.

Hook Integration

PostToolUse Hook

The PostToolUse hook is triggered after Write and Edit operations. When invoked, Claude Code provides hook input containing the tool_name (such as Write) and tool_input containing the file_path and content.

The hook processes diagnostics and returns hook output with hookSpecificOutput containing the hookEventName (PostToolUse) and additionalContext describing the diagnostic results. For example, the context might report LSP found 2 errors and 3 warnings in file.py, with specific error messages including line numbers.

Exit code 0 indicates no action needed. Exit code 2 indicates attention needed due to errors found.

Stop Hook for Loop Controller

The Stop hook is triggered after each Claude response. The hook reads the loop state file located at .moai/cache/.moai_loop_state.json. This state contains active status (true or false), current iteration number, max_iterations limit, last_error_count from previous iteration, and completion_reason when finished.

The hook returns output with hookSpecificOutput containing hookEventName (Stop) and additionalContext reporting loop status. For example, it might report Ralph Loop CONTINUE at Iteration 3 of 10 with 2 Errors, and next actions to fix the remaining errors.

Exit code 0 indicates loop complete or inactive. Exit code 1 indicates continue loop with more work needed.

LSP Client Usage

The Go LSP client is integrated into the hook system. LSP diagnostics are automatically collected