aiwf 0.3.15 → 0.3.17

package/docs/MODULE_MANAGEMENT_GUIDE.md

@@ -0,0 +1,289 @@
+# AIWF Module Management Guide
+
+> A comprehensive guide to understanding and managing AIWF's modular architecture and dependencies
+
+[한국어](MODULE_MANAGEMENT_GUIDE.ko.md) | [English](MODULE_MANAGEMENT_GUIDE.md)
+
+## Table of Contents
+
+1. [Overview](#overview)
+2. [Module Classification](#module-classification)
+3. [Dependency Matrix](#dependency-matrix)
+4. [Critical Modules](#critical-modules)
+5. [Safe Module Management](#safe-module-management)
+6. [Troubleshooting](#troubleshooting)
+7. [Best Practices](#best-practices)
+
+## Overview
+
+AIWF follows a modular architecture where functionality is distributed across specialized modules. Understanding the dependency relationships between these modules is crucial for:
+
+- **Safe refactoring**: Knowing which modules can be modified without breaking others
+- **Feature development**: Understanding where to place new functionality
+- **Debugging**: Tracing issues through the dependency chain
+- **Performance optimization**: Identifying bottlenecks in module loading
+
+## Module Classification
+
+### 🔧 Core Utilities (Critical - Never Delete)
+
+These modules are foundational and used throughout the system:
+
+#### `utils/paths.js`
+- **Usage**: 8+ locations across CLI and commands
+- **Purpose**: Centralized path management for cross-platform compatibility
+- **Dependencies**: None
+- **Critical for**: All file operations, template resolution, resource loading
+
+#### `utils/messages.js`
+- **Usage**: 5+ locations in CLI and user-facing commands
+- **Purpose**: Multi-language message system
+- **Dependencies**: `language-utils.js`
+- **Critical for**: User interface, error messages, internationalization
+
+#### `utils/language-utils.js`
+- **Usage**: 3+ locations in language management
+- **Purpose**: Language detection and configuration
+- **Dependencies**: `paths.js`
+- **Critical for**: Language switching, locale detection
+
+### 🚀 YOLO System (Critical - Never Delete)
+
+Specialized modules for autonomous execution:
+
+#### `utils/engineering-guard.js`
+- **Usage**: Dynamic import in YOLO templates
+- **Purpose**: Prevents over-engineering during autonomous execution
+- **Dependencies**: None (self-contained)
+- **Critical for**: YOLO mode quality control
+- **⚠️ Warning**: Loaded dynamically - won't show in static analysis
+
+#### `utils/checkpoint-manager.js`
+- **Usage**: YOLO commands and recovery systems
+- **Purpose**: Progress tracking and recovery for autonomous execution
+- **Dependencies**: None
+- **Critical for**: YOLO session management, progress recovery
+
+### 🎯 Command-Specific Modules
+
+#### AI Persona System
+```
+ai-persona-manager.js (main)
+├── context-engine.js
+├── metrics-collector.js
+├── task-analyzer.js
+└── token-optimizer.js (used by context-engine)
+```
+
+#### Installation & Backup System
+```
+installer.js (main)
+├── backup-manager.js
+├── file-downloader.js
+├── rollback-manager.js
+└── validator.js
+```
+
+#### Cache System
+```
+template-cache-system.js (main)
+├── offline-detector.js
+├── template-downloader.js
+└── template-version-manager.js
+```
+
+#### GitHub Integration
+```
+github-integration.js (main)
+├── state/state-index.js
+├── state/priority-calculator.js
+└── state/task-scanner.js
+```
+
+### 🌐 Shared Resources
+
+#### `lib/resource-loader.js`
+- **Usage**: 5+ commands (compress, token, evaluate, etc.)
+- **Purpose**: Unified resource management for bundled and user resources
+- **Dependencies**: `paths.js`
+- **Critical for**: Template loading, persona management, resource resolution
+
+## Dependency Matrix
+
+### CLI Command Dependencies
+
+| Command | Direct Dependencies | Indirect Dependencies | Special Notes |
+|---------|-------------------|---------------------|---------------|
+| `aiwf install` | installer.js | backup-manager.js, file-downloader.js, rollback-manager.js, validator.js | - |
+| `aiwf persona` | persona.js, ai-persona-manager.js | context-engine.js, metrics-collector.js, task-analyzer.js, token-optimizer.js | - |
+| `aiwf compress` | compress.js, resource-loader.js | - | - |
+| `aiwf token` | token.js, resource-loader.js | - | - |
+| `aiwf evaluate` | evaluate.js, resource-loader.js | - | - |
+| `aiwf checkpoint` | checkpoint-manager.js | - | ⚠️ YOLO only |
+| `aiwf-checkpoint` | checkpoint-manager.js | - | ⚠️ YOLO only |
+| `aiwf cache` | cache-cli.js | template-cache-system.js, offline-detector.js, template-downloader.js, template-version-manager.js | - |
+| `YOLO Mode` | engineering-guard.js | - | ⚠️ Dynamic import |
+
+## Critical Modules
+
+### Modules with ⚠️ Dynamic Loading
+
+These modules are loaded at runtime and won't appear in static dependency analysis:
+
+1. **`engineering-guard.js`**: Loaded by YOLO templates using `import()`
+2. **State system modules**: Used by GitHub integration
+3. **Persona sub-modules**: Loaded based on active persona
+
+### Deletion Risk Assessment
+
+#### ❌ Never Delete
+- `paths.js`, `messages.js`, `language-utils.js` (core utilities)
+- `engineering-guard.js`, `checkpoint-manager.js` (YOLO system)
+- `resource-loader.js` (shared by multiple commands)
+
+#### ⚠️ Delete with Caution
+- AI Persona system modules (check if persona commands are used)
+- Cache system modules (affects offline functionality)
+- GitHub integration modules (affects GitHub commands)
+
+#### ✅ Conditional Deletion
+- Command-specific modules can be deleted if the corresponding command is unused
+- Template-specific resources can be removed if templates are not needed
+
+## Safe Module Management
+
+### Before Modifying Any Module
+
+1. **Check the Dependency Map**: Review `src/DEPENDENCY_MAP.md`
+2. **Search for Usage**: Use `grep -r "module-name" src/` to find all references
+3. **Check for Dynamic Imports**: Search for `import()` statements
+4. **Verify CLI Integration**: Check if module is used in CLI commands
+5. **Test YOLO Functionality**: Ensure YOLO mode still works if modifying YOLO modules
+
+### Safe Modification Steps
+
+```bash
+# 1. Check static dependencies
+grep -r "your-module.js" src/
+
+# 2. Check dynamic imports
+grep -r "import.*your-module" src/
+
+# 3. Check YOLO integration
+grep -r "your-module" claude-code/
+
+# 4. Verify CLI command mapping
+grep -r "your-module" src/cli/
+
+# 5. Test critical functionality
+npm test
+aiwf install --force
+aiwf-checkpoint list
+```
+
+### Module Addition Guidelines
+
+When adding new modules:
+
+1. **Update Dependency Map**: Add entry to `src/DEPENDENCY_MAP.md`
+2. **Add Warning Comments**: Include `@warning` comments for critical modules
+3. **Document Usage**: Specify which commands or systems use the module
+4. **Consider Dynamic Loading**: Mark if module uses `import()` for lazy loading
+5. **Test Integration**: Verify module works in both development and production
+
+## Troubleshooting
+
+### Common Issues
+
+#### "Module not found" Errors
+```bash
+# Check if module exists
+ls -la src/utils/your-module.js
+
+# Check if path is correct in imports
+grep -r "your-module" src/
+
+# Verify module exports
+node -e "console.log(require('./src/utils/your-module.js'))"
+```
+
+#### YOLO Mode Failures
+```bash
+# Check engineering-guard availability
+ls -la src/utils/engineering-guard.js
+
+# Test dynamic import
+node -e "import('./src/utils/engineering-guard.js').then(m => console.log('OK'))"
+
+# Verify checkpoint system
+aiwf checkpoint status
+```
+
+#### Circular Dependencies
+```bash
+# Detect circular dependencies
+npm install -g madge
+madge --circular src/
+```
+
+### Recovery Procedures
+
+#### If Core Utility is Accidentally Deleted
+1. Restore from git: `git checkout HEAD -- src/utils/paths.js`
+2. Reinstall AIWF: `aiwf install --force`
+3. Verify functionality: `aiwf --version`
+
+#### If YOLO System is Broken
+1. Check YOLO config: `cat .aiwf/yolo-config.yaml`
+2. Restore checkpoint manager: `git checkout HEAD -- src/utils/checkpoint-manager.js`
+3. Test YOLO mode: `aiwf-checkpoint status`
+
+## Best Practices
+
+### Module Development
+
+1. **Single Responsibility**: Each module should have one clear purpose
+2. **Minimal Dependencies**: Avoid unnecessary dependencies to reduce coupling
+3. **Clear Interfaces**: Export only necessary functions/classes
+4. **Documentation**: Include usage comments and dependency information
+5. **Error Handling**: Gracefully handle missing dependencies
+
+### Dependency Management
+
+1. **Regular Audits**: Periodically review and update dependency map
+2. **Impact Analysis**: Before changes, analyze potential impact on dependent modules
+3. **Testing Strategy**: Test both direct and indirect dependencies
+4. **Version Control**: Use git to track module changes and dependencies
+5. **Documentation**: Keep dependency documentation up-to-date
+
+### Performance Considerations
+
+1. **Lazy Loading**: Use dynamic imports for non-critical modules
+2. **Caching**: Cache frequently accessed modules
+3. **Bundle Optimization**: Consider module size when adding dependencies
+4. **Tree Shaking**: Ensure modules support dead code elimination
+
+## Module Integration Checklist
+
+When integrating new modules or modifying existing ones:
+
+- [ ] Updated `src/DEPENDENCY_MAP.md`
+- [ ] Added appropriate warning comments
+- [ ] Documented usage patterns
+- [ ] Tested in both CLI and YOLO modes
+- [ ] Verified resource loading works
+- [ ] Checked for circular dependencies
+- [ ] Updated relevant documentation
+- [ ] Added integration tests if needed
+
+## Related Documents
+
+- [DEPENDENCY_MAP.md](../src/DEPENDENCY_MAP.md) - Detailed dependency matrix
+- [ARCHITECTURE.md](ARCHITECTURE.md) - Overall system architecture
+- [DEVELOPMENT_GUIDE.md](DEVELOPMENT_GUIDE.md) - Development guidelines
+- [YOLO_SYSTEM_GUIDE.md](YOLO_SYSTEM_GUIDE.md) - YOLO system specifics
+
+---
+
+**Last Updated**: 2025-01-27  
+**Verification Method**: Use `grep -r "module-name" src/` to verify usage patterns

package/docs/PERFORMANCE_GUIDELINES.ko.md

@@ -0,0 +1,388 @@
+# AIWF 성능 가이드라인
+
+[한국어](PERFORMANCE_GUIDELINES.ko.md) | [English](PERFORMANCE_GUIDELINES.md)
+
+> AIWF 프로젝트의 성능을 최적화하기 위한 모범 사례와 가이드라인
+
+## 📋 목차
+
+1. [개요](#개요)
+2. [토큰 최적화](#토큰-최적화)
+3. [파일 시스템 성능](#파일-시스템-성능)
+4. [상태 관리 최적화](#상태-관리-최적화)
+5. [메모리 관리](#메모리-관리)
+6. [명령어 실행 최적화](#명령어-실행-최적화)
+7. [AI 상호작용 최적화](#ai-상호작용-최적화)
+8. [모니터링과 프로파일링](#모니터링과-프로파일링)
+
+## 개요
+
+AIWF의 성능은 다음 요소들에 의해 결정됩니다:
+- AI 모델과의 토큰 교환량
+- 파일 시스템 작업 효율성
+- 상태 관리 오버헤드
+- 메모리 사용량
+- 명령어 실행 시간
+
+이 가이드는 각 영역에서 성능을 최적화하는 방법을 설명합니다.
+
+## 토큰 최적화
+
+### 컨텍스트 압축 전략
+
+토큰 사용량을 줄이는 것은 비용과 성능 모두에 중요합니다.
+
+#### 1. 적절한 압축 레벨 선택
+
+```bash
+# 최소 압축 (중요 정보 보존)
+aiwf compress minimal
+
+# 균형 압축 (권장)
+aiwf compress balanced
+
+# 공격적 압축 (최대 토큰 절약)
+aiwf compress aggressive
+```
+
+#### 2. 페르소나 기반 압축
+
+활성 페르소나에 맞춰 관련 정보만 보존:
+
+```bash
+# 백엔드 작업 시
+aiwf persona apply backend
+aiwf compress with-persona
+
+# 프론트엔드 작업 시
+aiwf persona apply frontend
+aiwf compress with-persona
+```
+
+#### 3. 파일 필터링
+
+불필요한 파일 제외:
+
+```bash
+# .aiwfignore 파일 생성
+cat > .aiwfignore << EOF
+# 빌드 산출물
+dist/
+build/
+*.min.js
+*.map
+
+# 의존성
+node_modules/
+vendor/
+
+# 로그 및 캐시
+*.log
+.cache/
+coverage/
+
+# 대용량 파일
+*.jpg
+*.png
+*.mp4
+*.zip
+EOF
+```
+
+### 토큰 사용량 모니터링
+
+```bash
+# 현재 세션 토큰 사용량
+aiwf token status
+
+# 일일 리포트
+aiwf token report daily
+
+# 주간 리포트
+aiwf token report weekly
+```
+
+### 토큰 한도 설정
+
+```bash
+# 세션당 한도 설정
+aiwf token limit session 50000
+
+# 일일 한도 설정
+aiwf token limit daily 200000
+
+# 경고 임계값 설정
+aiwf token limit warning 0.8
+```
+
+## 파일 시스템 성능
+
+### 인덱싱 최적화
+
+#### 1. 선택적 인덱싱
+
+```bash
+# 특정 디렉토리만 인덱싱
+aiwf index --include src/ docs/
+
+# 특정 파일 타입만 인덱싱
+aiwf index --types js,ts,md
+```
+
+#### 2. 인덱스 캐싱
+
+```bash
+# 인덱스 캐시 활성화
+aiwf config set index.cache true
+
+# 캐시 TTL 설정 (초 단위)
+aiwf config set index.cacheTTL 3600
+```
+
+### 파일 감시 최적화
+
+```bash
+# 감시 제외 패턴 설정
+aiwf config set watch.ignore "node_modules/**,dist/**"
+
+# 디바운스 시간 설정 (밀리초)
+aiwf config set watch.debounce 500
+```
+
+## 상태 관리 최적화
+
+### 상태 파일 크기 관리
+
+#### 1. 정기적인 정리
+
+```bash
+# 완료된 태스크 아카이브
+aiwf state archive --older-than 30d
+
+# 상태 파일 압축
+aiwf state compact
+```
+
+#### 2. 증분 업데이트
+
+```bash
+# 전체 업데이트 대신 증분 업데이트 사용
+aiwf state update --incremental
+
+# 특정 스프린트만 업데이트
+aiwf state update --sprint S01
+```
+
+### 상태 검증 최적화
+
+```bash
+# 빠른 검증 (기본 체크만)
+aiwf state validate --quick
+
+# 비동기 검증
+aiwf state validate --async
+```
+
+## 메모리 관리
+
+### Node.js 메모리 설정
+
+```bash
+# 힙 메모리 증가
+export NODE_OPTIONS="--max-old-space-size=4096"
+
+# 또는 .aiwf/config.json에 설정
+{
+  "performance": {
+    "nodeOptions": "--max-old-space-size=4096"
+  }
+}
+```
+
+### 메모리 누수 방지
+
+#### 1. 리소스 정리
+
+```bash
+# 임시 파일 정리
+aiwf cleanup temp
+
+# 오래된 체크포인트 제거
+aiwf checkpoint prune --keep-last 5
+```
+
+#### 2. 캐시 관리
+
+```bash
+# 캐시 크기 제한
+aiwf config set cache.maxSize "100MB"
+
+# 캐시 정리
+aiwf cache clear
+```
+
+## 명령어 실행 최적화
+
+### 병렬 처리
+
+```bash
+# 병렬 태스크 실행
+aiwf task run --parallel 4
+
+# 독립적인 스프린트 병렬 실행
+aiwf sprint run S01 S02 --parallel
+```
+
+### 배치 작업
+
+```bash
+# 여러 태스크 일괄 생성
+aiwf task create-batch tasks.json
+
+# 일괄 상태 업데이트
+aiwf state update-batch
+```
+
+### 지연 로딩
+
+```bash
+# 필요시에만 리소스 로드
+aiwf config set lazy.loading true
+
+# 명령어별 지연 로딩
+aiwf config set lazy.commands true
+```
+
+## AI 상호작용 최적화
+
+### 효율적인 프롬프트
+
+#### 1. 프롬프트 템플릿 사용
+
+```bash
+# 프롬프트 템플릿 생성
+aiwf prompt create backend-api
+
+# 템플릿 재사용
+aiwf task create --prompt-template backend-api
+```
+
+#### 2. 컨텍스트 재사용
+
+```bash
+# 컨텍스트 캐싱 활성화
+aiwf config set ai.contextCache true
+
+# 캐시 수명 설정
+aiwf config set ai.contextCacheTTL 1800
+```
+
+### 응답 최적화
+
+```bash
+# 응답 길이 제한
+aiwf config set ai.maxResponseTokens 2000
+
+# 스트리밍 응답 활성화
+aiwf config set ai.streaming true
+```
+
+## 모니터링과 프로파일링
+
+### 성능 메트릭
+
+```bash
+# 성능 모니터링 활성화
+aiwf monitor start
+
+# 실시간 메트릭 보기
+aiwf monitor status
+
+# 성능 리포트 생성
+aiwf monitor report
+```
+
+### 프로파일링
+
+```bash
+# CPU 프로파일링
+aiwf profile cpu --duration 30s
+
+# 메모리 프로파일링
+aiwf profile memory
+
+# 프로파일 분석
+aiwf profile analyze
+```
+
+### 벤치마크
+
+```bash
+# 기본 벤치마크 실행
+aiwf benchmark
+
+# 특정 명령어 벤치마크
+aiwf benchmark --command "state update"
+
+# 비교 벤치마크
+aiwf benchmark --compare v0.3.0
+```
+
+## 모범 사례 체크리스트
+
+### 일일 최적화
+- [ ] 토큰 사용량 확인
+- [ ] 임시 파일 정리
+- [ ] 캐시 상태 확인
+
+### 주간 최적화
+- [ ] 상태 파일 압축
+- [ ] 오래된 체크포인트 정리
+- [ ] 성능 리포트 검토
+
+### 월간 최적화
+- [ ] 전체 인덱스 재구축
+- [ ] 완료된 태스크 아카이브
+- [ ] 성능 벤치마크 실행
+
+## 성능 문제 해결
+
+### 느린 시작 시간
+
+1. **원인 파악**:
+   ```bash
+   aiwf debug startup
+   ```
+
+2. **해결책**:
+   - 지연 로딩 활성화
+   - 불필요한 플러그인 제거
+   - 캐시 프리로드
+
+### 높은 메모리 사용
+
+1. **메모리 프로파일**:
+   ```bash
+   aiwf profile memory --heap-snapshot
+   ```
+
+2. **해결책**:
+   - 캐시 크기 제한
+   - 리소스 풀 크기 조정
+   - 가비지 컬렉션 튜닝
+
+### 느린 파일 작업
+
+1. **I/O 분석**:
+   ```bash
+   aiwf debug io
+   ```
+
+2. **해결책**:
+   - SSD 사용
+   - 파일 감시 최적화
+   - 배치 I/O 작업
+
+---
+
+💡 **프로 팁**: 성능 최적화는 지속적인 과정입니다. 정기적으로 모니터링하고 조정하세요!

package/docs/PRD.ko.md

@@ -88,7 +88,7 @@ your_project/
 ├── .claude/commands/aiwf/              # Claude Code 사용자 정의 명령어
 │   ├── initialize.md                   # 프로젝트 초기화
 │   ├── prime_context.md                # 컨텍스트 로딩
-│   ├── plan_milestone.md               # 마일스톤 계획
+│   ├── aiwf_create_milestone_plan.md   # 마일스톤 계획
 │   ├── create_sprints_from_milestone.md # 스프린트 생성
 │   ├── do_task.md                      # 태스크 실행
 │   ├── commit.md                       # Git 커밋 워크플로우
@@ -115,7 +115,7 @@ your_project/
 ### 명령어 시스템
 이 프레임워크는 AI 지원 개발을 위한 25개 이상의 전문 명령어를 포함합니다:
 - **설정**: `initialize`, `prime`, `prime_context`
-- **계획**: `plan_milestone`, `create_sprints_from_milestone`, `create_sprint_tasks`
+- **계획**: `aiwf_create_milestone_plan`, `aiwf_create_sprints_from_milestone`, `aiwf_create_sprint_tasks`
 - **개발**: `do_task`, `commit`, `test`, `code_review`
 - **자동화**: `yolo` (자율 태스크 실행)
 - **GitHub 통합**: `issue_create`, `pr_create`

package/docs/PRD.md

@@ -90,7 +90,7 @@ your_project/
 ├── .claude/commands/aiwf/              # Claude Code custom commands
 │   ├── initialize.md                   # Project initialization
 │   ├── prime_context.md                # Context loading
-│   ├── plan_milestone.md               # Milestone planning
+│   ├── aiwf_create_milestone_plan.md   # Milestone planning
 │   ├── create_sprints_from_milestone.md # Sprint creation
 │   ├── do_task.md                      # Task execution
 │   ├── commit.md                       # Git commit workflow
@@ -117,7 +117,7 @@ your_project/
 ### Command System
 The framework includes 25+ specialized commands for AI-assisted development:
 - **Setup**: `initialize`, `prime`, `prime_context`
-- **Planning**: `plan_milestone`, `create_sprints_from_milestone`, `create_sprint_tasks`
+- **Planning**: `aiwf_create_milestone_plan`, `aiwf_create_sprints_from_milestone`, `aiwf_create_sprint_tasks`
 - **Development**: `do_task`, `commit`, `test`, `code_review`
 - **Automation**: `yolo` (autonomous task execution)
 - **GitHub Integration**: `issue_create`, `pr_create`