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.

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

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 ai/state/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:

For configuration, invocation, audit loop, govwatch, and ael-mcp detail, see docs/guide-orchestration.md.

Required for the MLX inference backend (Tactical Domain on Apple Silicon).

Full setup instructions: Apple Silicon + MLX Setup Guide

Two installation paths are provided. See docs/guide-install.md for full detail.

Bootstraps the ai/ framework into a project without cloning the repository. Always installs the latest release.

curl -fsSL https://raw.githubusercontent.com/William12556/LLM-Governance-and-Orchestration/main/bin/bootstrap.sh | bash -s -- <project-path>

Review ai/ael/config.yaml in the target project before first use.

For developing or extending the framework.

git clone https://github.com/William12556/LLM-Governance-and-Orchestration.git

After changes to ai/, propagate to a downstream project:

bin/propagate.sh <project-root>

To publish a release:

bin/release.sh <version>

• MCP servers: Filesystem and mcp-ripgrep configured in your Strategic Domain tool
• Git and GitHub Desktop (or equivalent)
• Tooling per selected implementation profile (see ai/profiles/)

1. Install the framework into the project using either path above
2. Select an implementation profile from ai/profiles/ and follow its setup instructions
3. Ask your Strategic Domain model to read ai/governance.md and initialize the project per P01 (§1.2 Project Initialization)
4. Begin with P00 (Governance) and follow the workflow flowchart in section 2.0

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.

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].

Copyright (c) 2026 William Watson. MIT License.