/moai

The fully autonomous automation command. When the user provides a goal, MoAI autonomously runs the plan → run → sync pipeline.

Info

One-line summary: /moai is the “fully autonomous automation” command. You simply describe the feature you want in natural language, and MoAI performs the entire process automatically, from SPEC creation through implementation to documentation.

Platform basics

Background on the platform layer is in Session Management. This page is the MoAI-ADK account of it.

Info

Slash command support: all MoAI subcommands are wrapped as skills, so typing just /moai shows the list of available subcommands. Each subcommand can also be run directly in the form /moai:fix, /moai:loop, /moai:review, and so on.

/moai is MoAI-ADK’s fully autonomous automation workflow command. Without running sub-commands separately, the entire development process is automated with a single command:

1. SPEC creation (manager-spec)
2. DDD/TDD implementation (manager-develop — per development_mode in quality.yaml)
3. Doc synchronization (manager-docs)

Starting with v3, /moai’s default routing is Analyze-First — language-independent intent analysis. It classifies the meaning of the request rather than matching English keywords, so requests in any conversation_language are routed with the same quality.

Routing proceeds in this order:

1. Intent analysis: classify the intent of the user’s request (regardless of input language)
2. Context-sufficiency check: if insufficient, clarify through a Socratic interview
3. Execution-plan composition: choose the skill / agent / dynamic-workflow chain
4. Orchestration mode selection (Phase 4): autonomous selection from the 4-mode catalog (direct / serial / fanout / sweep; agent-team as an explicit-request experimental footnote)

That is, even typing plain natural language without a subcommand, like /moai "fix the login bug", is routed through intent analysis to the right workflow (the fix family for a fix, or the plan→run→sync pipeline for a new feature).

The default pipeline passes four named gates in order:

1. Plan-audit gate (plan-auditor): independently audits the SPEC plan artifacts — aborts on FAIL/INCONCLUSIVE
2. Implementation Kickoff Approval (plan→run human gate): exactly once per pipeline entry, always obtaining user approval regardless of score
3. Phase 4 mode selection (4-mode catalog): autonomous selection after Implementation Kickoff Approval, recorded in progress.md
4. Sync-audit gate (sync-auditor): evaluates the synchronization result across 4 dimensions — aborts the chain on FAIL/INCONCLUSIVE

# Basic usage
> /moai "description of the feature you want"

# With a branch
> /moai "feature description" --branch

# Enable loop mode
> /moai "feature description" --loop

# Resume an existing SPEC
> /moai --resume SPEC-AUTH-001

Automatically runs iterative fixing after implementation completes, fixing all errors:

> /moai "JWT authentication system" --loop

When you use this option:

1. SPEC creation
2. DDD implementation
3. Automatic loop execution (resolves LSP errors, test failures, coverage gaps)
4. Doc synchronization
5. PR creation

Info

The --loop option fully automates post-implementation cleanup, maximizing productivity.

Run without a flag and MoAI looks at the size of the work and auto-selects the orchestration mode. The modes form a 4-entry catalog (direct / serial / fanout / sweep) ordered by how many agents run concurrently:

Auto-selection criteria (when no flag is given):

• Affected domains >= 3 → fanout (parallel execution)
• Modified files >= 10 → fanout (parallel execution)
• Complexity score >= 7 → fanout (parallel execution)
• Otherwise → serial (sequential execution, default fallback)

Info

Agent Teams — re-allowed as experimental: Agent Teams, retired in v3.0.0, has been re-allowed as an experimental surface. An explicit --team request selects the native teammate runtime — there is no auto-selection. During the retirement era, forcing --team announced MODE_TEAM_UNAVAILABLE and fell back to sub-agent mode, and that sentinel survives as documented history. Tier L coordination belongs to manager-lead; parallel investigation belongs to fanout and sweep.

Parallel execution increases token usage because each agent uses an independent context window. For simple single-domain work, --solo (sequential) is more economical — which is why scale-based auto-selection is the default.

The full process /moai performs internally:

flowchart TD
    A["Run command
/moai 'feature description'"] --> B{--resume?}
    B -->|Yes| C["Load SPEC
continue work"]
    B -->|No| D["Phase 0
parallel exploration"]

    subgraph D["Phase 0: parallel exploration (15-30 s)"]
        D1["Explore subagent
codebase analysis"]
        D2["Research subagent
external docs research"]
        D3["Quality subagent
quality baseline check"]
    end

    D --> E{"Single domain?"}
    E -->|Yes| F["Delegate directly to
a specialist agent"]
    E -->|No| G["Continue to Phase 1"]

    C --> G["Phase 1
SPEC creation"]
    G --> H["Invoke manager-spec"]
    H --> I["Create EARS-format SPEC"]
    I --> J[".moai/specs/SPEC-XXX/spec.md"]

    J --> K["Phase 2
DDD implementation"]

    K --> L["Invoke manager-develop
DDD/TDD cycle (per quality.yaml)"]
    L --> M{"Implementation complete?"}
    M -->|No| L
    M -->|Yes| N{"--loop?"}

    N -->|Yes| O["Run automatic loop"]
    O --> P["Resolve all issues"]
    N -->|No| P

    P --> Q["Phase 3
doc synchronization"]

    Q --> R["Invoke manager-docs
generate docs"]
    R --> S{"--pr?"}
    S -->|Yes| T["Create PR"]
    S -->|No| U["Completion signal"]
    T --> U

Key points:

• Phase 0 (parallel exploration): three agents run at the same time for a 2-3x speedup
• Single-domain routing: simple work is delegated directly to a specialist agent, skipping the SPEC
• Completion signal: on completion, the completion report explicitly states the work is done

Three agents run simultaneously to quickly grasp the project context:

Speedup: parallel execution is 2-3x faster than sequential (15-30 s vs 45-90 s)

Single-domain routing:

• Single-domain work (e.g. “SQL optimization”): delegated directly to a specialist agent, no SPEC creation
• Multi-domain work: proceeds through the full workflow

The manager-spec subagent creates an EARS-format SPEC document:

• .moai/specs/SPEC-XXX/spec.md
• EARS-format requirements
• Given-When-Then acceptance criteria
• Content written in the conversation_language

The manager-develop subagent implements based on the SPEC:

• DDD cycle: ANALYZE-PRESERVE-IMPROVE (refactoring existing code)
• TDD cycle: RED-GREEN-REFACTOR (new feature development)
• Automatic domain-context injection (backend, frontend, security, database, etc.)

quality.yaml development_mode setting:

• development_mode: ddd → uses the DDD cycle (improving existing code)
• development_mode: tdd → uses the TDD cycle (new feature development, default)

Loop behavior (with –loop or when loop.enabled is true):

While issues exist AND iterations < maximum:
  1. Run diagnostics (LSP errors, test failures, coverage)
  2. Delegate fixes to manager-develop
  3. Verify the fix results
  4. Check whether the completion condition is met
  5. Exit the loop when the completion sentence is detected

The manager-docs subagent synchronizes the implementation and the docs:

• API doc generation
• README update
• CHANGELOG addition
• On success, explicitly states the work is complete

[HARD] The TodoWrite tool is mandatory: TodoWrite must be used for all work tracking

• On discovering an issue: TodoWrite (pending state)
• Before starting work: TodoWrite (in_progress state)
• After completing work: TodoWrite (completed state)
• Printing the TODO list as plain text is forbidden

When every workflow stage completes successfully, MoAI explicitly states completion in the completion report (banner/prose) to make the outcome unambiguous.

A core tokenomics device. Based on the llm.yaml setting, Claude and GLM are routed automatically per phase — enabling a hybrid where Claude handles strategy and planning while low-cost GLM handles bulk implementation.

Step 1: Run the command

> /moai "JWT-based user authentication system: signup, login, token refresh" --loop --pr

Info

The pipeline does not create worktrees. To run this work in an isolated worktree, enter one first with moai cc -w <name> and issue the command there.

Step 2: Phase 0 - parallel exploration

[Parallel exploration started]
  Explore subagent: analyzing src/auth/...
  Research subagent: researching JWT best practices...
  Quality subagent: confirming 32% test coverage...

[Exploration complete - 23 s]
  Files discovered: 4
  Recommended libraries: PyJWT, bcrypt
  Baseline: 0 LSP errors, 32% coverage

Step 3: Phase 1 - SPEC creation

[Invoking manager-spec]
  SPEC ID: SPEC-AUTH-001
  Requirements: 5 (EARS format)
  Acceptance criteria: 3 scenarios

  User approval: complete

Step 4: Phase 2 - DDD implementation

[manager-spec]
  Task decomposition: 7 tasks
  Strategic planning complete

[manager-develop]
  ANALYZE: code structure analysis complete
  PRESERVE: 12 characterization tests written
  IMPROVE: 7 tasks implemented

[sync-auditor]
  TRUST 5: all pillars pass
  Coverage: 89%
  Status: PASS

Step 5: Automatic loop (–loop)

[Loop started - iteration 1/100]
  Diagnostics: 2 type errors found
  Fix: delegated to the manager-develop subagent
  Verify: all errors resolved

[Loop finished - 1 iteration]
  Completion condition met!

Step 6: Phase 3 - doc synchronization

[manager-docs]
  API docs: docs/api/auth.md created
  README: usage section updated
  CHANGELOG: v1.1.0 entry added
  SPEC-AUTH-001: ACTIVE → COMPLETED

Step 7: Done

[Done]
  SPEC: SPEC-AUTH-001
  Commits: 7
  Tests: 36/36 pass
  Coverage: 89%
  PR: #42 created (Draft → Ready)

  → the Completion Report banner signals that the work is done

Use it when you want all errors fixed automatically after implementation. It is especially useful for cleanup after large refactorings.

Single-domain work (e.g. “optimize SQL queries”) is delegated directly to the specialist agent for that domain without SPEC creation, saving time.

Yes. Analyze-First routing is language-independent intent analysis, so requests in Korean, Japanese, Chinese, or any other language behave identically.

• /moai plan - SPEC creation details
• /moai run - DDD implementation details
• /moai sync - Doc synchronization details
• /moai loop - Iterative fix loop details
• /moai fix - One-shot auto-fix details