MoAI-ADK: AI Development Kit for Claude Code

---

"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

Term	One-line definition
card	One unit of work. Enters via /moai todo, addressed by a short id
column	One stage of the board — five columns in fixed order
backlog	The entrance queue. No owning session, so only a human can add work
lane	The session+worktree pair that carries one card to the end. One parallel work stream
lead	The coordinating session. Advances cards only on evidence it read; never writes code itself
companion	The session seated in a column doing the work. Launched by hand, one per terminal
run-id	Short identifier the lead announces at start. It names the lead session; companions never carry it
worktree	The card's isolated checkout. The directory carries the card id; the branch carries what the card did (WT-<slug>). One carries the card from run through sync
dispatch	The instruction the lead sends a companion — a pointer to the work, never a copy

Full glossary with definitions and examples: Kanban board terms

Watching the board

moai web serves a local console. The Kanban screen shows the kanban chain alongside the SPEC pipeline, plus Overview, Specs, Monitor, Settings, and Todo screens.

Full guide: Kanban Mode · manager-lead Lead Coordinator · /moai todo

What v3.1.1 adds

Kanban Mode aside, here is what else landed in v3.1.1. Each one is covered in full in its own section further down.

Home directory hygiene. The longer you use it, the more leftovers from past runs pile up in ~/.moai. moai clean --home clears them out, staying inside an allowlist — it is a dry run by default, so it shows you what would go before anything goes, and actual deletion needs --force. How old something has to be before it is swept is set by state.home_retention_days (30 days by default, 0 turns it off). To see how far the directory has grown right now, moai doctor reports it under Home Disk Usage. The home path itself can be moved with the MOAI_HOME environment variable — it takes absolute paths only. Only Go processes read it, though: move the path and the statusline and the shell hooks still look under $HOME/.moai. Shell-side credentials like .env.glm and the statusline's data stay behind, and your state quietly splits in two.

Cross-session messaging settings. Whether a message from another Claude Code session arrives directly, waits for approval, or is refused outright is decided in crosssession.yaml. The switch that requires approval before a message leaves this machine lives there too.

Statusline GitLab support. statusline.forge picks whether open work is counted on GitHub or on GitLab. Left empty, it decides from the origin remote's host.

A bare /loop becomes the kanban foreman. Typing /loop with no arguments starts a cycle that watches the backlog queue, dispatches the next card the operator has already marked picked to an isolated worker, confirms completion from evidence it read rather than from a claim, and reports. Nobody is watching that seat, so both putting cards in the queue and picking them stay the operator's job — the foreman never picks, it only carries.

---

Why moai-adk?

The age of agents writing code has arrived, but you cannot take an agent's output on faith. Whether "the tests passed" is the result of actually running the tests or just the agent's guess has been the central problem from the start. moai-adk begins exactly there — it bans unverified completion claims at the system level and binds every completion claim to the command actually run and its output as evidence.

moai-adk is a harness that wraps Claude Code from the outside. It does not replace Claude Code; it takes over, in structure, the parts you used to manage by hand — which model to use, how deeply to reason, how to verify results, how to resume when a session breaks, how to keep parallel runs from stepping on each other. Verification integrity, the SPEC lifecycle, autonomous execution with real boundaries, a living codebase navigator, a self-improvement loop, and parallel-safe structure. These six form the identity of moai-adk.

This identity organizes into three keys: cost (tokenomics — the same quality for fewer tokens), self-improvement (agentic loop engineering — turning observation into rules so the harness gets better as it runs), and quality control (the SPEC lifecycle, TRUST 5 gates, and isolation that prevents rework). No one of them suffices alone — below, why each needs the others.

Eight differentiators

