MoAI-ADK (modu-ai/moai-adk)

MoAI-ADK

https://github.com/modu-ai/moai-adk
Admin
MoAI-ADK is an open-source, AI agent-powered development framework that combines SPEC-First...

Tokens:52,753
Snippets:476
Trust Score:7.5
Update:4 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# MoAI-ADK: Agentic AI-Based SPEC-First TDD Development Framework

MoAI-ADK (Agentic Development Kit) is an enterprise-grade development framework that combines SPEC-First methodology, Test-Driven Development, and 28 specialized AI agents to deliver transparent and quality-assured software development. The framework orchestrates development through Mr. Alfred, a SuperAgent coordinator that delegates tasks to specialized sub-agents, ensuring 85%+ test coverage and automated documentation synchronization with Phase 0.5 quality verification.

Built on Claude Code's official agent architecture, MoAI-ADK provides a complete workflow from specification creation (`/moai:1-plan`) through TDD implementation (`/moai:2-run`) to documentation synchronization with automated quality checks (`/moai:3-sync`). The framework supports Python 3.11-3.14, provides 16-language quality verification (Python, TypeScript, JavaScript, Go, Rust, Ruby, Java, PHP, Kotlin, Swift, C#, C++, Elixir, R, Flutter/Dart, Scala), and integrates with multiple MCP servers including Context7, Figma, Notion, and Playwright for enhanced development capabilities. With TRUST 5 quality assurance (Test, Readable, Unified, Secured, Trackable), MoAI-ADK achieves 90% reduction in rework and 60-70% time savings through intelligent agent orchestration.

---

## CLI Installation and Project Initialization

Install MoAI-ADK using uv package manager and initialize a new project with Smart Question System

```bash
# Install uv (macOS/Linux)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install MoAI-ADK
uv tool install moai-adk

# Initialize new project (interactive mode with Smart Questions)
moai-adk init

# Non-interactive initialization with options
moai-adk init --non-interactive --mode=personal --locale=en --language=python

# Initialize existing project
cd your-existing-project
moai-adk init .

# Force reinitialization of existing project
moai-adk init --force --locale=ko

# Check project status
moai-adk status

# Run system diagnostics
moai-adk doctor

# Update to latest version
moai-adk update

# Configure project metadata with Smart Question System
claude
> /moai:0-project

# Enable GLM integration for cost savings
> /moai:0-project --glm-on YOUR_API_TOKEN
```

---

## SPEC Creation and Planning

Create EARS-format specifications with optional Git branch or worktree using industry-standard EARS grammar patterns

```bash
# Create SPEC document only (default)
/moai:1-plan "User authentication system"

# Create SPEC with traditional Git branch
/moai:1-plan "Payment processing module" --branch

# Create SPEC with isolated Git worktree (parallel development)
/moai:1-plan "Real-time notification service" --worktree

# Modify existing SPEC
/moai:1-plan SPEC-001 modifications "Add OAuth2 support"
```

**SPEC Structure with EARS Official Grammar Patterns (2025 Industry Standard):**
```markdown
# SPEC-001: User Authentication System

## Metadata
- ID: SPEC-001
- Status: PLANNED
- Priority: HIGH
- Created: 2024-01-15
- Updated: 2024-01-15

## Requirements (EARS Format - 5 Official Pattern Types)

### Ubiquitous Requirements (Always Active)
- THE SYSTEM SHALL log all authentication attempts with timestamp and IP address
- THE SYSTEM SHALL encrypt passwords using bcrypt with minimum cost factor 12

### Event-Driven Requirements (Trigger → Response)
- WHEN user submits login credentials, THE SYSTEM SHALL validate against database
- WHEN authentication succeeds, THE SYSTEM SHALL generate JWT token with 24-hour expiration
- WHEN authentication fails, THE SYSTEM SHALL increment failure counter

### State-Driven Requirements (Condition → Constraint)
- WHERE authentication fails 5 times in 15 minutes, THE SYSTEM SHALL lock account for 30 minutes
- WHERE session is active, THE SYSTEM SHALL validate token on each request
- WHERE token expires, THE SYSTEM SHALL redirect to login page

### Unwanted Behaviors (Forbidden Actions)
- THE SYSTEM SHALL NOT store passwords in plaintext
- THE SYSTEM SHALL NOT log sensitive user data in plain text
- THE SYSTEM SHALL NOT allow SQL injection in authentication queries

### Optional Requirements (Nice-to-Have)
- WHERE POSSIBLE, THE SYSTEM SHALL support OAuth2 social login
- WHERE POSSIBLE, THE SYSTEM SHALL enable two-factor authentication
- WHERE POSSIBLE, THE SYSTEM SHALL provide password strength indicator

## Acceptance Criteria
- [ ] Login form accepts email and password with validation
- [ ] Failed attempts are limited to 5 per 15 minutes with account lockout
- [ ] JWT tokens expire after 24 hours with automatic refresh
- [ ] Session invalidation on logout works correctly
- [ ] All passwords encrypted with bcrypt cost factor 12+

## Technical Details
- FastAPI backend with bcrypt password hashing (cost factor 12)
- PostgreSQL for user storage with indexed email column
- Redis for session management and rate limiting
- 85%+ test coverage required per TRUST 5 standards
- Multi-language quality verification enabled

## Test Scenarios
### TC-1: Successful Login
- Input: email="user@example.com", password="secure123"
- Expected: Token issued, navigate to dashboard, response < 500ms

### TC-2: Invalid Password
- Input: email="user@example.com", password="wrong"
- Expected: "Incorrect password" error, attempt counter incremented

### TC-3: Account Lock After 5 Failures
- Input: 5 consecutive failures within 15 minutes
- Expected: "Account locked. Try again in 30 minutes" message
```

