github.com/modu-ai/moai-adk

Summary

This patch release resolves critical PATH environment variable issues affecting Claude Code native installations and completes the Alfred → MoAI rebranding. It also consolidates the architecture by removing MoAI-GO and unifying on Python.

Key Changes:

• Critical Fixes: PATH environment variable configuration for isolated environments (#318, #319)
• Rebranding Complete: All "Alfred" references replaced with "MoAI"
• Architecture Simplification: Removed MoAI-GO, Python-only implementation
• Bug Fixes: Hook migration report output corrected

Fixed

PATH Environment Issues (#318, #319)

• fix: Resolve PATH environment variable issues in isolated environments (877a36ad)
  • Added system paths to settings.json template env section
  • Fixed expert-chrome-extension.md to use standard template variables ({{HOOK_SHELL_PREFIX}})
  • Added PATH merge logic in merger.py to preserve user custom paths during updates
  • Improved shell detection in hook_context.py (check absolute paths before PATH-based lookup)
  • Impact: Fixes plugin loading failures, hook execution errors, and SSH command not found issues
  • Platforms: macOS, Linux, WSL, Windows

Hook Output

• fix: Send migration report to stderr to prevent JSON parse error (36e39f25)
  • Redirects migration report output to stderr, keeping stdout clean for JSON data
  • Follows Unix conventions (data to stdout, logs to stderr)

Changed

Complete Alfred → MoAI Rebranding

• refactor: Complete Alfred → MoAI rebranding cleanup (f78ffdb9, ef3a678c, b31dc3f6)
  • Output style: outputStyle: "Alfred" → outputStyle: "MoAI"
  • Output style files: .claude/output-styles/moai/alfred.md → .claude/output-styles/moai/moai.md
  • Agent definitions: All references to "Alfred" replaced with "MoAI"
  • Hooks, skills, commands: Updated across 177+ files
  • Tests: Updated statusline tests for MoAI branding
  • Breaking Change: Users with custom configurations referencing "Alfred" should update to "MoAI"

Architecture Consolidation

• refactor: Remove MoAI-GO and consolidate to Python-based implementation (d23f6ece, bd6995a2, 838faa20)
  • Removed entire MoAI-GO subsystem (Golang implementation)
  • Consolidated all functionality to Python codebase
  • Simplified maintenance and security surface
  • Note: MoAI-GO was experimental; no user-facing features removed

Dependencies

• chore: Update uv.lock with version 1.14.0 (cca6b545)

Installation & Update

# Update to the latest version
uv tool update moai-adk

# Update project templates in your folder
moai update

# Verify version
moai --version

Summary

Major refactoring release migrating the entire design tooling stack from Google Stitch MCP and Figma to Pencil MCP (.pen files). This consolidation simplifies the design workflow and empowers expert-frontend to handle UI/UX design directly.

Key Changes:

• Design Tool Migration: Complete replacement of Stitch/Figma with Pencil MCP for design-to-code workflows
• Simplified Architecture: Removed expert-stitch agent, consolidated into expert-frontend (Expert Agents: 9 → 8)
• Pencil MCP Integration: Added 14 Pencil MCP tools with comprehensive documentation
• Chrome Extension: Includes v1.13.0 Chrome Extension platform skill (previously untagged)

Breaking Changes

⚠️ Stitch MCP Removal: The moai-platform-stitch skill and expert-stitch agent have been removed. Projects using Google Stitch should migrate to Pencil MCP.

Migration Guide:

• Replace .stitch files with .pen files
• Update design references from expert-stitch to expert-frontend
• Remove Stitch MCP server from .mcp.json
• See Pencil MCP documentation for migration details

Added

Pencil MCP Design Integration

• refactor: Replace Stitch/Figma with Pencil MCP for UI/UX design (acfdc794)
  • Pencil MCP Tools (14 tools added to expert-frontend):
    • batch_design: Execute multiple insert/copy/update/replace/move/delete operations
    • batch_get: Retrieve nodes by patterns or IDs in batches
    • get_editor_state: Determine active .pen file and user selection
    • get_guidelines: Design guidelines for code, tables, Tailwind, landing pages
    • get_screenshot: Capture visual screenshots of .pen file nodes
    • get_style_guide: Retrieve style guides by tags or name for design inspiration
    • get_style_guide_tags: List available style guide tags
    • get_variables: Extract design tokens and themes from .pen files
    • set_variables: Add or update variables in .pen files
    • open_document: Create new or open existing .pen files
    • snapshot_layout: Check computed layout rectangles for node insertion
    • find_empty_space_on_canvas: Find empty space for new elements
    • search_all_unique_properties: Recursively search node properties
    • replace_all_matching_properties: Bulk property updates
  • Comprehensive Workflow Guide: Added "UI/UX Design with Pencil MCP" section to expert-frontend.md
    • 5-step design workflow: Initialize → Style Foundation → Design Creation → Iteration → Code Export
    • Variables and Design Tokens guide
    • Available UI Kits: Shadcn UI, Halo, Lunaris, Nitro
    • Best practices for prompting, file management, design-to-code
  • Design Philosophy: .pen files are JSON-based, Git-friendly, human-readable design-as-code format
  • Integration: Pencil MCP auto-starts with IDE extension/desktop app (no .mcp.json entry needed)

Chrome Extension Platform (from v1.13.0)

• feat: Add Chrome Extension platform skill and agent (be0ec50e)
  • Skill: moai-platform-chrome-extension with 8 modular guides
  • Agent: expert-chrome-extension for specialized development
  • Coverage: Manifest V3, service workers, content scripts, message passing, chrome.* APIs, security, publishing

Changed

Design Tool Architecture

• Removed: moai-platform-stitch skill directory (template + local)
• Removed: expert-stitch agent from agent catalog
• Updated: Expert Agents count from 9 to 8
• Updated: expert-frontend now handles UI/UX design directly
• Updated: All Figma/Stitch references replaced with Pencil MCP across:
  • Agent definitions: expert-frontend, manager-docs, manager-spec, manager-strategy
  • Skills: moai-domain-uiux, moai-foundation-core, moai-foundation-claude
  • Configurations: multilingual-triggers.yaml (4 languages), CLAUDE.md, README.zh.md
• Removed: Stitch MCP server from .mcp.json (all platforms: macOS, Windows)

Installation & Update

# Update to the latest version
uv tool update moai-adk

# Update project templates in your folder
moai update

# Verify version
moai --version

Summary

Feature release adding comprehensive Chrome Extension Manifest V3 development support.

Key Features:

• Chrome Extension Platform: Full Manifest V3 development support with service workers, content scripts, and chrome.* APIs
• Expert Agent: New expert-chrome-extension agent for specialized extension development
• Comprehensive Documentation: 8 modular guides covering APIs, security, publishing, and best practices

Breaking Changes

None. This is a backward-compatible feature addition.

Added

Chrome Extension Platform Skill

• feat: Add Chrome Extension platform skill and agent (be0ec50e)
  • Skill: moai-platform-chrome-extension with 8 modular guides
    • Manifest V3 reference and configuration
    • Service Worker patterns and lifecycle management
    • Content Scripts injection and communication
    • Message passing patterns (one-time, long-lived, native)
    • chrome.* APIs quick reference (storage, tabs, runtime, permissions)
    • Security and CSP configuration
    • UI components (popup, options, side panel)
    • Publishing and Chrome Web Store submission
  • Agent: expert-chrome-extension for specialized development
  • Coverage: Service workers, content scripts, message passing, chrome.* APIs, security, publishing
  • Integration: Seamless integration with MoAI-ADK workflow
  • Dependencies: Updated uv.lock for package consistency

Installation & Update

# Update to the latest version
uv tool update moai-adk

# Update project templates in your folder
moai update

# Verify version
moai --version

Summary

Bug fix release resolving statusLine command overwrite issue during moai-adk update.

Key Fix:

• StatusLine Update: Fixed _update_statusline_command() incorrectly replacing template-substituted statusLine commands
• Impact: StatusLine now consistently includes PATH augmentation, ensuring reliable moai-adk statusline execution
• Scope: Template variable detection and command generation logic

Breaking Changes

None. This is a backward-compatible bug fix.

Fixed

StatusLine Template Substitution Overwrite

• fix: Resolve statusLine template substitution overwrite issue (2afba5d7)
  • Issue: _update_statusline_command() replaced valid template-substituted commands
  • Root cause: Detection logic only accepted ${SHELL} literal, not actual shell paths like /bin/zsh -l -c
  • Fix: Updated detection to accept both ${SHELL} variable and login shell indicator (-l -c)
  • Enhancement: Use build_hook_context() for command generation (same as hooks)
  • Consistency: StatusLine now uses identical format to hooks (includes _PATH_AUGMENT)
  • Files modified:
    • update.py: Updated _update_statusline_command() detection and generation logic
  • Impact: StatusLine commands now match hook format with proper PATH augmentation

Installation & Update

# Update to the latest version
uv tool update moai-adk

# Update project templates in your folder
moai update

# Verify version
moai --version

Summary

Critical bug fix release resolving JSON parsing failure during moai-adk update on macOS, Linux, and WSL systems.

Key Fix:

• Template Sync: Fixed JSON parsing error when HOOK_SHELL_PREFIX contains shell syntax with quotes
• Impact: All users on macOS/Linux/WSL can now run moai update successfully
• Scope: Template variable substitution system

Breaking Changes

None. This is a backward-compatible bug fix.

Fixed

Template Sync JSON Parsing Error

• fix: Resolve JSON parsing error in template sync (058a9e46)
  • Issue: moai-adk update failed with Expecting ',' delimiter: line 9 column 55 error
  • Root cause: Unescaped quotes in _PATH_AUGMENT (export PATH="$HOME/...") broke JSON when substituted into settings.json
  • Fix: Removed unnecessary quotes from _PATH_AUGMENT (PATH values have no spaces)
  • Enhancement: Added json_safe parameter to _substitute_variables() for JSON-aware escaping using json.dumps()
  • WSL support: Handles _WSL_PATH_NORMALIZE with quotes correctly
  • Files modified:
    • hook_context.py: Simplified _PATH_AUGMENT from 'export PATH="$HOME/..."' to "export PATH=$HOME/..."
    • processor.py: Added JSON escaping with json.dumps()[1:-1] when json_safe=True
    • update.py: Applied JSON-safe escaping to .json files
  • Testing: 80/80 unit tests passing, verified with actual HOOK_SHELL_PREFIX values
  • Impact: Template sync now works correctly on all platforms (macOS/Linux/WSL)

Installation & Update

# Update to the latest version
uv tool update moai-adk

# Update project templates in your folder
moai update

# Verify version
moai --version

Summary

Experimental release introducing MoAI-GO, a high-performance Go-based CLI implementation, alongside critical UTF-8 encoding fixes for Windows compatibility.

Key Features:

• MoAI-GO System: Experimental Go implementation (Phases 1-4) for performance evaluation
• UTF-8 Encoding: Comprehensive UTF-8 encoding fixes for Windows (#314, #316)
• Cross-Platform: Improved PATH handling and hook execution

Note: MoAI-GO is experimental. Production use still relies on Python implementation.

Breaking Changes

None. All changes are backward compatible.

Added

MoAI-GO Experimental System

• feat(go): Implement MoAI-GO Phase 1 - Foundation and configuration system (b36ddd66)

  • Go-based configuration management
  • Cross-platform compatibility layer
  • Performance-optimized file operations

• feat(go): Implement MoAI-GO Phase 2 - Hook system with Python compatibility (f3e75202)

  • Go-based hook execution engine
  • Backward compatible with Python hooks
  • Improved hook performance

• feat(go): Implement MoAI-GO Phase 3 - CLI commands with direct binary paths (e47534d0)

  • Go-based CLI commands: rank, switch, worktree
  • Direct binary execution (no Python interpreter needed)
  • Cross-platform PATH handling improvements

• feat(go): Implement MoAI-GO Phase 4 - Distribution and migration system (d61f381d)

  • Binary distribution system
  • Migration tools from Python to Go
  • Version compatibility checks

• feat: Add MoAI-GO CLI commands (rank, switch, worktree) and improve cross-platform PATH handling (05d7b7be)

  • Integrated CLI commands with improved performance
  • Enhanced PATH resolution for Windows/macOS/Linux
  • Automatic binary fallback to Python implementation

Fixed

UTF-8 Encoding Issues

• fix: Add UTF-8 encoding to all hook scripts and file operations (33c0a483)

  • Fixed UTF-8 encoding in all .claude/hooks/moai/*.py files
  • Added explicit encoding='utf-8' to all file operations
  • Ensures correct handling of non-ASCII characters

• fix: Resolve cross-platform hook/encoding/credential issues (#314, #316) (bf280eeb)

  • Issue #314: Hook execution failures on Windows due to encoding
  • Issue #316: Credential file corruption with non-ASCII characters
  • Fix: Consistent UTF-8 encoding across all platforms
  • Impact: Windows users can now use hooks without encoding errors

• fix(cli): Resolve Windows UTF-8 encoding error on moai init (894abd3e)

  • Issue: moai init failed on Windows with UnicodeEncodeError
  • Root cause: Console output encoding mismatch
  • Fix: Force UTF-8 encoding for all console output
  • Impact: moai init now works correctly on Windows

Changed

Go Module Restructure

• refactor: Restructure Go module path to github.com/modu-ai/moai-adk/go (97be74a7)

  • Aligned Go module path with repository structure
  • Improved import clarity for Go developers
  • Prepared for future Go module distribution

• revert: Undo Go module restructure (testing needed) (324097d1)

  • Reverted Go module path change for further testing
  • Ensures stability before finalizing module structure

• refactor: Rename moai-adk to moai (2b9bf0e1)

  • Internal renaming for consistency
  • Updated import statements
  • Aligned with unified branding

Installation & Update

# Update to the latest version
uv tool update moai-adk

# Update project templates in your folder
moai update

# Verify version
moai --version