AI Workgroup Orchestrator: A Deterministic Control Plane for Multi-Agent Coding

AI Workgroup Orchestrator: A Deterministic Control Plane for Multi-Agent Coding

This open-source project (maintained by sun9bear, hosted on GitHub, released on 2026-06-16) acts as a local-first orchestration layer to enhance collaboration reliability between AI coding assistants like Codex and Claude Code. Key features include:

• SQLite-based ledger for tasks, checkpoints, audits, and gatekeeping
• Explicit safety gates with default conservative settings
• Dry-run priority workflow to preview actions

Its core design shifts coordination from chat memory to deterministic contracts, enabling predictable, auditable, and rollbackable AI collaboration.

Project Background

With the popularization of AI coding tools (GitHub Copilot, Claude Code, Codex, etc.), developers face a problem: these tools have distinct context windows, memory methods, and execution strategies, leading to chaotic collaboration that relies on manual human intervention. AI Workgroup Orchestrator was created to solve this—it is not a new coding assistant but a control plane to coordinate multiple AI tools, making their collaboration predictable and auditable.

Core Philosophy: Determinism Over Smartness

The project prioritizes determinism over pure AI "smartness". It assumes AI assistants may err or conflict, so it uses:

• Versioned workflows and role contracts (clear responsibilities, permissions, input/output formats)
• SQLite-backed state management (persistent records instead of volatile chat context)
• Machine-readable state coordination

Safety Model: Default Conservative

Default settings block risky operations:

• allow_write=false, allow_real_agents=false, allow_push=false, allow_merge=false, allow_deploy=false All changes require explicit authorization. The MCP server only exposes read-only tools (state queries, task lists, event history).

Technical Architecture

The project uses a layered structure:

1. Python CLI (aiwg/): Core functions (config parsing, task scheduling, state management) with commands like doctor checks and task queries.
2. Test Suite: Test-driven hardening (red tests first to prove unsafe behavior, then minimal green implementation, plus regression tests).
3. Docs: Detailed guides, workflow examples, and protocol topology.
4. Config (aiwg.yaml): Strict YAML validation for safety switches (rejects ambiguous values like "false" strings or 0).

Dry-Run First Workflow

Before allowing write operations to protected repositories, the system executes a dry-run to simulate impacts. The Git Steward component plans worktree changes, commits, PRs, and reviews—letting developers preview results before execution. This mirrors IaC best practices (e.g., Terraform's execution plan) to make AI actions verifiable.

Strict Development Process

The project enforces a 9-step workflow for contributors:

1. Planning (design docs)
2. Red tests (prove unsafe behavior)
3. Minimal implementation
4. Regression tests
5. Full test suite run
6. Doctor check (config/environment health)
7. MCP surface check (tool interface compliance)
8. Boundary scan (protected repo access)
9. Update docs

This process ensures reliability for code-modifying tools.

Limitations & Future

• Not an out-of-box autonomous coding system (it's a control plane foundation).
• Needs community input for AI assistant integrations, strategy optimizations, and workflow templates.
• Requires learning cost—value grows as teams deepen their understanding of AI collaboration.

The project aims to evolve with community contributions.

Conclusion

AI Workgroup Orchestrator balances AI convenience with system control. It emphasizes reliability through clear design, strict boundaries, and auditable processes instead of blind trust in AI models. For teams exploring multi-AI coding collaboration, it is a valuable reference implementation.