---

## TDD Implementation Execution

Execute Test-Driven Development cycle with RED-GREEN-REFACTOR methodology and multi-language support

```bash
# Implement single SPEC with automatic language detection
/moai:2-run SPEC-001

# Workflow automatically executes:
# Phase 1: manager-strategy analyzes SPEC and creates execution plan
# Phase 2: manager-tdd implements RED → GREEN → REFACTOR cycle
#   - Detects project language (Python/TypeScript/Go/Rust/etc.)
#   - Generates language-specific tests and implementation
#   - Runs appropriate test runner (pytest/jest/go test/cargo test/etc.)
# Phase 2.5: manager-quality validates TRUST 5 compliance
#   - Runs language-specific linter (ruff/eslint/golangci-lint/clippy/etc.)
#   - Executes type checker (mypy/tsc/go vet/etc.)
#   - Validates coverage target from config
# Phase 3: manager-git creates commits
# Phase 4: Presents completion summary and next steps
```

**TDD Cycle Example (Python with FastAPI):**
```python
# RED Phase - Write failing test first
def test_user_login_success():
    """Test successful user authentication"""
    user = {"email": "test@example.com", "password": "SecurePass123!"}
    response = client.post("/auth/login", json=user)

    assert response.status_code == 200
    assert "access_token" in response.json()
    assert response.json()["token_type"] == "bearer"

# GREEN Phase - Implement minimal code to pass
@app.post("/auth/login", response_model=TokenResponse)
async def login(credentials: LoginRequest, db: Session = Depends(get_db)):
    user = db.query(User).filter(User.email == credentials.email).first()
    if not user or not verify_password(credentials.password, user.hashed_password):
        raise HTTPException(status_code=401, detail="Invalid credentials")

    access_token = create_access_token(data={"sub": user.email})
    return {"access_token": access_token, "token_type": "bearer"}

# REFACTOR Phase - Optimize and clean up
async def authenticate_user(email: str, password: str, db: Session) -> User:
    """Authenticate user with rate limiting and security checks"""
    user = await get_user_by_email(db, email)
    if not user:
        raise AuthenticationError("Invalid credentials")

    await check_rate_limit(email)

    if not verify_password_secure(password, user.hashed_password):
        await log_failed_attempt(email)
        raise AuthenticationError("Invalid credentials")

    return user
```

**Multi-Language TDD Support:**
```bash
# Python with pytest
/moai:2-run SPEC-001  # Detects Python, uses pytest + ruff + mypy

# TypeScript with Jest
/moai:2-run SPEC-002  # Detects TypeScript, uses jest + eslint + tsc

# Go with testing package
/moai:2-run SPEC-003  # Detects Go, uses go test + golangci-lint + go vet

# Rust with cargo test
/moai:2-run SPEC-004  # Detects Rust, uses cargo test + clippy + cargo check
```

---

## Documentation Synchronization with Phase 0.5 Quality Verification

Automatically sync documentation with code changes and comprehensive quality checks across 16 languages

```bash
# Auto-sync mode (default) - syncs changes since last commit
/moai:3-sync auto SPEC-001

# Force sync - regenerate all documentation
/moai:3-sync force SPEC-001

# Status check - review sync status without changes
/moai:3-sync status SPEC-001

# Project-wide sync
/moai:3-sync project
```

