aiwf 0.3.17 → 0.3.19

package/README.ko.md

@@ -33,6 +33,7 @@ aiwf install
 2. **프로젝트 설정**: 현재 디렉토리에 AIWF 초기화
 3. **Claude 명령어**: 언어별 명령어 설치
 4. **문서화**: 가이드 및 템플릿 다운로드
+5. **검증**: 포괄적인 설치 검증 및 문제 해결
 
 ## 🚀 사용법
 
@@ -120,6 +121,42 @@ your_project/
 - English documentation and templates
 - Standard project management content
 
+## 🛠️ CLI 도구
+
+AIWF는 프로젝트 관리의 다양한 측면을 위한 여러 전문 CLI 도구를 제공합니다:
+
+### 주요 CLI 명령어
+- `aiwf install` - 현재 프로젝트에 AIWF 프레임워크 설치
+- `aiwf create-project` - 템플릿에서 새 프로젝트 생성
+- `aiwf compress` - 토큰 최적화를 위한 컨텍스트 압축
+- `aiwf token` - 토큰 사용량 모니터링 및 관리
+- `aiwf persona` - AI 페르소나 관리
+- `aiwf evaluate` - AI 응답 및 코드 품질 평가
+
+### 스프린트 관리 (`aiwf-sprint`)
+- `aiwf-sprint create` - 새로운 독립 스프린트 생성
+- `aiwf-sprint list` - 모든 스프린트 목록 조회
+- `aiwf-sprint status` - 스프린트 상태 및 진행상황 표시
+- `aiwf-sprint task create` - 스프린트에 작업 추가
+- `aiwf-sprint task execute` - 스프린트 작업 실행
+
+### 체크포인트 시스템 (`aiwf-checkpoint`)
+- `aiwf-checkpoint create` - 롤백을 위한 프로젝트 체크포인트 생성
+- `aiwf-checkpoint list` - 사용 가능한 모든 체크포인트 목록
+- `aiwf-checkpoint restore` - 이전 체크포인트로 프로젝트 복원
+
+### 언어 관리 (`aiwf-lang`)
+- `aiwf-lang status` - 현재 언어 설정 확인
+- `aiwf-lang set ko` - 한국어로 전환
+- `aiwf-lang set en` - 영어로 전환
+
+### 캐시 관리 (`aiwf-cache`)
+- `aiwf-cache download` - 템플릿을 로컬 캐시에 다운로드
+- `aiwf-cache list` - 캐시된 모든 템플릿 목록
+- `aiwf-cache clean` - 캐시 저장소 정리
+- `aiwf-cache update` - 캐시된 템플릿 업데이트
+- `aiwf-cache status` - 캐시 상태 및 사용량 확인
+
 ## 🎯 시작하기
 
 설치 후 다음 단계:
@@ -137,6 +174,51 @@ your_project/
 - **리뷰**: `/project:aiwf:code_review` - 코드 리뷰
 - **GitHub 연동**: `/project:aiwf:issue_create`, `/project:aiwf:pr_create`
 
