LLM Governance and Orchestration
William12556/LLM-Governance-and-Orchestration
Governança estruturada e orquestração de LLMs com ciclos de trabalho auditáveis
Ver no GitHubFramework modelo-agnóstico para governança de LLMs em desenvolvimento de software, coordenando captura de requisitos, design e geração de código através de protocolos estruturados e gates de aprovação. Implementa o Ralph Loop (ciclo worker/reviewer) com orquestração autônoma limitada por governança explícita e rastreabilidade bidirecional entre requisitos, design, código e testes.
Instalação
npx convez-ai William12556/LLM-Governance-and-Orchestration1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Coordenação de projetos complexos com múltiplos modelos de IA
- Garantia de rastreabilidade e conformidade em desenvolvimento assistido por IA
- Decomposição estruturada de grandes projetos em tarefas discretas e auditáveis
Veredito

Plugin robusto para equipes que necessitam governança rigorosa em workflows de IA, com arquitetura dual-domain e protocolos bem definidos. Ideal para contextos críticos onde rastreabilidade e controle humano são não-negociáveis; requer investimento em integração e customização de perfis de implementação.
README
A tradução para o português deste README ainda está na fila.
LLM Governance and Orchestration
Purpose
This repository provides a model-agnostic governance framework for AI-assisted software development. The framework coordinates requirements capture, design, and code generation through structured protocols and human-in-the-loop approval gates.
For positioning context and design rationale, see RATIONALE.md.
The framework was motivated by a practical observation: language models lose coherence when navigating large, complex projects — a known consequence of context window constraints [1][2]. Structured documentation provides a compact, navigable project representation that mitigates this. The protocol-driven workflow achieves this by decomposing work into discrete, bounded steps — each providing the model with only the structured context relevant to the current task. Tactical Domain autonomy is explicitly bounded by governance protocols and a human-approved task brief, trading open-ended autonomy for predictability and traceability.
Governance
ai/governance.md defines a dual-domain architecture separating strategic coordination (Strategic Domain) from tactical implementation (Tactical Domain). Communication between domains uses MCP filesystem-based message passing. The framework is independent of any specific AI model or toolchain; implementation profiles map abstract framework concepts to concrete tooling.
- Protocol-driven workflow: Eleven protocols (P00–P10) govern requirements capture, project initialization, three-tier design hierarchy, change management, issue resolution, traceability, testing, quality assurance, audit, prompting, and requirements management
- Human approval gates: Explicit human authorization required before requirements baseline, design tier transitions, code generation, and baseline modifications
- Three-tier design decomposition: Master (system) → Domain (functional) → Component (implementation) with validation gates between tiers
- Model-agnostic architecture: Strategic and Tactical Domain roles fulfilled by any capable LLM; implementation profiles provided for Apple Silicon MLX (primary) and Claude Code (optional)
- UUID-based document coupling: 8-character hex identifiers with iteration synchronization through debug cycles
- Document lifecycle management: Active/closed states with immutable archival and closure criteria across all document classes
- Bidirectional traceability: Requirements ↔ Design ↔ Code ↔ Test linkages
- Template-based documentation: Seven YAML templates (T01–T07) for all document classes
Orchestration
The Autonomous Execution Loop (AEL) implements the Ralph Loop: a worker/reviewer cycle in which the same model fulfills both roles, differentiated by prompt engineering. The loop runs iteratively until the reviewer emits SHIP (task complete) or BLOCKED (boundary exceeded). Based on Geoffrey Huntley's Ralph Wiggum techniques.
orchestrator.py is an AI agent. It perceives its environment by reading state files and tool outputs, reasons via the model inference endpoint, acts by dispatching tool calls and writing state, and maintains persistent state in .ael/ralph/ across iterations. The Ralph Loop constitutes a minimal two-agent system: the worker agent produces, the reviewer agent critiques, and the orchestrator arbitrates. Autonomy is constrained by the governance protocols and the T04 tactical brief — the agent cannot redefine its goal mid-run.
orchestrator.py is the AEL entry point. It connects to configured MCP servers, sends tool definitions to the inference endpoint, dispatches tool calls, injects results, and iterates until no tool calls remain. It supports four execution modes:
| Mode | Description |
|---|---|
loop | Full worker/reviewer Ralph Loop cycle (standard invocation) |
worker | Single work phase pass |
reviewer | Single review phase pass |
reset | Clear state directory after human acceptance |
Configuration — ai/ael/config.yaml:
| Section | Purpose |
|---|---|
omlx | Inference endpoint URL and default model |
mcp_servers | MCP server command and argument definitions |
loop | max_iterations (outer Ralph cycles), phase_max_iterations (inner tool-call iterations per phase), MCP error threshold, tool call cap |
context | Model directory path, context window size (or null to resolve from model config.json), warn/abort budget thresholds |
State directory — .ael/ralph/ (ephemeral, per-task):
| File | Signal |
|---|---|
task.md | Task description loaded from T04 prompt |
iteration.txt | Current Ralph Loop cycle number |
work-summary.txt | Worker phase output |
work-complete.txt | Worker completion signal |
review-result.txt | SHIP or REVISE decision |
review-feedback.txt | Reviewer notes for next worker iteration |
.ralph-complete | Success marker |
RALPH-BLOCKED.md | Failure details; seeds T03 Issue |
Invocation (from project root, after human approval of T04 prompt):
# Standard loop
python ai/ael/src/orchestrator.py --mode loop \
--task workspace/prompt/prompt-<uuid>-<n>.md
# With wall-clock time limit (hours)
python ai/ael/src/orchestrator.py --mode loop \
--task workspace/prompt/prompt-<uuid>-<n>.md \
--duration 12
| Flag | Purpose |
|---|---|
--mode | worker | reviewer | loop | reset (default: loop) |
--task | Task string or path to task file |
--model | Model for all phases (overrides config default) |
--worker-model | Model for work phase only (loop mode) |
--reviewer-model | Model for review phase only (loop mode) |
--max-iterations | Outer Ralph cycle limit override |
--duration | Wall-clock time limit in hours (default: no limit) |
--config | Path to config.yaml |
Audit Loop
The AEL includes a read-only codebase quality analysis capability. It uses dedicated recipes (audit-work.yaml, audit-review.yaml) in place of the standard Ralph recipes. The worker reads source files, records findings, and marks items in a traversal index. The reviewer checks finding quality and coverage. No source file is written.
Audit-specific state files (pre-populated by the Strategic Domain before launch):
| File | Purpose |
|---|---|
audit-index.md | Ordered list of items to audit; worker marks each [x] on completion |
audit-report.md | Append-only findings accumulator |
audit-uml.md | Optional structural map of the target codebase |
Audit criteria assessed per item: style, complexity, error handling, security, conformance, dead code.
Invocation:
python ai/ael/src/orchestrator.py --mode loop \
--task workspace/prompt/<uuid>-audit.md \
--duration 12
Without --duration the loop runs until all items in audit-index.md are marked complete or max_iterations is exhausted. High-severity findings are promoted to T03 issues post-run via the standard P04 workflow.
See docs/guide-audit-loop.md for an overview and framework/ai/doc/guide-audit-loop.md for operational detail.
govwatch — Governance Monitoring TUI
govwatch is a standalone read-only TUI for monitoring a downstream project's governance state. It scans workspace/ and .ael/ralph/ each polling cycle and reports:
- Inferred workflow phase (Idle, Change cycle, Tactical execution, etc.)
- Two-tier compliance alerts: coupling violations, UUID mismatches, invalid
tactical_brief, naming convention failures - Open document registry grouped by UUID
- Alert summary written to
dashboard-alerts.md; clipboard copy viaCkey
Invocation from project root:
python ai/src/govwatch.py [--project PATH] [--interval N]
See framework/ai/doc/guide-govwatch.md for full operational detail.
ael-mcp — Claude Desktop AEL Interface (optional)
ael-mcp is a standalone MCP server that registers once in Claude Desktop and exposes three tools: start_ael, ael_status, and reset_ael. When registered, the Strategic Domain can launch and monitor AEL without human terminal access.
At T04 handoff (P09 §1.10.3), the human selects the execution path:
| Option | Who launches AEL | Status notification |
|---|---|---|
| A — Human executes (all profiles) | Human runs terminal command | Human notifies Strategic Domain |
| B — ael-mcp (Claude Desktop profile only) | Strategic Domain calls start_ael | Strategic Domain calls ael_status on request |
Repository: https://github.com/William12556/ael-mcp
Setup instructions: P01 §1.2.8 in ai/governance.md
Repository Structure
| Directory | Purpose |
|---|---|
framework/ | Canonical framework — governance, templates, profiles, AEL orchestrator |
framework/ai/governance.md | Master governance document |
framework/ai/profiles/ | Implementation profiles (claude-desktop, claude, mlx) |
framework/ai/templates/ | Document templates T01–T07 |
framework/ai/ael/ | Python AEL orchestrator (orchestrator, mcp_client, parser, recipes) |
skel/ | Minimal deployable skeleton — copy to initialize a new project |
skel/ai/ | Governance, templates, profiles, and recipes for deployed projects |
skel/workspace/ | Pre-scaffolded workspace directories (design, prompt, test, trace, etc.) |
skel/src/ skel/tests/ skel/docs/ | Standard project directories |
dev/ | Framework development artefacts (requirements, design, issues, changes) |
dev/requirements/ | Framework-level requirements documents |
dev/design/ | Framework-level design documents |
docs/ | User-facing operational documentation |
docs/claude/ | Strategic Domain operational documents (instructions, guidelines, context) |
docs/setup-apple-silicon-mlx.md | Apple Silicon + MLX inference setup guide |
docs/software-testing-guidance.md | Software testing reference for framework adopters |
docs/guide-getting-started.md | End-to-end setup guide from clone to first AEL run |
docs/guide-profile-selection.md | Profile selection guide: AEL vs Claude Code vs claude-omlx |
docs/guide-audit-loop.md | Audit loop overview and usage guide |
framework/ai/doc/guide-audit-loop.md | Operational audit loop guide for the Strategic Domain (downstream projects) |
framework/ai/src/govwatch.py | Governance monitoring TUI — read-only, downstream project observer |
framework/ai/src/requirements-govwatch.txt | govwatch dependency manifest (textual, rich) |
framework/ai/doc/guide-govwatch.md | govwatch operational guide |
framework/ai/doc/guide-ael-operations.md | AEL operational reference for the Strategic Domain (downstream projects) |
Requirements
Common
| Item | Requirement |
|---|---|
| Operating system | macOS 14+ (Sonoma) required (Apple Silicon) |
| Python | 3.11+ |
| Git | Any recent version |
| Strategic Domain | Claude Desktop (or equivalent frontier LLM with MCP support) |
| MCP servers | Filesystem and mcp-grep configured in the Strategic Domain tool |
govwatch | pip install -r ai/src/requirements-govwatch.txt — required for governance monitoring TUI |
| Python MCP SDK | pip install -r ai/ael/requirements.txt — required for AEL orchestrator |
ael-mcp | Optional — Claude Desktop AEL interface; clone from https://github.com/William12556/ael-mcp; requires mcp Python package |
Apple Silicon + MLX
Required for the MLX inference backend (Tactical Domain on Apple Silicon).
| Item | Requirement |
|---|---|
| Chip | Apple M-series (M1 or later) |
| Unified memory | 24 GB minimum (Q8); 48 GB+ for BF16 |
mlx_lm | 0.21+ — required dependency of oMLX (pip install mlx_lm) |
omlx | Required inference server (pip install omlx) |
| Model | Devstral Small 2 (2512) Q8 |
Devstral Small 2 is the required Tactical Domain model. It is purpose-built for agentic coding and multi-file editing. The AEL parser (parser.py) is tuned to Mistral's tool-call format, which Devstral uses natively.
Full setup instructions: Apple Silicon + MLX Setup Guide
Getting Started
Prerequisites
- MCP servers: Filesystem and mcp-grep configured in your Strategic Domain tool
- Git and GitHub Desktop (or equivalent)
- Tooling per selected implementation profile (see
framework/ai/profiles/)
Initialization
- Copy
skel/to the desired parent directory and rename it to your project name - Select an implementation profile from
skel/ai/profiles/and follow its setup instructions - Ask your Strategic Domain model to read
ai/governance.mdand initialize the project per P01 (§1.2 Project Initialization) - Begin with P00 (Governance) and follow the workflow flowchart in section 2.0
Implementation Profiles
| Profile | Tactical Domain | AEL |
|---|---|---|
claude.md | Claude Code (optional) | Manual — human invokes per task |
mlx_devstral_small_2_2512_Q8.md | MLX + Devstral Small 2 2512 (primary) | AEL / Ralph Loop |
Important Notice
This framework is experimental, serving as a learning exercise in prompt engineering, AI-assisted development workflows, and protocol-driven project management. Actual fitness for purpose is not guaranteed.
References
HUNTLEY, G., 2026. Everything is a ralph loop [online]. Available from: https://ghuntley.com/loop/ [Accessed 4 March 2026].
[1] FACTORY.AI, 2025. The Context Window Problem: Scaling Agents Beyond Token Limits [online]. Available from: https://factory.ai/news/context-window-problem [Accessed 20 March 2026].
[2] REDIS, 2026. LLM context windows: what they are & how they work [online]. Available from: https://redis.io/blog/llm-context-windows/ [Accessed 20 March 2026].
Version History
| Version | Date | Description |
|---|---|---|
| 1.0 | 2026-03-04 | Initial README; repository restructured to framework/ and skel/ |
| 1.1 | 2026-03-04 | Added Ralph Loop / Geoffrey Huntley attribution to Overview, AEL description, and References section |
| 1.2 | 2026-03-04 | Renamed ai/implementation-profiles/ → ai/profiles/; renamed profile-*.md files to claude-desktop.md, claude.md, ollama.md |
| 1.3 | 2026-03-05 | Expanded Repository Structure to reflect actual directory contents; removed duplicate Ralph Loop attribution from Overview; added framework/ai/doc/examples/ entry |
| 1.4 | 2026-03-05 | Added Requirements section; created docs/ directory with setup guides for Goose, Apple Silicon + MLX, and OLLama + LM Studio |
| 1.5 | 2026-03-05 | Added omlx as optional Apple Silicon + MLX requirement for TTL-based memory management |
| 1.6 | 2026-03-06 | Added mlx.md to Implementation Profiles table |
| 1.7 | 2026-03-06 | Promoted oMLX to required inference server; updated mlx_lm to dependency role |
| 1.8 | 2026-03-11 | Replaced Goose with Python AEL orchestrator; updated repository structure, requirements, and implementation profiles table |
| 1.9 | 2026-03-11 | Narrowed scope to Apple Silicon + MLX; deprecated Goose, OLLama, and LM Studio docs and profiles; moved to deprecated/ |
| 2.0 | 2026-03-12 | Added Devstral Small 2 (2512) as supported model in Requirements |
| 2.1 | 2026-03-20 | Added motivation paragraph to Purpose; added references [1] and [2] |
| 2.2 | 2026-03-20 | Extended motivation paragraph with workflow rationale |
| 2.3 | 2026-03-26 | Revised Repository Structure: removed stale framework/ai/doc/examples/ and framework/ai/knowledge/ entries; added dev/, dev/requirements/, dev/design/, docs/claude/; updated skel/ description; added docs/ subdirectory entries |
| 2.4 | 2026-03-27 | Replaced Overview and Key Characteristics with Governance and Orchestration sections; Orchestration covers AEL/Ralph Loop, orchestrator.py modes, config.yaml, state directory, and invocation |
| 2.5 | 2026-03-31 | Added Devstral model rationale note to Apple Silicon + MLX Requirements |
| 2.6 | 2026-03-31 | Updated Implementation Profiles table; deprecated mlx_devstral_small_2507_Q8.md; reinstated claude.md as optional Claude Code profile; updated model-agnostic architecture bullet |
| 2.7 | 2026-04-28 | Added ael-mcp: Orchestration subsection (Option A/B launch table) and Requirements row |
| 2.8 | 2026-05-20 | Added agent characterisation to Orchestration; added bounded autonomy rationale to Purpose; corrected copyright year |
| 2.9 | 2026-05-20 | Added link to RATIONALE.md in Purpose section |
| 3.0 | 2026-06-02 | Added Audit Loop subsection; added --duration flag and CLI flags table to Orchestration; updated Repository Structure with new guide documents |
| 3.1 | 2026-06-10 | Added govwatch subsection; added govwatch entries to Repository Structure and Requirements |
Copyright (c) 2026 William Watson. MIT License.