Differentiator	What it means
No false verification	A claim that "tests pass" is always bound to the command actually run and its output. The system forbids presenting an unrun check as a success — verification-claim integrity is bound into every agent and orchestrator surface.
Autonomy with real boundaries	Declare a completion condition with /moai goal and the session works on its own until it holds. Four hard boundaries are attached — a turn limit (default 30), a stagnation guard, a wall-clock budget, and pre-approval gates — so it cannot fall into an infinite loop.
Parallel-safe	Every SPEC gets its own working tree, a branch-state guard blocks accidental branch switches in the primary checkout, and the gap against the remote is checked before spawning write agents. Two write-capable agents never run at the same time.
Long-horizon continuity	Work survives /clear. Progress stays in progress.md, handoff messages in memory, routing decisions in decision memory. The next session starts from what the last one learned, not from bare ground.
Cost-efficient	Models and reasoning depth are assigned declaratively, matched to work phase and SPEC size. CG mode (Claude leader + GLM workers) cuts 60–70% of cost on implementation-heavy work. Prompt caches are reused and long output is spilled to disk to keep the context light.
Equal support for 16 programming languages	Go, Python, TypeScript, JavaScript, Rust, Java, Kotlin, C#, Ruby, PHP, Elixir, C++, Scala, R, Flutter, Swift — sixteen programming languages handled as one set via marker-based auto-detection. None receives preferential treatment.
Self-improving	Recurring failure patterns observed in the wild rise as proposed rule changes. Nothing is applied silently — approval comes first. Routing decisions and gate evidence accumulate in decision memory as material for the next run.
Native-language friendly	Korean, Japanese, Chinese, and English locales are maintained in the same PR, translationese is banned, and each language gets its own native prose. Users are never forced into English.

What's different

	Claude Code alone	Typical harness	moai-adk
Evidence binding of completion claims	You check by hand	Usually absent	Enforced by the system (5-section evidence report format)
SPEC lifecycle	None	Limited	plan→run→sync 3-phase + Tier S/M/L
Hard boundaries on autonomous loops	N/A	Usually a turn cap only	Turn limit + stagnation guard + wall clock + approval gate
Parallel work isolation	Manual	Limited	worktree + branch guard + pre-spawn sync check
Session continuity	Broken by /clear	Limited	handoff + memory + progress files
Equal treatment of 16 programming languages	N/A	N/A	marker auto-detection + per-language toolchains
Self-improvement loop	None	Limited	failure observation → rule promotion (approval-gated)

flowchart TD
    User["User request"] --> Analyze["Intent analysis<br/>Analyze-First routing"]
    Analyze --> Plan["plan — SPEC authoring"]
    Plan --> Audit["Independent audit<br/>plan-auditor"]
    Audit --> Run["run — TDD/DDD implementation"]
    Run --> Verify["trust-but-verify<br/>verification batch"]
    Verify --> Sync["sync — docs + PR"]
    Sync --> Learn["Decision memory + lessons"]
    Learn -.next session.-> Analyze

The three keys hold each other up

Push the cost key alone and quality silently erodes — rework and debug loops follow, and rework is the most expensive token spend of all. Build quality gates with no learning loop and the same mistakes recur every session. Run an autonomous loop with no cost ceiling and a single runaway task drains the quota. The three keys hold each other up — cost stays economical because quality prevents rework, quality stays enforceable because the loop captures what worked, and the loop stays affordable because cost gates stop it before overage.

Every design decision serves one of these three keys. Which model to use, how deeply to reason, how to spend context — none of it is left to chance turn by turn. The system decides, and records the decision so the next run is smarter.

Cost is determined by assignment, not unit price

Token prices fell 98% over three years (Linux Foundation), yet enterprise AI spend rose 320% in the same window. Volume growth overwhelmed the price drop. Agents spin through dozens to hundreds of steps to solve a single task, burning tokens proportionally. In usage-based pricing this becomes the invoice; in subscription, it eats the weekly quota shared by every model.