+## 🏗️ 코드 아키텍처
+
+### 최적화된 검증 시스템
+
+AIWF는 안정적인 설치와 운영을 보장하는 크게 개선된 검증 시스템을 특징으로 합니다:
+
+#### v0.3.18+의 주요 개선사항
+- **86% 코드 감소**: validator.js를 348줄에서 48줄로 간소화
+- **통합 인터페이스**: 3개의 중복 메서드를 대체하는 단일 `validateInstallation()` 함수
+- **상수 기반 구성**: 모든 검증 매개변수가 `VALIDATION_CONSTANTS`에 중앙화됨
+- **향상된 오류 보고**: 상세한 진단을 포함한 구체적이고 실행 가능한 오류 메시지
+
+#### VALIDATION_CONSTANTS 구조
+```javascript
+const VALIDATION_CONSTANTS = {
+  MIN_FILE_SIZE: 10,              // 최소 파일 크기 요구사항
+  MIN_RULE_FILE_SIZE: 50,         // AI 도구 규칙 파일의 최소 크기
+  MIN_FILE_COUNT: {
+    CURSOR_MDC: 2,                // Cursor용 필수 .mdc 파일
+    WINDSURF_MD: 2,               // Windsurf용 필수 .md 파일  
+    CLAUDE_COMMANDS: 4            // Claude용 필수 명령 파일
+  }
+};
+```
+
+#### 검증 기능
+- **다중 도구 지원**: Claude Code, Cursor, Windsurf, Gemini CLI 검증
+- **파일 무결성 검사**: 크기 검증, 접근성 확인, 구조 검증
+- **지능적 오류 복구**: 실패한 검증에 대한 상세한 문제 해결 가이드
+- **성능 최적화**: 감소된 메모리 사용량으로 더 빠른 실행
+
+### 클린 아키텍처 원칙
+
+코드베이스는 유지보수성과 확장성을 위한 클린 아키텍처 원칙을 따릅니다:
+
+#### 코드 중복 제거
+- **통합된 검증 로직**: 통합된 검증 함수가 중복성을 제거함
+- **공유 상수**: 중앙화된 구성이 유지보수 오버헤드를 줄임
+- **간소화된 오류 처리**: 모든 검증 유형에 걸쳐 일관된 오류 보고
+
+#### 개선된 개발자 경험
+- **명확한 관심사 분리**: 검증, 파일 관리, 오류 보고가 적절히 분리됨
+- **유지보수 가능한 코드 구조**: 감소된 복잡성으로 코드베이스 이해와 수정이 더 쉬워짐
+- **성능 이점**: 최적화된 코드 경로가 설치 속도와 안정성을 향상시킴
+
 ## 📚 문서
 
 ### 핵심 문서
@@ -158,6 +240,8 @@ your_project/
 - [AI 워크플로우](docs/AI-WORKFLOW.ko.md) - AI 통합 패턴
 - [API 참조](docs/API_REFERENCE.md) - 프로그래머틱 사용
 - [전체 API 참조](docs/API_REFERENCE_FULL.ko.md) - 포괄적인 API 문서
+- [Validator API 참조](docs/VALIDATOR_API.ko.md) - 검증 시스템 API 문서
+- [코드 정리 가이드](docs/CODE_CLEANUP_GUIDE.ko.md) - 코드 정리 원칙과 패턴
 - [문제 해결](docs/TROUBLESHOOTING.md) - 일반적인 문제 및 해결책
 
 ## ✨ 주요 기능

package/README.md

@@ -35,6 +35,9 @@ AIWF operates as the master orchestration agent that coordinates complex develop
 ### 🔗 **Seamless Integration**
 Native support for Claude Code, Cursor, Windsurf, GitHub, and Git with automated hooks, issue creation, and PR management.
 
+### ✅ **Robust Validation System**
+Advanced installation validation with intelligent file checking, dependency verification, and automated troubleshooting. Enhanced validation architecture ensures reliable framework setup and operation.
+
 ## 📦 Installation
 
 ### Global Installation (Recommended)
@@ -57,6 +60,7 @@ The installer will guide you through:
 2. **Project Setup**: Initialize AIWF in your current directory
 3. **Claude Commands**: Install language-specific commands
 4. **Documentation**: Download guides and templates
+5. **Validation**: Comprehensive installation verification and troubleshooting
 
 ## 🚀 Getting Started Guide
 
@@ -141,6 +145,42 @@ Revolutionary multi-agent orchestration that enables completely autonomous devel
 
 Master agent analyzes requirements and coordinates specialized subagents that create tasks, write code, run tests, and commit changes - achieving true multi-agent autonomous software development.
 
