🗿 MoAI-ADK: Agentic AI Development Framework

Available Languages: 🇰🇷 한국어 | 🇺🇸 English | 🇯🇵 日本語 | 🇨🇳 中文

"The purpose of vibe coding is not rapid productivity but code quality."

MoAI-ADK provides an AI development environment for quality code. SPEC-First DDD (Domain-Driven Development), continuous refactoring with behavior preservation, and 20 specialized AI agents work together.

---

🎁 MoAI-ADK Sponsor: z.ai GLM 4.7

💎 Optimal Solution for Cost-Effective AI Development

MoAI-ADK partners with z.ai GLM 4.7 to provide developers with an economical AI development environment.

🚀 GLM 4.7 Special Benefits

| Benefit | Description | | -------------------------- | -------------------------------------------------------------- | | 💰 70% Cost Savings | 1/7 the price of Claude with equivalent performance | | ⚡ Fast Response Speed | Low-latency responses with optimized infrastructure | | 🔄 Compatibility | Fully compatible with Claude Code, no code modification needed | | 📈 Unlimited Usage | Use freely without daily/weekly token limits |

🎁 Sign-Up Special Discount

👉 GLM 4.7 Sign Up (10% Additional Discount)

By signing up through this link:

• ✅ Additional 10% discount benefit
• ✅ Contribute to MoAI open source development (reward credits are used for open source projects)

💡 Usage Guide

# 1. Get GLM API Key
Sign up at the link above and get your API key

# 2. Configure GLM in MoAI-ADK
moai glm YOUR_API_KEY

💡 Tip: Using GLM 4.7 in a Worktree environment allows you to design with Opus and implement in bulk with GLM, saving up to 70% on costs.

---

🌟 Core Values

• 🎯 SPEC-First: 90% reduction in rework with clear specifications
• 🔵 DDD (Domain-Driven Development): ANALYZE-PRESERVE-IMPROVE cycle with behavior preservation
• 🤖 AI Orchestration: 20 specialized agents + 49 skills
• 🧠 Sequential Thinking MCP: Structured problem-solving with step-by-step reasoning
• 🌐 Multilingual Routing: Automatic support for Korean/English/Japanese/Chinese
• 🌳 Worktree Parallel Development: Unlimited parallel work in completely isolated environments
• 🏆 MoAI Rank: Motivation through vibe coding leaderboard
• 🔗 Ralph-Style LSP Integration (NEW v1.9.0): LSP-based autonomous workflow with real-time quality feedback

---

🎯 Ralph-Style LSP Integration (NEW v1.9.0)

LSP Integration Overview

MoAI-ADK now supports Ralph-style autonomous workflow with LSP (Language Server Protocol) diagnostics integration. The system captures LSP diagnostic state at workflow entry, monitors diagnostic state during execution, and automatically completes phases when quality thresholds are met.

Key Features

LSP Baseline Capture:

• Automatic LSP diagnostic capture at phase start
• Tracks errors, warnings, type errors, lint errors
• Baseline used for regression detection

Completion Markers:

• Plan Phase: SPEC created, baseline recorded
• Run Phase: 0 errors, 0 type errors, coverage >= 85%
• Sync Phase: 0 errors, <10 warnings

Execution Modes:

• Interactive (default): Manual approval at each step
• Autonomous (optional): Continuous loop until completion

Loop Prevention:

• Maximum 100 iterations
• No progress detection (5 iterations)
• Alternative strategy on stall

Configuration:

# .moai/config/sections/workflow.yaml
execution_mode:
  autonomous:
    user_approval_required: false
    continuous_loop: true
    completion_marker_based: true
    lsp_feedback_integration: true

---

📚 For detailed information, see the official online documentation: https://adk.mo.ai.kr

1. 30-Second Installation

⚠️ Windows Users: MoAI-ADK supports PowerShell only. WSL (Windows Subsystem for Linux) and Command Prompt (cmd.exe) are not supported. Please use PowerShell or Windows Terminal with PowerShell.

🚀 Method 1: Quick Install (Recommended)

curl -LsSf https://modu-ai.github.io/moai-adk/install.sh | sh

🔧 Method 2: Manual Install

# Install MoAI-ADK
uv tool install moai-adk

🎨 Interactive Setup Wizard

Running moai init starts a 9-step interactive wizard:

---

Step 1: Language Selection

Select your conversation language. All subsequent instructions will be displayed in your chosen language.

🌐 Language Selection
❯ Select your conversation language: [↑↓] Navigate  [Enter] Select
❯ Korean (한국어)
  English
  Japanese (日本語)
  Chinese (中文)