**Phase 0.5 Quality Verification (NEW in v0.34.0):**
```markdown
# Automatic Quality Checks Before Documentation Sync

## Language Detection (16 Languages Supported)
- Auto-detects: Python, TypeScript, JavaScript, Go, Rust, Ruby, Java, PHP,
  Kotlin, Swift, C#, C++, Elixir, R, Flutter/Dart, Scala
- Selects appropriate tools for each language

## Language-Specific Verification
### Python Projects
- Test Runner: pytest with coverage plugin
- Linter: ruff (modern, fast Python linter)
- Type Checker: mypy (static type analysis)
- Coverage Target: From config (default 85%)

### TypeScript/JavaScript Projects
- Test Runner: jest or vitest
- Linter: eslint with TypeScript support
- Type Checker: tsc (TypeScript compiler)
- Coverage Target: From config (default 85%)

### Go Projects
- Test Runner: go test with coverage
- Linter: golangci-lint (aggregates 48+ linters)
- Type Checker: go vet (built-in static analysis)
- Coverage Target: From config (default 85%)

### Rust Projects
- Test Runner: cargo test
- Linter: clippy (official Rust linter)
- Type Checker: cargo check (compile-time verification)
- Coverage Target: From config (default 85%)

### Ruby Projects
- Test Runner: rspec or minitest
- Linter: rubocop (Ruby style guide enforcer)
- Type Checker: sorbet (optional static typing)
- Coverage Target: From config (default 85%)

### Java Projects
- Test Runner: junit5 or testng
- Linter: checkstyle or spotless
- Type Checker: javac (compile-time verification)
- Coverage Target: From config (default 85%)

## Quality Gates
- ✅ All tests must pass
- ✅ Coverage must meet config threshold (default: 85%)
- ✅ Linter checks must pass with zero errors
- ✅ Type checker must report no critical issues
- ✅ Code review by manager-quality agent
```

**Sync Report Example with Phase 0.5 Results:**
```markdown
# Sync Report: SPEC-001

## Phase 0.5: Quality Verification (Language: Python)
### Test Execution (pytest)
- Tests run: 47 passed, 0 failed
- Execution time: 2.3 seconds
- ✅ All tests passing

### Code Coverage (pytest-cov)
- Overall: 87.5% (target: 85%)
- New code: 92.3%
- Critical paths: 100%
- ✅ Coverage target met

### Linting (ruff)
- Files checked: 12
- Issues found: 0 errors, 0 warnings
- ✅ Linting passed

### Type Checking (mypy)
- Files checked: 12
- Type errors: 0
- ✅ Type checking passed

### Code Review (manager-quality agent)
- TRUST 5 compliance: ✅ PASSED
- Security scan: 0 vulnerabilities
- Code complexity: 7.2/10 (acceptable)
- ✅ Quality review passed

## Files Updated
- README.md: Added authentication section
- docs/api/auth.md: Generated API documentation
- .moai/specs/SPEC-001/spec.md: Updated implementation status

## Quality Metrics (TRUST 5)
- ✅ Test: 87.5% coverage (target: 85%)
- ✅ Readable: Complexity score 7.2/10
- ✅ Unified: Follows project patterns
- ✅ Secured: No security vulnerabilities
- ✅ Trackable: Git history complete

## Deployment Readiness
- ✅ All quality gates passed
- ✅ Documentation synchronized
- ✅ Ready for merge to main branch
```

**Supported Languages and Tools Matrix:**
| Language     | Test Runner          | Linter              | Type Checker        |
|--------------|---------------------|---------------------|---------------------|
| Python       | pytest              | ruff                | mypy                |
| TypeScript   | jest/vitest         | eslint              | tsc                 |
| JavaScript   | jest/vitest         | eslint              | -                   |
| Go           | go test             | golangci-lint       | go vet              |
| Rust         | cargo test          | clippy              | cargo check         |
| Ruby         | rspec/minitest      | rubocop             | sorbet              |
| Java         | junit5              | checkstyle          | javac               |
| PHP          | phpunit             | phpcs               | phpstan             |
| Kotlin       | junit               | ktlint              | kotlinc             |
| Swift        | xctest              | swiftlint           | swift build         |
| C#           | xunit               | dotnet format       | dotnet build        |
| C++          | googletest          | clang-tidy          | clang               |
| Elixir       | exunit              | credo               | dialyzer            |
| R            | testthat            | lintr               | -                   |
| Flutter/Dart | flutter test        | dart analyze        | dart analyze        |
| Scala        | scalatest           | scalafmt            | scalac              |