Uber deployed Claude Code to 5,000 engineers and burned through a year of coding budget in four months, then imposed monthly token limits. Meta, Amazon, and Microsoft each walked back unlimited-AI policies. Tokenomics — matching the model to the task to raise token efficiency — became the tech industry's new baseline.

Traditional cost control was built for rising unit prices, so it is helpless against this paradox: prices falling while total spend climbs. The bottleneck is not unit price but volume — more precisely, the step count an agent spins before finishing.

The DeepSWE leaderboard (113 tasks, per-effort view) demonstrates this. Within the same Claude family, per-task cost tracks how efficiently a model finishes — not what a token costs.

Model [effort]	Score	Per-task cost	Note
opus-5 [low]	58%±2	$1.66
opus-5 [medium]	69%±1	$3.29	value-for-money knee
opus-5 [high]	73%±2	$6.08	+4pt score, 1.8× cost
opus-5 [xhigh]	73%±3	$9.07	net loss — ties high, +49% cost only
opus-5 [max]	74%±4	$11.84
glm-5.2 [max]	44%±2	$3.92	API-metered disadvantage · valuable under z.ai flat-fee
sonnet-5 [max]	54%±4	$26.40	Pareto-dominated by opus-5 [low]

Opus 5 at its lowest effort scores higher than Sonnet 5 at its highest (58% vs 54%) while costing one-sixteenth as much per task ($1.66 vs $26.40) — even though Sonnet's per-token price is lower. The cause is 268 steps against 36: retry loops, not token rates, write the invoice. Cost is determined by assigning the right model and reasoning depth to each task, not by unit price.

Source: DeepSWE v1.1 leaderboard (datacurve.ai, 113 tasks, 2026-07-25)

---

Quick Start

Install

macOS / Linux / WSL

curl -fsSL https://adk.mo.ai.kr/install.sh | bash

Windows (PowerShell 7.x+)

irm https://adk.mo.ai.kr/install.ps1 | iex

Build from source (Go 1.26+)

git clone https://github.com/modu-ai/moai-adk.git
cd moai-adk && make build

Already installed? Run moai update to move to the latest version. From v3.1.1, before moai update wipes a template-managed directory and redeploys it, it first moves any unmanaged file sitting inside to .moai-backups/<timestamp>/pre-clean/. If that backup fails it stops right there instead of going on to delete — a file you put there yourself is not quietly swept away by a redeploy.

💡 To cut costs — z.ai GLM recommended: signing up via this link grants bonus tokens. The link is also a way to sponsor moai-adk open-source development. Free models (GLM-4.7-Flash, GLM-4.5-Flash) exist too — see the z.ai pricing.

Project initialization

moai init my-project
cd my-project

The interactive wizard auto-detects language, framework, and methodology, walks you through model policy, and generates the Claude Code integration files.

First workflow

claude        # or moai cc — run Claude Code inside the project

/moai plan "Add JWT login"      # author a SPEC
/moai run SPEC-AUTH-001         # TDD/DDD implementation
/moai sync SPEC-AUTH-001        # sync docs + create PR

Natural language works too. /moai "fix the login bug" triggers intent analysis (Analyze-First routing) to read the request and route to the appropriate workflow.

Requirements

Platform	Supported environments	Notes
macOS	Terminal, iTerm2	Full support
Linux	Bash, Zsh	Full support
Windows	WSL (recommended), PowerShell 7.x+	Native cmd.exe unsupported

• Git — required on all platforms
• Claude Code — moai-adk is a harness for Claude Code
• Recommended: gh CLI (PR automation), tmux (CG mode), your language's lint/test toolchain (e.g. golangci-lint)

---

Core Capabilities

One entry point: /moai

Natural language and 16 subcommands feed the same pipeline. /moai plan, /moai run, /moai sync are the backbone of the SPEC pipeline; goal, loop, fix, review, gate, clean, codemaps, e2e, mx, feedback, project, harness, and todo fill out the surroundings.

