Git-Native Agent Orchestration: A Stateless Maker-Checker Pattern

This guide introduces a drop-in architectural pattern for teams building multi-agent AI systems. It utilizes native Git features to orchestrate a stateless, collision-free Maker-Checker loop without relying on complex Python frameworks, external databases, or heavy memory management.

The Problem with Current Agent Frameworks

When building autonomous Maker-Checker loops (e.g., a Developer Agent writing code and a Reviewer Agent testing it), engineers often encounter three major friction points:

1. State Management: Passing large chunks of code, architectural plans, or evaluation feedback back and forth via JSON payloads or database entries is bulky and prone to token-limit failures.
2. Workspace Pollution: Agents operating in the same directory overwrite each other's files, trigger race conditions, or cause file-lock crashes.
3. PR Noise: Trial-and-error AI commits clutter the remote repository, making human code review a nightmare.

The Git-Native Solution

This workflow entirely eliminates those issues by treating the Git database itself as the state machine. The Orchestrator is reduced to a "dumb" trigger, while the agents manage the state autonomously using the following mechanisms:

• Git Worktrees: Agents are physically isolated in ephemeral sibling directories (foo-wt/maker and foo-wt/checker), completely preventing file collisions while sharing the same underlying .git repository.
• Context-Aware Agents: Agents are not hardcoded with static prompts. Instead, their first action upon waking up is to execute git branch --show-current. They dynamically parse their branch name scheme to determine their role, phase, and task context.
• Agent-Driven Handoffs via Git Notes: Instead of communicating via an API, the agents leave prompts for each other directly on the commits. The Maker creates a commit and uses git notes add to request a review. The Checker evaluates the code and uses git notes append to attach its Markdown feedback. Neither agent ever overwrites history.
• Auto-Generated Transcripts & Memory: Before squash merging, the Orchestrator dumps the complete git notes history into a Markdown transcript (history-XXX.md) and saves it to an isolated root branch (devlog). This auto-generates a perfect "AI thought process" engineering blog draft without polluting the production codebase.
• Squash Merging: Only the final, Checker-approved iteration is squash-merged into the integration branch, resulting in a pristine Pull Request for human reviewers.

Want the raw files? If you just want to drop this into your own project, you can download the original ORCHESTRATION.md from my GitHub Gist. For the full architectural deep dive, read on.

---

The Architecture: Multi-Agent Orchestration Workflow (Maker-Checker)

This outlines the workflow architecture for the multi-agent system. The core engine of this system relies entirely on a Maker-Checker pattern to iteratively generate, evaluate, and refine artifacts—ranging from software code to design specifications and whitepapers.

(Note on Terminology: In this document, foo represents your actual repository name. XXX represents a URL-friendly task identifier, exactly like the branch names GitHub automatically generates from issue titles—e.g., 123-add-auth.)

1. Core Principles

• General Purpose: This workflow applies to any text-based artifact (Code, Markdown, JSON, etc.).
• Physical Isolation: Agents operate in strictly isolated file systems using Git Worktrees.
• Autonomous State Machine: The Orchestrator is a "dumb" trigger. The agents themselves drive the state machine by passing prompts and feedback to each other exclusively through git notes.
• The Golden Rule of Notes:
  • The Maker creates new commits and exclusively uses git notes add to attach review requests.
  • The Checker never creates commits; it exclusively uses git notes append to add feedback to the Maker's commit. Neither agent ever overwrites history.
• Read-Only Checker: The Checker agent strictly evaluates work. It may execute tests and append git notes, but it must never modify project files or create standard commits.
• Context-Aware Agents: Agents determine their exact role, phase, and task dynamically upon initialization by executing git branch --show-current.
• Agnostic Orchestrator: The "Orchestrator" does not need to be a complex AI framework. It can be a simple Bash script, a CI/CD pipeline, or even a human developer manually typing Git commands in the terminal. Its only job is to trigger the agents and manage the final merge.

2. Infrastructure & Environment

To prevent file-lock collisions and environment drift, the repository is split into the Orchestrator context and active Worktree sandboxes.

Directory Structure

