AI & Development Tools

[EP4] MoAI-ADK Core Technology Deep Dive - alfred, Ralph Engine, Skills System

01/10/2026

7.85min

MoAI-ADKalfredRalph EngineAnti-HallucinationLSPAST-grepSPEC-First TDDSkills System

In-depth analysis of MoAI-ADK's three core technologies - /moai:alfred one-click automation, Ralph Engine quality engine, and Anti-Hallucination skills system - from an architectural perspective.

SeriesEP 4 / 5

EP 1. The Evolution of AI Coding Tools - Why MoAI-ADK?EP 2. OpenCode vs Claude Code Complete Comparison EP 3. oh-my-opencode vs MoAI-ADK In-Depth Analysis EP 4. MoAI-ADK Core Technology Deep Dive EP 5. The Future of AI Coding in 2026

←Prev Next→

Architecture Overview

MoAI-ADK consists of three core technology layers. Each layer operates independently while organically connecting to automate the entire development lifecycle.

Loading diagram...

1. /moai:alfred - One-Click Development Automation

1.1 Design Philosophy

The alfred command implements MoAI-ADK's philosophy in a single command: "From requirements to PR with one command".

The 759-line command definition is based on the following principles:

Intelligent Routing: Optimal path selection based on request complexity
Quality Gates: Quality validation at each Phase transition
Resumable State: Support for resuming interrupted workflows
Multi-LLM: Model selection based on task characteristics

1.2 Workflow Architecture

Loading diagram...

1.3 Intelligent Routing Implementation

alfred analyzes requests to determine optimal execution paths:

Plain Text
Domain Detection:
├── Backend Keywords: API, server, auth, database, REST, GraphQL
├── Frontend Keywords: UI, component, React, Vue, Next.js, CSS
├── Security Keywords: security, vulnerability, OWASP, auth, permission
├── DevOps Keywords: CI/CD, Docker, Kubernetes, deployment
└── Database Keywords: SQL, schema, query, index

Routing Logic:
├── Single domain detected → Direct Expert Agent delegation
└── Multiple domains detected → Full SPEC workflow (Plan → Run → Sync)

1.4 Multi-LLM Mode

alfred supports three LLM modes:

Mode	Phase 1 (Plan)	Phase 2-3 (Run/Sync)	Usage Scenario
opus-only	Claude Opus	Claude Opus	High quality required, single terminal
hybrid	Claude Opus	GLM (worktree)	Cost optimization, parallel work
glm-only	GLM	GLM	Cost minimization

1.5 State Management and Resumption

Workflow state is saved in .moai/cache/alfred-{spec-id}.json:

JSON
{
  "spec_id": "SPEC-AUTH-001",
  "current_phase": 2,
  "last_checkpoint": "2026-01-10T14:30:00Z",
  "phase_results": {
    "1": { "status": "completed", "spec_file": "specs/SPEC-AUTH-001.md" },
    "2": { "status": "in_progress", "coverage": 0.72 }
  },
  "git_state": {
    "branch": "feat/auth-001",
    "commits": ["abc123", "def456"]
  }
}

Resume interrupted workflows with the following command:

Bash

/moai:alfred resume SPEC-AUTH-001

2. Ralph Engine - Autonomous Quality Assurance System

2.1 Architecture Overview

Ralph Engine is a quality assurance system integrating three technologies:

Loading diagram...

2.2 LSP Client (394 lines)

The LSP (Language Server Protocol) Client implements the JSON-RPC 2.0 protocol:

Plain Text
LSP Client Features:
├── Real-time type error detection
├── Syntax error detection
├── Warning collection
├── Multiple language server management
└── Diagnostic result streaming

Supported language servers:

TypeScript: typescript-language-server
Python: pylsp, pyright
Go: gopls
Rust: rust-analyzer

2.3 AST-grep Integration

AST-grep performs structural pattern matching instead of regex:

Plain Text
AST-grep Features:
├── Security vulnerability detection
│   ├── SQL Injection patterns
│   ├── XSS vulnerabilities
│   └── Hardcoded secrets
├── Code smell identification
│   ├── Unused variables
│   ├── Excessive complexity functions
│   └── Duplicate code
└── Automatic refactoring
    ├── API migration
    └── Pattern transformation

2.4 Loop Controller (~400 lines)

Loop Controller manages autonomous fix-verify-fix cycles:

Plain Text
Loop Controller Operation:
├── Promise-based completion conditions
│   └── All errors resolved OR max iterations reached
├── Configurable max iterations (default: 3)
├── State persistence and resumption support
└── Autonomous fix cycle
    ├── Error analysis
    ├── Fix attempt
    ├── Re-verification
    └── Next iteration or completion

2.5 Core Method: diagnose_file()