---

## Agent Delegation Patterns

Delegate tasks to 28 specialized AI agents through explicit Task() calls with enhanced context propagation

```python
# Domain Expert Agents (10 agents)
# Backend API development
use_agent = "expert-backend"
prompt = """
Implement RESTful API endpoints for user management:
- POST /users (create user with validation)
- GET /users/{id} (retrieve user by ID)
- PUT /users/{id} (update user data)
- DELETE /users/{id} (soft delete user)

Requirements:
- FastAPI with Pydantic models
- PostgreSQL with SQLAlchemy ORM
- Password hashing with bcrypt
- JWT authentication middleware
- 90%+ test coverage
"""

# Frontend component creation
use_agent = "expert-frontend"
prompt = """
Create reusable React login form component:
- Email and password input fields with validation
- Remember me checkbox with localStorage
- Error state handling with user-friendly messages
- Loading state during authentication
- Accessibility (ARIA labels, keyboard navigation)
- Responsive design (mobile-first)
"""

# Database schema design
use_agent = "expert-database"
prompt = """
Design PostgreSQL schema for multi-tenant SaaS:
- Users table with role-based access control
- Organizations table with subscription tiers
- Audit logging for compliance
- Indexes for query optimization
- Foreign key constraints and cascading deletes
"""

# Performance optimization
use_agent = "expert-performance"
prompt = """
Optimize application response time:
- Profile API endpoints to identify bottlenecks
- Implement caching strategy (Redis)
- Optimize database queries (N+1 problem)
- Add connection pooling
- Target: < 200ms average response time
"""

# Testing strategy design
use_agent = "expert-testing"
prompt = """
Design comprehensive test strategy:
- Unit tests for business logic (85%+ coverage)
- Integration tests for API endpoints
- E2E tests for critical user flows
- Performance tests for load handling
- Security tests for vulnerability scanning
"""

# Workflow Manager Agents (8 agents)
# TDD implementation cycle with language detection
use_agent = "manager-tdd"
prompt = """
Implement SPEC-001 user authentication:
Follow RED-GREEN-REFACTOR cycle:
1. Write failing tests for all acceptance criteria
2. Implement minimal code to pass tests
3. Refactor for performance and maintainability
Target: 85%+ test coverage, all tests passing
Language: Auto-detect and use appropriate tools
"""

# Code quality validation with multi-language support
use_agent = "manager-quality"
prompt = """
Review authentication module for TRUST 5 compliance:
- Test: Verify coverage meets 85% threshold
- Readable: Check complexity and documentation
- Unified: Ensure pattern consistency
- Secured: Scan for vulnerabilities
- Trackable: Validate Git history
Language: Auto-detect and run appropriate linters/checkers
"""

# Documentation generation with context propagation
use_agent = "manager-docs"
prompt = """
Generate technical documentation for payment API:
- API endpoint reference with request/response examples
- Integration guide with code samples
- Error handling and troubleshooting
- Security considerations
- Webhook implementation guide
- Multi-language code examples
"""

# SPEC creation with EARS official grammar
use_agent = "manager-spec"
prompt = """
Create SPEC for payment processing system:
- Use EARS Official Grammar Patterns (2025 standard)
- Include all 5 pattern types (Ubiquitous, Event-Driven, State-Driven, Unwanted, Optional)
- Define clear acceptance criteria
- Specify technical implementation details
- Create comprehensive test scenarios
"""
```

---

## Skill System Integration

Load specialized knowledge modules for domain-specific tasks with enhanced 16-language support