Four retired subcommands — design · brain · coverage · security. What security did is now covered by the moai-ref-owasp-checklist + moai-ref-llm-security skills.

MCP server

moai init provisions exactly one active MCP entry by default — the self-hosted moai mcp-server (a local stdio server). It exposes 21 MoAI tools in six groups to Claude Code. Four documented-but-disabled entries (context7, chrome-devtools, playwright, ast-grep) are activated via moai mcp add <name>. The moai mcp add|remove|list CLI manages entries via an atomic-RWM seam — users never hand-edit .mcp.json.

Group	Tools	Purpose
SPEC lifecycle	spec_progress, spec_audit, spec_drift	Era classification + drift detection
Verification	verify_snapshot, verify_trend	Per-key evidence snapshots
Goal + session	goal_arm, goal_status, session_list	Autonomous loop + multi-session coordination
Cross-model audit	audit_multi, codex_audit, glm_audit, audit_cache	Multi-auditor convergence
Codex delegation	codex_task, codex_setup, codex_job_*	Background cross-model jobs
GLM delegation	glm_task, glm_job_status, glm_job_result, glm_job_cancel	GLM (z.ai) background job delegation

All backends are fail-open — GLM (~/.moai/.env.glm) and codex (~/.codex/auth.json) are optional; an unavailable backend returns inconclusive, never a hard error.

In the dual harness (moai init --agent codex|both), Codex supports only built-in identifier arrays for its status line (tui.status_line), so MoAI-specific items (goal, todo, SPEC state) cannot be displayed — a limitation until openai/codex#17827 lands command-backed status lines.

Details: MCP Server Guide · Claude Code MCP

Goal engine — an autonomous loop with real boundaries

