Introduction

MoAI-ADK is an Agentic Development Kit that wraps Claude Code around three things: cost (tokenomics), self-improvement (agentic loop engineering), and quality control (agentic harness). It delivers the same quality of code for fewer tokens. Declare a completion condition and the loop works on its own, and the observations piled up along the way become raw material for harness learning. “Done” is judged by evidence, through the SPEC 3-phase lifecycle and the TRUST 5 gates. Model selection, reasoning depth, and context usage are all managed by the system. It is written in Go and ships as a single binary, so it runs immediately with no dependencies.

This page introduces what MoAI-ADK is and why it is shaped the way it is, in one flow. It covers which problem each of the three pillars answers, where terms like SPEC · TRUST 5 stand inside that picture, and where to go when starting out. Installation and running your first project are left to the Installation and Quick Start pages — here we focus on the “why.”

In this documentation, a code block’s prefix indicates the execution environment:

• Commands you type in the Claude Code chat

  bash Copy

  > /moai plan "feature description"

• Commands you type in the terminal

  bash Copy

  $ moai init my-project

MoAI-ADK is an Agentic Development Kit that wraps Claude Code around three pillars — cost · self-improvement · quality control. Push only one and the others collapse. Cut only cost and quality turns harsh; raise only quality gates and the same mistakes repeat every session; run only autonomous loops and a single billing run burns through your limit. The three pillars hold each other up.

The same quality for fewer tokens. Cost is decided not by unit price but by model choice — in the DeepSWE benchmark, Opus at its lowest reasoning outscored Sonnet at its highest while costing one sixteenth as much. The session-level model policy · prompt caching · Token Circuit Breaker put the budget under the system’s management.

The harness gets smarter the more it runs. Declare a completion condition and the loop works on its own (/moai goal · /moai loop), while observations pile up into rules so the next session does not repeat the same mistakes.

“Done” is judged by evidence. The SPEC 3-phase lifecycle + TRUST 5 gates + worktree isolation block rework (the biggest token waste), and planning is separated from auditing so the one who built it never inspects it.

Each pillar is covered in detail in the Core Concepts section.

• /moai goal — declare a completion condition in one line and the session runs autonomously.
• Factory Mode — runs multiple sessions at once.
• BAS Navigator — auto-syncs the 3-tier codemap.
• manager-lead — coordinates large-scale work: Tier L milestone fan-out inside a SPEC, plus factory leader-session dispatch.
• multi-model audit — cross-validates with multiple models to catch bias.
• autonomy tier — dials the autonomy level so things run safely.
• session model policy — one choice sets the session’s default reasoning effort; subagents inherit the session’s model and effort.

MoAI-ADK follows the SPEC-based TDD/DDD methodology and guarantees code quality with the TRUST 5 quality framework.

A SPEC (Specification) is “keeping your conversation with the AI as a document.”

The biggest problem with vibe coding is context loss:

• An hour of discussion with the AI disappears when the session drops
• To continue the next day, you have to explain everything from scratch
• The more complex the feature, the more the result diverges from your intent

A SPEC solves this problem:

• Saves requirements as files for permanent preservation
• Even if the session drops, reading the SPEC is enough to resume work
• Defines things clearly and without ambiguity in the EARS format
• No repeated explanations, so tokens are saved too

Info

One-line summary: the “JWT auth + 1-hour expiry + refresh token” you discussed with the AI yesterday does not need re-explaining today — start implementation right away with the single line /moai run SPEC-AUTH-001!

One of two implementation methodologies is assigned automatically based on the project state, and the result is verified against a shared set of quality criteria.

Info

MoAI-ADK v2.5.0+ picks exactly one of TDD and DDD. The hybrid mode was removed for clarity and consistency. The methodology is chosen automatically at moai init and can be changed in development_mode in .moai/config/sections/quality.yaml.

MoAI-ADK fully rewrote the Python Edition in Go to maximize performance and efficiency.

• 13 agent catalog (12 MoAI-custom + 1 Anthropic built-in Explore)
• 31 skills (template-managed)
• 36 terminal CLI commands · 16 /moai slash subcommands
• 16 programming languages supported
• A codebase developed on the basis of 543 SPEC documents

Requirements:

• Git must be installed on all platforms
• Windows users: WSL (Windows Subsystem for Linux) is recommended for the smoothest experience

The MoAI orchestrator does not implement directly; it delegates work to 13 specialized agents. Planning and auditing are separated — the one who made it does not inspect it.

The goal is to pull quality as high as possible within your plan’s usage limits. On long-horizon agentic work a weaker model burns more steps and the per-task cost actually rises — so the lever is reasoning depth inside the same model, not a weaker model class. Since v3.2, the model and effort are decided at the session level: subagents inherit the main session’s model and effort, agent definitions declare neither, and the profile’s Session model policy (moai profile setup) sets the default reasoning effort used when none is chosen.

Info

The retired --model-policy / --profile flags are deprecated stubs: they print a warning pointing at moai profile setup and do nothing. Set the session’s effort as you go with /effort or ultrathink; the model with /model. Details: Model Policy.