```python
# Foundation Skills
# Core MoAI-ADK principles
skill_name = "moai-foundation-core"
# Provides: SPEC-First TDD, TRUST 5, delegation patterns, execution rules

# Claude Code integration patterns
skill_name = "moai-foundation-claude"
# Provides: Agent creation, slash commands, hooks, IAM rules, memory management

# Quality assurance framework
skill_name = "moai-foundation-quality"
# Provides: TRUST 5 validation, proactive analysis, 16-language verification

# Language Skills (16 Languages)
# Python development (3.11-3.14)
skill_name = "moai-lang-python"
# Covers: FastAPI, Django, async patterns, pytest, ruff, mypy

# TypeScript development (5.9+)
skill_name = "moai-lang-typescript"
# Covers: React 19, Next.js 16, tRPC, Zod, jest, eslint, tsc

# JavaScript development (ES2024+)
skill_name = "moai-lang-javascript"
# Covers: Node.js 22, Express, Fastify, Hono, vitest, eslint

# Go development (1.23+)
skill_name = "moai-lang-go"
# Covers: Fiber, Gin, GORM, go test, golangci-lint, go vet

# Rust development (1.91+)
skill_name = "moai-lang-rust"
# Covers: Axum, Tokio, SQLx, cargo test, clippy, cargo check

# Ruby development (3.3+)
skill_name = "moai-lang-ruby"
# Covers: Rails 8, ActiveRecord, Hotwire, rspec, rubocop

# Java development (21 LTS)
skill_name = "moai-lang-java"
# Covers: Spring Boot 3.3, virtual threads, junit5, checkstyle

# PHP development (8.3+)
skill_name = "moai-lang-php"
# Covers: Laravel 11, Symfony 7, phpunit, phpcs, phpstan

# Kotlin development (2.0+)
skill_name = "moai-lang-kotlin"
# Covers: Ktor, coroutines, Compose Multiplatform, junit, ktlint

# Swift development (6+)
skill_name = "moai-lang-swift"
# Covers: SwiftUI, Combine, Swift concurrency, xctest, swiftlint

# C# development (12/.NET 8)
skill_name = "moai-lang-csharp"
# Covers: ASP.NET Core, Entity Framework, xunit, dotnet format

# C++ development (C++23/20)
skill_name = "moai-lang-cpp"
# Covers: RAII, smart pointers, concepts, googletest, clang-tidy

# Elixir development (1.17+)
skill_name = "moai-lang-elixir"
# Covers: Phoenix 1.7, LiveView, Ecto, exunit, credo, dialyzer

# R development (4.4+)
skill_name = "moai-lang-r"
# Covers: tidyverse, ggplot2, Shiny, testthat, lintr

# Flutter development (3.24+/Dart 3.5+)
skill_name = "moai-lang-flutter"
# Covers: Riverpod, go_router, flutter test, dart analyze

# Scala development (3.4+)
skill_name = "moai-lang-scala"
# Covers: Akka, Cats Effect, ZIO, scalatest, scalafmt

# Domain Skills
# Backend development patterns
skill_name = "moai-domain-backend"
# Covers: API design, microservices, authentication, caching, message queues

# Frontend development patterns
skill_name = "moai-domain-frontend"
# Covers: React 19, Next.js 16, Vue 3.5, state management, component architecture

# Database design and optimization
skill_name = "moai-domain-database"
# Covers: PostgreSQL, MongoDB, Redis, schema design, query optimization

# UI/UX design systems
skill_name = "moai-domain-uiux"
# Covers: Accessibility, design systems, component libraries, theming

# Library Skills
# Mermaid diagram generation
skill_name = "moai-library-mermaid"
# Provides: Flowcharts, sequence diagrams, class diagrams, state machines

# Nextra documentation framework
skill_name = "moai-library-nextra"
# Provides: Next.js docs, MDX components, i18n, deployment patterns

# Shadcn UI components
skill_name = "moai-library-shadcn"
# Provides: Component installation, theming, customization, optimization

# Platform Skills
# Supabase integration
skill_name = "moai-platform-supabase"
# Covers: PostgreSQL 16, pgvector, RLS, real-time, Edge Functions

# Auth0 integration
skill_name = "moai-platform-auth0"
# Covers: SSO, SAML, OIDC, organizations, B2B multi-tenancy

# Clerk integration
skill_name = "moai-platform-clerk"
# Covers: WebAuthn, passkeys, passwordless, modern UI components

# Neon integration
skill_name = "moai-platform-neon"
# Covers: Auto-scaling, database branching, PITR, connection pooling

# Vercel integration
skill_name = "moai-platform-vercel"
# Covers: Edge Functions, Next.js optimization, ISR, preview deployments

# Railway integration
skill_name = "moai-platform-railway"
# Covers: Docker, multi-service architectures, persistent volumes, auto-scaling

# Workflow Skills
# Just-in-time documentation loading
skill_name = "moai-workflow-jit-docs"
# Provides: Dynamic doc loading, context-aware caching, intent detection

# Testing and quality assurance
skill_name = "moai-workflow-testing"
# Provides: TDD workflows, debugging, performance optimization, code review

# Git worktree management
skill_name = "moai-worktree"
# Provides: Parallel SPEC development, isolated workspaces, automatic registration
```