Declare a completion condition and the session works on its own until it holds. A turn limit, a stagnation guard, a wall-clock budget, and pre-approval gates are attached, so it cannot fall into an infinite loop. Mechanical conditions (a command's exit code) and model conditions (a claim in the transcript) are both supported. --max-turns 0 arms an auto-compact-driven infinite goal — in that case --max-duration and the stagnation guard provide the boundary.

Parallel worktrees

Every SPEC gets its own working tree. Enter with moai cc -w <name>; add --spawn to open it in a new window while keeping the current session. A branch-state guard blocks accidental branch switches in the primary checkout.

Kanban mode

--kanban (short -k) is a session-launcher switch — under the lead session's coordination it drives a single SPEC through plan → run → sync with multi-session board coordination. The board's backbone is the Origin-Trail Chain: an append-only JSONL lineage tree that tracks worktree ancestry, solves depth amnesia (root-to-leaf chain recovery after /clear), and detects dead leader sessions via heartbeat staleness.

Concept	What it does
Origin-Trail Chain	Append-only JSONL event stream at .moai/state/chain/events.jsonl
WorktreeNode (13 fields)	Per-session state: ID, parent, depth, origin chain, milestone, resume target
CWD-collision resolution	(worktree_path, session_id) pair disambiguates reused paths
Depth ceiling	Caps nesting complexity

Available now: moai cc -k (or moai glm -k) starts the lead and -k --name <role> joins each companion — launched by hand, one per terminal. moai chain <status|lineage|back|list|prune> reads the lineage, and moai todo (bare invocation lists the queue; subcommands add · list · next · done · unpick · drop · undrop · edit · move; two or more words become a new card) operates the backlog column. The launch sequence is in the "What's New in v3.1 — Kanban Mode" section above.

Details: Kanban Mode Guide

CG mode — Claude leader + GLM workers

Claude owns strategy, planning, and audits; GLM carries bulk implementation. The two are wired through tmux session-level environment isolation, cutting 60–70% of cost on implementation-heavy work.

Equal support for 16 programming languages

Go, Python, TypeScript, JavaScript, Rust, Java, Kotlin, C#, Ruby, PHP, Elixir, C++, Scala, R, Flutter, Swift. Marker-based auto-detection runs each language's standard lint/format/test toolchain.

Automated quality gates

TRUST 5 (Tested · Readable · Unified · Secured · Trackable) applies to every change. /moai gate runs lint + format + type + tests in one pass, and sync-auditor scores across four dimensions: functionality, security, craft, and consistency.

@MX tags

Inline code annotations that let AI agents exchange context, invariants, and danger zones. Only high-fan-in, complex, or dangerous code gets marked.

Navigator — a living codebase map

@NAV:DEC, @NAV:SYM, and @MX:SPEC bind into one addressable graph (nav-graph.json). Design decisions, SPECs, and code symbols link in both directions — fix the code and the decision's context follows.

Session handoff

Work survives /clear. A 6-block paste-ready resume message carries progress into the next session; in auto-inject mode, one message resumes the session.

loop / fix — error-driven development

/moai loop sweeps LSP diagnostics, AST-grep, and linters in parallel, buckets issues by level, and runs until the queue drains. /moai fix is the single-pass variant.

review --deep

/moai review --deep runs a multi-agent adversarial vulnerability scan, backed by OWASP · LLM-security · supply-chain · DevSecOps reference skills.

4-locale documentation

Korean, Japanese, Chinese, and English docs are maintained in the same PR. Translationese is banned, each language gets native prose, and a 4-locale parity check is bound into the build gate.

moai web console

moai web opens a console bound to localhost. Six screens — Overview, Kanban, Specs, Monitor, Settings, Todo; the settings screen splits into eleven tabs: Identity, Language, LLM, 3rd Party LLM, Workflow, Git & Worktree, Audit, Agents, Report, MCP, Cross-Session. Profile create/rename/delete lives on the same screen.

ref / domain skills

Eleven ref skills (moai-ref-api-patterns, moai-ref-owasp-checklist, moai-ref-llm-security, moai-ref-react-patterns, moai-ref-testing-pyramid, moai-ref-ui-polish, moai-ref-secops, moai-ref-supply-chain, moai-ref-seo, moai-ref-git-workflow, moai-ref-cross-model-audit) and seven domain skills (moai-domain-backend, moai-domain-frontend, moai-domain-database, moai-domain-design-dna, moai-domain-html-report, moai-domain-humanize, moai-domain-svg-infographic) inject field knowledge into agents.

Cross-platform

A single Go binary with no extra dependencies, running on macOS, Linux, and Windows. The hook system enforces gates mechanically, and the statusline surfaces cost and context in real time.

---

How It Works

The SPEC 3-phase lifecycle

All work flows through plan → run → sync. Tier S/M/L size classification determines verification depth and PR routing. GEARS-format requirements and acceptance criteria judge completion by evidence.

flowchart TD
    P["plan — SPEC authoring<br/>GEARS requirements + acceptance criteria"] --> PA["plan-auditor<br/>independent audit (bias prevention)"]
    PA -->|PASS| R["run — TDD / DDD implementation<br/>cycle_type auto-selected"]
    PA -->|DEBT| P
    R --> SA["sync-auditor<br/>4-dimension quality scoring"]
    SA -->|PASS| S["sync — doc sync + PR"]
    SA -->|DEBT| R
    S --> MX["@MX tags + Navigator update"]

Project state picks the methodology. moai init reads coverage and chooses automatically.

flowchart TD
    A["Project analysis"] --> B{"New project or<br/>10%+ coverage?"}
    B -->|"Yes"| C["TDD (default)"]
    B -->|"No"| D["DDD"]
    C --> F["RED → GREEN → REFACTOR"]
    D --> G["ANALYZE → PRESERVE → IMPROVE"]

Methodology	Cycle	Target
TDD (default)	RED → GREEN → REFACTOR	New projects and feature work
DDD	ANALYZE → PRESERVE → IMPROVE	Existing code under 10% coverage

The 12-agent catalog

Category	Agent	Cost	Role
Manager	manager-spec	🔴	Plan-phase SPEC authoring
	manager-develop	🔴	Run-phase TDD/DDD/autofix implementation
	manager-docs	🔵	Sync-phase documentation
	manager-git	🩵	PR creation and routing
	manager-design	🟠	Design-phase collaboration (Claude Design)
	manager-lead	🔴	Hierarchical-team Tier L coordination + kanban/factory lead-session dispatch (sole Agent-carrier, depth-2 sealed)
Evaluator	plan-auditor	🔴	Independent plan audit (bias prevention)
	sync-auditor	🔴	4-dimensional quality scoring (Functionality 40 · Security 25 · Craft 20 · Consistency 15)
Builder	builder-harness	🟠	Project-specific agents, skills, commands, hooks scaffolding
Advisor	super-advisor	🔵	On-demand high-reasoning consultation (E1-E4 escalation)
Specialist	e2e-tester	🟠	Web/mobile/desktop E2E test execution (CLI-first)
Built-in	Explore	⚪	Read-only codebase exploration

Cost colors follow the default medium profile's model×effort cells (inspect via moai model profile): 🔴 opus+high · 🟠 opus+medium · 🔵 opus+low · 🩵 sonnet+low · ⚪ session-model inherit (user-added agents). Assignments shift when switching profiles (high/low). Authoring and auditing are separated from the start, so the writing side never grades its own work.

Eleven of the twelve are agents moai-adk built; Explore is a built-in that already ships with Claude Code. Explore carries no model of its own — it inherits the session model — so it has no profile cell. That is why the catalog counts 12 while the model profile section further down counts 11 × 3 = 33 cells: the two numbers are not in conflict, they count different things.

trust-but-verify — binding evidence to completion claims

When an agent reports "tests passed", the orchestrator does not take the claim at face value; it runs its own verification batch. Seven read-only verifications (tests, coverage, subagent boundaries, sentinel scans, CLI smoke, benchmarks, lint) run in parallel in a single turn, leaving each one's exit code and output as evidence.

The verification-claim integrity rule backs this flow — you must not present an unrun check as a success, must not pass off a previously measured value as a fresh measurement, and must not wave through what was never observed. The 5-section report format (Claim · Evidence · Baseline attribution · Gaps · Residual risk) binds every completion report from every agent and orchestrator.

Trim verification cost, stop before overage

Verification is necessary; verification output sitting in context is not. Verbose output spills to disk files, leaving only the exit code and a bounded tail (max 50 lines) in context. Prompt-cache reuse (cached reads cost 0.1×) keeps the window light, and a context-diet /clear strategy issues recommendations at the thresholds (1M 50% / 200K 90%).

On the budget side, a token circuit breaker stands guard — it aborts at the hard limit (default 90%), saves progress to progress.md, and issues a paste-ready resume message. The statusline keeps context usage, cache hit rate, and rate-limit depletion visible at all times, so an overage never passes unnoticed.

Reading the statusline

🤖 Opus | 🧠 xhigh·t | ♻️ 87% | 🔅 v2.1.212 | 🗿 v3.1.2 | ⏳ 2h 34m | 💬 MoAI
🪫 CW: ████████░░ 88% (⚠️/clear) | 🔋 5H: ████░░░░░░ 45% (4h 30m) | 🪫 7D: ████████░░ 82% (Jan 21)
📁 moai-adk-go | 📡 modu-ai/moai-adk, 7/3 | 🅱️ [WT] release/v3.1.2 +3 | 💾 +1 M2 ?0 | 📋 [run SPEC-AUTH-001-run] | 💌 PR #1042 (⌥approved)
🏷️ run | 👤 manager-develop | 🔄 TODO: 1/3

Element	Meaning
🤖 Model	Current active model
🧠 effort	Reasoning effort — ·t suffix when extended reasoning is active
♻️ Cache hit rate	Prompt cache hit rate
CW: Context	Context-window usage + 2-stage /clear markers (⚠️ soft, 🛑 hard)
5H / 7D	Plan usage rate + reset time
📁 Directory	Project directory name
📡 Repo	GitHub repo owner/name + open issues/PRs pair (, 7/3, or , -/- when unreadable)
🅱️ Branch	Current branch — [WT] marks a worktree, + is the dirty count (modified+staged+untracked)
💾 git status	Staged + · modified M · untracked ? counts — one 💾 icon in every state
📋 Task	Active SPEC workflow [command SPEC-ID-phase]
💌 PR	Active GitHub PR number + review state (⌥state)
🏷️ Session line	Conditional last line — session name · 👤 agent · 🔄 TODO: in progress/queued backlog

Details: Statusline Guide

---

Workflow Examples

Build a new feature (TDD)

/moai plan "Add user profile image upload"
/moai run SPEC-PROFILE-001
/moai sync SPEC-PROFILE-001

New code, or code with sufficient coverage, gets TDD (RED → GREEN → REFACTOR). moai init detects project state and picks between TDD and DDD.

Run long jobs (goal)

/moai plan "Refactor the payment module"
/moai run SPEC-PAY-001
/moai goal "go test ./... exits 0 && lint clean, or stop after 20 turns"

Declare the completion condition and the session works on its own until it holds. The turn limit defaults to 30 and the stagnation guard is attached. When context reaches the threshold (1M 50% / 200K 90%), it recommends /clear and saves progress to progress.md.

Run in parallel (worktree)

moai cc -w feature-auth        # open the auth working tree
moai cc -w feature-billing --spawn   # billing in a new window, current session kept

# inside the auth tree
/moai run SPEC-AUTH-001

# inside the billing tree
/moai run SPEC-BILL-001

Each SPEC gets its own working tree so two agents never step on each other. The branch-state guard blocks accidental branch switches in the primary checkout.

Cut costs (CG mode)

moai glm sk-your-glm-api-key   # save the key once
moai cg                        # enter CG mode (Claude leader + GLM workers)

/moai run SPEC-DATA-001        # implementation-heavy work → GLM workers carry the bulk

CG mode puts a Claude leader over strategy, planning, and audits while GLM workers carry bulk implementation — a 60–70% cost cut on implementation-heavy work. The harness, SPEC workflow, and quality gates behave identically across all three modes.

Auto-fix bugs (loop)

/moai loop

Sweeps LSP diagnostics, AST-grep, and linters in parallel, buckets issues by level, and runs until the queue drains. Single issues end in one /moai fix pass.

---

Configuration and Profiles

.moai/config/sections/

Project configuration splits into YAML section files. moai init lays down 33 sections in all; the six below are the ones you end up editing.

Section	Role
language.yaml	User name · conversation language · code-comment language · commit-message language
quality.yaml	Quality gates · dev mode (TDD/DDD) · coverage
harness.yaml	Harness depth (minimal · standard · thorough) · auto-detection
workflow.yaml	Workflow behavior
lsp.yaml	LSP gate thresholds (SSOT)
user.yaml	User information

v3.1.1 adds four more sections worth touching.

Section	Role
crosssession.yaml	How cross-session messages are handled. inbound (empty, accept, hold, refuse), isolate_machines (whether a message leaving this machine needs approval), dialog_expiry (the deadline on the approval dialog for a held message)
cache.yaml	The prompt cache settings file. It holds session_ttl (1h, 5m, off), spec_ttl, and the smallest chunk worth caching, and round-trips through the moai web settings editor. Nothing currently reads these values, so changing them does not change behavior
state.yaml	home_retention_days — how old something has to be before moai clean --home sweeps it. Read from the HOME tier only (~/.moai/config/sections/state.yaml); 30 days by default, and 0 turns home cleanup off
statusline.yaml	A forge key joins the existing