MoAI-ADK: A Verification Harness That Wraps Claude Code in SPECs and Quality Gates

The Problem: A Session That Forgets What It Spent

The README states the premise in a single quoted line: the model is a stochastic worker moving token by token, and it cannot remember turn to turn what it used, whether the result is good, or how far the last session got. The harness is meant to enforce all three from the outside. That framing tells you what MoAI-ADK is not. It is not a better model and it is not an editor. It is an orchestration layer that sits between you and Claude Code, and its job is to make the output of an agentic coding run checkable rather than merely plausible. The target reader is an engineer already using Claude Code on work that spans more than one sitting: a feature that needs a written plan, an implementation pass, and a review before it lands. If your tasks are single-file edits that finish inside one prompt, the harness has nothing to enforce. The project describes itself as verification-driven, and the vocabulary it uses (SPEC, TRUST 5, plan/run/sync) is the substance of the claim. Apache-2.0 licensed, single Go binary, no dependencies.

Kanban Mode: Four Terminals, One Card, Three Columns

The central mechanism in v3.1 is Kanban Mode. The README explains the motivation concretely: a session holds one context window, and a long SPEC fills it. Everything that follows carries everything before it, so the plan you no longer need is still in the window while you review, and the review is still there while you write docs. The usual escape is `/clear`, which discards the thread along with the ballast. Kanban Mode splits one unit of work across four terminals instead of one. A lead session drives the chain. Three companion sessions each own a single column, `plan`, `run` or `sync`, and carry only that column's context. Review is not a separate column: the sync gate absorbs it and runs the review lenses itself to reach the verdict. The README is explicit that nothing is uncapped. Each session still has its own limit. What changes is that no session carries three phases of history, so the same budget goes further and a finished phase is cleared without losing the card. The board has five columns, `backlog → plan → run → sync → done`, and `backlog` has no owning session by design, so work enters only when you put it there with `/moai todo "fix the stale rename hint"` to append or `/moai todo` to list the queue. One rule stands out as a design stance: the lead advances a card only on evidence it read from the card's `progress.md`, never on a companion's reply, because a reply is a claim and inter-session delivery is not guaranteed. That is the most interesting decision in the whole system.

Model and Effort Routing Per Column

Each column can run a different backend and effort level. The README gives one worked example: Plan on Opus 5 at high effort, Run on GLM 5.2 at xhigh, and Sync on GLM 5.2, on the reasoning that the depth of reasoning a column needs is not the same in every column. When you open a kanban run, a bootstrap notice carries a default recommendation weighted toward token availability: lead on `moai glm -k`, plan on `moai cc -k --name plan`, run on `moai glm -k --name run`, sync on `moai cc -k --name sync`. The stated logic is that plan and sync turn on judgment and review, so they sit on Claude, while run is implementation-heavy and GLM keeps its cost down. The lead is not the seat that renders verdicts, it watches the queue and moves cards, so a cheap model that can wait fits it. When a Claude verdict is needed under a GLM lead, the documented escape is a session named `judge`, described as the only route by which the GLM lead uses Claude. The README also notes that when one account starts hitting 429s, spreading lanes across accounts is the workable move. It then says plainly that this mix is only the default, and a different combination or unifying every session on one backend is equally fine. Treat the recommendation as a starting point, not a constraint.

Getting a Run Started

The launch surface is small. For Kanban Mode, the lead is `moai cc -k`, which announces a run-id and seeds the chain. Companions are launched by hand, one per terminal: `moai cc -k --name plan`, `moai cc -k --name run`, `moai cc -k --name sync`. The README is clear that a session never spawns a peer, so you open the terminals yourself. Companions are named by their bare role. The run-id stays the lead session's identifier and never rides a companion name, and a second live session claiming the same role takes the next free number. Swapping `moai cc` for `moai glm` on any column puts just that column on the GLM backend. Factory Mode is the second form, opened with `-f`. Where a kanban card hops between columns, a factory card goes whole to one lane and that lane carries it through `plan → run → sync` serially in-session, each phase spawned as an `Agent()` subagent. Lanes are labelled `lane-1` through `lane-N`. The commands are `moai cc -f` for a lead with one lane, `moai cc -f 4` for four lanes, `moai cc -f lane-1` for a lane in its own terminal, and `moai glm -f lane-3` for a lane on GLM. A lane runs up to 10 concurrent `Agent()` subagents, and write-capable spawns are isolated in their own worktree. Two constraints are worth memorising before you type anything: `-k` with `-f` is an error because one launch takes one entry token, and `moai cg` refuses factory mode.

