moai-adk 0.3.12__py3-none-any.whl → 0.4.0__py3-none-any.whl

moai_adk/templates/.claude/skills/scripts/standardize_skills.py

@@ -0,0 +1,166 @@
+#!/usr/bin/env python3
+"""
+Skills 표준화 통합 스크립트
+- YAML 필드 정리 (version, author, license, tags, model 제거)
+- allowed-tools 추가 (누락된 스킬에만)
+"""
+
+import sys
+import re
+from pathlib import Path
+
+# Alfred 에이전트 도구
+ALFRED_TOOLS = ["Read", "Write", "Edit", "Bash", "TodoWrite"]
+# Lang 스킬 도구
+LANG_TOOLS = ["Read", "Bash"]
+# Domain 스킬 도구
+DOMAIN_TOOLS = ["Read", "Bash"]
+
+def parse_yaml_frontmatter(content):
+    """YAML frontmatter 파싱 (간단한 파서)"""
+    if not content.startswith('---'):
+        return None, content
+    
+    parts = content.split('---', 2)
+    if len(parts) < 3:
+        return None, content
+    
+    yaml_str = parts[1]
+    body = parts[2]
+    
+    # YAML 파싱 (딕셔너리로)
+    data = {}
+    current_key = None
+    in_list = False
+    
+    for line in yaml_str.strip().split('\n'):
+        if not line.strip():
+            continue
+        
+        # 리스트 아이템
+        if line.strip().startswith('-'):
+            if in_list and current_key:
+                if isinstance(data[current_key], list):
+                    data[current_key].append(line.strip()[1:].strip())
+            continue
+        
+        # 키-값 쌍
+        if ':' in line:
+            key, value = line.split(':', 1)
+            key = key.strip()
+            value = value.strip()
+            
+            if not value:  # 리스트 시작
+                in_list = True
+                current_key = key
+                data[key] = []
+            else:
+                in_list = False
+                current_key = None
+                data[key] = value
+    
+    return data, body
+
+def build_yaml_frontmatter(data):
+    """딕셔너리를 YAML frontmatter로 변환"""
+    lines = []
+    for key, value in data.items():
+        if isinstance(value, list):
+            lines.append(f"{key}:")
+            for item in value:
+                lines.append(f"  - {item}")
+        else:
+            lines.append(f"{key}: {value}")
+    
+    return '\n'.join(lines)
+
+def standardize_skill(skill_file):
+    """스킬 파일 표준화"""
+    content = skill_file.read_text()
+    
+    data, body = parse_yaml_frontmatter(content)
+    
+    if data is None:
+        print(f"⚠️  No YAML frontmatter: {skill_file}")
+        return False
+    
+    # 보존할 필드만 추출
+    preserved = {}
+    
+    if 'name' in data:
+        preserved['name'] = data['name']
+    if 'description' in data:
+        preserved['description'] = data['description']
+    
+    # allowed-tools 처리
+    if 'allowed-tools' in data:
+        # 이미 있으면 유지
+        preserved['allowed-tools'] = data['allowed-tools']
+    else:
+        # 없으면 스킬 유형별로 추가
+        name = data.get('name', '')
+        
+        if 'alfred' in name:
+            tools = ALFRED_TOOLS
+        elif 'lang' in name:
+            tools = LANG_TOOLS
+        elif 'domain' in name:
+            tools = DOMAIN_TOOLS
+        elif 'claude-code' in name:
+            # moai-claude-code는 이미 allowed-tools 있음 (건너뛰기)
+            tools = None
+        else:
+            # 기본값
+            tools = ["Read"]
+        
+        if tools:
+            preserved['allowed-tools'] = tools
+    
+    # 파일 재작성
+    new_yaml = build_yaml_frontmatter(preserved)
+    new_content = f"---\n{new_yaml}\n---{body}"
+    
+    skill_file.write_text(new_content)
+    print(f"✅ Standardized: {skill_file.name}")
+    return True
+
+def main():
+    """메인 함수"""
+    base_dir = Path("/Users/goos/MoAI/MoAI-ADK")
+    
+    # .claude/skills/
+    skills_dir = base_dir / ".claude/skills"
+    success_count = 0
+    fail_count = 0
+    
+    for skill_dir in sorted(skills_dir.glob("moai-*")):
+        skill_file = skill_dir / "SKILL.md"
+        if skill_file.exists():
+            try:
+                if standardize_skill(skill_file):
+                    success_count += 1
+                else:
+                    fail_count += 1
+            except Exception as e:
+                print(f"❌ Error: {skill_file.name} - {e}")
+                fail_count += 1
+    
+    # src/moai_adk/templates/.claude/skills/
+    templates_dir = base_dir / "src/moai_adk/templates/.claude/skills"
+    for skill_dir in sorted(templates_dir.glob("moai-*")):
+        skill_file = skill_dir / "SKILL.md"
+        if skill_file.exists():
+            try:
+                if standardize_skill(skill_file):
+                    success_count += 1
+                else:
+                    fail_count += 1
+            except Exception as e:
+                print(f"❌ Error: {skill_file.name} - {e}")
+                fail_count += 1
+    
+    print(f"\n📊 Summary: {success_count} succeeded, {fail_count} failed")
+    return 0 if fail_count == 0 else 1
+
+if __name__ == "__main__":
+    sys.exit(main())

