moai-adk 0.9.0__py3-none-any.whl → 0.15.0__py3-none-any.whl

{moai_adk-0.9.0.dist-info → moai_adk-0.15.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.9.0
+Version: 0.15.0
 Summary: MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent & Complete Skills v2.0
 Project-URL: Homepage, https://github.com/modu-ai/moai-adk
 Project-URL: Repository, https://github.com/modu-ai/moai-adk
@@ -14,17 +14,21 @@ Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Software Development :: Quality Assurance
 Classifier: Topic :: Software Development :: Testing
-Requires-Python: >=3.13
+Requires-Python: >=3.11
 Requires-Dist: click>=8.1.0
 Requires-Dist: gitpython>=3.1.45
+Requires-Dist: jinja2>=3.0.0
 Requires-Dist: packaging>=21.0
 Requires-Dist: pyfiglet>=1.0.2
 Requires-Dist: pyyaml>=6.0
 Requires-Dist: questionary>=2.0.0
+Requires-Dist: requests>=2.28.0
 Requires-Dist: rich>=13.0.0
 Provides-Extra: dev
 Requires-Dist: mypy>=1.7.0; extra == 'dev'
@@ -40,7 +44,7 @@ Description-Content-Type: text/markdown
 
 # MoAI-ADK (Agentic Development Kit)
 
-[한국어](README.ko.md) |[English](README.md) | [ไทย](README.th.md) | [日本語](README.ja.md) | [中文](README.zh.md) | [हिन्दी](README.hi.md)
+[한국어](README.ko.md) | [English](README.md)
 
 [![PyPI version](https://img.shields.io/pypi/v/moai-adk)](https://pypi.org/project/moai-adk/)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -111,7 +115,7 @@ Write SPECs first with the `/alfred:1-plan` command. A vague request like "login
 A single `/alfred:3-sync` command **synchronizes** all code, tests, and documentation. README, CHANGELOG, API docs, and Living Documents all update automatically. Six months later, code and docs still match.
 
 **4️⃣ Tracking with @TAG System**
-Every piece of code, test, and documentation gets a `@TAG:ID`. When requirements change later, one command—`rg "@SPEC:AUTH-001"`—**finds all related tests, implementations, and docs**. You gain confidence during refactoring.
+Every piece of code, test, and documentation gets a `@TAG:ID`. When requirements change later, one command—`rg "@SPEC:EX-AUTH-001"`—**finds all related tests, implementations, and docs**. You gain confidence during refactoring.
 
 **5️⃣ Alfred Remembers Context**
 A team of AI agents collaborate to **remember** your project's structure, decision rationale, and work history. No need to repeat the same questions.
@@ -158,61 +162,364 @@ From the moment you adopt MoAI-ADK, you'll feel:
 
 ---
 
-## 5-Minute Quick Start
+## 🖥️ Platform Support
 
-Now let's start your first project with MoAI-ADK. Follow these 5 steps and in just **5 minutes** you'll have a project with SPEC, TDD, and documentation all connected.
+### Supported Platforms
+- ✅ **macOS** (11.0+)
+- ✅ **Linux** (Ubuntu 20.04+, Debian 11+, etc.)
+- ✅ **Windows** (10/11) - Full support as of v0.11.0
+  - Note: Hooks system requires Python 3.11+
+  - All hook features work seamlessly on Windows with cross-platform timeout handling
 
-### Step 1: Install uv (about 30 seconds)
+### System Requirements
+- **Python**: 3.11 or higher
+- **Git**: 2.30+
+- **GitHub CLI** (`gh`): Optional, required for PR automation in team mode
 
-First, install `uv`. `uv` is an ultra-fast Python package manager written in Rust. It's **10+ times faster** than traditional `pip` and works perfectly with MoAI-ADK.
+---
+
+## ⚡ 3-Minute Lightning Start
+
+Get your first MoAI-ADK project running in **3 simple steps**. Beginners can finish in under 5 minutes.
+
+### Step 1: Install uv (about 1 minute)
+
+#### Command
+
+**Choose your platform**:
 
 ```bash
 # macOS/Linux
 curl -LsSf https://astral.sh/uv/install.sh | sh
 
-# Windows (PowerShell)
+# Windows (PowerShell) - RECOMMENDED FOR WINDOWS USERS
 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 
+# Windows (Git Bash) - Alternative
+curl -LsSf https://astral.sh/uv/install.sh | bash
+
+# WSL (Windows Subsystem for Linux)
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
 # Verify installation
 uv --version
-# Output: uv 0.x.x
 ```
 
-**Why uv?** MoAI-ADK is optimized to leverage uv's fast installation speed and stability. Perfect project isolation means no impact on other Python environments.
+**Platform Selection Guide**:
+
+| Platform | Method | Notes |
+|----------|--------|-------|
+| **macOS** | bash | Native UNIX-based, use standard installation |
+| **Linux** | bash | Native Linux support |
+| **Windows (Native)** | ⭐ PowerShell | **RECOMMENDED** - Most stable, native Windows support |
+| **Windows (Git Bash)** | bash | Alternative if PowerShell unavailable |
+| **WSL** | bash | Use Linux installation within WSL2 |
 
-### Step 2: Install MoAI-ADK (about 1 minute)
+**Important Notes on Windows**:
+- 🟢 **PowerShell (Native)**: Most reliable and stable method. No WSL or Git Bash needed.
+- 🟡 **Git Bash / WSL**: Works, but may encounter path issues. Try PowerShell first.
+- ❌ **Do NOT use WSL if**: You're testing on Windows—PowerShell native is easier and faster.
 
-Install MoAI-ADK as a global tool. This won't affect your project dependencies.
+**Why PowerShell for Windows?**
+- Fewer environment setup issues
+- Better Windows integration
+- Faster execution
+- No WSL overhead
+
+#### Expected Output
+```
+✓ uv 0.5.1 is already installed
+$ uv --version
+uv 0.5.1
+```
+
+#### Next: Install MoAI-ADK
 
 ```bash
-# Install in tool mode (recommended: runs in isolated environment)
 uv tool install moai-adk
 
-# Verify installation
+# Result: ✅ Installed moai-adk v0.14.0
+```
+
+**Verification**:
+```bash
 moai-adk --version
-# Output: MoAI-ADK v1.0.0
+# Output: MoAI-ADK v0.14.0
+```
+
+---
+
+### Step 2: Create Your First Project (about 1 minute)
+
+#### Command
+
+```bash
+moai-adk init hello-world
+cd hello-world
 ```
 
-Once installed, you can use the `moai-adk` command anywhere.
+#### What Gets Created
 
-### Step 3: Create Project (about 1 minute)
+```
+hello-world/
+├── .moai/              ✅ Alfred configuration
+├── .claude/            ✅ Claude Code automation
+├── CLAUDE.md           ✅ Project guide
+└── README.md           ✅ Project documentation
+```
 
-**To start a new project:**
+#### Verification: Check Core Files
 
+```bash
+# Verify core config file exists
+ls -la .moai/config.json  # ✅ Should exist
+ls -la .claude/commands/  # ✅ Should have commands
+
+# Or all at once
+moai-adk doctor
+```
+
+**Expected Output**:
+```
+✅ Python 3.13.0
+✅ uv 0.5.1
+✅ .moai/ directory initialized
+✅ .claude/ directory ready
+✅ 16 agents configured
+✅ 74 skills loaded
+```
+
+---
+
+### Step 3: Start Alfred (about 1 minute)
+
+#### Run Claude Code
+
+```bash
+claude
+```
+
+#### Enter in Claude Code
+
+```
+/alfred:0-project
+```
+
+#### Alfred Will Ask
+
+```
+Q1: Project name?
+A: hello-world
+
+Q2: Project goal?
+A: Learning MoAI-ADK
+
+Q3: Main development language?
+A: python
+
+Q4: Mode?
+A: personal (for local development)
+```
+
+#### Result: Project Ready! ✅
+
+```
+✅ Project initialized
+✅ Config saved to .moai/config.json
+✅ Documents created in .moai/project/
+✅ Alfred recommends skills
+
+Next: Run /alfred:1-plan "your feature description"
+```
+
+---
+
+## Next: Complete Your First Feature in 10 Minutes
+
+You're now ready to build your first complete feature with SPEC, TDD, and auto-generated docs!
+
+> **→ Continue to: ["First 10-Minute Hands-On: Hello World API"](#-first-10-minute-hands-on-hello-world-api)**
+
+In this section you'll experience:
+- ✅ Define an API using SPEC
+- ✅ Complete TDD cycle (RED → GREEN → REFACTOR)
+- ✅ Auto-generate documentation
+- ✅ Understand @TAG system
+
+---
+
+## Language Support
+
+MoAI-ADK automatically detects and supports **15 programming languages** with dedicated CI/CD workflows:
+
+### Core Languages (v0.11.0+)
+- **Python** (pytest, mypy, ruff, 85% coverage target)
+- **JavaScript** (npm/yarn/pnpm/bun auto-detect, 80% coverage target)
+- **TypeScript** (tsc type checking, biome/eslint, 85% coverage target)
+- **Go** (golangci-lint, gofmt, 75% coverage target)
+
+### Extended Languages (v0.11.1+)
+- **Ruby** (RSpec, Rubocop, bundle)
+- **PHP** (PHPUnit, PHPCS, composer)
+- **Java** (JUnit 5, Jacoco, Maven/Gradle auto-detection)
+- **Rust** (cargo test, clippy, rustfmt)
+- **Dart** (flutter test, dart analyze)
+- **Swift** (XCTest, SwiftLint, SPM)
+- **Kotlin** (JUnit 5, ktlint, Gradle)
+- **C#** (xUnit, StyleCop, dotnet CLI)
+- **C** (gcc/clang, cppcheck, CMake)
+- **C++** (g++/clang++, Google Test, cpplint)
+- **Shell** (shellcheck, bats-core)
+
+### How Language Detection Works
+
+When you run `/alfred:2-run SPEC-XXX`, MoAI-ADK automatically:
+1. Scans your project for configuration files (package.json, pyproject.toml, go.mod, Cargo.toml, pom.xml, build.gradle, etc.)
+2. Detects your project's primary language using priority-based detection (Rust → Dart → Swift → ... → Shell)
+3. Auto-detects build tools (Maven/Gradle for Java, CMake for C/C++, SPM for Swift, etc.)
+4. Selects the appropriate CI/CD workflow template
+5. Generates language-specific testing and linting configuration
+
+### Supported Languages
+
+For detailed language detection priority and build tool detection, see [Language Detection Guide](.moai/docs/language-detection-guide.md)
+
+### Customization
+
+For advanced workflow customization, see [Workflow Templates Guide](.moai/docs/workflow-templates.md)
+
+---
+
+## Language Localization Architecture (v0.7.0+)
+
+### Hybrid Language Model
+
+MoAI-ADK v0.7.0 introduced a **two-layer language architecture** that enables global teams to work in their preferred language while keeping the infrastructure in English for consistency and maintainability.
+
+### Layer 1: User Conversation & Dynamic Content
+
+**All user-facing content uses your configured `conversation_language`** (set during `/alfred:0-project`):
+
+- ✅ **Responses & Explanations**: Your language (Korean, Japanese, Spanish, English, Chinese, etc.)
+- ✅ **Generated Documents**: SPEC, test files, implementation guides in your language
+- ✅ **Code Comments**: Function docstrings and inline comments in your language
+- ✅ **Git Commit Messages**: All commits in your language
+- ✅ **Sub-agent Communication**: All task prompts in your language
+
+### Layer 2: Static Infrastructure (English Only)
+
+**System infrastructure stays in English** for global consistency:
+
+- 🔒 `.claude/agents/` — Agent templates (English)
+- 🔒 `.claude/commands/` — Command templates (English)
+- 🔒 `.claude/skills/` — Skill content (English, industry standard)
+- 🔒 `.moai/memory/` — Internal guidelines (English)
+- 🔒 @TAG identifiers — Technical markers (English)
+- 🔒 Package code in `src/moai_adk/` — Source code comments (English for global distribution)
+
+### Configuration Example
+
+```json
+{
+  "language": {
+    "conversation_language": "ko",
+    "conversation_language_name": "Korean"
+  }
+}
+```
+
+When configured, Alfred will:
+- Respond in Korean (모든 대화)
+- Generate SPECs in Korean
+- Write code comments in Korean
+- Create Git commits in Korean
+- All while using English-only Skill() invocations internally
+
+### Supported Languages
+
+- 🇬🇧 English
+- 🇰🇷 Korean (한국어)
+- 🇯🇵 Japanese (日本語)
+- 🇨🇳 Chinese (中文)
+- 🇪🇸 Spanish (Español)
+
+### Implementation Status (v0.7.0+)
+
+| Component | Status | Details |
+|-----------|--------|---------|
+| **Config System** | ✅ Complete | Nested language structure in `.moai/config.json` |
+| **Sub-agent Instructions** | ✅ Complete | All 16 agents support language parameter |
+| **Code Generation** | ✅ Complete | Comments/docs in user language |
+| **Git Integration** | ✅ Complete | Commit messages in user language |
+| **Dynamic Content** | ✅ Complete | All reports/explanations in user language |
+
+### Why This Matters
+
+1. **Global Accessibility**: Support teams in any language without translating infrastructure
+2. **Developer Experience**: Write code comments in your native language
+3. **Maintainability**: Infrastructure stays in English (single source of truth)
+4. **Scalability**: Add new languages instantly without code changes
+
+### How to Change Language
+
+**During Project Initialization**:
+```bash
+/alfred:0-project
+# Select your language when prompted
+```
+
+**After Project Creation**:
+Edit `.moai/config.json`:
+```json
+{
+  "language": {
+    "conversation_language": "ja",
+    "conversation_language_name": "Japanese"
+  }
+}
+```
+
+Then restart Claude Code for changes to take effect.
+
+---
+
+## Earlier Detailed Guide (Optional Reading)
+
+Need more explanations? See detailed guides below.
+
+### Detailed Installation Guide
+
+**After installing uv, verify PATH is set**:
+```bash
+# If uv command not found, set PATH manually (macOS/Linux)
+export PATH="$HOME/.cargo/bin:$PATH"
+
+# Verify again
+uv --version
+```
+
+**Available moai-adk commands**:
+```bash
+moai-adk init          # Initialize new project
+moai-adk doctor        # System diagnostics
+moai-adk update        # Update to latest version
+```
+
+### Detailed Project Creation
+
+**Create a new project**:
 ```bash
 moai-adk init my-project
 cd my-project
 ```
 
-**To add to an existing project:**
-
+**Add to existing project**:
 ```bash
 cd your-existing-project
 moai-adk init .
 ```
 
-This one command automatically generates:
-
+Complete directory structure created:
 ```
 my-project/
 ├── .moai/                          # MoAI-ADK project configuration
@@ -267,11 +574,6 @@ my-project/
 │   ├── hooks/                      # Event-driven automation
 │   │   └── alfred/
 │   │       └── alfred_hooks.py     # 5 hooks (Session, PreTool, etc.)
-│   ├── output-styles/              # Response styles
-│   │   └── alfred/
-│   │       ├── agentic-coding.md       # Professional development mode
-│   │       ├── moai-adk-learning.md    # Educational explanations mode
-│   │       └── study-with-alfred.md    # Interactive learning mode
 │   └── settings.json               # Claude Code settings
 ├── src/                            # Implementation code
 ├── tests/                          # Test code
@@ -280,178 +582,331 @@ my-project/
 └── README.md
 ```
 
-### Step 4: Start Alfred in Claude Code (about 2 minutes)
+---
+
+## Core Concept: 3-Step Repeating Cycle
+
+After initial setup, every feature follows this cycle:
+
+| Step | Command | What It Does | Output |
+|------|---------|-------------|--------|
+| 🚀 **INIT** | `/alfred:0-project` | Collect project description, create config/docs, recommend Skills | `.moai/config.json`, `.moai/project/*`, initial report |
+| 📋 **PLAN** | `/alfred:1-plan "feature description"` | Analyze requirements, draft SPEC, create Plan Board | `.moai/specs/SPEC-*/spec.md`, plan/acceptance docs, feature branch |
+| 💻 **RUN** | `/alfred:2-run SPEC-ID` | Execute TDD, run tests/implementation/refactor, verify quality | `tests/`, `src/` implementation, quality report, TAG links |
+| 📚 **SYNC** | `/alfred:3-sync` | Auto-sync docs/README/CHANGELOG, organize TAG/PR status | `docs/`, `.moai/reports/sync-report.md`, Ready PR |
+| 💬 **FEEDBACK** | `/alfred:9-feedback` | Interactive GitHub Issue creation (type → title → description → priority) | GitHub Issue + auto labels + priority + URL |
+
+> ✅ All commands follow the **Phase 0(optional) → Phase 1 → Phase 2 → Phase 3** cycle. Alfred automatically reports status and suggests next steps.
+>
+> 💡 **New in v0.7.0+**: Use `/alfred:9-feedback` to create GitHub Issues on-the-fly during development. Keep your team in sync without interrupting your workflow.
+
+---
+
+## Original Detailed Guide (Complete 7-Step Analysis)
+
+For comprehensive explanation, see the previous version in [GitHub History](https://github.com/modu-ai/moai-adk/blob/main/README.md).
 
-Run Claude Code and invoke the Alfred SuperAgent:
+---
+
+---
 
+## 🚀 First 10-Minute Hands-On: Hello World API
+
+**Goal**: Experience the complete MoAI-ADK workflow in 10 minutes
+**Learn**: SPEC writing, TDD implementation, documentation automation, @TAG system
+
+> Already completed the 3-minute quick start? Start here!
+
+### Prerequisites
+- ✅ MoAI-ADK installed
+- ✅ Project created (`moai-adk init hello-world`)
+- ✅ Claude Code running
+
+---
+
+### Step 1: Write SPEC (2 minutes)
+
+#### Command
 ```bash
-# Run Claude Code
-claude
+/alfred:1-plan "GET /hello endpoint - receive query parameter 'name' and return greeting"
 ```
 
-Then enter this in Claude Code's command input:
-
+#### Alfred Automatically Creates
 ```
-/alfred:0-project
+✅ SPEC ID: HELLO-001
+✅ File: .moai/specs/SPEC-HELLO-001/spec.md
+✅ Branch: feature/SPEC-HELLO-001
 ```
 
-This command performs:
+#### Check Generated SPEC
+```bash
+cat .moai/specs/SPEC-HELLO-001/spec.md
+```
 
-1. **Collect Project Info**: "Project name?", "Goals?", "Main language?"
-2. **Auto-detect Tech Stack**: Automatically recognizes Python/JavaScript/Go, etc.
-3. **Deploy Skill Packs**: Prepares necessary Skills for your project
-4. **Generate Initial Report**: Project structure, suggested next steps
+**Example Content**:
+```yaml
+---
+id: HELLO-001
+version: 0.0.1
+status: draft
+priority: high
+---
 
-### Step 5: Write First SPEC (about 1 minute)
+# `@SPEC:EX-HELLO-001: Hello World API
 
-After project initialization completes, write your first feature as a SPEC:
+## Ubiquitous Requirements
+- System SHALL provide HTTP GET /hello endpoint
+
+## Event-driven Requirements
+- WHEN query parameter 'name' is provided, THEN return "Hello, {name}!"
+- WHEN name is absent, THEN return "Hello, World!"
 
+## Constraints
+- name limited to 50 characters max
+- Response format: JSON
 ```
-/alfred:1-plan "User registration feature"
+
+✅ **Verify**: `ls .moai/specs/SPEC-HELLO-001/`
+
+---
+
+### Step 2: TDD Implementation (5 minutes)
+
+#### Command
+```bash
+/alfred:2-run HELLO-001
 ```
 
-Automatically generated:
+#### 🔴 RED Phase: Write Failing Test
+
+**File Created**: `tests/test_hello.py`
+
+```python
+# `@TEST:EX-HELLO-001 | SPEC: SPEC-HELLO-001.md
+
+import pytest
+from fastapi.testclient import TestClient
+from src.hello.api import app
 
-- `@SPEC:USER-001` - Unique ID assigned
-- `.moai/specs/SPEC-USER-001/spec.md` - Professional SPEC in EARS format
-- `feature/spec-user-001` - Git branch auto-created
+client = TestClient(app)
 
-### Step 6: TDD Implementation (about 3 minutes)
+def test_hello_with_name_should_return_personalized_greeting():
+    """WHEN name provided, THEN return personalized greeting"""
+    response = client.get("/hello?name=Alice")
+    assert response.status_code == 200
+    assert response.json() == {"message": "Hello, Alice!"}
 
-Once SPEC is written, implement using TDD:
+def test_hello_without_name_should_return_default_greeting():
+    """WHEN name absent, THEN return default greeting"""
+    response = client.get("/hello")
+    assert response.status_code == 200
+    assert response.json() == {"message": "Hello, World!"}
+```
 
+**Run**:
+```bash
+pytest tests/test_hello.py -v
 ```
-/alfred:2-run USER-001
+
+**Result**: ❌ FAILED (app doesn't exist yet - expected!)
+
+**Commit**:
+```bash
+git add tests/test_hello.py
+git commit -m "🔴 test(HELLO-001): add failing hello API tests"
 ```
 
-This command handles:
+---
+
+#### 🟢 GREEN Phase: Minimal Implementation
 
-- 🔴 **RED**: Automatically write failing test (`@TEST:USER-001`)
-- 🟢 **GREEN**: Minimal implementation to pass test (`@CODE:USER-001`)
-- ♻️ **REFACTOR**: Improve code quality
+**File Created**: `src/hello/api.py`
 
-### Step 7: Documentation Sync (about 1 minute)
+```python
+# `@CODE:EX-HELLO-001:API | SPEC: SPEC-HELLO-001.md | TEST: tests/test_hello.py
 
-Finally, auto-sync all documentation:
+from fastapi import FastAPI
+
+app = FastAPI()
 
+@app.get("/hello")
+def hello(name: str = "World"):
+    """@CODE:EX-HELLO-001:API - Hello endpoint"""
+    return {"message": f"Hello, {name}!"}
 ```
-/alfred:3-sync
+
+**Run**:
+```bash
+pytest tests/test_hello.py -v
 ```
 
-Automatically generated/updated:
+**Result**: ✅ PASSED (all tests pass!)
 
-- Living Document (API documentation)
-- README updates
-- CHANGELOG generation
-- @TAG chain validation
+**Commit**:
+```bash
+git add src/hello/api.py
+git commit -m "🟢 feat(HELLO-001): implement hello API"
+```
 
-### Complete!
+---
 
-After these 7 steps, everything is ready:
+#### ♻️ REFACTOR Phase: Add Validation
 
-✅ Requirements specification (SPEC)
-✅ Test code (85%+ coverage)
-✅ Implementation code (tracked with @TAG)
-✅ API documentation (auto-generated)
-✅ Change history (CHANGELOG)
-✅ Git commit history (RED/GREEN/REFACTOR)
+**Enhanced Code**:
 
-**Everything completes in 15 minutes!**
+```python
+from fastapi import FastAPI, HTTPException
 
-### Verify Generated Results
+app = FastAPI()
 
-Check if the generated results were properly created:
+@app.get("/hello")
+def hello(name: str = "World"):
+    """@CODE:EX-HELLO-001:API - Hello endpoint with validation"""
+    if len(name) > 50:
+        raise HTTPException(status_code=400, detail="Name too long (max 50 chars)")
+    return {"message": f"Hello, {name}!"}
+```
 
+**Add Test**:
+```python
+def test_hello_with_long_name_should_return_400():
+    """WHEN name exceeds 50 chars, THEN return 400 error"""
+    long_name = "a" * 51
+    response = client.get(f"/hello?name={long_name}")
+    assert response.status_code == 400
+```
+
+**Run**:
 ```bash
-# 1. Check TAG chain (SPEC → TEST → CODE → DOC)
-rg '@(SPEC|TEST|CODE):USER-001' -n
+pytest tests/test_hello.py -v
+```
 
-# 2. Run tests
-pytest tests/ -v
+**Result**: ✅ PASSED (all tests pass!)
 
-# 3. Check generated documentation
-cat docs/api/user.md
-cat README.md
+**Commit**:
+```bash
+git add tests/test_hello.py src/hello/api.py
+git commit -m "♻️ refactor(HELLO-001): add name length validation"
 ```
 
-> 🔍 **Verification Command**: `moai-adk doctor` — Checks if Python/uv versions, `.moai/` structure, and agent/Skills configuration are all ready.
->
-> ```bash
-> moai-adk doctor
-> ```
->
-> All green checkmarks mean perfect readiness!
-
 ---
 
-## Understanding CLAUDE.md (Alfred's Configuration Documents)
+### Step 3: Documentation Sync (2 minutes)
 
-MoAI-ADK's AI coordination is powered by **Alfred**, the MoAI SuperAgent. Alfred's behavior and decision-making are guided by a set of **internal configuration documents** in the `.claude/` directory.
+#### Command
+```bash
+/alfred:3-sync
+```
+
+#### Alfred Automatically
+```
+✅ docs/api/hello.md - API documentation generated
+✅ README.md - Usage examples added
+✅ CHANGELOG.md - Release notes added
+✅ TAG chain validated - All @TAG verified
+```
+
+#### Check Generated API Documentation
+```bash
+cat docs/api/hello.md
+```
+
+**Example Content**:
+```markdown
+# Hello API Documentation
 
-### 4-Document Structure (Progressive Disclosure Pattern)
+## GET /hello
 
-When you run MoAI-ADK, Alfred loads configuration from **4 coordinated documents** (stored in your `.claude/` directory). This layered approach follows **Progressive Disclosure** — each document adds context only when needed:
+### Description
+Returns a personalized greeting based on provided name.
 
-#### Layer 1: Bootstrap (Always Loaded)
+### Parameters
+- `name` (query, optional): Person's name (default: "World", max 50 chars)
 
-| Document | Size | Purpose | Single Responsibility |
-|----------|------|---------|----------------------|
-| **CLAUDE.md** | ~7kb | Alfred's identity, directives, project metadata, language settings | **Project-specific guidance** (your team's working playbook) |
+### Responses
+- **200**: Success
+  ```json
+  { "message": "Hello, Alice!" }
+  ```
+- **400**: Name too long
 
-#### Layers 2-4: Just-In-Time (JIT) Loading
+### Examples
+```bash
+curl "http://localhost:8000/hello?name=Alice"
+# → {"message": "Hello, Alice!"}
+
+curl "http://localhost:8000/hello"
+# → {"message": "Hello, World!"}
+```
+
+### Traceability
+- `@SPEC:EX-HELLO-001` - Requirements
+- `@TEST:EX-HELLO-001` - Tests
+- `@CODE:EX-HELLO-001:API` - Implementation
+```
 
-| Document | Size | Purpose | Triggered When |
-|----------|------|---------|----------------|
-| **CLAUDE-AGENTS-GUIDE.md** | ~14kb | Sub-agent roster (19 members), Skills map (55 packs), selection criteria | Deciding which agent to invoke (e.g., `/alfred:2-run` → need tdd-implementer) |
-| **CLAUDE-RULES.md** | ~17kb | Decision rules: Skill invocation, Interactive Questions, TAG validation, TRUST gates, commit templates | At decision points (e.g., "Should I ask user?", "Which Skill applies?") |
-| **CLAUDE-PRACTICES.md** | ~8kb | Real-world workflows, context engineering (JIT retrieval), agent collaboration patterns, code examples | During implementation phase (e.g., executing `/alfred:2-run` RED→GREEN→REFACTOR) |
+---
 
-### How Progressive Disclosure Works
+### Step 4: Verify TAG Chain (1 minute)
 
-**Example: You run `/alfred:2-run AUTH-001`**
+#### Command
+```bash
+rg '@(SPEC|TEST|CODE|DOC):HELLO-001' -n
+```
 
+#### Output (Complete Traceability)
 ```
-Session Start
-    ↓ Load CLAUDE.md (7kb)
-    ├─ Alfred knows: project context, language settings, core directives
-    ↓ User invokes /alfred:2-run
-    ├─ Load CLAUDE-AGENTS-GUIDE.md (14kb)
-    ├─ Alfred decides: "I need tdd-implementer agent"
-    ├─ Load CLAUDE-RULES.md (17kb)
-    ├─ Alfred checks: "TDD rules? TEST before CODE? TRUST gates?"
-    ├─ Load CLAUDE-PRACTICES.md (8kb)
-    ├─ Alfred references: "RED → GREEN → REFACTOR pattern"
-    ↓ Implementation complete
-    └─ Context cleaned up (only CLAUDE.md remains for next task)
+.moai/specs/SPEC-HELLO-001/spec.md:7:# `@SPEC:EX-HELLO-001: Hello World API
+tests/test_hello.py:3:# `@TEST:EX-HELLO-001 | SPEC: SPEC-HELLO-001.md
+src/hello/api.py:3:# `@CODE:EX-HELLO-001:API | SPEC: SPEC-HELLO-001.md
+docs/api/hello.md:24:- `@SPEC:EX-HELLO-001`
 ```
 
-**Result**:
-- ✅ Session boots fast (only 7kb initial load)
-- ✅ Context stays clean (7kb → 7kb+14kb → 7kb+14kb+17kb as needed)
-- ✅ Each document has single responsibility (easier to maintain)
-- ✅ Developers know exactly where to find/modify specific guidance
+✅ **Complete chain**: SPEC → TEST → CODE → DOC (fully traceable!)
+
+---
+
+### Summary: What You've Accomplished
+
+In just 10 minutes:
+
+✅ **SPEC** - Clear requirements documented
+✅ **TDD** - Red → Green → Refactor cycle
+✅ **Implementation** - Simple, testable code with @CODE TAG
+✅ **Documentation** - Auto-generated from code
+✅ **Traceability** - Complete @TAG chain: SPEC → TEST → CODE → DOC
+✅ **Git History** - Clean, semantic commits (🔴 🟢 ♻️)
+
+---
+
+## Understanding CLAUDE.md (Alfred's Configuration Documents)
+
+MoAI-ADK's AI coordination is powered by **Alfred**, the MoAI SuperAgent. Alfred's behavior and decision-making are guided by a set of **internal configuration documents** in the `.claude/` directory.
+
+### 4-Document Structure
+
+When you run MoAI-ADK, Alfred loads configuration from **4 coordinated documents** (stored in your `.claude/` directory):
+
+| Document                   | Size  | Purpose                                                                                                          | When Alfred Reads It                                          |
+| -------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| **CLAUDE.md**              | ~7kb  | Alfred's identity, core directives, project metadata                                                             | At session start (bootstrap)                                  |
+| **CLAUDE-AGENTS-GUIDE.md** | ~14kb | Sub-agent roster (19 members), Skills distribution (55 packs), team structure                                    | When selecting which agent to invoke                          |
+| **CLAUDE-RULES.md**        | ~17kb | Decision-making rules (Skill invocation, Interactive Questions, TAG validation), commit templates, TRUST 5 gates | During each decision point (e.g., when to ask user questions) |
+| **CLAUDE-PRACTICES.md**    | ~8kb  | Practical workflows, context engineering (JIT retrieval), on-demand agent patterns, real examples                | During implementation phase                                   |
 
 ### Why This Structure Matters
 
-**For Developers**:
-1. **CLAUDE.md**: Your project's working guide (language, settings, directives)
-2. **CLAUDE-AGENTS-GUIDE.md**: "Who does what?" (agent selection logic)
-3. **CLAUDE-RULES.md**: "How do we decide?" (decision frameworks, gates)
-4. **CLAUDE-PRACTICES.md**: "Real examples" (practical patterns to follow)
+**For Developers**: These documents define how Alfred interprets your requirements and orchestrates development. Understanding them helps you:
 
-Understanding this helps you:
-- Write clearer SPEC requirements that Alfred understands
-- Know which agent/Skill executes your request
-- Predict where Alfred might ask questions or apply TRUST verification
+- Write clearer specifications that Alfred understands better
+- Know which agent/Skill will be invoked for your request
+- Understand decision points where Alfred might ask you questions
 
-**For AI (Context Efficiency)**:
-- **Phase 1** (Session Start): Minimal context footprint (7kb)
-- **Phase 2** (Planning): Load agent selection guide (total ~21kb)
-- **Phase 3** (Implementation): Load decision rules (~38kb)
-- **Phase 4** (Execution): Load practical patterns (~46kb)
-- **Between Tasks**: Unload unnecessary layers, keep CLAUDE.md active
+**For AI**: Progressive disclosure means:
 
-📚 **Learn More**: `.claude/CLAUDE.md` | `.claude/CLAUDE-AGENTS-GUIDE.md` | `.claude/CLAUDE-RULES.md` | `.claude/CLAUDE-PRACTICES.md`
+- **Session Start**: Load only CLAUDE.md (7kb) — minimal overhead
+- **On-Demand**: Load CLAUDE-AGENTS-GUIDE.md, CLAUDE-RULES.md, CLAUDE-PRACTICES.md only when needed
+- **Result**: Faster session boot, cleaner context, clear decision logic
 
 ### Example: What Happens When You Run `/alfred:2-run`
 
@@ -472,6 +927,39 @@ Understanding this helps you:
 
 > ⚠️ **Important**: These are internal configuration files for Alfred, not user guides. Keep them concise and decision-focused. Most teams don't modify them.
 
+### Language Policy in CLAUDE.md (v0.7.0+)
+
+**Key Language Rules**:
+
+1. **User Conversation**: Your configured language (Korean, Japanese, Spanish, etc.)
+   - All responses, explanations, and guidance use your `conversation_language`
+   - Alfred reads this from `.moai/config.json`
+
+2. **Code & Git History**: Your configured language
+   - Code comments: Your language
+   - Commit messages: Your language
+   - Documentation: Your language
+
+3. **Infrastructure Only**: English
+   - `.claude/agents/`, `.claude/commands/`, `.claude/skills/` stay in English
+   - `@TAG` identifiers and technical terms use English
+   - `.moai/memory/` files remain in English
+
+**Example**:
+```
+Your CLAUDE.md talks to you in Korean (한국어)
+Your code comments are in Korean (한국어)
+Your git commits are in Korean (한국어)
+Your SPEC documents are in Korean (한국어)
+
+But Alfred's internal commands use English:
+  ✅ Skill("moai-foundation-trust")
+  ✅ @CODE:EX-AUTH-001 (TAG format)
+  ✅ .claude/skills/ (infrastructure)
+```
+
+**See Also**: [Language Localization Architecture](#language-localization-architecture-v070) for complete details on the hybrid language model.
+
 ---
 
 ## Alfred's Memory Files (.moai/memory/)
@@ -675,14 +1163,124 @@ claude
 /alfred:0-project  # Verify new features like language selection
 ```
 
-> 💡 **New 2-Stage Update Workflow**:
->
-> - **Stage 1**: `moai-adk update` detects installer (uv tool, pipx, or pip) and upgrades package
-> - **Stage 2**: `moai-adk update` again to sync templates, config, and agent/Skills
-> - **Smart detection**: Auto-detects whether package upgrade is needed based on version comparison
-> - **CI/CD ready**: Use `moai-adk update --yes` for fully automated updates in pipelines
-> - **Manual upgrade path**: Use `moai-adk update --templates-only` after manually upgrading the package
-> - **Rollback safe**: Automatic backups in `.moai-backups/` before template sync
+> 💡 **New 2-Stage Update Workflow**:
+>
+> - **Stage 1**: `moai-adk update` detects installer (uv tool, pipx, or pip) and upgrades package
+> - **Stage 2**: `moai-adk update` again to sync templates, config, and agent/Skills
+> - **Smart detection**: Auto-detects whether package upgrade is needed based on version comparison
+> - **CI/CD ready**: Use `moai-adk update --yes` for fully automated updates in pipelines
+> - **Manual upgrade path**: Use `moai-adk update --templates-only` after manually upgrading the package
+> - **Rollback safe**: Automatic backups in `.moai-backups/` before template sync
+
+### Optimize Project Templates with `/alfred:0-project update` (v0.9.0+)
+
+After upgrading MoAI-ADK with `moai-adk update`, your project templates and configurations may need optimization to stay in sync with the latest package version. Use the **dedicated Alfred command** to automatically merge template updates while preserving your customizations.
+
+#### When to Run `/alfred:0-project update`
+
+**Automatic Trigger**: After running `moai-adk update`, your project's `optimized` flag is set based on template changes:
+
+```bash
+# 1. Upgrade MoAI-ADK package
+moai-adk update
+# Output: ✓ Package upgraded to v0.9.0!
+# ℹ️  Next: Run `/alfred:0-project update` in Claude Code to optimize templates
+
+# 2. Open Claude Code
+claude
+
+# 3. Run optimization command
+/alfred:0-project update
+```
+
+#### What `/alfred:0-project update` Does
+
+**Phase 1: Smart Backup & Analysis**
+- ✅ Creates automatic backup in `.moai-backups/` (preserves all customizations)
+- ✅ Compares backup version with new template version
+- ✅ Generates comparison report showing changed sections
+- ✅ Presents user-friendly analysis with merge recommendations
+
+**Phase 2: Smart Merge (User Approval)**
+After reviewing the analysis, you can choose:
+- **"Proceed"** → Execute smart merge (merge backup + latest template)
+- **"Preview"** → View detailed change summary before proceeding
+- **"Skip"** → Keep current files unchanged (safe to proceed later)
+
+**Phase 3: Preserve Customizations**
+- ✅ Maintains latest template structure (sections, headers, @TAG format)
+- ✅ Inserts only your customizations (actual content you wrote)
+- ✅ Preserves HISTORY sections cumulatively
+- ✅ Updates version numbers automatically
+
+#### Complete Example
+
+```bash
+# Terminal: Upgrade MoAI-ADK
+$ moai-adk update
+✓ Package upgraded to v0.9.0!
+
+# Claude Code
+/alfred:0-project update
+
+# Alfred displays:
+# 📊 Project Update Analysis
+#
+# Current: CLAUDE.md v0.8.1 (248 lines, template + your customizations)
+# Latest:  Template v0.9.0 (787 lines, expanded guidelines)
+#
+# Changes Detected:
+# ✅ Alfred Persona System (new)
+# ✅ Language Boundary Rules (enhanced)
+# ✅ Report Style Standards (new)
+# ✅ Your Customizations: Preserved (한국어, GOOS🪿엉아, etc.)
+
+# User selects: 🔄 Smart Merge Proceed
+
+# Result:
+# ✅ Merge Complete!
+# - CLAUDE.md updated (v0.8.1 → v0.9.0)
+# - User customizations preserved
+# - config.json updated with optimization metadata
+# - Backup saved to .moai-backups/20251102-221000/
+```
+
+#### Key Features
+
+1. **Automatic Backup**: Always creates backup before merge (safe rollback available)
+2. **Smart Detection**: Identifies template defaults vs. your customizations
+3. **Preservation Policy**: Never overwrites your custom content
+4. **Version Tracking**: Automatically updates template_version in config.json
+5. **HISTORY Section**: Cumulative merge history preserved
+
+#### Command Reference
+
+| Operation | Command |
+|-----------|---------|
+| **Optimize** | `/alfred:0-project update` |
+| **Review First** | Select "Preview" option when prompted |
+| **Keep Current** | Select "Skip" option (safe—run later anytime) |
+| **Check Status** | `cat .moai/config.json \| grep -A2 optimization` |
+
+#### Rollback If Needed
+
+If something goes wrong, restore from automatic backup:
+
+```bash
+# List available backups
+ls -lt .moai-backups/
+
+# Restore from backup (example)
+cp -r .moai-backups/20251102-221000/CLAUDE.md ./CLAUDE.md
+cp -r .moai-backups/20251102-221000/.moai/config.json ./.moai/config.json
+```
+
+#### Why This Matters
+
+- **Stay Current**: Get latest Alfred improvements, fixes, and features
+- **Keep Your Work**: All customizations preserved through merges
+- **No Manual Editing**: Smart merge handles complex version synchronization
+- **Trust the Process**: Automatic backups ensure safe rollback anytime
 
 ---
 
@@ -869,6 +1467,40 @@ This issue has been **fixed** in v0.8.1+. If you're experiencing this:
 - Code now gracefully handles InvalidVersion exceptions
 - Added comprehensive unit tests for placeholder detection
 
+#### Problem: UV Tool Upgrade Shows "Nothing to upgrade" Despite New Version
+
+**Status**: Automatically fixed in v0.9.1+ with cache refresh retry
+
+**Symptoms:**
+- `moai-adk update` shows "Nothing to upgrade"
+- PyPI has a newer version available
+- Caused by stale UV cache metadata
+
+**Automatic Fix (v0.9.1+):**
+The system now automatically detects stale cache and retries:
+1. Detects "Nothing to upgrade" message
+2. Compares installed version vs PyPI latest version
+3. Clears UV cache: `uv cache clean moai-adk`
+4. Automatically retries upgrade
+5. Completes in a single command run
+
+**Manual Workaround (if needed):**
+```bash
+# Clear UV cache and retry
+uv cache clean moai-adk && moai-adk update
+```
+
+**Technical Details:**
+- Root cause: UV caches PyPI metadata that can become outdated
+- Detection: Compares version strings when "Nothing to upgrade" appears
+- Retry limit: Maximum 1 retry to prevent infinite loops
+- Timeout: 10 seconds for cache clear operation
+
+**References:**
+- SPEC: @SPEC:EX-UPDATE-001
+- Implementation: @CODE:EX-UPDATE-001-001, @CODE:EX-UPDATE-001-002, @CODE:EX-UPDATE-001-003
+- Tests: @TEST:EX-UPDATE-001
+
 ### Contributing Tests
 
 When adding new features, always include tests:
@@ -913,109 +1545,19 @@ moai-adk update --check
 
 ## Core Workflow (0 → 3)
 
-Alfred iteratively develops projects with four commands, guided by the **4-Step Workflow Logic** for every user request.
+Alfred iteratively develops projects with four commands.
 
 ```mermaid
 %%{init: {'theme':'neutral'}}%%
 graph TD
-    Start([User Request]) --> Intent[Step 1: Intent Understanding<br/>Clarify ambiguity if needed]
-    Intent --> Plan[Step 2: Plan Creation<br/>Decompose tasks + identify order]
-    Plan --> Execute[Step 3: Task Execution<br/>TodoWrite: pending → in_progress → completed]
-    Execute --> Report[Step 4: Report & Commit<br/>Document decisions + create git commits]
-    Report --> Init[0. Init<br/>/alfred:0-project]
-    Init --> PlanPhase[1. Plan & SPEC<br/>/alfred:1-plan]
-    PlanPhase --> Run[2. Run & TDD<br/>/alfred:2-run]
+    Start([User Request]) --> Init[0. Init<br/>/alfred:0-project]
+    Init --> Plan[1. Plan & SPEC<br/>/alfred:1-plan]
+    Plan --> Run[2. Run & TDD<br/>/alfred:2-run]
     Run --> Sync[3. Sync & Docs<br/>/alfred:3-sync]
-    Sync --> PlanPhase
+    Sync --> Plan
     Sync -.-> End([Release])
 ```
 
-### Alfred's 4-Step Workflow Logic
-
-Every user request follows this systematic process:
-
-#### Step 1: Intent Understanding
-- **Goal**: Clarify user intent before any action
-- **Action**: Evaluate request clarity
-  - **HIGH clarity**: Technical stack, requirements, scope all specified → Skip to Step 2
-  - **MEDIUM/LOW clarity**: Multiple interpretations possible → Invoke `AskUserQuestion`
-- **Outcome**: Clear, unambiguous intent confirmed with user
-
-#### Step 2: Plan Creation
-- **Goal**: Analyze tasks and identify execution strategy
-- **Action**: Invoke Plan Agent to:
-  - Decompose tasks into structured steps
-  - Identify dependencies between tasks
-  - Determine single vs parallel execution opportunities
-  - Estimate work scope and files affected
-- **Outcome**: Structured task breakdown for TodoWrite initialization
-
-#### Step 3: Task Execution
-- **Goal**: Execute tasks with transparent progress tracking
-- **Action**:
-  1. Initialize TodoWrite with all pending tasks
-  2. For each task:
-     - Update status: pending → **in_progress** (exactly ONE at a time)
-     - Execute task (call appropriate sub-agent or tool)
-     - Update status: in_progress → **completed** (immediately after)
-  3. Handle blockers: Keep task in_progress, create new blocking task
-- **Outcome**: All tasks completed with verified progress
-
-#### Step 4: Report & Commit
-- **Goal**: Document work and create git history
-- **Action**:
-  - **Report Generation**: ONLY if user explicitly requested
-    - ❌ Prohibited: Auto-generate reports without request
-    - ✅ Allowed: `.moai/docs/`, `.moai/reports/`, `.moai/specs/`
-  - **Git Commit**: ALWAYS create commits
-    - Call git-manager for all Git operations
-    - TDD commits: RED → GREEN → REFACTOR → DOCS
-    - Include Alfred co-authorship
-- **Outcome**: Complete audit trail with documented decisions
-
-### How 4-Step Workflow Maps to Phase 0-3 Commands
-
-The **4-Step Workflow Logic** is universal and applies to **every command execution**. Here's how it manifests in each Phase:
-
-#### Phase 0: Project Initialization (`/alfred:0-project`)
-```
-Step 1: Intent → Clarify project needs (language, framework, team structure)
-Step 2: Plan  → Design `.moai/` structure, detect tech stack
-Step 3: Run   → Initialize config, deploy Skills, set up project template
-Step 4: Report → Create product/structure/tech.md documentation
-```
-
-#### Phase 1: Planning (`/alfred:1-plan <description>`)
-```
-Step 1: Intent → Parse requirements, clarify SPEC scope
-Step 2: Plan  → Decompose into EARS statements, identify acceptance criteria
-Step 3: Run   → Write SPEC document, create Plan Board, generate GitHub Issue
-Step 4: Report → Create feature branch, commit SPEC with TAG
-```
-
-#### Phase 2: TDD Implementation (`/alfred:2-run <SPEC-ID>`)
-```
-Step 1: Intent → Understand SPEC requirements and test strategy
-Step 2: Plan  → Decompose SPEC into 3-step TDD cycle (RED/GREEN/REFACTOR)
-Step 3: Run   → Execute TDD: 🔴 RED test → 🟢 GREEN implementation → ♻️ REFACTOR quality
-Step 4: Report → Verify TRUST 5 gates, commit code with @TEST/@CODE TAGs
-```
-
-#### Phase 3: Sync & Docs (`/alfred:3-sync`)
-```
-Step 1: Intent → Understand what documentation needs synchronization
-Step 2: Plan  → Identify TAG chains, detect orphans, plan doc updates
-Step 3: Run   → Sync docs, validate TAGs, update README/CHANGELOG
-Step 4: Report → Create sync report, auto-close SPEC Issues, ready PR for merge
-```
-
-**Key Insight**: Each command (0, 1, 2, 3) follows the same **4-Step Logic**. This ensures:
-- ✅ Consistent decision-making across all phases
-- ✅ Clear progression: understand → plan → execute → document
-- ✅ Predictable workflow that teams can rely on
-
----
-
 ### 0. INIT — Project Preparation
 
 - Questions about project introduction, target, language, mode (locale)
@@ -1040,19 +1582,18 @@ Step 4: Report → Create sync report, auto-close SPEC Issues, ready PR for merg
 - Sync Living Document, README, CHANGELOG, etc.
 - Validate TAG chain and recover orphan TAGs
 - Generate Sync Report, transition Draft → Ready for Review, support `--auto-merge` option
-- **Auto-close related SPEC Issues** (Closes #XX reference in commit message)
 
 ---
 
 ## Command Cheat Sheet
 
-| Command | What It Does | Key Outputs |
-|---------|-------------|------------|
-| `/alfred:0-project` | **Initialize project**: gather metadata, detect tech stack, deploy 55 Claude Skills, set up `.moai/` directory | `.moai/config.json`, `.moai/project/*`, `product/structure/tech.md` |
-| `/alfred:1-plan <desc>` | **Write SPEC** in EARS format, create Plan Board, auto-generate acceptance criteria, create feature branch | `.moai/specs/SPEC-*/spec.md`, plan board, acceptance criteria, GitHub Issue |
-| `/alfred:2-run <ID>` | **Execute TDD cycle**: 🔴 RED (failing test) → 🟢 GREEN (minimal implementation) → ♻️ REFACTOR (cleanup) → quality gates | `tests/`, `src/` with `@TEST:ID` and `@CODE:ID` tags, test report |
-| `/alfred:3-sync` | **Synchronize Living Docs**: sync README, docs, CHANGELOG; validate TAG chains; auto-close SPEC Issues on PR merge | `docs/`, `.moai/reports/`, `@DOC:ID` tags, Issue closed |
-| `/alfred:9-feedback` | **Create GitHub Issues** interactively (workflow: issue type → title → description → priority/labels) | GitHub Issue with proper labels, priority, auto-assignable |
+| Command                        | What it does                                                      | Key Outputs                                                        |
+| ------------------------------ | ----------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `/alfred:0-project`            | Collect project description, create config/docs, recommend Skills | `.moai/config.json`, `.moai/project/*`, initial report             |
+| `/alfred:1-plan <description>` | Analyze requirements, draft SPEC, write Plan Board                | `.moai/specs/SPEC-*/spec.md`, plan/acceptance docs, feature branch |
+| `/alfred:2-run <SPEC-ID>`      | Execute TDD, test/implement/refactor, verify quality              | `tests/`, `src/` implementation, quality report, TAG connection    |
+| `/alfred:3-sync`               | Sync docs/README/CHANGELOG, organize TAG/PR status                | `docs/`, `.moai/reports/sync-report.md`, Ready PR                  |
+| `/alfred:9-feedback` | Interactively create GitHub Issues (type → title → description → priority) | GitHub Issue with auto labels, priority, URL        |
 
 > ❗ All commands maintain **Phase 0 (optional) → Phase 1 → Phase 2 → Phase 3** cycle structure. Alfred automatically reports execution status and next-step suggestions.
 >
@@ -1074,69 +1615,6 @@ When you create a SPEC document using `/alfred:1-plan` and push it to a feature
 4. **PR Comment** is added with a link to the created issue
 5. **Labels** are automatically applied based on priority (critical, high, medium, low)
 
-### Automatic Issue Closure & Lifecycle Synchronization
-
-When you complete implementation and run `/alfred:3-sync`, the system manages the complete SPEC-to-Issue lifecycle:
-
-#### Issue Lifecycle Stages
-
-| Stage | SPEC Status | GitHub Issue Status | Action |
-|-------|------------|-------------------|--------|
-| **1. Creation** | `draft` | `open` + `spec` label | SPEC created, Issue auto-created |
-| **2. Review** | `in-review` | `open` + `planning` label | Awaiting SPEC approval |
-| **3. Implementation** | `in-progress` | `open` + `in_progress` label | `/alfred:2-run` execution |
-| **4. Completion** | `completed` | Closing... | `/alfred:3-sync` adds `Closes #XX` |
-| **5. Release** | `stable` | `closed` ✅ | PR merges → Issue auto-closes |
-
-#### Auto-Close Workflow Detail
-
-When you run `/alfred:3-sync` to finalize implementation:
-
-1. **SPEC Issue Detection**: System scans SPEC document for GitHub Issue number
-2. **Status Validation**: Confirms SPEC status is `completed` or `stable`
-3. **Closes Reference Generation**: Automatically generates `Closes #XX` in commit message
-4. **Smart Linking**: Issues PR to SPEC Issue with correlation
-5. **Auto-Close on Merge**: When PR merges to main branch:
-   - GitHub reads `Closes #XX` reference in commit message
-   - Automatically transitions Issue to `closed` status
-   - SPEC Issue and GitHub Issue statuses now match
-
-**Complete Example Workflow:**
-```
-Day 1: Create SPEC
-├─ /alfred:1-plan "User Authentication"
-├─ SPEC-AUTH-001 created in .moai/specs/SPEC-AUTH-001/
-└─ GitHub Issue #45 auto-created (status: open)
-
-Day 2: Implement Feature
-├─ /alfred:2-run AUTH-001
-├─ 🔴 RED: Add failing test @TEST:AUTH-001
-├─ 🟢 GREEN: Implement minimal solution @CODE:AUTH-001
-├─ ♻️ REFACTOR: Improve quality per TRUST 5
-├─ GitHub Issue #45 status: open, developer assignment active
-
-Day 3: Finalize & Sync
-├─ /alfred:3-sync
-├─ SPEC status: draft → completed → stable
-├─ Commit message: "🔖 RELEASE: v0.8.3 ... Closes #45"
-├─ PR created with automatic Issue linking
-└─ PR merges to main → Issue #45 automatically closed ✅
-
-Result:
-- ✅ SPEC-AUTH-001 fully implemented
-- ✅ All tests passing (85%+ coverage)
-- ✅ Documentation synchronized
-- ✅ GitHub Issue #45 closed
-- ✅ Complete audit trail via git history
-```
-
-#### Benefits of Automatic Closure
-
-- **Single Source of Truth**: SPEC document status always matches GitHub Issue status
-- **No Manual Updates**: No need to manually close issues (GitHub does it automatically)
-- **Traceable History**: Complete record in git commits shows SPEC→Issue→Close chain
-- **Team Coordination**: Everyone sees status via GitHub, no separate tracking system needed
-
 ### What Gets Synchronized
 
 **From SPEC to GitHub Issue:**
@@ -1381,8 +1859,6 @@ MoAI-ADK consists of 5 key concepts. Each concept connects to the others, and to
 - ✅ SPEC-based test cases (what to test is already defined)
 - ✅ When requirements change, track all affected code with `@SPEC:ID` TAG
 
-📚 **Learn More**: `.moai/specs/` | [EARS Syntax Guide](./CLAUDE-RULES.md#ears-syntax) | [SPEC Examples](./CLAUDE-PRACTICES.md#spec-examples)
-
 ---
 
 ### Key Concept 2: TDD (Test-Driven Development)
@@ -1419,8 +1895,6 @@ MoAI-ADK consists of 5 key concepts. Each concept connects to the others, and to
 - ✅ Refactoring confidence (always verifiable with tests)
 - ✅ Clear Git history (trace RED → GREEN → REFACTOR process)
 
-📚 **Learn More**: [TDD Workflow](./CLAUDE-PRACTICES.md#tdd-workflow) | [Test Examples](./CLAUDE-PRACTICES.md#test-examples) | [Quality Gates](./CLAUDE-RULES.md#trust-5-principles)
-
 ---
 
 ### Key Concept 3: @TAG System
@@ -1432,13 +1906,13 @@ MoAI-ADK consists of 5 key concepts. Each concept connects to the others, and to
 **TAG Chain**:
 
 ```
-@SPEC:AUTH-001 (requirements)
+@SPEC:EX-AUTH-001 (requirements)
     ↓
-@TEST:AUTH-001 (test)
+@TEST:EX-AUTH-001 (test)
     ↓
-@CODE:AUTH-001 (implementation)
+@CODE:EX-AUTH-001 (implementation)
     ↓
-@DOC:AUTH-001 (documentation)
+@DOC:EX-AUTH-001 (documentation)
 ```
 
 **TAG ID Rules**: `<Domain>-<3 digits>`
@@ -1447,36 +1921,6 @@ MoAI-ADK consists of 5 key concepts. Each concept connects to the others, and to
 - USER-001, USER-002...
 - Once assigned, **never change**
 
-**Advanced TAG Usage: Multi-Component TAGs**
-
-For complex features with multiple components, use sub-tags:
-
-```
-@SPEC:AUTH-001 (complete requirements)
-    ↓
-@TEST:AUTH-001 (test suite)
-├─ @TEST:AUTH-001:login (login flow tests)
-├─ @TEST:AUTH-001:token (token refresh tests)
-└─ @TEST:AUTH-001:session (session management tests)
-    ↓
-@CODE:AUTH-001 (implementation)
-├─ @CODE:AUTH-001:service (authentication service)
-├─ @CODE:AUTH-001:model (User/Token models)
-├─ @CODE:AUTH-001:middleware (auth middleware)
-└─ @CODE:AUTH-001:repository (database access layer)
-    ↓
-@DOC:AUTH-001 (documentation)
-├─ @DOC:AUTH-001:api (API documentation)
-└─ @DOC:AUTH-001:guide (integration guide)
-```
-
-**Component TAG Rules**:
-- Format: `@TAG:ID` or `@TAG:ID:component`
-- Component names are optional but **highly recommended** for clarity
-- All components share the same ID (never change ID once assigned)
-- When querying: `rg '@TAG:AUTH-001' -n` finds all components
-- Helps organize large features without creating new IDs
-
 **How to Use?** When requirements change:
 
 ```bash
@@ -1495,8 +1939,6 @@ rg '@TAG:AUTH-001' -n
 - ✅ Instantly identify all affected code during refactoring
 - ✅ Code remains understandable 3 months later (trace TAG → SPEC)
 
-📚 **Learn More**: [TAG System Guide](./CLAUDE-RULES.md#tag-system) | [TAG Validation](./CLAUDE-PRACTICES.md#tag-validation) | [Orphan Detection](./CLAUDE-RULES.md#orphan-tag-detection)
-
 ---
 
 ### Key Concept 4: TRUST 5 Principles
@@ -1542,8 +1984,6 @@ rg '@TAG:AUTH-001' -n
 - ✅ Entire team develops with same standards
 - ✅ Fewer bugs, prevent security vulnerabilities in advance
 
-📚 **Learn More**: [TRUST 5 Validation](./CLAUDE-RULES.md#trust-5-principles) | [Quality Gates](./CLAUDE-RULES.md#quality-gates) | [Security Best Practices](./CLAUDE-RULES.md#security-guidelines)
-
 ---
 
 ### Key Concept 5: Alfred SuperAgent
@@ -1554,40 +1994,10 @@ rg '@TAG:AUTH-001' -n
 
 **Agent Composition**:
 
-#### 1. Alfred SuperAgent (1)
-- **🎩 Alfred**: Overall orchestration, workflow management, team coordination
-
-#### 2. Core Sub-agents (10)
-Specialized experts handling SPEC → TDD → SYNC pipeline:
-
-| Agent | Role | Responsibility |
-|-------|------|-----------------|
-| **📋 project-manager** | Project Initialization | Setup `.moai/` structure, tech stack detection, Skills deployment |
-| **🏗️ spec-builder** | SPEC Authoring | Write EARS-format specifications, acceptance criteria |
-| **💎 tdd-implementer** | TDD Implementation | RED → GREEN → REFACTOR cycle, test-first development |
-| **📖 doc-syncer** | Documentation Sync | Living docs, README sync, changelog management |
-| **🏷️ tag-agent** | TAG Validation | @TAG chain verification, orphan detection, traceability |
-| **🚀 git-manager** | Git Workflow | Branch management, commits, PR automation, releases |
-| **🔬 debug-helper** | Error Analysis | Stack trace parsing, error diagnosis, fix suggestions |
-| **✅ trust-checker** | TRUST Verification | Test coverage (85%+), code quality, security checks |
-| **🛠️ cc-manager** | Claude Code Config | Session settings, tool permissions, hook management |
-| **📊 implementation-planner** | Strategy Planning | Task decomposition, dependency analysis, parallelization |
-
-#### 3. Specialist Sub-agents (6)
-Domain-specific experts:
-
-- **Language Detection**: Auto-detect Python, TS, Go, Rust, Java from package config
-- **Skills Factory**: Research and integrate new Claude Skills
-- **Template Managers**: Project scaffolding, documentation templates
-- **Quality Gate**: Code review, linting, type checking orchestration
-- **Context Optimizer**: Memory management, JIT context loading
-- **Interactive Questions**: TUI-based user input for AskUserQuestion
-
-#### 4. Built-in Claude Agents (2)
-General-purpose capabilities:
-
-- **General Q&A**: Answer questions about coding, architecture, debugging
-- **Codebase Exploration**: Fast grep/glob searches, code pattern analysis
+- **Alfred SuperAgent**: Overall orchestration (1)
+- **Core Sub-agents**: Specialized tasks like SPEC writing, TDD implementation, documentation sync (10)
+- **Zero-project Specialists**: Project initialization, language detection, etc. (6)
+- **Built-in Agents**: General questions, codebase exploration (2)
 
 **55 Claude Skills**:
 
@@ -1638,7 +2048,7 @@ author: @user
 priority: high
 ---
 
-# @SPEC:TODO-001: Todo Management API
+# @SPEC:EX-TODO-001: Todo Management API
 
 ## Ubiquitous Requirements
 - The system SHALL be able to add todos
@@ -1674,7 +2084,7 @@ The **implementation-planner** Sub-agent decides:
 
 - 📚 Libraries: FastAPI + SQLAlchemy
 - 📁 Folder structure: `src/todo/`, `tests/todo/`
-- 🏷️ TAG design: `@CODE:TODO-001:API`, `@CODE:TODO-001:MODEL`, `@CODE:TODO-001:REPO`
+- 🏷️ TAG design: `@CODE:EX-TODO-001:API`, `@CODE:EX-TODO-001:MODEL`, `@CODE:EX-TODO-001:REPO`
 
 **Phase 2: RED → GREEN → REFACTOR**
 
@@ -1682,7 +2092,7 @@ The **implementation-planner** Sub-agent decides:
 
 ```python
 # tests/test_todo_api.py
-# @TEST:TODO-001 | SPEC: SPEC-TODO-001.md
+# @TEST:README-EXAMPLE-TODO | SPEC: SPEC-TODO-001.md
 
 import pytest
 from src.todo.api import create_todo, get_todos
@@ -1724,7 +2134,7 @@ git commit -m "🔴 test(TODO-001): add failing API tests"
 
 ```python
 # src/todo/api.py
-# @CODE:TODO-001:API | SPEC: SPEC-TODO-001.md | TEST: tests/test_todo_api.py
+# @CODE:EX-TODO-001:API | SPEC: SPEC-TODO-001.md | TEST: tests/test_todo_api.py
 
 from fastapi import FastAPI, HTTPException
 from pydantic import BaseModel
@@ -1738,19 +2148,19 @@ class TodoRequest(BaseModel):
 
 @app.post("/todos", status_code=201)
 def create_todo(todo: TodoRequest):
-    """@CODE:TODO-001:API - POST endpoint"""
+    """@CODE:EX-TODO-001:API - POST endpoint"""
     todo_id = str(uuid.uuid4())
     todos_db[todo_id] = {"id": todo_id, "title": todo.title}
     return todos_db[todo_id]
 
 @app.get("/todos")
 def get_todos():
-    """@CODE:TODO-001:API - GET all endpoint"""
+    """@CODE:EX-TODO-001:API - GET all endpoint"""
     return list(todos_db.values())
 
 @app.get("/todos/{todo_id}")
 def get_todo(todo_id: str):
-    """@CODE:TODO-001:API - GET by ID endpoint"""
+    """@CODE:EX-TODO-001:API - GET by ID endpoint"""
     if todo_id not in todos_db:
         raise HTTPException(status_code=404, detail="Todo not found")
     return todos_db[todo_id]
@@ -1769,7 +2179,7 @@ git commit -m "🟢 feat(TODO-001): implement minimal Todo API"
 
 ```python
 # src/todo/models.py
-# @CODE:TODO-001:MODEL | SPEC: SPEC-TODO-001.md
+# @CODE:EX-TODO-001:MODEL | SPEC: SPEC-TODO-001.md
 
 from datetime import datetime
 from sqlalchemy import Column, String, DateTime
@@ -1778,7 +2188,7 @@ from sqlalchemy.ext.declarative import declarative_base
 Base = declarative_base()
 
 class Todo(Base):
-    """@CODE:TODO-001:MODEL - Todo data model"""
+    """@CODE:EX-TODO-001:MODEL - Todo data model"""
     __tablename__ = "todos"
 
     id = Column(String, primary_key=True)
@@ -1786,7 +2196,7 @@ class Todo(Base):
     created_at = Column(DateTime, default=datetime.utcnow)   # Auto creation time
 
     def validate(self):
-        """@CODE:TODO-001:MODEL - Validation"""
+        """@CODE:EX-TODO-001:MODEL - Validation"""
         if not self.title or len(self.title) > 200:
             raise ValueError("Title must be 1-200 characters")
 ```
@@ -1822,10 +2232,10 @@ git commit -m "♻️ refactor(TODO-001): add database models and validation"
 1. **TAG Chain Validation**
 
    ```bash
-   ✅ @SPEC:TODO-001 → .moai/specs/SPEC-TODO-001/spec.md
-   ✅ @TEST:TODO-001 → tests/test_todo_api.py
-   ✅ @CODE:TODO-001 → src/todo/ (3 files)
-   ✅ @DOC:TODO-001 → docs/api/todo.md (auto-generated)
+   ✅ @SPEC:EX-TODO-001 → .moai/specs/SPEC-TODO-001/spec.md
+   ✅ @TEST:README-EXAMPLE-TODO → tests/test_todo_api.py
+   ✅ @CODE:EX-TODO-001 → src/todo/ (3 files)
+   ✅ @DOC:EX-TODO-001 → docs/api/todo.md (auto-generated)
 
    TAG Chain Integrity: 100%
    Orphan TAGs: None
@@ -1834,7 +2244,7 @@ git commit -m "♻️ refactor(TODO-001): add database models and validation"
 2. **Living Document Generation**
 
    ```markdown
-   # @DOC:TODO-001: Todo Management API
+   # @DOC:EX-TODO-001: Todo Management API
 
    ## Overview
 
@@ -1848,8 +2258,8 @@ git commit -m "♻️ refactor(TODO-001): add database models and validation"
    - URL: /todos
    - Request: {"title": "string (1-200 chars)"}
    - Response: 201 Created with todo object
-   - Implemented in: @CODE:TODO-001:API
-   - Tested in: @TEST:TODO-001
+   - Implemented in: @CODE:EX-TODO-001:API
+   - Tested in: @TEST:README-EXAMPLE-TODO
 
    ### Get All Todos
 
@@ -1877,7 +2287,7 @@ git commit -m "♻️ refactor(TODO-001): add database models and validation"
 
    ### Added
 
-   - Todo Management API with CRUD operations (@SPEC:TODO-001)
+   - Todo Management API with CRUD operations (@SPEC:EX-TODO-001)
      - Create new todos
      - List all todos
      - Update existing todos
@@ -1899,11 +2309,11 @@ Let's verify everything generated is properly connected:
 rg '@(SPEC|TEST|CODE|DOC):TODO-001' -n
 
 # Output:
-# .moai/specs/SPEC-TODO-001/spec.md:1: # @SPEC:TODO-001: Todo Management API
-# tests/test_todo_api.py:2: # @TEST:TODO-001 | SPEC: SPEC-TODO-001.md
-# src/todo/api.py:5: # @CODE:TODO-001:API | SPEC: SPEC-TODO-001.md
-# src/todo/models.py:5: # @CODE:TODO-001:MODEL | SPEC: SPEC-TODO-001.md
-# docs/api/todo.md:1: # @DOC:TODO-001: Todo Management API
+# .moai/specs/SPEC-TODO-001/spec.md:1: # @SPEC:EX-TODO-001: Todo Management API
+# tests/test_todo_api.py:2: # @TEST:README-EXAMPLE-TODO | SPEC: SPEC-TODO-001.md
+# src/todo/api.py:5: # @CODE:EX-TODO-001:API | SPEC: SPEC-TODO-001.md
+# src/todo/models.py:5: # @CODE:EX-TODO-001:MODEL | SPEC: SPEC-TODO-001.md
+# docs/api/todo.md:1: # @DOC:EX-TODO-001: Todo Management API
 
 
 # 2️⃣ Run tests
@@ -1933,21 +2343,21 @@ git log --oneline | head -5
 
 ```
 ✅ SPEC written (3 minutes)
-   └─ @SPEC:TODO-001 TAG assigned
+   └─ @SPEC:EX-TODO-001 TAG assigned
    └─ Clear requirements in EARS format
 
 ✅ TDD implementation (5 minutes)
    └─ 🔴 RED: Tests written first
    └─ 🟢 GREEN: Minimal implementation
    └─ ♻️ REFACTOR: Quality improvement
-   └─ @TEST:TODO-001, @CODE:TODO-001 TAGs assigned
+   └─ @TEST:README-EXAMPLE-TODO, @CODE:EX-TODO-001 TAGs assigned
    └─ 87% coverage, TRUST 5 principles verified
 
 ✅ Documentation sync (1 minute)
    └─ Living Document auto-generated
    └─ README, CHANGELOG updated
    └─ TAG chain validation complete
-   └─ @DOC:TODO-001 TAG assigned
+   └─ @DOC:EX-TODO-001 TAG assigned
    └─ PR status: Draft → Ready for Review
 
 Result:
@@ -1973,16 +2383,33 @@ Alfred works by combining multiple specialized agents with Claude Skills.
 | Sub-agent          | Model  | Role                                                                    |
 | ------------------ | ------ | ----------------------------------------------------------------------- |
 | project-manager 📋 | Sonnet | Project initialization, metadata interviews                             |
-| spec-builder 🏗️    | Sonnet | Plan board, EARS SPEC authoring                                         |
+| spec-builder 🏗️    | Sonnet | Plan board, EARS SPEC authoring, expert consultation recommendations    |
 | code-builder 💎    | Sonnet | Performs complete TDD with `implementation-planner` + `tdd-implementer` |
 | doc-syncer 📖      | Haiku  | Living Doc, README, CHANGELOG sync                                      |
-| tag-agent 🏷️       | Haiku  | TAG inventory, orphan detection                                         |
+| tag-agent 🏷️       | Haiku  | TAG inventory, orphan detection, @EXPERT TAG validation                 |
 | git-manager 🚀     | Haiku  | GitFlow, Draft/Ready, Auto Merge                                        |
 | debug-helper 🔍    | Sonnet | Failure analysis, fix-forward strategy                                  |
 | trust-checker ✅   | Haiku  | TRUST 5 quality gate                                                    |
 | quality-gate 🛡️    | Haiku  | Coverage change and release blocker review                              |
 | cc-manager 🛠️      | Sonnet | Claude Code session optimization, Skill deployment                      |
 
+### Expert Agents (Proactively Triggered by SPEC Keywords)
+
+Expert agents activate automatically when `implementation-planner` detects domain-specific keywords in SPEC documents. They provide architecture guidance, technology recommendations, and risk analysis for their specialized domains.
+
+| Expert Agent      | Model  | Specialty                                           | Auto-Trigger Keywords                                                    |
+| ----------------- | ------ | --------------------------------------------------- | ------------------------------------------------------------------------ |
+| backend-expert 🔧 | Sonnet | Backend architecture, API design, database, auth   | 'backend', 'api', 'server', 'database', 'deployment', 'authentication'  |
+| frontend-expert 💻| Sonnet | Frontend architecture, components, state mgmt      | 'frontend', 'ui', 'page', 'component', 'client-side', 'web interface'   |
+| devops-expert 🚀  | Sonnet | DevOps, CI/CD, deployment, containerization        | 'deployment', 'docker', 'kubernetes', 'ci/cd', 'pipeline', 'aws'        |
+| ui-ux-expert 🎨   | Sonnet | UI/UX design, accessibility (WCAG), design systems | 'design', 'ux', 'accessibility', 'a11y', 'figma', 'design system'       |
+
+**How It Works**:
+- When `/alfred:2-run` starts, `implementation-planner` scans the SPEC content
+- Matching keywords trigger automatic expert agent invocation
+- Experts provide domain-specific architecture guidance
+- All expert consultations are tagged with `@EXPERT:DOMAIN` for traceability
+
 ### Skills (Progressive Disclosure - v0.4 New!)
 
 Alfred organizes Claude Skills in a 4-tier architecture using **Progressive Disclosure** to load Just-In-Time only when needed. Each Skill is a production-grade guide stored in `.claude/skills/` directory.
@@ -2035,6 +2462,7 @@ Specialized domain expertise
 | `moai-domain-cli-tool`     | CLI tool development, argument parsing, POSIX compliance, user-friendly help messages    |
 | `moai-domain-data-science` | Data analysis, visualization, statistical modeling, reproducible research workflows      |
 | `moai-domain-database`     | Database design, schema optimization, indexing strategies, migration management          |
+| `moai-domain-design-systems` | Design system architecture, W3C DTCG tokens, WCAG 2.2 accessibility, design-to-code, Figma MCP |
 | `moai-domain-devops`       | CI/CD pipelines, Docker containerization, Kubernetes orchestration, IaC                  |
 | `moai-domain-frontend`     | React/Vue/Angular development, state management, performance optimization, accessibility |
 | `moai-domain-ml`           | Machine learning model training, evaluation, deployment, MLOps workflows                 |
@@ -2158,42 +2586,7 @@ Or when TAGs are missing:
 
 **Why It Matters**: Prevents data loss from mistakes and ensures @TAG traceability. You can always restore from the checkpoint if something goes wrong.
 
-#### 3. PostToolUse (After Tool Execution)
-
-**Triggers**: After executing file edits, code changes, or MultiEdit operations
-**Purpose**: Automatically run tests to verify changes didn't break anything
-
-**Auto-Test Execution**:
-
-Supported Languages (9 total):
-- 🐍 **Python**: `pytest` with coverage report
-- 📘 **TypeScript/JavaScript**: `Vitest` or `Jest`
-- 🐹 **Go**: `go test` with `-v` flag
-- 🦀 **Rust**: `cargo test` with `--all`
-- ☕ **Java**: `JUnit` via Maven/Gradle
-- 🎯 **Kotlin**: `JUnit` with Gradle
-- 🍎 **Swift**: `XCTest` via Xcode
-- 🎨 **Dart**: `flutter test`
-
-**What You See**:
-
-```
-✅ Tests passed (47 passed in 2.3s)
-   Coverage: 87% (improved from 84%)
-```
-
-Or if tests fail:
-
-```
-❌ Test failures detected
-   ├─ src/auth/service.test.ts:23
-   │  Expected token.length > 0
-   └─ Revert to previous version? (y/n)
-```
-
-**Why It Matters**: Instant feedback on code quality. Catches breaking changes immediately before you commit.
-
-#### 4. UserPromptSubmit (Prompt Input)
+#### 3. UserPromptSubmit (Prompt Input)
 
 **Triggers**: When you submit a prompt to Claude
 **Purpose**: JIT (Just-In-Time) context loading—automatically add relevant files
@@ -2207,7 +2600,7 @@ Or if tests fail:
 
 **Why It Matters**: Saves time and ensures Claude has all the relevant context for your request.
 
-#### 5. SessionEnd (Session Cleanup)
+#### 4. SessionEnd (Session Cleanup)
 
 **Triggers**: When you close your Claude Code session
 **Purpose**: Cleanup tasks and state preservation
@@ -2296,7 +2689,6 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 | Version     | Key Features                                                                                     | Date       |
 | ----------- | ------------------------------------------------------------------------------------------------ | ---------- |
-| **v0.8.3**  | 🔄 4-Step Workflow Logic (Intent → Plan → Execute → Report) + AI decision framework               | 2025-10-30 |
 | **v0.8.2**  | 📖 EARS terminology update: "Constraints" → "Unwanted Behaviors" for clarity                     | 2025-10-29 |
 | **v0.8.1**  | 🔄 Command rename: `/alfred:9-help` → `/alfred:9-feedback` + User feedback workflow improvements | 2025-10-28 |
 | **v0.8.0**  | 🏷️ @DOC TAG auto-generation system + SessionStart version check enhancement                      | 2025-10-27 |
@@ -2310,12 +2702,331 @@ If you need to temporarily disable hooks, edit `.claude/settings.json`:
 
 ---
 
+## 🔧 Beginner's Troubleshooting Guide
+
+Common errors and solutions for getting started with MoAI-ADK.
+
+### 1. uv is Not Installed
+
+**Symptom**:
+```bash
+$ uv --version
+bash: uv: command not found
+```
+
+**Cause**: uv not installed or not in PATH
+
+**Solution**:
+
+**macOS/Linux**:
+```bash
+# Install
+curl -LsSf https://astral.sh/uv/install.sh | sh
+
+# Restart shell
+source ~/.bashrc  # or ~/.zshrc
+
+# Verify
+uv --version
+```
+
+**Windows (PowerShell)**:
+```powershell
+powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# Verify
+uv --version
+```
+
+**If still not working**:
+```bash
+# Manually add PATH (macOS/Linux)
+export PATH="$HOME/.cargo/bin:$PATH"
+
+# Verify
+uv --version
+```
+
+---
+
+### 2. Python Version Mismatch
+
+**Symptom**:
+```
+Python 3.8 found, but 3.13+ required
+```
+
+**Cause**: Python version is less than 3.13
+
+**Solution**:
+
+**Option A: Using pyenv (Recommended)**:
+```bash
+# Install pyenv
+curl https://pyenv.run | bash
+
+# Install Python 3.13
+pyenv install 3.13
+pyenv global 3.13
+
+# Verify
+python --version  # Python 3.13.x
+```
+
+**Option B: Let uv manage Python**:
+```bash
+# uv automatically downloads Python 3.13
+uv python install 3.13
+uv python pin 3.13
+
+# Verify
+python --version
+```
+
+---
+
+### 3. Git Not Found
+
+**Symptom**:
+```
+✗ Git (runtime): not found
+```
+
+**Cause**: Git not installed on system
+
+**Solution**:
+
+**macOS**:
+```bash
+# Using Homebrew
+brew install git
+
+# Or install Xcode Command Line Tools
+xcode-select --install
+```
+
+**Ubuntu/Debian**:
+```bash
+sudo apt update
+sudo apt install git -y
+```
+
+**Windows**:
+```powershell
+# Using winget
+winget install Git.Git
+
+# Or download from https://git-scm.com/download/win
+```
+
+**Verify**:
+```bash
+git --version  # git version 2.x.x
+```
+
+---
+
+### 4. Claude Code Doesn't Recognize .moai/ Folder
+
+**Symptom**:
+```
+"Project not initialized"
+/alfred:0-project command doesn't work
+```
+
+**Cause**: `.moai/` or `.claude/` folders missing or corrupted
+
+**Solution**:
+
+```bash
+# 1. Verify current directory
+pwd  # /path/to/your-project
+
+# 2. Check if .moai/ exists
+ls -la .moai/config.json
+
+# 3. If missing, reinitialize
+moai-adk init .
+
+# 4. Restart Claude Code
+exit  # Exit Claude Code
+claude  # Restart
+```
+
+**Verify**:
+```bash
+moai-adk doctor
+# All items should show ✅
+```
+
+---
+
+### 5. Module Not Found When Running Tests
+
+**Symptom**:
+```
+FAILED tests/test_hello.py - ModuleNotFoundError: No module named 'fastapi'
+```
+
+**Cause**: Required package not installed
+
+**Solution**:
+
+```bash
+# Install dependencies from project root
+uv sync
+
+# Or install specific packages
+uv add fastapi pytest
+
+# Activate virtual environment
+source .venv/bin/activate  # macOS/Linux
+.venv\Scripts\activate     # Windows
+
+# Run tests
+pytest tests/ -v
+```
+
+---
+
+### 6. `/alfred` Commands Not Working
+
+**Symptom**:
+```
+Unknown command: /alfred:1-plan
+```
+
+**Cause**: Claude Code version issue or `.claude/` folder corrupted
+
+**Solution**:
+
+```bash
+# 1. Check Claude Code version (need v1.5.0+)
+claude --version
+
+# 2. Verify .claude/ folder
+ls -la .claude/commands/
+
+# 3. Reinitialize if needed
+moai-adk init .
+
+# 4. Restart Claude Code
+exit
+claude
+```
+
+---
+
+### 7. TAG Chain Broken
+
+**Symptom**:
+```
+⚠ Orphan TAG detected: @TEST:EX-HELLO-001 (no matching @SPEC)
+```
+
+**Cause**: SPEC deleted or TAGs don't match
+
+**Solution**:
+
+```bash
+# 1. Validate TAG chain
+rg '@(SPEC|TEST|CODE):HELLO-001' -n
+
+# 2. Check if SPEC exists
+rg '@SPEC:EX-HELLO-001' -n .moai/specs/
+
+# 3. If SPEC missing, regenerate
+/alfred:1-plan "feature description"
+
+# Or fix TAG in test file
+# Edit tests/test_hello.py: @TEST:EX-HELLO-001 → @TEST:README-EXAMPLE-HELLO
+
+# 4. Sync
+/alfred:3-sync
+```
+
+---
+
+### 8. General Debugging Commands
+
+**Check System Status**:
+```bash
+moai-adk doctor
+```
+Shows all dependency checks + recommendations
+
+**Check Project Structure**:
+```bash
+tree -L 2 .moai/
+```
+
+**Validate TAG Chain Integrity**:
+```bash
+rg '@(SPEC|TEST|CODE|DOC):' -n | wc -l
+```
+Shows total TAG count
+
+**Check Git Status**:
+```bash
+git status
+git log --oneline -5
+```
+
+---
+
+### Debugging Checklist
+
+When something goes wrong:
+
+1. **Read**: Copy the complete error message
+2. **Search**: Check GitHub Issues for similar errors
+3. **Diagnose**: Run `moai-adk doctor`
+4. **Restart**: Quit and restart Claude Code
+5. **Ask**: Post in GitHub Discussions
+
+Quick diagnosis with details:
+```bash
+moai-adk doctor --verbose
+```
+
+---
+
+### Need More Help?
+
+- **GitHub Issues**: Search for similar problems
+- **GitHub Discussions**: Ask questions
+- **Discord Community**: Real-time chat support
+
+**When reporting issues, include**:
+1. Output from `moai-adk doctor --verbose`
+2. Complete error message (screenshot or text)
+3. Steps to reproduce
+4. Your OS and version
+
+---
+
+### Frequently Asked Questions
+
+**Q. Can I install on an existing project?**
+A. Yes! Run `moai-adk init .` - it only adds `.moai/` structure without touching existing code.
+
+**Q. How do I run tests?**
+A. `/alfred:2-run` runs tests first. You can also run `pytest`, `pnpm test` separately.
+
+**Q. How do I verify documentation is current?**
+A. Run `/alfred:3-sync` which generates a Sync Report. Check the PR to see the report.
+
+**Q. Can I do this manually without Alfred?**
+A. Possible, but remember: SPEC → TEST → CODE → DOC order and keep @TAGs updated.
+
+---
+
 ## Additional Resources
 
 | Purpose                   | Resource                                                        |
 | ------------------------- | --------------------------------------------------------------- |
-| Skills detailed structure | `.claude/skills/` directory (55+ Skills)                         |
-| Sub-agent details         | `.claude/agents/alfred/` directory (12 agents)                  |
+| Skills detailed structure | `.claude/skills/` directory (74 Skills)                         |
+| Sub-agent details         | `.claude/agents/alfred/` directory (16 agents + 4 commands)    |
 | Workflow guide            | `.claude/commands/alfred/` (4 commands: 0-project ~ 3-sync)     |
 | Documentation             | Coming soon (see `.moai/`, `.claude/`, `docs/` in your project) |
 | Release notes             | GitHub Releases: https://github.com/modu-ai/moai-adk/releases   |