How modu-ai/moai-adk works
The MoAI-ADK project is an open-source, Python-based CLI framework that orchestrates AI agents in a SPEC-First TDD workflow. Its architecture can be broken down into the following high-level components:
User & CLI Layer
• User invokes commands (moai-adk, /moai:1-plan, /moai:2-run, /moai:3-sync) via a shell
• CLI module (src/moai_adk/cli/*) parses commands and forwards them to the Core Engine
Core Engine (Mr. Alfred Orchestrator)
• Command Dispatcher & Context Manager (command_helpers.py, context_manager.py)
• Phase Executor (phase_executor.py): implements Plan → Run → Sync loop
• Integration Layer (integration/engine.py): interfaces with LLMs (Claude Code) and MCP servers
• Hook & Plugin Manager (core/hooks/*, .claude/hooks/*): pre- and post-tool hooks
Agents & Skills
• Agents (.claude/agents/moai/*.md + generated via builder-agent) perform specialized tasks (SPEC writing, TDD, docs, quality, domain experts)
• Skills (.claude/skills/moai-* + Python skill modules) provide knowledge bases and patterns
• The Orchestrator dynamically loads agents/skills via the “modular system”
Configuration, Memory & Specs
• Config files (.moai/config/*.json, .claude/settings.json, pyproject.toml)
• Project memory (.moai/memory/last-session-state.json)
• SPEC docs (.moai/specs/SPEC-*/spec.md)
• Templates (src/moai_adk/templates, .claude/output-styles, .claude/skills/*/modules)
Output & Documentation
• Code artifacts: source (src/moai_adk), tests (tests/), hooks, scripts
External Integrations
• LLM service (Claude via CLI or API)
• MCP servers (.mcp.json): Context7 (docs lookup), Sequential-Thinking (complex reasoning), Playwright (E2E), Figma, Nano-Banana (image gen)
• Git & CI/CD (GitHub Actions workflows in .github/workflows/)
Testing & Quality
• Unit, integration, e2e, statusline, shell, hooks tests under tests/
• TRUST 5 quality checks automated by manager-quality agent
1. User & CLI (blue rectangle)
2. Core Engine / Mr. Alfred (green hexagon)
– Subcomponents: Command Parser, Phase Executor, Hook Manager, Integration Engine
3. Agents (orange circles) & Skills (orange hexagons)
5. Specs & Templates (gray documents)
6. File System (gray folder)
7. External Services (purple clouds): LLM, MCP servers, GitHub
• User → CLI → Core Engine
• Core Engine → Agents/Skills
• Agents/Skills → Core Engine (results)
• Core Engine ↔ LLM/MCP (API calls)
• Core Engine → File System (read/write specs, memory, config, code, docs)
• Core Engine → External Git/CI for commit, PR creation
C. Highlight Architectural Patterns
• Mediator (Mr. Alfred orchestrates agents)
• Pipeline (Plan → Run → Sync phases)
• Plugin/Modular (dynamic agent & skill loading)
• Adapter (integration layer for external LLMs & MCPs)
• Config-Driven (behavior controlled by JSON/YAML settings)
D. Annotate Key Technologies
• Python 3.11+, Typer or Click for CLI
• PyTest for testing
• JSON/YAML for configs & specs
• Markdown for SPECs, Skills, Hooks
• LLM API (Claude Code), MCP server protocols
• As an open-source framework, emphasize extension points: where new agents/skills/hooks can be plugged in.
• “Templates → CLI → Core Engine → Agents/Skills → File System” flow to illustrate how user input leads to spec generation, code, tests, docs.
• 3-phase loop (Plan, Run, Sync) as an inset or small flowchart next to the Core Engine.
• Clear labels on every component