aiwf 0.3.8 → 0.3.12

package/docs/STATE_MANAGEMENT_GUIDE.ko.md

@@ -0,0 +1,278 @@
+# AIWF 상태 관리 가이드
+
+## 개요
+
+AIWF 상태 관리 시스템은 AI 어시스턴트가 세션 간에 완벽한 컨텍스트 인식을 유지하도록 돕는 혁신적인 기능입니다. 지능적인 작업 우선순위 지정, 의존성 추적, 워크플로우 검증을 통해 개발 효율성을 극대화합니다.
+
+## 핵심 개념
+
+### 1. 상태 인덱스
+중앙 `task-state-index.json` 파일이 관리하는 내용:
+- 현재 프로젝트 상태 (마일스톤, 스프린트, 태스크)
+- 태스크 의존성 및 관계
+- 진행 추적 및 완료 상태
+- 원활한 세션 연속성을 위한 AI 컨텍스트
+
+### 2. 워크플로우 규칙
+`workflow-rules.json`이 정의하는 내용:
+- 마일스톤 → 스프린트 → 태스크 계층 구조
+- 상태 전환 조건
+- 우선순위 계산 가중치
+- AI 동작 선호 설정
+
+### 3. 우선순위 매트릭스
+태스크 점수 계산 기준:
+- **긴급도 (40%)**: 마감일 기반 점수
+- **중요도 (30%)**: 우선순위 레벨 (high/medium/low)
+- **의존성 (20%)**: 차단된 태스크 수
+- **노력 (10%)**: 역관계 (낮은 노력 = 높은 우선순위)
+
+## CLI 명령어
+
+### 기본 상태 관리
+
+```bash
+# 파일 시스템에서 상태 인덱스 업데이트
+aiwf state update
+
+# 현재 상태 및 통계 표시
+aiwf state show
+
+# 다음 권장 작업 가져오기
+aiwf state next
+
+# 워크플로우 일관성 검증
+aiwf state validate
+```
+
+### 태스크 진행 추적
+
+```bash
+# 태스크를 시작됨으로 표시
+aiwf state start T01_S01
+
+# 태스크를 완료됨으로 표시
+aiwf state complete T01_S01
+
+# 특정 태스크에 집중 (상세 보기)
+aiwf state focus T01_S01
+```
+
+### 고급 옵션
+
+```bash
+# 프로젝트 전체 강제 재스캔
+aiwf state update --force
+
+# JSON 형식으로 다음 작업 가져오기
+aiwf state next --format=json
+
+# 특정 측면 검증
+aiwf state validate --focus=dependencies
+aiwf state validate --check=sprint-consistency
+```
+
+## Claude 명령어와의 통합
+
+### 스마트 태스크 실행
+
+새로운 스마트 명령어는 상태 관리와 통합됩니다:
+
+```bash
+# 워크플로우 인식으로 태스크 시작
+/project:aiwf:smart_start T01_S01
+
+# 상태 동기화와 함께 태스크 완료
+/project:aiwf:smart_complete T01_S01
+```
+
+### 향상된 YOLO 모드
+
+YOLO 모드는 이제 워크플로우 인텔리전스를 사용합니다:
+
+```bash
+# 자동 태스크 선택으로 실행
+/project:aiwf:yolo
+
+# 워크플로우 최적화를 통한 스프린트별 실행
+/project:aiwf:yolo S03
+
+# 적응적 스프린트 관리 (80% 규칙)
+/project:aiwf:yolo sprint-all
+```
+
+## 워크플로우 검증
+
+### 검증 보고서 예시
+
+```
+🔍 워크플로우 검증 보고서
+
+3개의 문제 발견:
+
+❌ 오류 (1):
+  1. INCONSISTENT_STATE
+     스프린트 S02가 완료로 표시되었지만 2개의 미완료 태스크 존재
+     
+⚠️  경고 (1):
+  1. STALE_TASK
+     태스크 T03_S01이 7일 이상 진행 중
+     
+💡 제안사항 (1):
+  1. SPRINT_PREPARATION
+     스프린트 S02가 85% 완료. 다음 스프린트 준비를 고려하세요.
+```
+
+### 일반적인 문제 및 해결책
+
+#### 1. 상태 불일치
+```bash
+# 상태 업데이트로 수정
+aiwf state update --force
+
+# 또는 수동으로 태스크 완료
+aiwf state complete T05_S02
+aiwf state complete T07_S02
+```
+
+#### 2. 순환 의존성
+- 태스크 파일에서 태스크 의존성 검토
+- 순환 참조 제거
+- `aiwf state validate`를 실행하여 수정 확인
+
+#### 3. 80% 규칙 트리거
+```bash
+# 스프린트가 80%에 도달하면 다음 스프린트 준비
+/project:aiwf:create_sprint_tasks S03
+```
+
+## 모범 사례
+
+### 1. 정기적인 상태 업데이트
+- 주요 변경 후 `aiwf state update` 실행
+- YOLO 모드 시작 전에 사용
+- 스프린트 완료 후 검증
+
+### 2. 의존성 관리
+- 태스크 메타데이터에 의존성 정의
+- 순환 의존성 피하기
+- `blocks`와 `depends_on` 필드를 올바르게 사용
+
+### 3. 스프린트 계획
+- 80% 규칙이 스프린트 전환을 안내하도록 허용
+- 주요 결정 전에 워크플로우 검증 사용
+- `aiwf state next`의 AI 권장사항 신뢰
+
+## 예제 워크플로우
+
+### 새 세션 시작
+
+```bash
+# 1. 최신 상태로 업데이트
+aiwf state update
+
+# 2. 현재 상태 확인
+aiwf state show
+
+# 3. 권장사항 가져오기
+aiwf state next
+
+# 4. 권장 태스크 시작
+aiwf state start T01_S01
+/project:aiwf:smart_start T01_S01
+```
+
+### 작업 완료
+
+```bash
+# 1. 태스크 완료
+/project:aiwf:smart_complete T01_S01
+
+# 2. 상태가 자동으로 업데이트됨
+# 3. 다음 권장사항 가져오기
+aiwf state next
+
+# 4. 다음 태스크로 계속
+```
+
+### 스프린트 전환
+
+```bash
+# 1. 스프린트 진행 상황 확인
+aiwf state show
+
+# 2. 80% 완료 시 검증
+aiwf state validate
+
+# 3. 검증이 제안하면 다음 스프린트 준비
+/project:aiwf:create_sprint_tasks S03
+
+# 4. 워크플로우 계속
+```
+
+## 문제 해결
+
+### 상태가 업데이트되지 않음
+```bash
+# 전체 강제 재스캔
+aiwf state update --force
+
+# 파일 권한 확인
+ls -la .aiwf/
+```
+
+### 의존성 누락
+```bash
+# 의존성 검증
+aiwf state validate --focus=dependencies
+
+# 적절한 메타데이터를 위해 태스크 파일 검토
+```
+
+### 워크플로우 오류
+```bash
+# 종합적인 검증 실행
+aiwf state validate
+
+# 워크플로우 규칙 확인
+cat .aiwf/workflow-rules.json
+```
+
+## 고급 기능
+
+### 사용자 정의 우선순위 가중치
+
+`.aiwf/workflow-rules.json` 편집:
+```json
+{
+  "priority_weights": {
+    "urgency": 0.4,
+    "importance": 0.3,
+    "dependencies": 0.2,
+    "effort": 0.1
+  }
+}
+```
+
+### AI 동작 조정
+
+AI 선호 설정 구성:
+```json
+{
+  "ai_behavior": {
+    "auto_select_tasks": true,
+    "prefer_blocked_tasks": true,
+    "parallel_task_limit": 3,
+    "risk_tolerance": "conservative"
+  }
+}
+```
+
+## 결론
+
+AIWF 상태 관리 시스템은 AI 어시스턴트가 프로젝트와 작업하는 방식을 변화시킵니다. 완벽한 컨텍스트 인식을 유지하고 지능적인 권장사항을 제공함으로써 인간 개발자와 AI 어시스턴트 간의 최대 생산성과 원활한 협업을 보장합니다.
+
+자세한 정보는 다음을 참조하세요:
+- [COMMANDS_GUIDE.md](./COMMANDS_GUIDE.md) - 전체 명령어 참조
+- [README.md](../README.md) - 프로젝트 개요
+- [CHANGELOG.md](../CHANGELOG.md) - 최신 업데이트