---

## Git Worktree Management

Manage parallel SPEC development with isolated workspaces using enhanced worktree system

```bash
# List all registered worktrees
moai-worktree list

# Create new worktree for SPEC
moai-worktree new SPEC-002 "Payment Integration"

# Navigate to worktree directory
moai-worktree go SPEC-002

# Show worktree status
moai-worktree status SPEC-002

# Sync worktree with main branch
moai-worktree sync SPEC-002

# Sync with automatic conflict resolution
moai-worktree sync SPEC-002 --auto-resolve

# Sync all worktrees
moai-worktree sync --all --auto-resolve

# Remove worktree after merging
moai-worktree remove SPEC-002

# Clean merged worktrees
moai-worktree clean --merged-only

# Interactive cleanup
moai-worktree clean --interactive

# Validate worktree integrity
moai-worktree validate
```

**Worktree Registry (.moai/worktrees/registry.json):**
```json
{
  "worktrees": [
    {
      "spec_id": "SPEC-002",
      "path": "/Users/dev/project-worktrees/SPEC-002",
      "branch": "feature/SPEC-002-payment-integration",
      "created_at": "2024-01-15T10:30:00Z",
      "status": "active",
      "description": "Payment Integration",
      "last_commit": "abc123d"
    }
  ],
  "registry_version": "1.0",
  "last_updated": "2024-01-15T10:30:00Z"
}
```

---

## Configuration Management with Smart Question System

Centralized project configuration with language and user settings using interactive Smart Questions

```bash
# Initialize project with Smart Question System (NEW in v0.34.0)
> /moai:0-project

# Smart Questions guide you through:
# 1. Project Information (name, description, version)
# 2. User Configuration (name, email)
# 3. Language Settings (conversation, code, docs)
# 4. Programming Languages (primary, frameworks)
# 5. Quality Standards (coverage threshold, complexity limits)
# 6. Git Strategy (mode, auto-commit, branch naming)

# Configuration structure (.moai/config/sections/)
sections/
  ├── user.yaml          # User name and email
  ├── language.yaml      # All language preferences
  ├── project.yaml       # Project metadata
  ├── git-strategy.yaml  # Git workflow configuration
  ├── quality.yaml       # TDD and quality settings
  └── system.yaml        # MoAI system settings
```

**Example Configuration (config.yaml merged view):**
```yaml
project:
  name: "MyApp"
  mode: "personal"
  version: "0.34.0"
  created_at: "2024-01-15T09:00:00Z"

user:
  name: "Developer"
  email: "dev@example.com"

language:
  conversation_language: "en"
  conversation_language_name: "English"
  agent_prompt_language: "en"
  git_commit_messages: "en"
  code_comments: "en"
  documentation: "en"
  error_messages: "en"

programming_languages:
  primary: "python"
  detected: ["python", "javascript", "typescript"]
  frameworks: ["fastapi", "react", "nextjs"]

constitution:
  enforce_tdd: true
  test_coverage_target: 85
  complexity_max: 10
  security_scan_enabled: true

git_strategy:
  mode: "personal"
  auto_commit: false
  commit_message_format: "conventional"
  branch_prefix: "feature/SPEC-"
  branch_creation:
    prompt_always: false
    auto_enabled: true
```

---

## Hook System Integration

Event-driven hooks for session management and document automation with enhanced error handling

```python
# Session Start Hook (.claude/hooks/moai/session_start__show_project_info.py)
#!/usr/bin/env python3
"""Display project information at session start"""

from pathlib import Path
from lib.config_manager import load_config
from lib.project import get_project_stats

def main():
    config = load_config(Path.cwd() / ".moai/config/sections")
    stats = get_project_stats()

    print(f"🗿 MoAI-ADK Project: {config['project']['name']}")
    print(f"📊 SPECs: {stats['specs_total']} ({stats['specs_completed']} completed)")
    print(f"✅ Test Coverage: {stats['test_coverage']}%")
    print(f"🌍 Language: {config['language']['conversation_language_name']}")
    print(f"🔧 Primary Language: {config['programming_languages']['primary']}")

if __name__ == "__main__":
    main()

# Document Management Hook (.claude/hooks/moai/pre_tool__document_management.py)
#!/usr/bin/env python3
"""Auto-sync documentation when files change"""

from lib.git_operations_manager import GitOpsManager
from lib.checkpoint import CheckpointManager

def should_sync_docs(modified_files):
    """Check if documentation sync is needed"""
    code_extensions = ['.py', '.js', '.ts', '.jsx', '.tsx', '.go', '.rs',
                       '.rb', '.java', '.php', '.kt', '.swift', '.cs', '.cpp']
    return any(file.endswith(tuple(code_extensions)) for file in modified_files)

def main():
    git_ops = GitOpsManager()
    modified = git_ops.get_modified_files()

    if should_sync_docs(modified):
        checkpoint = CheckpointManager()
        checkpoint.create("pre-doc-sync")
        # Trigger documentation sync with Phase 0.5 quality verification
        print("📝 Documentation sync with quality verification recommended")

if __name__ == "__main__":
    main()
```

---

## Quality Assurance System with Multi-Language Support

TRUST 5 framework for enterprise-grade quality validation across 16 languages

```python
# Test Coverage Validation with Language Detection
from moai_adk.core.quality.trust_checker import TrustChecker

checker = TrustChecker(
    coverage_threshold=85.0,
    complexity_max=10,
    security_enabled=True,
    language="auto"  # Auto-detect language (NEW)
)

# Run TRUST 5 validation with language-specific tools
results = checker.validate_all(project_path=".")

print(f"Detected Language: {results.language}")
# Output: Detected Language: python

print(f"Test Coverage: {results.test_coverage}% (target: 85%)")
# Output: Test Coverage: 87.5% (target: 85%)

print(f"Readable: Complexity {results.complexity_score}/10")
# Output: Readable: Complexity 7.2/10

print(f"Unified: Pattern compliance {results.pattern_compliance}%")
# Output: Unified: Pattern compliance 95%

print(f"Secured: {results.vulnerabilities_found} vulnerabilities")
# Output: Secured: 0 vulnerabilities

print(f"Trackable: Git history complete {results.git_complete}")
# Output: Trackable: Git history complete True

# Language-specific tool execution (NEW)
print(f"Test Runner: {results.test_runner}")
# Output: Test Runner: pytest

print(f"Linter: {results.linter}")
# Output: Linter: ruff

print(f"Type Checker: {results.type_checker}")
# Output: Type Checker: mypy

# Individual component validation with language detection
test_result = checker.validate_test_coverage("src/auth/")
if test_result.passed:
    print("✅ Test coverage meets standards")
else:
    print(f"❌ Coverage {test_result.coverage}% below threshold {test_result.threshold}%")

# Security scan with multi-language support
security_result = checker.validate_security("src/")
for vuln in security_result.vulnerabilities:
    print(f"🔒 {vuln.severity}: {vuln.description} in {vuln.file}:{vuln.line}")

# Multi-language quality verification example
languages = ["python", "typescript", "go", "rust"]
for lang in languages:
    lang_checker = TrustChecker(language=lang)
    result = lang_checker.validate_all(f"projects/{lang}-project")
    print(f"{lang}: Coverage {result.test_coverage}%, Tools: {result.test_runner}/{result.linter}")
```

---

## MCP Server Integration

Connect to Model Context Protocol servers for enhanced capabilities

```json
{
  "mcpServers": {
    "context7": {
      "command": "npx",
      "args": ["-y", "@upstairs/mcp-server-context7"],
      "env": {
        "CONTEXT7_API_KEY": "${CONTEXT7_API_KEY}"
      }
    },
    "figma": {
      "command": "npx",
      "args": ["-y", "@figma/mcp-server-figma"],
      "env": {
        "FIGMA_ACCESS_TOKEN": "${FIGMA_ACCESS_TOKEN}"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp-server"],
      "env": {}
    },
    "sequential-thinking": {
      "command": "npx",
      "args": ["-y", "@sequential-thinking/mcp-server"],
      "env": {}
    }
  }
}
```

**Using MCP Agents:**
```python
# Context7 for latest documentation with version compatibility
use_agent = "mcp-context7"
prompt = "Research latest FastAPI 0.115 async patterns and security best practices"

# Figma for design-to-code with component extraction
use_agent = "mcp-figma"
prompt = "Extract component specifications from Figma design file ABC123 with design tokens"

# Playwright for E2E testing with screenshot validation
use_agent = "mcp-playwright"
prompt = "Create E2E test suite for user registration flow with visual regression testing"

# Sequential-Thinking for complex analysis with trade-off evaluation
use_agent = "mcp-sequential-thinking"
prompt = "Analyze trade-offs between microservices vs monolithic architecture for our use case"
```

---

## Error Recovery and Debugging