Where the Harness Stops Helping

The limitations are mostly structural rather than bugs, and the README states several of them without softening. Companion sessions must be launched by hand, one per terminal. There is no supervisor that brings up the chain for you, so a four-terminal Kanban run is four manual launches and four windows to keep alive. The board's honesty rule cuts the other way too: the lead trusts `progress.md` and not the companion's reply, which means a companion that fails to write progress leaves the card stuck regardless of what it actually accomplished. Factory Mode carries an explicit warning: never bring every lane up at once. Start the first, confirm it is actually producing output, then activate the rest. That is an operational instruction, and it implies the failure mode is real. Lane numbers are recorded in `.moai/state/factory/workers.json`, and that file is described as where stale claims get cleared, so a crashed lane can leave a claim you have to clean by hand. The `-f lane-<n>` form already names the lane, so passing `--name` or `-n` alongside it is an error, which is a sharp edge if you are used to the kanban flags. Finally, the material does not describe what TRUST 5 actually checks, only that the gates exist and that sync runs review lenses to reach a verdict. Until you read the gate definitions, you cannot know whether they match your team's standards.

How This Differs From Running Claude Code Directly

The obvious alternative is Claude Code on its own, and the difference is not features, it is where the state lives. A plain session keeps plan, implementation and review in one context window, and the only tool for reclaiming that window is `/clear`, which drops the thread. MoAI-ADK moves the state out of the window and onto disk, into a card with a `progress.md`, and then splits the phases into sessions that each read only what their column needs. The lead's advance decision is evidence-based rather than conversational. That is a real architectural difference, and it is also the cost: you are now running a multi-process system with a state directory, a lead that can stall on missing evidence, and a lane registry that needs occasional manual clearing. A second alternative worth naming is a conventional CI pipeline with human review. That approach also enforces gates, but it enforces them after the code is written, whereas MoAI-ADK puts the gate inside the agent loop at the sync column, before the card reaches done. If your review already happens in a pull request and you are happy with that, the sync gate duplicates work you are doing anyway. If your problem is that the agent's output is not reviewable in the first place, the in-loop gate is the part that matters.

Licence, Maintenance and Upgrade Cost

The project is Apache-2.0, which permits commercial use, modification and redistribution provided you keep the licence and notice files and state significant changes. That is a permissive arrangement, and it is the same licence family most Go tooling ships under. Nothing in the supplied material indicates a dual licence, a contributor licence agreement, or a paid tier, so the usual Apache-2.0 obligations apply and nothing more. This is not legal advice; if you are embedding the binary in a product, have your own counsel read the licence text. On maintenance, the release cadence visible in the material is fast: v3.1.0 on 2026-08-15, v3.1.1 on 2026-08-20, v3.1.2 on 2026-08-21, and the README badge references v3.1.3. The last push to the repository is dated 2026-09-10. Three releases inside a week during a minor version bump tells you the surface is still moving, and the README itself frames v3.1 as a change in the shape of a run, not a patch. Plan for the possibility that flags and state file layouts shift between minor versions. The Go requirement is 1.26 or later, which is a newer toolchain than many teams are running, so a build from source may require a Go upgrade before it requires anything else.

Editorial conclusion

Adopt MoAI-ADK if you already run Claude Code on multi-phase work and want the plan, implementation and review phases separated into sessions that each carry only their own context. Skip it if your tasks fit in one context window, because the four-terminal Kanban setup adds coordination cost that a single session does not have. Before committing, verify three things yourself: that `moai cc -k` starts and announces a run-id on your machine, that the TRUST 5 gate definitions match the checks your team actually enforces, and that `.moai/state/factory/workers.json` behaves as documented when a lane dies mid-run.

Official sources

1. License: Apache-2.0
2. modu-ai/moai-adk on GitHub
3. Project website
4. README
5. Releases