---

Step 2: Name Input

Enter your user name. AI will provide personalized responses.

👤 User Settings
❯ Enter your user name (optional):

---

Step 3: GLM API Key Input

Enter your GLM API key from Z.AI.

🔑 API Key Input
GLM CodePlan API key (optional - press Enter to skip)

✓ Found existing GLM API key: 99c1a2df...
Press Enter to keep existing key, or enter new key to replace

? Enter your GLM API key:

🎁 GLM Sign-Up Benefit: If you don't have a GLM account, sign up using the link below!

👉 GLM Sign Up (10% Additional Discount)

By signing up through this link, you'll receive an additional 10% discount. Also, rewards generated from link sign-ups are used for MoAI open source development. 🙏

---

Step 4: Project Setup

Enter your project name.

📁 Project Setup
❯ Project name: MoAI-ADK

---

Step 5: Git Setup

Select your Git mode.

🔀 Git Setup
❯ Select your Git mode: [↑↓] Navigate  [Enter] Select
❯ manual (local only) - Use local repository only
  personal (GitHub personal) - Use GitHub personal account
  team (GitHub team) - Use GitHub team/organization

---

Step 6: GitHub Username

For personal/team selection, enter your GitHub username.

❯ GitHub username:

---

Step 7: Commit Message Language

Select the language for Git commit messages.

🗣️ Output Language Settings
❯ Commit message language: [↑↓] Navigate  [Enter] Select
  English
❯ Korean (한국어)
  Japanese (日本語)
  Chinese (中文)

---

Step 8: Code Comment Language

Select the language for code comments.

❯ Code comment language: [↑↓] Navigate  [Enter] Select
  English
❯ Korean (한국어)
  Japanese (日本語)
  Chinese (中文)

---

Step 9: Documentation Language

Select the language for documentation.

❯ Documentation language: [↑↓] Navigate  [Enter] Select
  English
❯ Korean (한국어)
  Japanese (日本語)
  Chinese (中文)

💡 Token Optimization Strategy: Internal prompts for agent instructions are fixed in English.

Reason: Non-English languages consume 12-20% additional tokens in Claude. When infinite agent loops are frequent, this significantly impacts costs and weekly token limits, so MoAI fixes internal agent instructions in English and provides user conversations only in the user's language.

This is MoAI's effort to reduce token waste.

---

Installation Complete

When all settings are complete, 5-phase installation runs automatically:

🚀 Starting installation...

Phase 1: Preparation and backup...        ████████████████ 100%
Phase 2: Creating directory structure...  ████████████████ 100%
Phase 3: Installing resources...          ████████████████ 100%
Phase 4: Generating configurations...     ████████████████ 100%
Phase 5: Validation and finalization...   ████████████████ 100%

✅ Initialization Completed Successfully!
────────────────────────────────────────────────────────────────

📊 Summary:
  📁 Location:   /path/to/my-project
  🌐 Language:   Auto-detect (use /moai:0-project)
  🔀 Git:        manual (github-flow, branch: manual)
  🌍 Locale:     ko
  📄 Files:      47 created
  ⏱️  Duration:   1234ms

🚀 Next Steps:
  1. Run cd my-project to enter the project
  2. Run /moai:0-project in Claude Code for full setup
  3. Start developing with MoAI-ADK!

Add to Existing Project

cd your-existing-project
moai init .
# Existing files are preserved

---

🔄 MoAI-ADK Update

Update existing projects to the latest version.

moai update

3-Phase Smart Update Workflow:

Stage 1: 📦 Package Version Check
         └─ Check latest version from PyPI → Auto-upgrade if needed

Stage 2: 🔍 Config Version Comparison
         └─ Compare package template vs project config
         └─ Skip if same (70-80% performance improvement)

Stage 3: 📄 Template Synchronization
         └─ Create backup → Update template → Restore user settings

Key Options:

# Check version only (no update)
moai update --check

# Synchronize templates only (skip package upgrade)
moai update --templates-only

# Config edit mode (re-run init wizard)
moai update --config
moai update -c

# Force update without backup
moai update --force

# All is well~ Auto mode (auto-approve all confirmations)
moai update --yes

Merge Strategy Selection:

🔀 Choose merge strategy:
  [1] Auto-merge (default)
      → Automatically preserve template + user changes
  [2] Manual merge
      → Create backup + merge guide (direct control)

# Force auto-merge (default)
moai update --merge

# Force manual merge
moai update --manual

Automatically Preserved Items:

| Item