+## 🛠️ CLI Tools
+
+AIWF provides several specialized CLI tools for different aspects of project management:
+
+### Main CLI Commands
+- `aiwf install` - Install AIWF framework in current project
+- `aiwf create-project` - Create new project from templates
+- `aiwf compress` - Context compression for token optimization
+- `aiwf token` - Token usage monitoring and management
+- `aiwf persona` - AI persona management
+- `aiwf evaluate` - AI response and code quality evaluation
+
+### Sprint Management (`aiwf-sprint`)
+- `aiwf-sprint create` - Create new independent sprint
+- `aiwf-sprint list` - List all sprints
+- `aiwf-sprint status` - Show sprint status and progress
+- `aiwf-sprint task create` - Add tasks to sprint
+- `aiwf-sprint task execute` - Execute sprint tasks
+
+### Checkpoint System (`aiwf-checkpoint`)
+- `aiwf-checkpoint create` - Create project checkpoint for rollback
+- `aiwf-checkpoint list` - List all available checkpoints
+- `aiwf-checkpoint restore` - Restore project to previous checkpoint
+
+### Language Management (`aiwf-lang`)
+- `aiwf-lang status` - Check current language settings
+- `aiwf-lang set ko` - Switch to Korean
+- `aiwf-lang set en` - Switch to English
+
+### Cache Management (`aiwf-cache`)
+- `aiwf-cache download` - Download templates to local cache
+- `aiwf-cache list` - List all cached templates
+- `aiwf-cache clean` - Clean cache storage
+- `aiwf-cache update` - Update cached templates
+- `aiwf-cache status` - Check cache status and usage
+
 ## 📁 What Gets Installed
 
 ### Directory Structure
@@ -178,6 +218,51 @@ Based on your language selection, you'll get:
 - Korean documentation and templates
 - Localized project management content
 
+## 🏗️ Code Architecture
+
+### Optimized Validation System
+
+AIWF features a significantly improved validation system that ensures reliable installation and operation:
+
+#### Key Improvements in v0.3.18+
+- **86% Code Reduction**: Streamlined validator.js from 348 lines to 48 lines
+- **Unified Interface**: Single `validateInstallation()` function replaces 3 redundant methods
+- **Constants-Based Configuration**: All validation parameters centralized in `VALIDATION_CONSTANTS`
+- **Enhanced Error Reporting**: Specific, actionable error messages with detailed diagnostics
+
+#### VALIDATION_CONSTANTS Structure
+```javascript
+const VALIDATION_CONSTANTS = {
+  MIN_FILE_SIZE: 10,              // Minimum file size requirement
+  MIN_RULE_FILE_SIZE: 50,         // Minimum size for AI tool rule files
+  MIN_FILE_COUNT: {
+    CURSOR_MDC: 2,                // Required .mdc files for Cursor
+    WINDSURF_MD: 2,               // Required .md files for Windsurf  
+    CLAUDE_COMMANDS: 4            // Required command files for Claude
+  }
+};
+```
+
+#### Validation Features
+- **Multi-Tool Support**: Validates Claude Code, Cursor, Windsurf, and Gemini CLI
+- **File Integrity Checks**: Size validation, accessibility verification, and structure validation
+- **Intelligent Error Recovery**: Detailed troubleshooting guidance for failed validations
+- **Performance Optimized**: Faster execution with reduced memory footprint
+
+### Clean Architecture Principles
+
+The codebase follows clean architecture principles for maintainability and extensibility:
+
+#### Eliminated Code Duplication
+- **Unified Validation Logic**: Consolidated validation functions eliminate redundancy
+- **Shared Constants**: Centralized configuration reduces maintenance overhead
+- **Streamlined Error Handling**: Consistent error reporting across all validation types
+
+#### Improved Developer Experience
+- **Clear Separation of Concerns**: Validation, file management, and error reporting are properly isolated
+- **Maintainable Code Structure**: Reduced complexity makes the codebase easier to understand and modify
+- **Performance Benefits**: Optimized code paths improve installation speed and reliability
+
 ## 📚 Documentation
 
 ### Core Documentation
@@ -199,6 +284,8 @@ Based on your language selection, you'll get:
 - [AI Workflow](docs/AI-WORKFLOW.md) - AI integration patterns
 - [API Reference](docs/API_REFERENCE.md) - Programmatic usage
 - [Complete API Reference](docs/API_REFERENCE_FULL.md) - Comprehensive API documentation
