moai-adk 0.3.12__tar.gz → 0.4.0__tar.gz

{moai_adk-0.3.12 → moai_adk-0.4.0}/PKG-INFO

@@ -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
 ```
 

{moai_adk-0.3.12 → moai_adk-0.4.0}/README.md

@@ -25,6 +25,7 @@
 - [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)
@@ -357,6 +358,10 @@ uv --version
 #### 2. moai-adk 설치 (10초)
 
 ```bash
+# 권장: uv tool 모드 (샌드박스 격리, 전역 접근)
+uv tool install moai-adk
+
+# 대안: 현재 가상 환경에 설치
 uv pip install moai-adk
 
 # 설치 확인
@@ -666,6 +671,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)
@@ -1245,7 +1478,10 @@ Alfred가 모든 코드에 자동으로 적용하는 품질 기준입니다.
 ```bash
 moai-adk update
 
-# 또는
+# 또는 (tool 모드 - 권장)
+uv tool upgrade moai-adk
+
+# 또는 (pip 모드 - 레거시)
 uv pip install --upgrade moai-adk
 ```
 
@@ -1399,7 +1635,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
 ```
 

{moai_adk-0.3.12 → moai_adk-0.4.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "moai-adk"
-version = "0.3.12"
+version = "0.4.0"
 description = "MoAI Agentic Development Kit - SPEC-First TDD with Alfred SuperAgent"
 readme = "README.md"
 requires-python = ">=3.13"
@@ -25,7 +25,8 @@ dependencies = [
     "pyfiglet>=1.0.2",
     "questionary>=2.0.0",
     "gitpython>=3.1.45",
-    "packaging>=21.0"
+    "packaging>=21.0",
+    "pyyaml>=6.0.0"
 ]
 
 [project.optional-dependencies]

moai_adk-0.4.0/src/moai_adk/__init__.py

@@ -0,0 +1,15 @@
+# @CODE:PY314-001 | SPEC: SPEC-PY314-001.md | TEST: tests/unit/test_foundation.py
+"""MoAI Agentic Development Kit
+
+SPEC-First TDD Framework with Alfred SuperAgent
+"""
+
+from importlib.metadata import version, PackageNotFoundError
+
+try:
+    __version__ = version("moai-adk")
+except PackageNotFoundError:
+    # Development mode fallback
+    __version__ = "0.4.0-dev"
+
+__all__ = ["__version__"]

{moai_adk-0.3.12 → moai_adk-0.4.0}/src/moai_adk/__main__.py

@@ -1,4 +1,4 @@
-# @CODE:CLI-001 | SPEC: SPEC-CLI-001.md | TEST: tests/unit/test_cli_commands.py
+# @CODE:CLI-001 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_cli_commands.py
 """MoAI-ADK CLI Entry Point
 
 Implements the CLI entry point:

{moai_adk-0.3.12 → moai_adk-0.4.0}/src/moai_adk/cli/commands/__init__.py

@@ -1,4 +1,4 @@
-# @CODE:CLI-001 | SPEC: SPEC-CLI-001.md | TEST: tests/unit/test_cli_commands.py
+# @CODE:CLI-001 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_cli_commands.py
 """CLI command module
 
 Core commands:

{moai_adk-0.3.12 → moai_adk-0.4.0}/src/moai_adk/cli/commands/doctor.py

@@ -1,5 +1,5 @@
-# @CODE:CLI-001 | SPEC: SPEC-CLI-001.md | TEST: tests/unit/test_doctor.py
-# @CODE:CLAUDE-COMMANDS-001:CLI | SPEC: SPEC-CLAUDE-COMMANDS-001.md | TEST: tests/unit/test_slash_commands.py
+# @CODE:CLI-001 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_doctor.py
+# @CODE:CLAUDE-COMMANDS-001:CLI | SPEC: SPEC-CLAUDE-COMMANDS-001/spec.md | TEST: tests/unit/test_slash_commands.py
 """MoAI-ADK doctor command
 
 System diagnostics command:

{moai_adk-0.3.12 → moai_adk-0.4.0}/src/moai_adk/cli/commands/status.py

@@ -1,4 +1,4 @@
-# @CODE:CLI-001 | SPEC: SPEC-CLI-001.md | TEST: tests/unit/test_cli_commands.py
+# @CODE:CLI-001 | SPEC: SPEC-CLI-001/spec.md | TEST: tests/unit/test_cli_commands.py
 """MoAI-ADK status command
 
 Project status display: