aiwf 0.3.14 → 0.3.16

package/docs/ROADMAP_v0.4.0.md

@@ -0,0 +1,286 @@
+# AIWF v0.4.0 로드맵: "Autonomous AI Development Partner"
+
+## 🎯 비전 선언
+
+AIWF v0.4.0은 **자율 AI 개발 파트너**로의 진화를 목표로 합니다. 단순한 프로젝트 관리 도구를 넘어서, AI가 스스로 판단하고 행동하며 개발자와 진정한 협업을 이루는 혁신적인 플랫폼을 구축합니다.
+
+## 📅 개발 일정
+
+**전체 기간**: 2025년 8월 - 2025년 11월 (4개월)
+**메이저 마일스톤**: 4개
+**예상 릴리스**: 2025년 11월
+
+---
+
+## 🎯 M1: 지능형 자동화 시스템 (8월)
+
+### 🤖 자율 태스크 실행 엔진
+
+**목표**: AI가 반복적인 개발 작업을 완전 자동으로 수행
+
+#### 핵심 기능
+- **Smart Task Executor**: 태스크 내용을 분석하여 자동 실행 계획 수립
+- **Code Generation Pipeline**: 요구사항에서 코드까지 완전 자동 생성
+- **Test Auto-Generation**: 코드 변경 시 관련 테스트 자동 생성
+- **Documentation Sync**: 코드 변경 시 문서 자동 업데이트
+
+#### 기술 구현
+```javascript
+// 자율 실행 엔진 예시
+class AutonomousTaskExecutor {
+  async executeTask(taskId) {
+    const plan = await this.analyzeTask(taskId);
+    const steps = await this.generateExecutionSteps(plan);
+    
+    for (const step of steps) {
+      await this.executeStep(step);
+      await this.validateStep(step);
+      await this.updateProgress(taskId, step);
+    }
+  }
+}
+```
+
+#### CLI 명령어
+```bash
+aiwf auto execute T001      # 태스크 자동 실행
+aiwf auto plan T001         # 실행 계획 미리보기
+aiwf auto monitor           # 자동 실행 모니터링
+aiwf auto rollback T001     # 실행 결과 롤백
+```
+
+### 🔍 지능형 코드 분석
+
+**목표**: 코드베이스를 이해하고 개선점을 자동 제안
+
+#### 핵심 기능
+- **Architecture Analysis**: 코드 구조 자동 분석 및 리팩토링 제안
+- **Performance Profiling**: 성능 병목 지점 자동 식별
+- **Security Audit**: 보안 취약점 자동 스캔 및 수정 제안
+- **Code Quality Metrics**: 지속적인 코드 품질 모니터링
+
+---
+
+## 🎯 M2: 예측 분석 및 인사이트 (9월)
+
+### 📊 AI 기반 프로젝트 예측
+
+**목표**: 데이터 기반 프로젝트 성공 예측 및 리스크 관리
+
+#### 핵심 기능
+- **Completion Prediction**: 머신러닝 기반 프로젝트 완료 시점 예측
+- **Risk Assessment**: 프로젝트 리스크 자동 평가 및 완화 방안 제시
+- **Resource Optimization**: 팀 리소스 배분 최적화 제안
+- **Velocity Analysis**: 팀 개발 속도 분석 및 개선 방안
+
+#### 예측 모델
+```python
+# 프로젝트 완료 예측 모델 (Python/FastAPI)
+class ProjectPredictionModel:
+    def predict_completion(self, project_data):
+        features = self.extract_features(project_data)
+        completion_date = self.model.predict(features)
+        confidence = self.calculate_confidence(features)
+        return {
+            'predicted_date': completion_date,
+            'confidence': confidence,
+            'risk_factors': self.identify_risks(features)
+        }
+```
+
+### 🧠 학습형 AI 어시스턴트
+
+**목표**: 팀의 작업 패턴을 학습하여 맞춤형 지원 제공
+
+#### 핵심 기능
+- **Pattern Learning**: 개발자 개인/팀의 작업 패턴 학습
+- **Personalized Suggestions**: 개인 선호도 기반 작업 제안
+- **Adaptive Workflows**: 팀 특성에 맞는 워크플로우 자동 조정
+- **Knowledge Base Building**: 프로젝트 특화 지식 자동 구축
+
+---
+
+## 🎯 M3: 고급 협업 시스템 (10월)
+
+### 🤝 실시간 AI 협업
+
+**목표**: 개발자와 AI 간 실시간 협업 환경 구축
+
+#### 핵심 기능
+- **Live Code Review**: 코드 작성 중 실시간 AI 리뷰
+- **Pair Programming AI**: AI와 함께하는 페어 프로그래밍
+- **Context Sharing**: 팀원 간 AI 컨텍스트 공유
+- **Collaborative Planning**: AI 참여형 프로젝트 계획 수립
+
+#### 실시간 협업 아키텍처
+```javascript
+// WebSocket 기반 실시간 협업
+class AICollaborationHub {
+  constructor() {
+    this.aiAgents = new Map();
+    this.developers = new Map();
+    this.sharedContext = new SharedContext();
+  }
+  
+  async startPairProgramming(developerId, taskId) {
+    const aiAgent = await this.createAIAgent(taskId);
+    const session = new PairProgrammingSession(developerId, aiAgent);
+    return session.start();
+  }
+}
+```
+
+### 🌐 멀티 플랫폼 통합
+
+**목표**: 모든 개발 도구와 원활한 통합
+
+#### 지원 플랫폼
+- **IDE 통합**: VSCode, IntelliJ, Sublime Text 확장
+- **CI/CD 통합**: GitHub Actions, GitLab CI, Jenkins
+- **커뮤니케이션**: Slack, Discord, Microsoft Teams
+- **프로젝트 관리**: Jira, Asana, Notion, Linear
+
+---
+
+## 🎯 M4: 지능형 생태계 (11월)
+
+### 🏪 AI 마켓플레이스
+
+**목표**: 커뮤니티 기반 AI 모듈 생태계 구축
+
+#### 핵심 기능
+- **AI Module Store**: 전문화된 AI 모듈 마켓플레이스
+- **Custom AI Training**: 프로젝트 특화 AI 모델 훈련
+- **Community Templates**: 커뮤니티 제작 프로젝트 템플릿
+- **Performance Benchmarks**: AI 모듈 성능 비교 시스템
+
+### 🔮 미래 기술 통합
+
+**목표**: 차세대 AI 기술과의 통합
+
+#### 통합 기술
+- **GPT-5/Claude-4**: 최신 LLM 모델 지원
+- **Code Llama 2**: 코드 특화 AI 모델 통합
+- **Multimodal AI**: 이미지, 음성, 코드 멀티모달 처리
+- **Agentic AI**: 자율적 AI 에이전트 네트워크
+
+---
+
+## 🏗️ 기술 아키텍처 v0.4.0
+
+### 마이크로서비스 아키텍처
+
+```
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Frontend      │    │   AI Gateway    │    │  Prediction     │
+│   Dashboard     │◄──►│    Service      │◄──►│   Service       │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+         │                       │                       │
+         ▼                       ▼                       ▼
+┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
+│   Task Engine   │    │  Code Analysis  │    │   Learning      │
+│    Service      │    │    Service      │    │   Service       │
+└─────────────────┘    └─────────────────┘    └─────────────────┘
+         │                       │                       │
+         └───────────────────────┼───────────────────────┘
+                                 ▼
+                    ┌─────────────────┐
+                    │   Data Lake     │
+                    │   (Vector DB)   │
+                    └─────────────────┘
+```
+
+### 새로운 기술 스택
+
+#### Backend
+- **Node.js 20+**: 최신 ECMAScript 기능 활용
+- **TypeScript 5.x**: 강력한 타입 시스템
+- **Fastify**: 고성능 웹 프레임워크
+- **Prisma**: 타입세이프 ORM
+- **Redis**: 고성능 캐싱 및 세션 관리
+
+#### AI/ML
+- **LangChain**: LLM 체이닝 및 에이전트
+- **Pinecone**: 벡터 데이터베이스
+- **TensorFlow.js**: 브라우저/Node.js AI 추론
+- **Hugging Face**: 오픈소스 AI 모델 허브
+
+#### Frontend
+- **React 18**: 동시성 기능 활용
+- **Next.js 14**: 풀스택 React 프레임워크
+- **Tailwind CSS**: 유틸리티 우선 CSS
+- **Framer Motion**: 고급 애니메이션
+
+---
+
+## 📈 성능 목표 v0.4.0
+
+| 지표 | v0.3.10 | v0.4.0 목표 | 개선율 |
+|------|---------|-------------|--------|
+| 태스크 자동 실행 | 수동 | 80% 자동화 | ∞ |
+| 코드 품질 예측 정확도 | N/A | 85% | N/A |
+| 프로젝트 완료 예측 오차 | N/A | ±15% | N/A |
+| 시스템 응답 시간 | 100ms | 50ms | 50% |
+| 메모리 사용량 | 11MB | 25MB | -127% |
+| 동시 사용자 지원 | 1명 | 100명 | 10,000% |
+
+---
+
+## 🎯 성공 지표
+
+### 정량적 지표
+- **자동화율**: 전체 태스크의 80% 이상 자동 실행
+- **예측 정확도**: 프로젝트 완료 시점 예측 오차 15% 이내
+- **사용자 만족도**: NPS 점수 70+ 달성
+- **성능**: 평균 응답 시간 50ms 이하
+- **확장성**: 100명 동시 사용자 지원
+
+### 정성적 지표
+- **개발자 경험**: "AI가 진짜 팀원 같다"는 피드백 50% 이상
+- **생산성**: 개발 속도 2배 향상 사례 창출
+- **혁신성**: 업계 벤치마크 도구로 인정
+- **생태계**: 커뮤니티 기여 모듈 100개 이상
+
+---
+
+## 🚧 도전 과제 및 해결 방안
+
+### 기술적 도전
+1. **AI 응답 지연**: 로컬 AI 모델 활용으로 지연 최소화
+2. **데이터 프라이버시**: 온프레미스 배포 옵션 제공
+3. **모델 정확도**: 지속적 학습 및 피드백 루프 구축
+4. **시스템 복잡성**: 마이크로서비스 아키텍처로 모듈화
+
+### 비즈니스 도전
+1. **사용자 수용성**: 점진적 AI 도입으로 학습 곡선 완화
+2. **경쟁 차별화**: 독특한 자율 AI 기능으로 차별화
+3. **비용 효율성**: 오픈소스 AI 모델 활용으로 비용 절감
+4. **규모 확장**: 클라우드 네이티브 아키텍처 채택
+
+---
+
+## 🎉 v0.4.0 출시 계획
+
+### 베타 프로그램 (2025년 10월)
+- **얼리 어답터 모집**: 100명 베타 테스터
+- **피드백 수집**: 주간 설문 조사 및 인터뷰
+- **버그 수정**: 실시간 이슈 트래킹 및 해결
+
+### 정식 출시 (2025년 11월)
+- **론칭 이벤트**: 온라인 컨퍼런스 개최
+- **문서화**: 완전한 API 문서 및 튜토리얼
+- **커뮤니티**: Discord/Slack 커뮤니티 개설
+- **파트너십**: 주요 개발 도구업체와 협력
+
+---
+
+## 🌟 장기 비전 (2026년+)
+
+AIWF v0.4.0은 **자율 AI 개발 시대**의 시작점입니다. 미래에는:
+
+- **AI 팀원**: AI가 정식 팀원으로 인정받는 시대
+- **자율 개발**: 요구사항만 주면 완전한 소프트웨어 생성
+- **지능형 유지보수**: AI가 버그 수정과 기능 개선을 자동 수행
+- **창의적 협업**: AI와 인간이 함께 혁신적 솔루션 창출
+
+AIWF는 이러한 미래를 현실로 만드는 핵심 플랫폼이 될 것입니다! 🚀

