moai-adk 0.9.1__py3-none-any.whl → 0.11.0__py3-none-any.whl

{moai_adk-0.9.1.dist-info → moai_adk-0.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.9.1
+Version: 0.11.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'
@@ -158,13 +162,29 @@ 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
 
 ```bash
 # macOS/Linux
@@ -173,46 +193,169 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
 # Windows (PowerShell)
 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 
-# Verify installation
+# Verify
 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.
-
-### Step 2: Install MoAI-ADK (about 1 minute)
+#### Expected Output
+```
+✓ uv 0.5.1 is already installed
+$ uv --version
+uv 0.5.1
+```
 
-Install MoAI-ADK as a global tool. This won't affect your project dependencies.
+#### 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.9.0
+```
+
+**Verification**:
+```bash
 moai-adk --version
-# Output: MoAI-ADK v1.0.0
+# Output: MoAI-ADK v0.9.0
+```
+
+---
+
+### Step 2: Create Your First Project (about 1 minute)
+
+#### Command
+
+```bash
+moai-adk init hello-world
+cd hello-world
+```
+
+#### What Gets Created
+
+```
+hello-world/
+├── .moai/              ✅ Alfred configuration
+├── .claude/            ✅ Claude Code automation
+├── CLAUDE.md           ✅ Project guide
+└── README.md           ✅ Project documentation
+```
+
+#### 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
+✅ 12 agents configured
+✅ 55 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)
 ```
 
-Once installed, you can use the `moai-adk` command anywhere.
+#### 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"
+```
+
+---
 
-### Step 3: Create Project (about 1 minute)
+## Next: Complete Your First Feature in 10 Minutes
 
-**To start a new project:**
+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
+
+---
+
+## 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 +410,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,107 +418,300 @@ 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
+```
+✅ SPEC ID: HELLO-001
+✅ File: .moai/specs/SPEC-HELLO-001/spec.md
+✅ Branch: feature/SPEC-HELLO-001
+```
 
+#### Check Generated SPEC
+```bash
+cat .moai/specs/SPEC-HELLO-001/spec.md
 ```
-/alfred:0-project
+
+**Example Content**:
+```yaml
+---
+id: HELLO-001
+version: 0.0.1
+status: draft
+priority: high
+---
+
+# `@SPEC:HELLO-001: Hello World API
+
+## 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
 ```
 
-This command performs:
+✅ **Verify**: `ls .moai/specs/SPEC-HELLO-001/`
+
+---
+
+### Step 2: TDD Implementation (5 minutes)
+
+#### Command
+```bash
+/alfred:2-run HELLO-001
+```
+
+#### 🔴 RED Phase: Write Failing Test
+
+**File Created**: `tests/test_hello.py`
 
-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
+```python
+# `@TEST:HELLO-001 | SPEC: SPEC-HELLO-001.md
+
+import pytest
+from fastapi.testclient import TestClient
+from src.hello.api import app
 
-### Step 5: Write First SPEC (about 1 minute)
+client = TestClient(app)
 
-After project initialization completes, write your first feature as a SPEC:
+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!"}
 
+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!"}
 ```
-/alfred:1-plan "User registration feature"
+
+**Run**:
+```bash
+pytest tests/test_hello.py -v
 ```
 
-Automatically generated:
+**Result**: ❌ FAILED (app doesn't exist yet - expected!)
 
-- `@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
+**Commit**:
+```bash
+git add tests/test_hello.py
+git commit -m "🔴 test(HELLO-001): add failing hello API tests"
+```
+
+---
 
-### Step 6: TDD Implementation (about 3 minutes)
+#### 🟢 GREEN Phase: Minimal Implementation
 
-Once SPEC is written, implement using TDD:
+**File Created**: `src/hello/api.py`
 
+```python
+# `@CODE:HELLO-001:API | SPEC: SPEC-HELLO-001.md | TEST: tests/test_hello.py
+
+from fastapi import FastAPI
+
+app = FastAPI()
+
+@app.get("/hello")
+def hello(name: str = "World"):
+    """@CODE:HELLO-001:API - Hello endpoint"""
+    return {"message": f"Hello, {name}!"}
 ```
-/alfred:2-run USER-001
+
+**Run**:
+```bash
+pytest tests/test_hello.py -v
+```
+
+**Result**: ✅ PASSED (all tests pass!)
+
+**Commit**:
+```bash
+git add src/hello/api.py
+git commit -m "🟢 feat(HELLO-001): implement hello API"
 ```
 
-This command handles:
+---
+
+#### ♻️ REFACTOR Phase: Add Validation
 
-- 🔴 **RED**: Automatically write failing test (`@TEST:USER-001`)
-- 🟢 **GREEN**: Minimal implementation to pass test (`@CODE:USER-001`)
-- ♻️ **REFACTOR**: Improve code quality
+**Enhanced Code**:
 
-### Step 7: Documentation Sync (about 1 minute)
+```python
+from fastapi import FastAPI, HTTPException
 
-Finally, auto-sync all documentation:
+app = FastAPI()
 
+@app.get("/hello")
+def hello(name: str = "World"):
+    """@CODE: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}!"}
 ```
-/alfred:3-sync
+
+**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
+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 tests/test_hello.py src/hello/api.py
+git commit -m "♻️ refactor(HELLO-001): add name length validation"
+```
+
+---
+
+### Step 3: Documentation Sync (2 minutes)
+
+#### 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
+```
 
-### Complete!
+#### Check Generated API Documentation
+```bash
+cat docs/api/hello.md
+```
 
-After these 7 steps, everything is ready:
+**Example Content**:
+```markdown
+# Hello API Documentation
 
-✅ 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)
+## GET /hello
 
-**Everything completes in 15 minutes!**
+### Description
+Returns a personalized greeting based on provided name.
 
-### Verify Generated Results
+### Parameters
+- `name` (query, optional): Person's name (default: "World", max 50 chars)
 
-Check if the generated results were properly created:
+### Responses
+- **200**: Success
+  ```json
+  { "message": "Hello, Alice!" }
+  ```
+- **400**: Name too long
 
+### Examples
 ```bash
-# 1. Check TAG chain (SPEC → TEST → CODE → DOC)
-rg '@(SPEC|TEST|CODE):USER-001' -n
+curl "http://localhost:8000/hello?name=Alice"
+# → {"message": "Hello, Alice!"}
 
-# 2. Run tests
-pytest tests/ -v
+curl "http://localhost:8000/hello"
+# → {"message": "Hello, World!"}
+```
 
-# 3. Check generated documentation
-cat docs/api/user.md
-cat README.md
+### Traceability
+- `@SPEC:HELLO-001` - Requirements
+- `@TEST:HELLO-001` - Tests
+- `@CODE:HELLO-001:API` - Implementation
 ```
 
-> 🔍 **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!
+---
+
+### Step 4: Verify TAG Chain (1 minute)
+
+#### Command
+```bash
+rg '@(SPEC|TEST|CODE|DOC):HELLO-001' -n
+```
+
+#### Output (Complete Traceability)
+```
+.moai/specs/SPEC-HELLO-001/spec.md:7:# `@SPEC:HELLO-001: Hello World API
+tests/test_hello.py:3:# `@TEST:HELLO-001 | SPEC: SPEC-HELLO-001.md
+src/hello/api.py:3:# `@CODE:HELLO-001:API | SPEC: SPEC-HELLO-001.md
+docs/api/hello.md:24:- `@SPEC:HELLO-001`
+```
+
+✅ **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 (🔴 🟢 ♻️)
 
 ---
 
@@ -1454,7 +1785,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
@@ -1595,7 +1926,7 @@ git commit -m "♻️ refactor(TODO-001): add database models and validation"
 
    ```bash
    ✅ @SPEC:TODO-001 → .moai/specs/SPEC-TODO-001/spec.md
-   ✅ @TEST:TODO-001 → tests/test_todo_api.py
+   ✅ @TEST:README-EXAMPLE-TODO → tests/test_todo_api.py
    ✅ @CODE:TODO-001 → src/todo/ (3 files)
    ✅ @DOC:TODO-001 → docs/api/todo.md (auto-generated)
 
@@ -1621,7 +1952,7 @@ git commit -m "♻️ refactor(TODO-001): add database models and validation"
    - Request: {"title": "string (1-200 chars)"}
    - Response: 201 Created with todo object
    - Implemented in: @CODE:TODO-001:API
-   - Tested in: @TEST:TODO-001
+   - Tested in: @TEST:README-EXAMPLE-TODO
 
    ### Get All Todos
 
@@ -1672,7 +2003,7 @@ 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
+# tests/test_todo_api.py:2: # @TEST:README-EXAMPLE-TODO | 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
@@ -1712,7 +2043,7 @@ git log --oneline | head -5
    └─ 🔴 RED: Tests written first
    └─ 🟢 GREEN: Minimal implementation
    └─ ♻️ REFACTOR: Quality improvement
-   └─ @TEST:TODO-001, @CODE:TODO-001 TAGs assigned
+   └─ @TEST:README-EXAMPLE-TODO, @CODE:TODO-001 TAGs assigned
    └─ 87% coverage, TRUST 5 principles verified
 
 ✅ Documentation sync (1 minute)
@@ -2046,6 +2377,325 @@ 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: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: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: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                                                        |