+- [Validator API Reference](docs/VALIDATOR_API.md) - Validation system API documentation
+- [Code Cleanup Guide](docs/CODE_CLEANUP_GUIDE.md) - Code cleanup principles and patterns
 - [Troubleshooting](docs/TROUBLESHOOTING.md) - Common issues and solutions
 
 ## 📖 Source

package/ai-tools/README.md

@@ -0,0 +1,105 @@
+# AIWF AI Tool Integration Templates
+
+This directory contains integration templates for various AI development tools to work seamlessly with the AI Workflow Framework (AIWF).
+
+## Available Tools
+
+### 1. Claude Code (`claude-code`)
+- **Description**: Official Anthropic Claude Code integration
+- **Features**: Deep AIWF integration, feature ledger sync, AI personas
+- **Installation**: `aiwf ai-tool install claude-code`
+
+### 2. GitHub Copilot (`github-copilot`)
+- **Description**: GitHub Copilot configuration for AIWF projects
+- **Features**: Feature-aware suggestions, sprint task integration
+- **Installation**: `aiwf ai-tool install github-copilot`
+
+### 3. Cursor (`cursor`)
+- **Description**: Cursor IDE integration with AIWF
+- **Features**: Multi-file context, composer enhancement, task tracking
+- **Installation**: `aiwf ai-tool install cursor`
+
+### 4. Windsurf (`windsurf`)
+- **Description**: Windsurf IDE with Cascade AI integration
+- **Features**: Flow-based development, multi-agent support, visual progress
+- **Installation**: `aiwf ai-tool install windsurf`
+
+### 5. Augment (`augment`)
+- **Description**: Augment Code with deep codebase understanding
+- **Features**: Team collaboration, knowledge queries, smart refactoring
+- **Installation**: `aiwf ai-tool install augment`
+
+## Quick Start
+
+1. **List available tools**:
+   ```bash
+   aiwf ai-tool list
+   ```
+
+2. **Install a tool**:
+   ```bash
+   aiwf ai-tool install <tool-name>
+   ```
+
+3. **Update installed tools**:
+   ```bash
+   aiwf ai-tool update <tool-name>
+   ```
+
+4. **Verify installation**:
+   ```bash
+   aiwf ai-tool verify <tool-name>
+   ```
+
+## Integration Features
+
+All templates provide:
+- ✅ Feature Ledger integration
+- ✅ AI Persona support
+- ✅ Sprint task management
+- ✅ Context optimization
+- ✅ Offline cache support
+
+## Directory Structure
+
+```
+ai-tools/
+├── claude-code/
+│   ├── template/
+│   ├── config.json
+│   └── README.md
+├── github-copilot/
+│   ├── template/
+│   ├── config.json
+│   └── README.md
+├── cursor/
+│   ├── template/
+│   ├── config.json
+│   └── README.md
+├── windsurf/
+│   ├── template/
+│   ├── config.json
+│   └── README.md
+└── augment/
+    ├── template/
+    ├── config.json
+    └── README.md
+```
+
+## Customization
+
+Each tool template can be customized:
+1. Edit the template files in the tool directory
+2. Modify config.json for tool-specific settings
+3. Add project-specific rules to the template files
+
+## Support
+
+For issues or questions:
+- Check individual tool README files
+- Visit [AIWF Documentation](https://aiwf.dev)
+- Submit issues on GitHub
+
+---
+
+*AIWF AI Tool Integration System v1.0.0*

package/ai-tools/augment/README.md

@@ -0,0 +1,371 @@
+# Augment AIWF Integration Template
+
+## Overview
+
+This template integrates Augment Code's deep codebase understanding and team collaboration features with AIWF's structured development framework. It creates a powerful combination for AI-assisted team development.
+
+## Features
+
+- **Deep Codebase Understanding**: Augment comprehends your entire AIWF structure
+- **Team Collaboration**: Shared feature knowledge and task coordination
+- **Intelligent Code Completion**: Context-aware suggestions based on features
+- **Automated Documentation**: Generate docs aligned with AIWF standards
+- **Smart Refactoring**: Feature-aware code improvements
+- **Knowledge Queries**: Ask questions about your AIWF project
+
+## Installation
+
+```bash
+# Install Augment template
+aiwf ai-tool install augment
+
+# Or manually copy template files
+cp -r .aiwf/ai-tools/augment/template/* .
+```
+
+## Configuration
+
+The template includes:
+
+1. **augment.config.json**: Main configuration
+   - AIWF integration settings
+   - Team collaboration options
+   - AI model preferences
+   - Automation rules
+
+2. **.augment/aiwf-integration.md**: Integration guide
+   - Usage patterns
+   - Team features
+   - Best practices
+   - Command reference
+
+## Core Capabilities
+
+### 1. Feature-Aware Development
+
+Augment understands your Feature Ledger:
+
+```javascript
+// Start typing code
+function createUser() {
+  // Augment suggests:
+  // This relates to Feature FL-002 - User Management
+  // Dependencies: FL-001 (Authentication)
+  // Current status: in_progress
+}
+```
+
+### 2. Team Knowledge Sharing
+
+Share understanding across your team:
+
+```
+@augment who implemented authentication?
+// Alice implemented FL-001 last week
+
+@augment show alice's patterns for error handling
+// Shows consistent patterns from Alice's code
+```
+
+### 3. Sprint Task Management
+
+Stay aligned with sprints:
+
+```
+@augment my current tasks
+// T13_S03 - AI Tool Integration (in_progress)
+// T14_S03 - Performance Optimization (pending)
+
+@augment suggest next task
+// Based on your expertise and dependencies
+```
+
+### 4. Intelligent Documentation
+
+Auto-generate AIWF-compliant docs:
+
+```javascript
+// @augment document this class
+/**
+ * UserService handles user management operations
+ * 
+ * @feature FL-002 - User Management
+ * @sprint S03
+ * @implements Requirements from FL-002 specification
+ * @dependencies FL-001 (Authentication)
+ * 
+ * @example
+ * const userService = new UserService();
+ * const user = await userService.createUser(data);
+ */
+class UserService {
+  // Implementation
+}
+```
+
+## Usage Examples
+
+### 1. Feature Development
+
+```javascript
+// @augment implement FL-003 payment processing
+
+// Augment provides:
+// - Feature specification summary
+// - Required methods from spec
+// - Integration points with other features
+// - Test requirements
+// - Documentation template
+```
+
+### 2. Code Review
+
+```javascript
+// @augment review this PR for FL-001 compliance
+
+// Augment checks:
+// ✓ Implements all required features
+// ✓ Follows team patterns
+// ✓ Has appropriate tests
+// ⚠ Missing error handling for edge case X
+// ⚠ Consider using established pattern from auth.js
+```
+
+### 3. Refactoring
+
+```javascript
+// @augment refactor payment module for better feature separation
+
+// Augment suggests:
+// 1. Extract FL-003 logic to PaymentService
+// 2. Move FL-001 auth checks to middleware
+// 3. Create feature flags for gradual rollout
+// 4. Add monitoring for new architecture
+```
+
+### 4. Knowledge Queries
+
+```
+@augment how does our authentication flow work?
+// Augment explains FL-001 implementation with code examples
+
+@augment what depends on the user service?
+// Features: FL-003 (payments), FL-004 (notifications)
+// Files: 15 controllers, 8 services, 23 tests
+
+@augment show architecture diagram
+// Generates visual representation of feature dependencies
+```
+
+## Team Collaboration Features
+
+### 1. Expertise Mapping
+
+```
+@augment team expertise
+// Alice: FL-001 (auth), FL-002 (users) - Senior
+// Bob: FL-003 (payments), FL-005 (analytics) - Expert
+// Carol: FL-004 (notifications) - Intermediate
+```
+
+### 2. Task Assignment
+
+```
+@augment assign T14_S03
+// Recommends: Bob (payment expertise, available capacity)
+// Alternative: Alice (general expertise, higher load)
+```
+
+### 3. Code Patterns
+
+```
+@augment show team patterns for error handling
+// Consistent patterns across team:
+// - Custom error classes per feature
+// - Centralized error logging
+// - User-friendly error messages
+```
+
+### 4. Onboarding
+
+```
+@augment create onboarding guide for new developer
+// Generates comprehensive guide:
+// - Project structure
+// - Feature overview
+// - Team patterns
+// - Development workflow
+// - Key architecture decisions
+```
+
+## Advanced Features
+
+### 1. Codebase Analysis
+
+```
+@augment analyze feature coverage
+// FL-001: 95% implemented, 90% tested
+// FL-002: 80% implemented, 85% tested
+// FL-003: 60% implemented, 70% tested
+
+@augment find technical debt
+// - Duplicated auth logic in 3 files
+// - Missing tests for edge cases in FL-002
+// - Outdated dependencies in payment module
+```
+
+### 2. Architecture Insights
+
+```
+@augment analyze architecture
+// - Clean separation between features
+// - Some circular dependencies detected
+// - Opportunity to extract shared utilities
+// - Consider implementing event system
+```
+
+### 3. Performance Analysis
+
+```
+@augment analyze performance bottlenecks
+// - Database queries in user service (N+1)
+// - Synchronous payment processing
+// - Large bundle size from unused imports
+```
+
+### 4. Test Generation
+
+```javascript
+// @augment generate tests for UserService
+
+describe('UserService (FL-002)', () => {
+  // Generates comprehensive test suite
+  // based on feature specifications
+});
+```
+
+## Best Practices
+
+### 1. Feature-First Approach
+
+Always start with feature context:
+- Check Feature Ledger before coding
+- Reference features in all code
+- Update feature status regularly
+
+### 2. Team Alignment
+
+Leverage team features:
+- Share knowledge through Augment
+- Follow team patterns
+- Document decisions
+
+### 3. Sprint Discipline
+
+Stay focused on current work:
+- Check sprint tasks daily
+- Update progress regularly
+- Complete tasks fully
+
+### 4. Continuous Learning
+
+Let Augment teach:
+- Ask about unfamiliar code
+- Learn team patterns
+- Understand architecture
+
+## Configuration Options
+
+### 1. Model Selection
+
+```json
+{
+  "models": {
+    "completion": "augment-fast",      // Quick suggestions
+    "understanding": "augment-deep",   // Complex analysis
+    "documentation": "augment-doc",    // Doc generation
+    "review": "augment-review"         // Code review
+  }
+}
+```
+
+### 2. Team Settings
+
+```json
+{
+  "team": {
+    "sync_interval": "5m",
+    "share_patterns": true,
+    "expertise_tracking": true,
+    "automated_assignment": false
+  }
+}
+```
+
+### 3. Automation
+
+```json
+{
+  "automation": {
+    "auto_document": true,
+    "suggest_refactoring": true,
+    "update_feature_status": true,
+    "generate_tests": false
+  }
+}
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Slow indexing**
+   ```
+   @augment config set indexing.incremental true
+   @augment reindex --fast
+   ```
+
+2. **Team sync problems**
+   ```
+   @augment team sync --reset
+   @augment team verify
+   ```
+
+3. **Feature recognition**
+   ```
+   @augment feature reindex
+   @augment feature validate
+   ```
+
+### Performance Tips
+
+1. Enable caching for faster responses
+2. Use incremental indexing
+3. Compress large contexts
+4. Limit analysis scope when needed
+
+## Updates
+
+Keep Augment template current:
+
+```bash
+# Check version
+aiwf ai-tool version augment
+
+# Update template
+aiwf ai-tool update augment
+
+# Verify installation
+aiwf ai-tool verify augment
+```
+
+## Resources
+
+- [Augment Documentation](https://augmentcode.com/docs)
+- [AIWF Documentation](https://aiwf.dev/docs)
+- [Integration Examples](https://github.com/aiwf/augment-examples)
+- [Team Playbook](https://aiwf.dev/guides/team-collaboration)
+
+---
+
+*Augment Integration Template v1.0.0*