package/docs/TROUBLESHOOTING.ko.md

@@ -0,0 +1,366 @@
+# AIWF 문제 해결 가이드
+
+[한국어](TROUBLESHOOTING.ko.md) | [English](TROUBLESHOOTING.md)
+
+> AIWF 사용 중 발생할 수 있는 일반적인 문제와 해결 방법
+
+## 📋 목차
+
+1. [설치 문제](#설치-문제)
+2. [명령어 실행 오류](#명령어-실행-오류)
+3. [상태 관리 문제](#상태-관리-문제)
+4. [Git 통합 문제](#git-통합-문제)
+5. [YOLO 모드 문제](#yolo-모드-문제)
+6. [성능 문제](#성능-문제)
+7. [호환성 문제](#호환성-문제)
+8. [FAQ](#faq)
+
+## 설치 문제
+
+### 전역 설치 실패
+
+**문제**: `npm install -g aiwf` 실행 시 권한 오류
+
+**해결책**:
+```bash
+# macOS/Linux
+sudo npm install -g aiwf
+
+# Windows (관리자 권한으로 실행)
+npm install -g aiwf
+
+# 또는 npm 권한 설정 변경
+npm config set prefix ~/.npm-global
+export PATH=~/.npm-global/bin:$PATH
+```
+
+### 프로젝트 설치 실패
+
+**문제**: `aiwf install` 실행 시 오류
+
+**원인 및 해결책**:
+1. **Node.js 버전**: Node.js 16.0.0 이상 필요
+   ```bash
+   node --version  # 버전 확인
+   ```
+
+2. **기존 설치 충돌**: 
+   ```bash
+   # 기존 설치 제거
+   rm -rf .aiwf
+   # 재설치
+   aiwf install --force
+   ```
+
+3. **권한 문제**:
+   ```bash
+   # 현재 디렉토리 권한 확인
+   ls -la
+   # 필요시 권한 변경
+   chmod -R 755 .
+   ```
+
+## 명령어 실행 오류
+
+### "Command not found" 오류
+
+**문제**: `aiwf: command not found`
+
+**해결책**:
+```bash
+# PATH 확인
+echo $PATH
+
+# npm 전역 경로 확인
+npm config get prefix
+
+# PATH에 추가 (bash)
+echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.bashrc
+source ~/.bashrc
+
+# PATH에 추가 (zsh)
+echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
+source ~/.zshrc
+```
+
+### ES 모듈 오류
+
+**문제**: `Cannot use import statement outside a module`
+
+**해결책**:
+```bash
+# Node.js 버전 확인 (16+ 필요)
+node --version
+
+# package.json에 type 추가
+{
+  "type": "module"
+}
+```
+
+### 리소스를 찾을 수 없음
+
+**문제**: `Resource not found: commands/...`
+
+**해결책**:
+```bash
+# AIWF 재설치
+aiwf install --force
+
+# 캐시 정리
+npm cache clean --force
+npm install -g aiwf@latest
+```
+
+## 상태 관리 문제
+
+### 상태 동기화 실패
+
+**문제**: `aiwf state update` 실행 시 오류
+
+**해결책**:
+1. **상태 파일 확인**:
+   ```bash
+   ls -la .aiwf/state/
+   ```
+
+2. **상태 초기화**:
+   ```bash
+   aiwf state init --force
+   ```
+
+3. **권한 문제 해결**:
+   ```bash
+   chmod -R 644 .aiwf/state/*
+   ```
+
+### 순환 의존성 감지
+
+**문제**: "Circular dependency detected"
+
+**해결책**:
+1. 의존성 확인:
+   ```bash
+   aiwf state validate
+   ```
+
+2. 의존성 제거:
+   - 태스크 파일에서 순환 참조 수정
+   - 의존성 재구성
+
+### 상태 파일 손상
+
+**문제**: "Invalid state file format"
+
+**해결책**:
+```bash
+# 백업에서 복원
+cp .aiwf/state/task-state-index.json.backup .aiwf/state/task-state-index.json
+
+# 또는 상태 재구성
+aiwf state rebuild
+```
+
+## Git 통합 문제
+
+### Git Hook 오류
+
+**문제**: 커밋 시 hook 오류 발생
+
+**해결책**:
+1. **Hook 확인**:
+   ```bash
+   ls -la .git/hooks/
+   ```
+
+2. **Hook 재설치**:
+   ```bash
+   ./hooks/install-hooks.sh
+   ```
+
+3. **Hook 비활성화** (임시):
+   ```bash
+   git commit --no-verify
+   ```
+
+### Feature ID 추출 실패
+
+**문제**: 커밋 메시지에서 Feature ID가 인식되지 않음
+
+**해결책**:
+- 올바른 형식 사용: `FL001`, `FL002` 등
+- 커밋 메시지 예:
+  ```
+  feat(FL001): 사용자 인증 구현
+  ```
+
+## YOLO 모드 문제
+
+### YOLO 실행 중단
+
+**문제**: YOLO 모드가 예기치 않게 중단됨
+
+**해결책**:
+1. **체크포인트에서 재개**:
+   ```bash
+   # 마지막 체크포인트 확인
+   aiwf checkpoint list
+   
+   # 재개
+   aiwf yolo --resume
+   ```
+
+2. **안전 모드 사용**:
+   ```bash
+   aiwf yolo --safe
+   ```
+
+### 메모리 부족
+
+**문제**: "JavaScript heap out of memory"
+
+**해결책**:
+```bash
+# Node.js 메모리 증가
+export NODE_OPTIONS="--max-old-space-size=4096"
+
+# 또는 명령어 실행 시
+NODE_OPTIONS="--max-old-space-size=4096" aiwf yolo
+```
+
+### 무한 루프 감지
+
+**문제**: YOLO가 같은 태스크를 반복 실행
+
+**해결책**:
+1. 태스크 상태 확인
+2. 의존성 검증
+3. 필요시 수동으로 태스크 완료:
+   ```bash
+   aiwf state complete TASK_ID
+   ```
+
+## 성능 문제
+
+### 느린 명령어 실행
+
+**원인 및 해결책**:
+1. **큰 프로젝트**: 
+   ```bash
+   # 인덱싱 최적화
+   aiwf optimize index
+   ```
+
+2. **많은 파일**:
+   ```bash
+   # .aiwfignore 파일 생성
+   echo "node_modules/" > .aiwfignore
+   echo "dist/" >> .aiwfignore
+   ```
+
+3. **캐시 문제**:
+   ```bash
+   # 캐시 정리
+   rm -rf .aiwf/cache/*
+   ```
+
+### 높은 토큰 사용량
+
+**해결책**:
+1. **컨텍스트 압축 사용**:
+   ```bash
+   aiwf compress aggressive
+   ```
+
+2. **불필요한 파일 제외**:
+   ```bash
+   # .aiwfignore에 추가
+   *.log
+   *.tmp
+   coverage/
+   ```
+
+## 호환성 문제
+
+### Windows 경로 문제
+
+**문제**: Windows에서 경로 오류
+
+**해결책**:
+```bash
+# Git Bash 또는 WSL 사용 권장
+# 또는 경로에 슬래시 사용
+aiwf create-task "태스크" --path ./tasks/
+```
+
+### 인코딩 문제
+
+**문제**: 한글 깨짐 현상
+
+**해결책**:
+1. **터미널 인코딩 설정**:
+   ```bash
+   export LANG=ko_KR.UTF-8
+   export LC_ALL=ko_KR.UTF-8
+   ```
+
+2. **파일 인코딩 확인**:
+   - 모든 파일을 UTF-8로 저장
+
+## FAQ
+
+### Q: AIWF 버전을 확인하려면?
+```bash
+aiwf --version
+```
+
+### Q: 업데이트하려면?
+```bash
+npm update -g aiwf
+```
+
+### Q: 설정을 초기화하려면?
+```bash
+aiwf reset --all
+```
+
+### Q: 로그를 확인하려면?
+```bash
+# 상세 로그 활성화
+export AIWF_DEBUG=true
+aiwf [명령어]
+
+# 로그 파일 확인
+cat .aiwf/logs/aiwf.log
+```
+
+### Q: 백업을 생성하려면?
+```bash
+# 전체 백업
+tar -czf aiwf-backup.tar.gz .aiwf/
+
+# 상태만 백업
+cp -r .aiwf/state/ .aiwf/state.backup/
+```
+
+## 추가 도움말
+
+### 디버그 모드
+```bash
+# 디버그 모드 활성화
+AIWF_DEBUG=true aiwf [명령어]
+```
+
+### 지원 받기
+1. [공식 문서](https://github.com/moonklabs/aiwf/docs) 확인
+2. [GitHub 이슈](https://github.com/moonklabs/aiwf/issues) 검색
+3. 새 이슈 생성 시 포함할 정보:
+   - AIWF 버전 (`aiwf --version`)
+   - Node.js 버전 (`node --version`)
+   - 운영체제
+   - 오류 메시지 전문
+   - 재현 단계
+
+---
+
+💡 **팁**: 대부분의 문제는 `aiwf install --force`로 해결됩니다!

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "aiwf",
-    "version": "0.3.14",
+    "version": "0.3.16",
     "description": "AI Workflow Framework for Claude Code with multi-language support (Korean/English)",
     "main": "index.js",
     "type": "module",
@@ -59,7 +59,6 @@
         "hooks/",
         "scripts/",
         "ai-tools/",
-        "feature-ledger/",
         "index.js",
         "README.md",
         "README.ko.md",
@@ -83,5 +82,54 @@
     },
     "devDependencies": {
         "jest": "^30.0.3"
+    },
+    "aiwf": {
+        "moduleCategories": {
+            "core": [
+                "utils/paths.js",
+                "utils/messages.js",
+                "utils/language-utils.js"
+            ],
+            "yolo": [
+                "utils/engineering-guard.js",
+                "utils/checkpoint-manager.js"
+            ],
+            "persona": [
+                "lib/ai-persona-manager.js",
+                "lib/context-engine.js",
+                "lib/metrics-collector.js",
+                "lib/task-analyzer.js",
+                "lib/token-optimizer.js"
+            ],
+            "installer": [
+                "lib/installer.js",
+                "lib/backup-manager.js",
+                "lib/file-downloader.js",
+                "lib/rollback-manager.js",
+                "lib/validator.js"
+            ],
+            "cache": [
+                "lib/template-cache-system.js",
+                "lib/offline-detector.js",
+                "lib/template-downloader.js",
+                "lib/template-version-manager.js"
+            ],
+            "github": [
+                "lib/github-integration.js",
+                "lib/state/state-index.js",
+                "lib/state/priority-calculator.js",
+                "lib/state/task-scanner.js"
+            ],
+            "common": [
+                "lib/resource-loader.js"
+            ]
+        },
+        "criticalModules": [
+            "utils/engineering-guard.js",
+            "utils/checkpoint-manager.js"
+        ],
+        "dynamicImports": [
+            "utils/engineering-guard.js"
+        ]
     }
 }