Natural-language requests go through Analyze-First routing. Whatever language you request in, intent is analyzed first and connected to the right workflow. Depending on task complexity, the orchestrator chooses sequential sub-agents (default), parallel sub-agent fan-out, or dynamic workflows.

/moai run SPEC-AUTH-001           # complexity-based auto selection
/moai run SPEC-AUTH-001 --solo    # force sequential sub-agents

Info

v3.0 change: the former Agent Teams static-orchestration layer was retired. Forcing --team falls back to sub-agent mode. CG is retired; use moai migrate cg to preview explicit migration choices.

MoAI-ADK follows a 3-phase development workflow. The run-phase methodology is selected automatically based on the project state:

flowchart TD
    A["Phase 1: SPEC
/moai plan"] -->|"Define requirements in EARS format"| B{"Methodology selection"}
    B -->|"New project (TDD)"| C["Phase 2: TDD
/moai run"]
    B -->|"Existing project (DDD)"| D["Phase 2: DDD
/moai run"]
    C -->|"RED → GREEN → REFACTOR"| E["Phase 3: Docs
/moai sync"]
    D -->|"ANALYZE → PRESERVE → IMPROVE"| E
    E -->|"Documentation and deployment"| F["Done"]

    style C fill:#4CAF50,color:#fff
    style D fill:#2196F3,color:#fff

Declare a completion condition and the loop works on its own:

/moai goal "until all tests pass and lint is clean"   # condition-declared loop
/moai loop                                            # diagnostic-based iterative fix (loop_prevention default 100)
/moai fix                                             # single-pass auto-fix

/moai loop is a preset on top of the goal engine. It keeps fixing until the issue queue found by the diagnostic tools is drained.

Two separate settings bound iteration at two separate layers. workflow.loop_prevention.max_iterations (default 100) is the per-task diagnostic-fix loop limit, while workflow.agentic_loop.max_iterations (default 10) is the completion-loop ceiling over the whole pipeline. They are distinct settings, so different values are normal, not a contradiction.

New feature development:

/moai plan → /moai run SPEC-XXX → /moai sync SPEC-XXX

Bug fixing:

/moai fix (or /moai loop) → /moai review → /moai sync

Refactoring:

/moai plan → /moai clean → /moai run SPEC-XXX → /moai review → /moai codemaps

Documentation updates:

/moai codemaps → /moai sync

MoAI-ADK supports the following 4 languages:

• Korean
• English
• Japanese
• Chinese

Choose your preferred language in the installation wizard, or change it directly in the config file.

LSP (Language Server Protocol) is a standard communication protocol between code editors and language tools. It detects code errors, type errors, and lint results in real time and reports them immediately.

Ralph-Loop Style is an autonomous workflow that uses LSP diagnostics as a feedback loop. When a quality issue is detected, it automatically invokes a fix agent and iterates until the quality criteria are met.

MoAI-ADK’s Ralph-Loop Style LSP integration works like this:

• LSP-based completion auto-detection: monitors code quality state in real time
• Real-time regression detection: immediately detects the impact of changes on existing functionality
• Automatic completion condition: automatically marks work complete at 0 errors, 0 type errors, and 85% coverage

Info

Ralph-Loop Style LSP integration automates the quality gates of the development workflow, keeping code quality high without a person touching it each time.

It exits with a migration diagnostic without starting Claude or GLM. It is not an alias for moai cc. Projects with llm.team_mode: cg must make an explicit migration choice before launching a session. CG retirement and migration CG is retired; use moai migrate cg to preview explicit migration choices.

This writes llm.team_mode: claude, llm.gateway.teammate_mode: in-process, and llm.gateway.teammate_provider: inherit. It removes the old hybrid role assignment; it does not preserve a Claude leader with GLM teammate panes.

The claude-glm target describes a Claude leader with GLM teammates in tmux. Its apply and launch paths are currently unavailable because the TEAMMATE integration gate has not passed. Preview is available. Installing tmux or setting verified: true does not open this gate.

Info

A practical tool for self-improvement (agentic loop engineering): declare a completion condition and the session works on its own until it is met. /moai goal "<condition>" is a condition-declared autonomous loop, /moai loop keeps fixing until the issue queue found by LSP diagnostics · AST-grep · linters is drained (pipeline completion loop, default 10 — agentic_loop.max_iterations), and /moai fix is a single-pass auto-fix. The observations the loop leaves behind — user corrections, failure patterns, routing decisions — accumulate into harness guidance along the 4-tier learning ladder (observation → heuristic → rule → auto-update, under the user-approval gate). That is why the next session does not repeat the previous session’s mistakes.

To start with MoAI-ADK, follow this order:

1. Installation - Install MoAI-ADK on your system
2. Initial Setup - Run the interactive setup wizard
3. Quick Start - Create your first project
4. Core Concepts - Understand MoAI-ADK in depth

• GitHub repository
• Documentation site
• GitHub Issues

Learn how to install MoAI-ADK in the Installation guide.