aiwf 0.3.23 → 0.4.0

package/docs/STATE_MANAGEMENT_GUIDE.md

@@ -1,278 +0,0 @@
-# AIWF State Management Guide
-
-## Overview
-
-The AIWF State Management System is a revolutionary feature that helps AI assistants maintain perfect context awareness across sessions. It provides intelligent task prioritization, dependency tracking, and workflow validation to maximize development efficiency.
-
-## Key Concepts
-
-### 1. State Index
-The central `task-state-index.json` file maintains:
-- Current project state (milestones, sprints, tasks)
-- Task dependencies and relationships
-- Progress tracking and completion status
-- AI context for seamless session continuity
-
-### 2. Workflow Rules
-The `workflow-rules.json` defines:
-- Milestone → Sprint → Task hierarchy
-- State transition conditions
-- Priority calculation weights
-- AI behavior preferences
-
-### 3. Priority Matrix
-Tasks are scored based on:
-- **Urgency (40%)**: Deadline-based scoring
-- **Importance (30%)**: Priority level (high/medium/low)
-- **Dependencies (20%)**: Number of blocked tasks
-- **Effort (10%)**: Inverse relationship (lower effort = higher priority)
-
-## CLI Commands
-
-### Basic State Management
-
-```bash
-# Update state index from file system
-aiwf state update
-
-# Display current state and statistics
-aiwf state show
-
-# Get next recommended actions
-aiwf state next
-
-# Validate workflow consistency
-aiwf state validate
-```
-
-### Task Progress Tracking
-
-```bash
-# Mark task as started
-aiwf state start T01_S01
-
-# Mark task as completed
-aiwf state complete T01_S01
-
-# Focus on specific task (for detailed view)
-aiwf state focus T01_S01
-```
-
-### Advanced Options
-
-```bash
-# Force full rescan of project
-aiwf state update --force
-
-# Get next actions in JSON format
-aiwf state next --format=json
-
-# Validate specific aspects
-aiwf state validate --focus=dependencies
-aiwf state validate --check=sprint-consistency
-```
-
-## Integration with Claude Commands
-
-### Smart Task Execution
-
-The new smart commands integrate with state management:
-
-```bash
-# Start task with workflow awareness
-/project:aiwf:smart_start T01_S01
-
-# Complete task with state synchronization
-/project:aiwf:smart_complete T01_S01
-```
-
-### Enhanced YOLO Mode
-
-YOLO mode now uses workflow intelligence:
-
-```bash
-# Run with automatic task selection
-/project:aiwf:yolo
-
-# Sprint-specific with workflow optimization
-/project:aiwf:yolo S03
-
-# Adaptive sprint management (80% rule)
-/project:aiwf:yolo sprint-all
-```
-
-## Workflow Validation
-
-### Validation Report Example
-
-```
-🔍 Workflow Validation Report
-
-Found 3 issue(s):
-
-❌ Errors (1):
-  1. INCONSISTENT_STATE
-     Sprint S02 marked complete but has 2 incomplete tasks
-     
-⚠️  Warnings (1):
-  1. STALE_TASK
-     Task T03_S01 in progress for over 7 days
-     
-💡 Suggestions (1):
-  1. SPRINT_PREPARATION
-     Sprint S02 is 85% complete. Consider preparing next sprint.
-```
-
-### Common Issues and Solutions
-
-#### 1. State Inconsistency
-```bash
-# Fix by updating state
-aiwf state update --force
-
-# Or manually complete tasks
-aiwf state complete T05_S02
-aiwf state complete T07_S02
-```
-
-#### 2. Circular Dependencies
-- Review task dependencies in task files
-- Remove circular references
-- Run `aiwf state validate` to verify fix
-
-#### 3. 80% Rule Trigger
-```bash
-# When sprint reaches 80%, prepare next sprint
-/project:aiwf:create_sprint_tasks S03
-```
-
-## Best Practices
-
-### 1. Regular State Updates
-- Run `aiwf state update` after major changes
-- Use before starting YOLO mode
-- Validate after sprint completions
-
-### 2. Dependency Management
-- Define dependencies in task metadata
-- Avoid circular dependencies
-- Use `blocks` and `depends_on` fields correctly
-
-### 3. Sprint Planning
-- Let the 80% rule guide sprint transitions
-- Use workflow validation before major decisions
-- Trust AI recommendations from `aiwf state next`
-
-## Example Workflow
-
-### Starting a New Session
-
-```bash
-# 1. Update state to latest
-aiwf state update
-
-# 2. Check current status
-aiwf state show
-
-# 3. Get recommendations
-aiwf state next
-
-# 4. Start recommended task
-aiwf state start T01_S01
-/project:aiwf:smart_start T01_S01
-```
-
-### Completing Work
-
-```bash
-# 1. Complete the task
-/project:aiwf:smart_complete T01_S01
-
-# 2. State is automatically updated
-# 3. Get next recommendation
-aiwf state next
-
-# 4. Continue with next task
-```
-
-### Sprint Transition
-
-```bash
-# 1. Check sprint progress
-aiwf state show
-
-# 2. When 80% complete, validate
-aiwf state validate
-
-# 3. If validation suggests, prepare next sprint
-/project:aiwf:create_sprint_tasks S03
-
-# 4. Continue with workflow
-```
-
-## Troubleshooting
-
-### State Not Updating
-```bash
-# Force full rescan
-aiwf state update --force
-
-# Check for file permissions
-ls -la .aiwf/
-```
-
-### Missing Dependencies
-```bash
-# Validate dependencies
-aiwf state validate --focus=dependencies
-
-# Review task files for proper metadata
-```
-
-### Workflow Errors
-```bash
-# Run comprehensive validation
-aiwf state validate
-
-# Check workflow rules
-cat .aiwf/workflow-rules.json
-```
-
-## Advanced Features
-
-### Custom Priority Weights
-
-Edit `.aiwf/workflow-rules.json`:
-```json
-{
-  "priority_weights": {
-    "urgency": 0.4,
-    "importance": 0.3,
-    "dependencies": 0.2,
-    "effort": 0.1
-  }
-}
-```
-
-### AI Behavior Tuning
-
-Configure AI preferences:
-```json
-{
-  "ai_behavior": {
-    "auto_select_tasks": true,
-    "prefer_blocked_tasks": true,
-    "parallel_task_limit": 3,
-    "risk_tolerance": "conservative"
-  }
-}
-```
-
-## Conclusion
-
-The AIWF State Management System transforms how AI assistants work with your projects. By maintaining perfect context awareness and providing intelligent recommendations, it ensures maximum productivity and seamless collaboration between human developers and AI assistants.
-
-For more information, see:
-- [COMMANDS_GUIDE.md](./COMMANDS_GUIDE.md) - Full command reference
-- [README.md](../README.md) - Project overview
-- [CHANGELOG.md](../CHANGELOG.md) - Latest updates

package/docs/TROUBLESHOOTING.ko.md

@@ -1,366 +0,0 @@
-# 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`로 해결됩니다!