diagnose_file() returns LSP diagnostics and AST-grep matches as an integrated DiagnosisResult:

Python
class DiagnosisResult:
    file_path: str
    lsp_diagnostics: List[Diagnostic]
    ast_matches: List[AstMatch]
    severity_summary: Dict[str, int]
    auto_fixable: List[FixSuggestion]

3. Anti-Hallucination Strategy: Skills System

3.1 Design Principles

To prevent LLM hallucinations, MoAI-ADK takes a verified knowledge base approach:

Plain Text
Anti-Hallucination Principles:
├── Use only verified patterns
│   └── Each skill contains actually working code patterns
├── Version specification
│   └── Library/framework versions specified
├── Source tracking
│   └── All patterns include source information
└── Automatic updates
    └── Latest documentation reference through Context7 MCP

3.2 Skills Classification System

Over 90 domain skills are classified into 4 categories:

Category	Count	Examples	Role
Foundation	4	moai-foundation-core, moai-foundation-claude	Core rule enforcement
Language	16	Python, TypeScript, Go, Rust, Java...	Language-specific best practices
Platform	9	Auth0, Firebase, Supabase, Vercel...	Platform-specific API patterns
Domain	10+	Frontend, Backend, Database...	Domain-specific architecture

3.3 Skills Loading System (580 lines)

The skills loading system provides the following features:

Loading diagram...

Core Features:

LRU Cache + TTL: Memory caching for performance optimization
Dependency Management: Automatic related skill loading (e.g., React skill loading automatically includes Frontend base skill)
Effort-based Filtering: Detail level adjustment from 1 (basic) to 5 (comprehensive)
Automatic Detection: Related skill keyword detection from user prompts

3.4 Skills Structure Example

Skill files consist of YAML frontmatter and markdown content:

Frontmatter Structure:

YAML
name: moai-lang-typescript
version: 5.9
category: language
effort: 3
dependencies:
  - moai-domain-frontend
triggers:
  - typescript
  - tsx
  - type-safe

Skill Content Example - TypeScript 5.9 Best Practices:

TypeScript
// ✅ Recommended: Type inference with const assertion
const config = {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
} as const;

// ❌ Avoid: Explicit any
const data: any = fetchData();

Zod Validation Pattern:

TypeScript
import { z } from 'zod';

const UserSchema = z.object({
  id: z.string().uuid(),
  email: z.string().email(),
  role: z.enum(['admin', 'user']),
});

type User = z.infer<typeof UserSchema>;

3.5 Context7 MCP Integration

The skills system integrates with Context7 MCP to reference latest documentation:

Plain Text
Context7 Integration:
├── resolve-library-id: Library identifier resolution
└── get-library-docs: Retrieve latest documentation

Usage Scenarios:
├── Reference latest APIs not in skills
├── Check version updates
└── Real-time documentation validation

4. Integrated Architecture

Examining how the three layers integrate and operate:

Loading diagram...

5. Performance Metrics

Quantitative indicators of MoAI-ADK core technologies:

Metric	Value	Description
/moai:alfred code	759 lines	Flagship command definition
Ralph Engine core	308 lines	Quality assurance engine
LSP Client	394 lines	Language server communication
Loop Controller	~400 lines	Autonomous fix cycle
Skill Loading System	580 lines	Skills management
Claude Integration	394 lines	Headless automation
Domain Skills	90+	Verified knowledge base
Supported Languages	16	Programming languages
Test Coverage Target	85%	TRUST 5 standard
CLI Startup Time Reduction	75%	400ms → 100ms

Next Episode Preview

The next episode EP.5: The Future of AI Coding in 2026 concludes the series and covers:

Comprehensive Comparison Table: 4 tools × 12 items comparison
Scenario-based Recommendations: Optimal tool selection guide for situations
v0.5.0 Roadmap: MoAI-ADK's future direction
Conclusion: Core criteria for AI coding tool selection

Architecture Overview

1. /moai:alfred - One-Click Development Automation

1.1 Design Philosophy

1.2 Workflow Architecture

1.3 Intelligent Routing Implementation

1.4 Multi-LLM Mode

1.5 State Management and Resumption

2. Ralph Engine - Autonomous Quality Assurance System

2.1 Architecture Overview

2.2 LSP Client (394 lines)

2.3 AST-grep Integration

2.4 Loop Controller (~400 lines)

2.5 Core Method: diagnose_file()

3. Anti-Hallucination Strategy: Skills System

3.1 Design Principles

3.2 Skills Classification System

3.3 Skills Loading System (580 lines)

3.4 Skills Structure Example

3.5 Context7 MCP Integration

4. Integrated Architecture

5. Performance Metrics

Next Episode Preview

References