moai-adk

Benefits:

• Single unified design workflow instead of dual /moai + /agency commands
• Improved integration with MoAI core (brand context, quality gates, SPEC-driven workflows)
• Enhanced documentation at adk.mo.ai.kr/design

Opus 4.7 Native Support

MoAI-ADK now targets Claude Opus 4.7 with native Adaptive Thinking:

• Automatic dynamic token allocation for reasoning (no fixed budgets)
• Faster inference through streamlined prompt phrasing
• Better cost efficiency on complex tasks

Self-Research & Memory Evolution

v2.11+ self-research system now integrated with agent learnings:

• Agents auto-capture lessons from corrections
• Memory system persists across sessions (.claude/agent-memory/)
• Documentation loads just-in-time based on task context

Why MoAI-ADK?

We completely rewrote the Python-based MoAI-ADK (~73,000 lines) in Go.

| Aspect | Python Edition | Go Edition | |--------|---------------|------------| | Distribution | pip + venv + dependencies | Single binary, zero dependencies | | Startup time | ~800ms interpreter boot | ~5ms native execution | | Concurrency | asyncio / threading | Native goroutines | | Type safety | Runtime (mypy optional) | Compile-time enforced | | Cross-platform | Python runtime required | Prebuilt binaries (macOS, Linux, Windows) | | Hook execution | Shell wrapper + Python | Compiled binary, JSON protocol |

Key Numbers

• 38,700+ lines of Go code, 38 packages
• 85-100% test coverage
• 26 specialized AI agents + 47 skills
• 18 programming languages supported
• 27 Claude Code hook events

Harness Engineering Architecture

MoAI-ADK implements the Harness Engineering paradigm — designing the environment for AI agents rather than writing code directly.

| Component | Description | Command | |-----------|-------------|---------| | Self-Verify Loop | Agents write code → test → fail → fix → pass cycle autonomously | /moai loop | | Context Map | Codebase architecture maps and documentation always available to agents | /moai codemaps | | Session Persistence | progress.md tracks completed phases across sessions; interrupted runs resume automatically | /moai run SPEC-XXX | | Failing Checklist | All acceptance criteria registered as pending tasks at run start; marked complete as implemented | /moai run SPEC-XXX | | Language-Agnostic | 16 languages supported: auto-detects language, selects correct LSP/linter/test/coverage tools | All workflows | | Garbage Collection | Periodic scan and removal of dead code, AI Slop, and unused imports | /moai clean | | Scaffolding First | Empty file stubs created before implementation to prevent entropy | /moai run SPEC-XXX |

"Human steers, agents execute." — The engineer's role shifts from writing code to designing the harness: SPECs, quality gates, and feedback loops.

System Requirements

| Platform | Supported Environments | Notes | |----------|----------------------|-------| | macOS | Terminal, iTerm2 | Fully supported | | Linux | Bash, Zsh | Fully supported | | Windows | WSL (recommended), PowerShell 7.x+ | Native cmd.exe is not supported |

Prerequisites:

• Git must be installed on all platforms
• Windows users: Git for Windows is required (includes Git Bash)
  • Use WSL (Windows Subsystem for Linux) for the best experience
  • PowerShell 7.x or later is supported as an alternative
  • Legacy Windows PowerShell 5.x and cmd.exe are not supported

Quick Start

1. Installation

macOS / Linux / WSL

curl -fsSL https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.sh | bash

Windows (PowerShell 7.x+)

Recommended: Use WSL with the Linux installation command above for the best experience.

irm https://raw.githubusercontent.com/modu-ai/moai-adk/main/install.ps1 | iex

Requires Git for Windows to be installed first.

Build from Source (Go 1.26+)

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

Prebuilt binaries are available on the Releases page.

2. Windows-Specific Issues

Korean Username Path Errors

If your Windows username contains non-ASCII characters (Korean, Chinese, etc.), you may encounter EINVAL errors due to Windows 8.3 short filename conversion.

Workaround 1: Set an alternative temp directory:

# Command Prompt
set MOAI_TEMP_DIR=C:\temp
mkdir C:\temp 2>nul

# PowerShell
$env:MOAI_TEMP_DIR="C:\temp"
New-Item -ItemType Directory -Path "C:\temp" -Force

Workaround 2: Disable 8.3 filename generation (requires admin):

fsutil 8dot3name set 1

Workaround 3: Create a new Windows user account with ASCII-only username.

3. Initialize a Project

moai init my-project

An interactive wizard auto-detects your language, framework, and methodology, then generates Claude Code integration files.

4. Start Developing with Claude Code

# After launching Claude Code
/moai project                            # Generate project docs (product.md, structure.md, tech.md)
/moai plan "Add user authentication"     # Create a SPEC document
/moai run SPEC-AUTH-001                   # DDD/TDD implementation
/moai sync SPEC-AUTH-001                  # Sync docs & create PR
/moai github issues                      # Fix GitHub issues with Agent Teams
/moai github pr 123                       # Review PR with multi-perspective analysis

graph LR
    A["🔍 /moai project"] --> B["📋 /moai plan"]
    B -->|"SPEC Document"| C["🔨 /moai run"]
    C -->|"Implementation Complete"| D["📄 /moai sync"]
    D -->|"PR Created"| E["✅ Done"]

MoAI Development Methodology

MoAI-ADK automatically selects the optimal development methodology based on your project's state.

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

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

TDD Methodology (Default)

The default methodology for new projects and feature development. Write tests first, then implement.

| Phase | Description | |-------|-------------| | RED | Write a failing test that defines expected behavior | | GREEN | Write minimal code to make the test pass | | REFACTOR | Improve code quality while keeping tests green. /simplify runs automatically after REFACTOR completes. |

For brownfield projects (existing codebases), TDD is enhanced with a pre-RED analysis step: read existing code to understand current behavior before writing tests.

DDD Methodology (Existing Projects with < 10% Coverage)

A methodology