master-workflow

Multi-agent orchestration loop: worker → cross-model reviewer → score ≥ 9.

An AI agent orchestration framework that runs a deterministic build-review loop across multiple LLM backends. You define the goal and acceptance criteria; the harness spawns a fresh worker agent, captures the real git diff, hands it to a different model running read-only, and loops until an independent reviewer scores the work 9/10 or higher.

Ships as an MCP server, an agent skill, and a plain CLI.

                    ┌──────────────── harness (deterministic) ────────────────┐
you ─▶ orchestrator ─▶ brief ─▶ worker CLI ─▶ git diff ─▶ reviewer ─▶ score ≥ 9?
        (your agent)     ▲       fresh ctx     (not the    (other model,   │ no
                         │                      summary)    read-only)     │
                         └──────── findings folded into a new brief ◀───────┘

Features

• Cross-model code review — the reviewer is never the worker; a different backend grades every diff in a clean, read-only context

• Deterministic loop — the control flow is code, not a prompt that promises to loop; every iteration is auditable

• Five backends — Codex, Grok, Claude, OpenCode, and Kimi, with advisory routing based on task type

• Git-native verification — the reviewer reads the actual diff from git, never the worker's summary

• Fresh context per iteration — each worker spawns clean; findings from the previous round become requirements in the next brief

• Sandbox enforcement — OS-level read-only sandboxes where available (Codex, Grok), with PTY-verified enforcement for Grok

• Full audit trail — every run leaves a filesystem ledger: briefs, diffs, event streams, scores, and verdicts

• Session search — fold decisions from past agent sessions (any backend) into the worker brief

Why it is shaped like this

The reviewer is never the worker. A model grading its own diff scores it far too generously, and your orchestrator's context already wants the task to be finished. The reviewer runs on a different backend, in a clean context, with writes disabled. It is the only thing that can end the loop.

The reviewer reads the diff, never the summary. A worker's final message is the least reliable artifact it produces. The harness takes the diff from git itself and puts that in front of the reviewer.

Every iteration spawns a fresh worker. A context that already argued for a failed attempt tends to defend it; a clean one reads the reviewer's findings as requirements. Everything the worker needs travels in the brief, which is why the brief is the thing worth designing. (carry_session: true opts out.)

Verify, don't trust. Grok's --sandbox silently does nothing when there is no TTY — the Landlock profile fails to apply, the run continues unconfined, and the command still exits 0. The vendored wrapper supplies a PTY and then verifies enforcement after the fact, reporting NOT ENFORCED rather than letting an unconfined run pass as a sandboxed one.

Requirements

• Python 3.10+

• At least two agent CLIs installed (one to work, one to review)

• Git

Installation

git clone https://github.com/luckeyfaraday/master-workflow
cd master-workflow
python3 -m venv .venv && .venv/bin/pip install -e ".[mcp]"
.venv/bin/master-workflow status

backend    installed  review-sandbox  version
codex      yes        os-enforced     codex-cli 0.145.0
grok       yes        os-enforced     grok 0.2.112
claude     yes        tool-denied     2.1.220 (Claude Code)
opencode   yes        none            0.0.0-dev
kimi       yes        none            kimi, version 1.49.0

review-sandbox is how a reviewer's writes are suppressed. os-enforced means the sandbox blocks them (codex -s read-only, grok --sandbox read-only) while the reviewer can still run the tests — the best kind. tool-denied means the editing tools are denied by name but nothing stops a shell command; Claude Code's --allowedTools is additive, not exclusive, so it cannot be used to lock a reviewer down. none means don't review with it. The harness prefers os-enforced reviewers automatically.

As an MCP server

claude mcp add --scope user master-workflow -- /path/to/master-workflow/.venv/bin/master-workflow-mcp

As an agent skill

ln -s "$PWD/skills/master-workflow" ~/.claude/skills/master-workflow

Then just talk to your agent:

Use master-workflow to add rate limiting to the API. Send it to Codex, have Claude review it, and don't stop until it's a 9.

Backend routing

Suggestions, not rules — your explicit choice always wins.

master-workflow suggest "<task>" scores a task against these and explains the route it picks.

CLI usage

master-workflow run \
  --goal "Add a /health endpoint that reports DB connectivity" \
  --criteria "Returns 200 with {status,db} when reachable, 503 when not. Has a test. Existing tests still pass." \
  --cwd ~/code/api \
  --backend codex --reviewer claude \
  --threshold 9 --max-iterations 4

run_id=20260728-141902-add-a-health-endpoint
worker=codex reviewer=claude threshold=9.0

iteration 1  worker=codex  reviewer=claude  score=6.0/9.0
verdict: Endpoint works but the failure path is untested and swallows the error.
  - `except Exception: return {"db": "down"}` at health.py:24 hides the real error
  - No test covers the 503 branch
-> continue: score 6.0 < 9.0; 2 findings to fix

iteration 2  worker=codex  reviewer=claude  score=9.0/9.0
verdict: Meets every criterion; failure path tested and the error is surfaced.
-> stop: score 9.0 >= 9.0

status=passed best_score=9.0 — score 9.0 >= 9.0

Other commands: status, suggest, iterate <run_id>, list, show <run_id>, ledger <run_id>, search <query>.

MCP tools

Context from your own history

Workers start clean, so anything they need has to travel in the brief. When the goal depends on a decision made in an earlier session — with any agent — search_sessions finds it and the orchestrator folds it into context_notes before the first worker spawns.

master-workflow search "why we dropped the redis cache" --agent codex

Requires sessions-search on PATH. Optional — everything else works without it.

Run artifacts

Everything writes to one layout, so resume works uniformly and the audit log is just the filesystem:

~/.master-workflow/runs/<run_id>/
    run.json                  full state, rewritten on every transition
    ledger.jsonl              append-only event log
    iterations/01/worker/     brief.md prompt.md events.jsonl last_message.txt
                              session_id diff.patch sandbox stderr.log
    iterations/01/review/     brief.md last_message.txt review.json

Override the root with MASTER_WORKFLOW_HOME.

Scoring rubric

The reviewer is calibrated to be hard to please:

A review that fails to emit its JSON verdict is capped below threshold — an unparsed review can never end the loop on its own.

Related projects

Consolidates ideas from codex-router, delegate-to-grok, delegate-to-opencode, frontier-orchestrator, athena-loops, athena-graphs, multi-loops, and sessions-search. The Grok PTY sandbox wrapper is vendored from delegate-to-grok.

License

MIT