moai_adk/templates/.claude/skills/scripts/verify_standardization.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+
+echo "=== Skills 표준화 검증 ==="
+
+# 1. 파일명 검증
+skill_md_count=$(find .claude/skills/ -name "skill.md" 2>/dev/null | wc -l | tr -d ' ')
+SKILL_md_count=$(find .claude/skills/ -name "SKILL.md" 2>/dev/null | wc -l | tr -d ' ')
+
+echo "1. 파일명 표준화:"
+echo "   - skill.md (비표준): $skill_md_count (0이어야 함)"
+echo "   - SKILL.md (표준): $SKILL_md_count (46이어야 함)"
+
+# 2. 중복 템플릿 검증
+duplicate_count=$(ls .claude/skills/ 2>/dev/null | grep -c "moai-cc-.*-template" || echo 0)
+
+echo "2. 중복 템플릿:"
+echo "   - moai-cc-*-template: $duplicate_count (0이어야 함)"
+
+# 3. YAML 필드 검증
+version_count=$(rg "^version:" .claude/skills/*/SKILL.md 2>/dev/null | wc -l | tr -d ' ')
+model_count=$(rg "^model:" .claude/skills/*/SKILL.md 2>/dev/null | wc -l | tr -d ' ')
+allowed_tools_count=$(rg "^allowed-tools:" .claude/skills/*/SKILL.md 2>/dev/null | wc -l | tr -d ' ')
+
+echo "3. YAML 필드:"
+echo "   - version 필드: $version_count (0이어야 함)"
+echo "   - model 필드: $model_count (0이어야 함)"
+echo "   - allowed-tools 필드: $allowed_tools_count (46이어야 함)"
+
+# 종합 판정
+if [ "$skill_md_count" -eq 0 ] && \
+   [ "$SKILL_md_count" -eq 46 ] && \
+   [ "$duplicate_count" -eq 0 ] && \
+   [ "$version_count" -eq 0 ] && \
+   [ "$model_count" -eq 0 ] && \
+   [ "$allowed_tools_count" -eq 46 ]; then
+    echo ""
+    echo "✅ 모든 검증 통과!"
+    exit 0
+else
+    echo ""
+    echo "❌ 검증 실패. 위 항목을 확인하세요."
+    exit 1
+fi

moai_adk/templates/CLAUDE.md

@@ -176,6 +176,159 @@ Task(
 - `/alfred:2-build`: Phase 1에서 SPEC 분석 및 TDD 계획 수립 → Phase 2에서 RED-GREEN-REFACTOR 구현
 - `/alfred:3-sync`: Phase 1에서 동기화 범위 분석 → Phase 2에서 Living Document 동기화 및 TAG 업데이트
 
+---
+
+### Alfred 다음 단계 제안 원칙
+
+**CRITICAL**: Alfred는 작업 완료 후 다음 단계를 제안할 때 **반드시 현재 상태를 확인**해야 합니다.
+
+#### 제안 전 필수 체크리스트
+
+```python
+# 다음 단계 제안 전 체크 (의사코드)
+def suggest_next_step():
+    # 1. SPEC 상태 확인
+    spec_exists = check_spec_file_exists()  # .moai/specs/SPEC-{ID}/spec.md
+    spec_version = get_spec_version()       # YAML Front Matter의 version
+    spec_status = get_spec_status()         # draft|active|completed|deprecated
+
+    # 2. 구현 상태 확인
+    tests_exist = check_test_files()        # tests/**/*test*.py|ts|...
+    code_exists = check_code_files()        # src/**/*.py|ts|...
+    tests_passing = check_test_results()    # pytest, vitest 등 실행 결과
+
+    # 3. 문서 상태 확인
+    docs_synced = check_sync_status()       # @TAG 체인 완전성
+
+    # 4. Git 상태 확인
+    branch_name = get_current_branch()
+    pr_status = get_pr_status()             # draft|ready|merged
+
+    # 5. 현재 상태 기반 다음 단계 결정
+    if not spec_exists:
+        return "SPEC 작성: /alfred:1-spec"
+    elif spec_status == "draft" and not code_exists:
+        return "TDD 구현: /alfred:2-build SPEC-{ID}"
+    elif code_exists and not tests_passing:
+        return "테스트 수정: 실패한 테스트 확인"
+    elif tests_passing and not docs_synced:
+        return "문서 동기화: /alfred:3-sync"
+    elif pr_status == "ready":
+        return "PR 머지 대기 또는 다음 SPEC 작성"
+    else:
+        return "Git 커밋 또는 다음 작업"
+```
+
+#### 잘못된 제안 예시 (❌)
+
+```markdown
+# 시나리오: Alfred가 SPEC을 작성하고, 구현하고, 테스트까지 완료한 상태
+
+❌ 잘못된 제안:
+"다음 단계:
+1. SPEC 검토        # ← SPEC은 이미 Alfred가 작성했음
+2. 테스트 실행      # ← 테스트는 이미 실행되었음
+3. Git 커밋"
+
+✅ 올바른 제안:
+"다음 단계:
+1. Git 커밋 (변경 사항 커밋)  # ← 실제 필요한 작업
+2. 통합 테스트 (수동)         # ← 실제 동작 확인 필요"
+```
+
+#### 올바른 제안 예시 (✅)
+
+**시나리오 1: SPEC만 작성 완료**
+```markdown
+✅ 다음 단계:
+- /alfred:2-build SPEC-{ID} 실행하여 TDD 구현 시작
+```
+
+**시나리오 2: SPEC + 구현 완료, 테스트 통과**
+```markdown
+✅ 다음 단계:
+1. Git 커밋 (RED → GREEN → REFACTOR 커밋)
+2. /alfred:3-sync 실행하여 문서 동기화
+```
+
+**시나리오 3: SPEC + 구현 + 동기화 완료**
+```markdown
+✅ 다음 단계:
+1. Git 커밋 (문서 동기화 커밋)
+2. PR 상태 확인 (Draft → Ready 전환)
+3. 다음 SPEC 작성 (/alfred:1-spec)
+```
+
+**시나리오 4: 모든 작업 완료 (Git 커밋만 남음)**
+```markdown
+✅ 다음 단계:
+- Git 커밋 (변경 사항 커밋)
+
+Note: SPEC, 구현, 테스트, 문서는 모두 완료되었으므로 별도 검토 불필요
+```
+
+#### 제안 금지 사항
+
+Alfred는 다음과 같은 **불필요한 제안을 하지 않아야** 합니다:
+
+1. ❌ **자신이 작성한 문서 검토**: "SPEC-{ID}/spec.md 검토"
+   - Alfred가 SPEC을 작성했다면 이미 완료된 작업
+   - 사용자가 명시적으로 검토 요청하지 않는 한 불필요
+
+2. ❌ **이미 실행한 테스트 재실행**: "테스트 실행"
+   - Alfred가 이미 pytest/vitest를 실행하고 결과를 확인했다면 완료
+   - 실패한 테스트가 있을 때만 재실행 제안
+
+3. ❌ **이미 확인한 상태 재확인**: "Git 상태 확인"
+   - Alfred가 이미 git status를 실행했다면 불필요
+   - 새로운 변경사항이 있을 때만 재확인 제안
+
+4. ❌ **완료된 작업 반복**: "코드 품질 확인"
+   - mypy, ruff 검사를 이미 통과했다면 완료
+   - 새로운 코드 추가 시에만 재검사 제안
+
+#### 제안 우선순위
+
+Alfred는 다음 순서로 다음 단계를 제안합니다:
+
+1. **필수 작업** (반드시 수행해야 함)
+   - SPEC 없음 → SPEC 작성
+   - 테스트 실패 → 테스트 수정
+   - Git 커밋 필요 → Git 커밋
+
+2. **권장 작업** (수행하면 좋음)
+   - 문서 동기화 필요 → /alfred:3-sync
+   - PR 상태 변경 필요 → Draft → Ready 전환
+   - 다음 기능 개발 → 다음 SPEC 작성
+
+3. **선택 작업** (사용자 요청 시에만)
+   - 수동 통합 테스트
+   - 성능 테스트
+   - 보안 검사
+
+#### 상태 확인 명령어
+
+Alfred는 다음 명령어로 현재 상태를 확인합니다:
+
+```bash
+# SPEC 존재 확인
+ls .moai/specs/SPEC-*/spec.md
+
+# SPEC 버전 및 상태 확인
+grep "^version:" .moai/specs/SPEC-*/spec.md
+grep "^status:" .moai/specs/SPEC-*/spec.md
+
+# 테스트 파일 확인
+find tests/ -name "*test*.py" -o -name "*test*.ts"
+
+# Git 상태 확인
+git status --short
+git branch --show-current
+
+# PR 상태 확인 (GitHub CLI)
+gh pr list --head $(git branch --show-current)
+```
+
 ### 에러 메시지 표준 (공통)
 
 모든 Alfred 커맨드와 에이전트는 일관된 심각도 표시를 사용합니다:

moai_adk/templates/__init__.py

@@ -1,2 +1,2 @@
-# @CODE:TEST-INTEGRATION-001 | SPEC: SPEC-TEST-INTEGRATION-001.md
+# @CODE:TEST-INTEGRATION-001 | SPEC: SPEC-TEST-INTEGRATION-001/spec.md
 """MoAI-ADK Templates Package"""

moai_adk/utils/__init__.py

@@ -1,4 +1,4 @@
-# @CODE:LOGGING-001 | SPEC: SPEC-LOGGING-001.md | TEST: tests/unit/test_logger.py
+# @CODE:LOGGING-001 | SPEC: SPEC-LOGGING-001/spec.md | TEST: tests/unit/test_logger.py
 """
 MoAI-ADK utility module
 """

moai_adk/utils/banner.py

@@ -1,4 +1,4 @@
-# @CODE:UTILS-001 | SPEC: SPEC-CLI-001.md
+# @CODE:UTILS-001 | SPEC: SPEC-CLI-001/spec.md
 """ASCII banner module
 
 Render the MoAI-ADK ASCII art banner

moai_adk/utils/logger.py

@@ -1,4 +1,4 @@
-# @CODE:LOGGING-001 | SPEC: SPEC-LOGGING-001.md | TEST: tests/unit/test_logger.py
+# @CODE:LOGGING-001 | SPEC: SPEC-LOGGING-001/spec.md | TEST: tests/unit/test_logger.py
 """
 Logging system built on Python's logging module
 

{moai_adk-0.3.12.dist-info → moai_adk-0.4.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: moai-adk
-Version: 0.3.12
+Version: 0.4.0
 Summary: MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent
 Project-URL: Homepage, https://github.com/modu-ai/moai-adk
 Project-URL: Repository, https://github.com/modu-ai/moai-adk
@@ -23,6 +23,7 @@ Requires-Dist: click>=8.1.0
 Requires-Dist: gitpython>=3.1.45
 Requires-Dist: packaging>=21.0
 Requires-Dist: pyfiglet>=1.0.2
+Requires-Dist: pyyaml>=6.0.0
 Requires-Dist: questionary>=2.0.0
 Requires-Dist: rich>=13.0.0
 Provides-Extra: dev
@@ -63,6 +64,7 @@ Description-Content-Type: text/markdown
 - [Quick Start](#quick-start-3분-실전)
 - [첫 번째 프로젝트: Todo API](#첫-번째-프로젝트-todo-api-만들기)
 - [3단계 워크플로우](#3단계-워크플로우)
+- [v0.4.0: Skills Revolution (계획 중)](#v040-skills-revolution-계획-중)
 - [실전 시나리오](#실전-시나리오)
 - [AI 모델 선택 가이드](#ai-모델-선택-가이드)
 - [CLI Reference](#cli-reference)
@@ -395,6 +397,10 @@ uv --version
 #### 2. moai-adk 설치 (10초)
 
 ```bash
+# 권장: uv tool 모드 (샌드박스 격리, 전역 접근)
+uv tool install moai-adk
+
+# 대안: 현재 가상 환경에 설치
 uv pip install moai-adk
 
 # 설치 확인
@@ -704,6 +710,234 @@ graph TD
 
 ---
 
+## ■ v0.4.0: Skills Revolution (진행 중)
+
+> **📍 현재 진행 상태**: v0.4.0 Skills 표준화 Phase 1 완료, SPEC-SKILLS-REDESIGN-001 v0.1.0 완료
+>
+> 모든 44개 Skills 재구성 완료, 4-Tier 아키텍처 구현 완료, Progressive Disclosure 메커니즘 활성화
+>
+> 상세 진행도는 [UPDATE-PLAN-0.4.0.md](UPDATE-PLAN-0.4.0.md) 및 [SPEC-SKILLS-REDESIGN-001](.moai/specs/SPEC-SKILLS-REDESIGN-001/spec.md)를 참고하세요.
+
+MoAI-ADK v0.4.0은 **Claude Code Skills** 시스템을 도입하여 개발자 경험을 혁신합니다.
+
+### 🎯 핵심 비전
+
+> **"Commands는 진입점, Skills는 능력, Sub-agents는 두뇌"**
+
+v0.4.0은 Claude Code의 **Agent Skills 기능**을 핵심 실행 계층으로 도입하여 **4-Layer 아키텍처**로 전환합니다. Progressive Disclosure 메커니즘으로 **Effectively Unbounded Context**를 실현하며, 개발자는 명령어를 암기하지 않고 **자연어 대화**만으로 **레고 블록처럼 조립 가능한 개발 워크플로우**를 경험합니다.
+
+### 🔑 핵심 변경사항
+
+| 변경 사항 | Before (v0.3.x) | After (v0.4.0) |
+|-----------|-----------------|----------------|
+| **아키텍처** | 3-Layer (Commands/Agents/Hooks) | **4-Layer (Commands/Sub-agents/Skills/Hooks)** |
+| **용어** | "Agents" (혼동) | **"Sub-agents" (Claude Code 표준)** |
+| **컨텍스트 전략** | Always Loaded | **Progressive Disclosure (Effectively Unbounded)** |
+| **재사용성** | 프로젝트 전용 | **전역 (모든 프로젝트 공유)** |
+| **Hooks 성능** | SessionStart 220ms | **<100ms (50% 단축)** |
+| **조합 가능성** | 없음 (단독 실행) | **Composable (Skills 자동 조합)** |
+
+### 🏗️ 4-Layer 아키텍처
+
+```mermaid
+%%{init: {'theme':'neutral'}}%%
+graph TD
+    User([사용자]) --> L1[Layer 1: Commands<br/>워크플로우 진입점]
+    L1 --> L2[Layer 2: Sub-agents<br/>복잡한 추론 & 판단]
+    L2 --> L3[Layer 3: Skills ⭐<br/>재사용 가능한 지식]
+    L3 --> L4[Layer 4: Hooks<br/>가드레일 & JIT Context]
+
+    L1 -.직접 참조.-> L3
+
+    style L3 fill:#e1f5ff,stroke:#0066cc,stroke-width:3px
+    style L1 fill:#fff4e1,stroke:#cc6600
+    style L2 fill:#f0e1ff,stroke:#6600cc
+    style L4 fill:#e1ffe1,stroke:#00cc66
+```
+
+**4-Layer 상세**:
+
+| Layer | 역할 | 예시 | 특징 |
+|-------|------|------|------|
+| **Layer 1: Commands** | 워크플로우 진입점 | `/alfred:1-plan`, `/alfred:2-run` | 사용자 요청 해석, Skills/Sub-agents 조율 |
+| **Layer 2: Sub-agents** | 복잡한 추론 & 판단 | spec-builder, tdd-implementer | Task tool 호출, 독립 컨텍스트 |
+| **Layer 3: Skills ⭐** | 재사용 가능한 지식 | moai-spec-writer, python-expert | Progressive Disclosure, 전역 재사용 |
+| **Layer 4: Hooks** | 가드레일 & JIT Context | SessionStart, PreToolUse | 위험 작업 차단, 빠른 실행 (<100ms) |
+
+### ▶ Progressive Disclosure - 게임 체인저
+
+**3-Layer 로딩 메커니즘**:
+
+```text
+┌──────────────────────────────────────────────┐
+│ Layer 1: Metadata (Startup)                 │
+│ - name + description만 사전 로드            │
+│ - 각 Skill당 ≈50 토큰만 소비               │
+│ - 다수의 Skills 설치 시에도 부담 적음       │
+└──────────────────────────────────────────────┘
+              ↓ Claude가 관련성 판단
+┌──────────────────────────────────────────────┐
+│ Layer 2: SKILL.md (On-Demand)               │
+│ - 관련 있는 Skill만 전체 내용 로드          │
+│ - 필요 시에만 로드 (≈500 토큰)             │
+│ - 여러 Skills 동시 로드 가능                │
+└──────────────────────────────────────────────┘
+              ↓ 추가 정보 필요 시
+┌──────────────────────────────────────────────┐
+│ Layer 3: Additional Files (Lazy Loading)    │
+│ - templates/, scripts/, resources/          │
+│ - 필요한 파일만 선택적 로드                 │
+│ - 대용량 참고 자료를 효율적으로 관리        │
+└──────────────────────────────────────────────┘
+```
+
+**효과**:
+- ✅ **Effectively Unbounded Context** (Anthropic 공식 표현)
+- ✅ **컨텍스트 사용량 30% 절감** (Skills 재사용)
+- ✅ **응답 속도 50% 단축** (Hooks 경량화: 220ms→100ms)
+
+### ▶ Composability - 레고 블록처럼 조립
+
+Claude가 자동으로 필요한 Skills를 식별하고 조합합니다.
+
+**예시: 모바일 앱 개발**
+
+```text
+사용자: "Flutter로 Todo 앱 만들어줘"
+
+Alfred가 자동 조합:
+  ✅ moai-spec-writer (SPEC 작성)
+  ✅ dart-expert (Dart 베스트 프랙티스)
+  ✅ mobile-app-expert (iOS/Android 설계)
+  ✅ moai-tdd-orchestrator (TDD 구현)
+
+사용자: "Firebase 인증도 추가해줘"
+
+Alfred가 자동 조합:
+  ✅ firebase-expert (새로 추가)
+  ✅ dart-expert (이미 로드됨, 재사용)
+  ✅ security-expert (자동 추가)
+```
+
+**조합 원리**:
+- **Automatic Coordination**: Claude가 자동으로 필요한 Skills 식별
+- **No Explicit Reference**: Skills는 서로를 명시적으로 참조하지 않아도 됨
+- **Multiple Skills Together**: 동시에 여러 Skills 활성화 가능
+
+### ▶ Commands 명칭 변경 철학
+
+#### `/alfred:1-spec` → `/alfred:1-plan` ⭐ 핵심 변경
+
+**철학적 배경**:
+- **"항상 계획을 먼저 세우고 진행한다"** - 계획 우선 원칙 강조
+- SPEC 문서 생성뿐만 아니라 **브레인스토밍 모드**로 확장
+- 아이디어 구상, 요구사항 정리, 설계 논의 등 **계획 수립 전반** 지원
+
+**사용 시나리오**:
+
+```bash
+# 시나리오 1: SPEC 문서 생성 (기존 방식)
+/alfred:1-plan "JWT 인증 시스템"
+→ SPEC-AUTH-001 생성, EARS 구문, 브랜치/PR
+
+# 시나리오 2: 브레인스토밍 모드 (신규)
+/alfred:1-plan "프로젝트 아키텍처 설계 논의"
+→ Alfred와 대화형 브레인스토밍
+→ 아이디어 정리 → SPEC 후보 도출
+
+# 시나리오 3: 기술 선택 논의 (신규)
+/alfred:1-plan "인증 방식 비교 (JWT vs Session)"
+→ 장단점 분석 → 의사결정 지원 → SPEC 문서화
+```
+
+**핵심 가치**:
+- ✅ **Think First, Code Later** (생각 먼저, 코딩 나중)
+- ✅ **Collaborative Planning** (Alfred와 함께 계획 수립)
+- ✅ **SPEC-First 유지** (최종적으로 SPEC 문서 생성)
+
+#### `/alfred:2-build` → `/alfred:2-run` ⭐ 핵심 변경
+
+**철학적 배경**:
+- **"계획(Plan) → 실행(Run) → 동기화(Sync)"** - 명확한 워크플로우
+- "build"는 코드 빌드만을 의미하지만, 실제로는 **계획 수행 전반** 지원
+- TDD 구현, 테스트 실행, 리팩토링, 문서 초안 등 **다양한 실행 작업**
+
+**사용 시나리오**:
+
+```bash
+# 시나리오 1: TDD 구현 (주 사용 방식)
+/alfred:2-run SPEC-AUTH-001
+→ RED → GREEN → REFACTOR
+
+# 시나리오 2: 프로토타입 제작
+/alfred:2-run SPEC-PROTO-001
+→ 빠른 검증을 위한 프로토타입 구현
+
+# 시나리오 3: 문서화 작업
+/alfred:2-run SPEC-DOCS-001
+→ 문서 작성 및 샘플 코드 생성
+```
+
+**핵심 가치**:
+- ✅ **Plan First, Run Next** (계획 먼저, 실행 나중)
+- ✅ **Flexible Execution** (TDD뿐 아니라 다양한 실행 작업)
+- ✅ **SPEC-Driven** (SPEC 기반 실행)
+
+#### `/alfred:3-sync` - 유지
+
+- **이유**: "sync(동기화)"가 문서-코드-TAG 동기화 의미를 정확히 전달
+- **기능**: Living Document 갱신, TAG 체인 검증, PR Ready 전환
+
+### ▶ 10개 Foundation Skills
+
+v0.4.0 Phase 1에서 도입되는 핵심 Skills:
+
+| Skill | 역할 | 기존 대응 | 특징 |
+|-------|------|----------|------|
+| `moai-spec-writer` | EARS 명세 작성 | spec-builder 일부 | SPEC 문서 생성, EARS 구문 |
+| `moai-tdd-orchestrator` | TDD 오케스트레이션 | tdd-implementer 일부 | RED-GREEN-REFACTOR 사이클 |
+| `moai-tag-validator` | TAG 무결성 검증 | tag-agent 일부 | TAG 체인 검증, 고아 TAG 탐지 |
+| `moai-doc-syncer` | Living Document 동기 | doc-syncer 일부 | 문서 자동 업데이트 |
+| `moai-git-flow` | GitFlow 자동화 | git-manager 일부 | 브랜치/PR 생성, 커밋 자동화 |
+| `moai-quality-gate` | TRUST 5원칙 검증 | trust-checker 일부 | 품질 게이트, 자동 검증 |
+| `python-expert` | Python 전문가 | (신규) | pytest, mypy, ruff |
+| `typescript-expert` | TypeScript 전문가 | (신규) | Vitest, Biome |
+| `web-api-expert` | REST/GraphQL 전문가 | (신규) | API 설계, 보안 |
+| `mobile-app-expert` | 모바일 전문가 | (신규) | iOS, Android, Flutter |
+
+**Phase 2 이후**: 추가 35개 Skills (Language 18개 + Domain 8개 + Advanced 9개)
+
+### ▶ Before/After 개발 시간 비교
+
+| 작업                | 기존 (Commands + Agents) | Skills 기반 (v0.4.0) | 개선율 |
+| ------------------- | ------------------------ | -------------------- | ------ |
+| **SPEC 작성**       | 2~3분                    | 1~2분                | 40%↓   |
+| **TDD 구현**        | 5~7분                    | 3~4분                | 43%↓   |
+| **문서 동기화**     | 1~2분                    | 30초~1분             | 50%↓   |
+| **전체 사이클**     | 8~12분                   | 4.5~7분              | **44%↓** |
+| **학습 곡선**       | 3개 커맨드 + 12개 에이전트 | 자연어만             | **90%↓** |
+
+**실제 개발자 경험**:
+
+```text
+# 기존: 커맨드 이름 외우기
+개발자: "/alfred:1-spec 뭐였더라... /alfred:0-project? 아니면 /alfred:1-spec?"
+→ 커맨드 참조 → 실행 (학습 부담)
+
+# Skills: 그냥 말하기
+개발자: "사용자 인증 SPEC 작성해줘"
+→ Alfred: "moai-spec-writer + web-api-expert 조합하겠습니다"
+→ 즉시 실행 (학습 불필요)
+```
+
+### ▶ 자세한 정보
+
+v0.4.0 전체 계획, 아키텍처 설계, 마이그레이션 전략은 다음 문서를 참고하세요:
+
+📖 **[UPDATE-PLAN-0.4.0.md](UPDATE-PLAN-0.4.0.md)** - 전체 상세 분석 문서
+
+---
+
 ## ■ 실전 시나리오
 
 ### 시나리오 1: 긴급 버그 수정 (Hotfix)
@@ -1283,7 +1517,10 @@ Alfred가 모든 코드에 자동으로 적용하는 품질 기준입니다.
 ```bash
 moai-adk update
 
-# 또는
+# 또는 (tool 모드 - 권장)
+uv tool upgrade moai-adk
+
+# 또는 (pip 모드 - 레거시)
 uv pip install --upgrade moai-adk
 ```
 
@@ -1437,7 +1674,11 @@ curl -LsSf https://astral.sh/uv/install.sh | sh
 # Windows:
 powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 
-# moai-adk 재설치
+# moai-adk 재설치 (tool 모드 - 권장)
+uv tool uninstall moai-adk
+uv tool install moai-adk
+
+# 또는 (pip 모드 - 레거시)
 uv pip install moai-adk --force-reinstall
 ```