workspace/
├── foo-wt/                  # Ephemeral worktree sandboxes
│   ├── feature/             # The integration baseline
│   ├── maker/               # Maker's workspace
│   └── checker/             # Checker's workspace
└── foo/                     # Main Orchestrator repository
    ├── .git/                # Shared Git repository
    └── ORCHESTRATION.md     # This file

3. Branching & Push Strategy

For every new task or document generation (XXX), the Orchestrator manages a strict branching lifecycle. Strict remote isolation is enforced to prevent repository pollution.

Branch	Worktree	Remote Policy	Purpose
feature/XXX	foo-wt/feature/	Pushed	The integration branch. Pushed to remote for final PR review.
devlog	N/A	Pushed	Isolated root branch. Acts as the permanent knowledge base for AI plans.
maker/XXX	foo-wt/maker/	Never Pushed	Branched from feature or devlog. Contains the Maker's raw, messy iterative commits.
checker/XXX	foo-wt/checker/	Never Pushed	Branched from feature or devlog. The Checker pulls the Maker's commits here to run evaluations safely.

4. The Workflow Execution Loop

The Maker and Checker never communicate directly via API or memory. They pass code forward via Git commits and pass execution prompts backward and forward via git notes.

To prevent agent hallucination and ensure strict context, every prompt written to a git note must explicitly reference the exact commit hash it applies to (e.g., [REVIEW] Evaluate commit 7a8b9c0).

The Step-by-Step Handoff Protocol

1. The Anchor (Orchestrator): The Orchestrator creates an empty commit on maker/XXX and adds a git note containing the initial, completely stateless task prompt. (Example: git notes add -m "[TASK] Add a /health endpoint to server.js returning 200 OK"). Notice there is no complex persona or framework context—just the raw task.
2. Maker Iteration: The Maker reads the note on HEAD, writes code, and creates Commit A. The Maker then runs git notes add on Commit A, tagging it with a [REVIEW] prompt asking the Checker to evaluate it (e.g., [REVIEW] Evaluate commit 7a8b9c0).
3. Checker Iteration: The Checker reads the note on Commit A, evaluates the code, and runs git notes append on Commit A with its feedback, tagging it with a [REVISE] prompt for the Maker to fix the identified issues (e.g., [REVISE] Fix null pointer in commit 7a8b9c0).
4. The Loop Continues: The Maker reads the updated note on Commit A, fixes the code, creates Commit B, and executes a new git notes add review request.
5. Approval: Once the Checker's evaluation passes, it appends an [APPROVED] note. The Orchestrator sees this, generates the transcript, and squash merges the branch.

Max Iterations Guardrail
To prevent infinite loops, the Orchestrator enforces a strict limit (e.g., 5 iterations). If the Maker fails to achieve Checker approval within this limit, the loop aborts and escalates to a human.

5. Merging & Feedback Storage Rules

To maintain a pristine project history while simultaneously preserving the AI's "thought process" for documentation, strict rules are enforced.

Rule 1: Transcript Generation (For Engineering Blogs)
Before the Orchestrator merges the Maker's code into production, it compiles the complete AI conversation history. To prevent polluting the production codebase, this transcript is always saved directly to the isolated devlog knowledge-base branch.

Because every prompt, Maker commit, and Checker critique is stored in the Git notes, the Orchestrator simply dumps this into a Markdown transcript:

# 1. Generate the transcript from the Maker's branch
git log maker/XXX --show-notes --pretty=format:"### Commit: %h%n**Maker:** %B%n%N%n---" > history-XXX.md

# 2. Save it exclusively to the devlog branch
git checkout devlog
mv history-XXX.md transcripts/
git add transcripts/history-XXX.md
git commit -m "docs: save iteration transcript for task XXX"

# 3. Return to the target branch to merge the actual code
git checkout feature/XXX

Rule 2: Squash Merging Only
Once the transcript is safely committed to devlog, the Orchestrator must squash merge the actual code from maker/XXX into the target integration branch (typically feature/XXX) using git merge --squash maker/XXX. This condenses dozens of broken, AI-generated trial-and-error commits into a single, clean commit for human reviewers.

6. Cleanup Guardrails

Upon successful PR creation or plan approval, the Orchestrator enforces strict teardown:

1. (If applicable) Destroy the Maker and Checker containerized environments.
2. Execute git worktree remove for both sandbox directories.
3. Delete local maker/XXX and checker/XXX branches.

7. Agent System Instructions

Because the system runs entirely through Git state, the Orchestrator does not generate complex prompts. Instead, the AI agents are configured with the following baseline system instructions regarding how they interact with the Git database:

Maker Agent System Prompt

"When triggered, run git notes show HEAD to read your current instructions. If it is a new task, write the code. If it is Checker feedback, fix the code. Once your work is done, you must create a standard git commit. Then, you must run git notes add -m '[REVIEW] <your review request>' HEAD to attach a prompt for the Checker to evaluate your new commit."

Checker Agent System Prompt

"When triggered, run git merge maker/XXX to pull the Maker's latest commit into your workspace. Run git notes show HEAD to read the Maker's review request. Run tests and evaluate the code. You must never create a new commit. Instead, you must run git notes append -m '[REVISE] <your feedback>' HEAD to attach your feedback to the Maker's commit. If the code is perfect, append [APPROVED]."

8. Advanced Pattern: Plan & Execute (Optional)

For complex tasks, large language models perform significantly better when planning is separated from execution. The Orchestrator can utilize a two-phase "Plan & Execute" pattern using an isolated knowledge-base branch.

The devlog Knowledge Base
Instead of storing AI plans in the main branch, a dedicated isolated root branch named devlog is maintained. This acts as the long-term memory for the AI system. Plans are generated here by the Maker and Checker, and the resulting transcripts/history-XXX.md acts as a perfectly formatted draft for an engineering blog post detailing how the system designed the feature.

Standardizing Plans with Frontmatter
To ensure plans are machine-readable, the Maker agent is instructed to include standard YAML frontmatter at the top of every plan-XXX.md file.

Example plan-XXX.md format:

---
title: "Implement OAuth2 Authentication"
task_id: "123-add-oauth"
date: 2026-03-16
---

Phase 1: The Planning Phase
The Orchestrator initiates the Maker-Checker loop targeting the devlog branch. The Orchestrator's anchor commit note tells the Maker: "Draft the architecture plan for task XXX." The loop runs until the Checker appends [APPROVED]. The Orchestrator generates the transcript and squash merges into devlog.

Phase 2: The Execution Phase
The Orchestrator initiates a second Maker-Checker loop, this time targeting the feature/XXX branch. The Orchestrator reads the approved plans/plan-XXX.md from devlog and attaches it to the empty anchor commit as the Maker's instructions. The loop runs until [APPROVED], ending in a clean feature PR.

---

Origin Story: Grafana Hackathon 16

This Git-native architecture wasn't born in a vacuum—it evolved from real developer friction.

During Grafana Hackathon 16, I was heavily experimenting with autonomous AI agent coding. I quickly ran into the pain points of managing state and passing files between multiple agents. To fix this on the fly, I intuitively built a two-agent feedback loop. It wasn't until later, while reading up on AI architecture, that I realized I had naturally arrived at the industry-standard Maker-Checker pattern.

However, while the pattern worked, the underlying plumbing was still messy. After the hackathon, reflecting on the friction of file-locks and state management, the "Git-Native" concept finally clicked. I realized we didn't need to build complex ways to pass files between agents—Git was already the perfect, battle-tested state machine for the job.

A massive thank you to Grafana for consistently providing access to the latest AI technologies and models. Furthermore, the hackathon itself provided the perfect dedicated space to experiment with new ideas. That freedom to just "build and break things" is exactly what made this architecture possible.

What's Next: Executable Skills & Battle Testing

This orchestration document is just the foundation. Over the coming weeks, I am taking this theoretical architecture and battle-testing it inside a live, production-scale project.

Once the pattern is fully refined under real-world conditions, I will be publishing Git-Native Agent Skills (utilizing the new Anthropic SKILL.md format) in a dedicated, full GitHub repository.

These drop-in skills will allow CLI agents like Claude Code to natively understand and execute this exact Maker-Checker Git loop with zero extra framework configuration.

(This article was originally published on my blog at codecommis.hashnode.dev)

Follow me on GitHub to get notified when the official repository and executable skills drop!