package/docs/STATE_MANAGEMENT_GUIDE.md

@@ -0,0 +1,278 @@
+# 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.md

@@ -1,6 +1,6 @@
 # AIWF Troubleshooting Guide
 
-This guide helps you resolve common issues when using AIWF (AI Workflow Framework). If you can't find a solution here, please check our [GitHub Issues](https://github.com/aiwf/aiwf/issues) or create a new issue.
+This guide helps you resolve common issues when using AIWF (AI Workflow Framework). If you can't find a solution here, please check our [GitHub Issues](https://github.com/moonklabs/aiwf/issues) or create a new issue.
 
 ## Table of Contents
 
@@ -30,9 +30,10 @@ npm ERR! path /usr/local/lib/node_modules/aiwf
 
 **Solutions:**
 
-1. **Use npx instead of global install (Recommended):**
+1. **Install globally:**
    ```bash
-   npx aiwf
+   npm install -g aiwf
+   aiwf install
    ```
 
 2. **Fix npm permissions:**
@@ -100,7 +101,7 @@ Error: Cannot find module 'ora'
 
 4. **Try offline installation:**
    ```bash
-   npx aiwf --offline
+   aiwf install --offline
    ```
 
 ---
@@ -123,7 +124,7 @@ Command not found: /project:aiwf:initialize
 
 2. **Reinstall AIWF commands:**
    ```bash
-   npx aiwf --force
+   aiwf install --force
    ```
 
 3. **Check Claude Code settings:**
