moai-adk

"The model is a stochastic worker moving token by token. It cannot remember, turn to turn, what it used this turn and how much, whether the result is good, or how far the last session got. A harness enforces all three from the outside."

What's New in v3.1 — Kanban Mode

v3.1 ships on August 15, Liberation Day in Korea. The intent: release work from the old shape of a single session bound to one context limit. The limit itself does not disappear — what actually changes is written down below.

A session holds one context window, and a long SPEC fills it. Everything that comes after carries everything that came before: 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 throws away 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, sync — and carry only that column's context. Review is not a separate column: the sync gate absorbs it, running the review lenses itself to reach the verdict. Nothing is uncapped: each session still has its own limit. What changes is that no session carries three phases' worth of history, so the same budget goes considerably further, and a finished phase is cleared without losing the card.

Each column can run a different backend and effort level. The run above puts Plan on Opus 5 at high effort, Run on GLM 5.2 at xhigh, and Sync on GLM 5.2 — the depth of reasoning a column needs is not the same in every column.

Getting started

moai cc -k                    # lead — announces a run-id, seeds the chain
moai cc -k --name plan        # companion, in its own terminal
moai cc -k --name run
moai cc -k --name sync

Companion sessions are launched by hand, one per terminal — a session never spawns a peer. Companions are named by their bare role: the run-id stays the lead session's identifier and never rides a companion name; a second live session claiming the same role takes the next free number. Swap moai cc for moai glm on any column to put just that column on the GLM backend.

Which backend goes where

When you open a kanban run, the bootstrap notice carries a default recommendation — token availability first: 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 reasoning is the kind of thinking each lane needs. Plan and sync turn on judgment and review, so they sit on Claude; run is implementation-heavy, so GLM keeps its cost down. The lead is not the seat that renders verdicts — it watches the queue and moves cards — so GLM, cheap to keep waiting, fits it. When a Claude verdict is needed under a GLM lead, escape through a session named judge — the only route by which the GLM lead uses Claude. When one account starts hitting 429s, spreading lanes across accounts is the workable move. This mix is only the default — a different combination, or unifying every session on one backend, is equally fine.

Factory Mode — many cards at once across N lanes

-f opens a factory lead, Kanban's second form. 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 Agent() subagents. Lanes are labelled lane-1 … lane-N.

moai cc -f                    # lead — one lane (lane-1) by default
moai cc -f 4                  # lead — four lanes
moai cc -f lane-1             # a lane, in its own terminal
moai glm -f lane-3            # …and one lane on the GLM backend

Grow a run one lane at a time with moai cc -f lane-<n>. That form already names the lane, so passing --name/-n alongside it is an error. A number is skipped only while a live session holds it — a dead lane's number is released and reused. Which numbers are held is recorded in .moai/state/factory/workers.json, and that is where stale claims get cleared. A lane runs up to 10 concurrent Agent() subagents, and write-capable spawns are isolated in their own worktree. Never bring every lane up at once — start the first, confirm it is actually producing output, then activate the rest. Cards are never split across lanes. -k still drives the three-role kanban chain; one launch takes one entry token, so -k with -f is an error, and moai cg refuses factory mode.

Details: Kanban mode — Factory Mode

The board has five columns, backlog → plan → run → sync → done. backlog has no owning session by design, so work enters the board only when you put it there:

/moai todo "fix the stale rename hint"   # append a card
/moai todo                               # list the queue

Two rules keep the board honest. 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. And when a phase ends, the lead asks for that session to be /clear-ed, since /clear is user-typed and cannot be sent as an instruction.

Words the four sessions share

The recurring vocabulary of the kanban docs, gathered into one picture. A column is a stage of the board; a lane is the pair of a session and its worktree that carries one card through those stages to the end — the difference between a stop and a route.

Operator ── /moai todo ──▶ backlog ─▶ plan ─▶ run ─▶ sync ─▶ done
                          (the lead advances a card only on evidence it read)

Lane — card t0:  run session + worktree t0      ┐ the two flows share one board,
Lane — card t1:  run session + worktree t1      ┘ run side by side, never mix

Full glossary with definitions and examples: Kanban board terms

Cards also differ in which columns they pass through, by shape. As a card leaves backlog, the lead classifies it into one of the three Card Classes and names the class in the dispatch.

Class A is admitted on checked evidence, not assertion — a card that cannot cite a diff measured to one file and green CI on the head that will merge is not Class A. Class B skips only plan; the sync gate's review still runs, and the cause-establishing evidence (reproduction command and its output) is left in the card's progress record.

Details: Kanban Mode — card classes

Watching the board

moai web serves a local console. The Kanban screen shows the kanban chain alongside the SPEC pipeline, plus Overview, Spe