Systematic error handling with specialized debug agent and multi-language support

```bash
# Debug agent automatically invoked on errors
# Agent execution errors → expert-debug troubleshoots issues
# Token limit errors → /clear refreshes context
# Permission errors → system-admin checks settings
# Integration errors → integration-specialist resolves component issues
```

**Debug Agent Example with Language Detection:**
```python
# Automatic error analysis with language-specific diagnostics
use_agent = "expert-debug"
prompt = """
Analyze authentication test failure:
Error: AssertionError: Expected 200, got 401
Test: test_user_login_success
File: tests/test_auth.py:45
Language: Python (FastAPI)

Stack trace:
  File "tests/test_auth.py", line 45, in test_user_login_success
    assert response.status_code == 200
  File "src/auth/routes.py", line 23, in login
    raise HTTPException(status_code=401)

Context:
- Database connected: Yes
- Test user exists: Yes
- Password hash verification: Failed
- Test runner: pytest
- Framework: FastAPI

Investigate root cause and provide fix with explanation.
Include language-specific debugging techniques.
"""

# Expected output:
# Root cause: Password hash algorithm mismatch (bcrypt vs argon2)
# Solution: Standardize on bcrypt throughout codebase
# Files to modify: src/auth/utils.py, src/models/user.py
# Test verification: Update 3 test cases
# Language-specific tip: Use FastAPI's dependency injection for password hashing
```

---

## GLM Integration for Cost Savings (NEW)

Configure MoAI-ADK to use GLM 4.6 through z.ai for 70% cost reduction

```bash
# Enable GLM mode with API token
> /moai:0-project --glm-on YOUR_API_TOKEN

# Or enable interactively (prompts for token)
> /moai:0-project --glm-on

# Disable GLM (switch back to Claude)
> /moai:0-project --glm-off

# GLM Coding Plan subscription (cost-effective alternative)
# Subscribe: https://z.ai/subscribe?ic=1NDV03BGWU
# Plans: Lite ($6/month), Pro ($30/month), Max ($60/month)
# Benefits: 3x-20x usage, 40-60% faster (Pro+), Vision & Web features
```

**GLM Configuration (.claude/settings.local.json):**
```json
{
  "env": {
    "ANTHROPIC_AUTH_TOKEN": "your_glm_token_here",
    "ANTHROPIC_BASE_URL": "https://api.z.ai/api/anthropic",
    "ANTHROPIC_DEFAULT_HAIKU_MODEL": "glm-4.5-air",
    "ANTHROPIC_DEFAULT_SONNET_MODEL": "glm-4.6",
    "ANTHROPIC_DEFAULT_OPUS_MODEL": "glm-4.6"
  }
}
```

**Performance Comparison:**
| Task                        | Claude 4.5 Sonnet | GLM 4.6       | Cost Savings |
|-----------------------------|-------------------|---------------|--------------|
| Code Generation             | Excellent         | Excellent     | 70% cheaper  |
| TDD Implementation          | Excellent         | Very Good     | 70% cheaper  |
| Documentation Writing       | Very Good         | Good          | 70% cheaper  |
| Complex Problem Solving     | Excellent         | Very Good     | 70% cheaper  |
| API Rate Limits            | Moderate          | 3x-20x higher | Flexible     |
| Performance Speed (Pro+)   | Fast              | 40-60% faster | Significant  |

---

MoAI-ADK provides a comprehensive development framework that eliminates 90% of requirement-related rework through SPEC-First methodology, guarantees 85%+ test coverage through TDD enforcement with 16-language support, and saves 60-70% development time through intelligent AI agent orchestration. The framework integrates seamlessly with modern development tools, supports 16+ programming languages with language-specific quality verification, and provides enterprise-grade quality assurance through the TRUST 5 framework with Phase 0.5 automated checks.

Use MoAI-ADK for projects requiring high quality standards, clear documentation, comprehensive testing, and scalable agent-based workflows with multi-language support. The framework excels in team environments with complex requirements, multi-language codebases, and strict compliance needs. Integration with MCP servers extends capabilities to design-to-code workflows, browser automation, real-time documentation access, and complex analytical reasoning. The new Smart Question System simplifies project initialization, while Phase 0.5 quality verification ensures consistent quality across Python, TypeScript, JavaScript, Go, Rust, Ruby, Java, PHP, Kotlin, Swift, C#, C++, Elixir, R, Flutter/Dart, and Scala projects. GLM integration offers cost-effective alternative with 70% savings while maintaining full development productivity.