@@ -571,7 +572,7 @@ Jest: "global" coverage threshold for statements (80%) not met: 0%
 
 1. **Update language files:**
    ```bash
-   npx aiwf --update-lang
+   aiwf install --update-lang
    ```
 
 2. **Check translation files:**
@@ -595,7 +596,7 @@ Jest: "global" coverage threshold for statements (80%) not met: 0%
 **Solution:**
 ```bash
 # Recreate AIWF structure
-npx aiwf --repair
+aiwf install --repair
 ```
 
 ### "EPERM: operation not permitted"
@@ -615,7 +616,7 @@ chmod -R u+rw .aiwf/
 **Solution:**
 ```bash
 # Force overwrite
-npx aiwf --force
+aiwf install --force
 ```
 
 ### "ValidationError: Invalid feature ID"
@@ -639,7 +640,7 @@ npx aiwf --force
 export AIWF_DEBUG=true
 
 # Run with verbose output
-npx aiwf --verbose
+aiwf install --verbose
 ```
 
 ### Check System Information
@@ -679,10 +680,10 @@ tail -f .aiwf/logs/commands.log
 If you can't resolve your issue:
 
 1. **Search existing issues:**
-   - [GitHub Issues](https://github.com/aiwf/aiwf/issues)
+   - [GitHub Issues](https://github.com/moonklabs/aiwf/issues)
 
 2. **Create a new issue with:**
-   - AIWF version: `npx aiwf --version`
+   - AIWF version: `aiwf --version`
    - Node.js version: `node --version`
    - Operating system
    - Error messages
@@ -690,7 +691,7 @@ If you can't resolve your issue:
 
 3. **Join the community:**
    - Discord: [discord.gg/aiwf](https://discord.gg/aiwf)
-   - Discussions: [GitHub Discussions](https://github.com/aiwf/aiwf/discussions)
+   - Discussions: [GitHub Discussions](https://github.com/moonklabs/aiwf/discussions)
 
 4. **Emergency support:**
    - Email: support@aiwf.dev (for critical issues only)
@@ -701,7 +702,7 @@ If you can't resolve your issue:
 
 1. **Keep AIWF updated:**
    ```bash
-   npx aiwf --check-updates
+   aiwf --check-updates
    ```
 
 2. **Regular backups:**