aiwf 0.3.1 → 0.3.3

package/docs/guides/feature-git-integration-guide.md

@@ -0,0 +1,481 @@
+[Read in Korean (한국어로 보기)](feature-git-integration-guide-ko.md)
+
+# Feature-Git Integration Setup Guide
+
+## Overview
+
+The Feature-Git integration system is a tool that automatically connects AIWF's Feature Ledger with Git commits to track and manage feature development progress. It automates project management through commit message parsing, automatic status updates, and progress tracking.
+
+## Key Features
+
+### 1. Automatic Feature Tracking
+- Automatic connection between Git commits and Feature IDs
+- Extract Feature information from commit messages
+- Automatic Feature status updates
+
+### 2. Pre-commit Hook
+- Validate Feature ID before commit
+- Check commit message format
+- Automatic Feature Ledger updates
+
+### 3. Progress Management
+- Calculate progress based on commit count
+- Track contribution by Feature
+- Generate team productivity metrics
+
+## Installation and Setup
+
+### 1. Basic Installation
+
+**Automatic Installation (Recommended)**:
+```bash
+/project:aiwf:install_git_hooks
+# or
+/프로젝트:aiwf:git_훅_설치
+```
+
+**Manual Installation**:
+```bash
+# Navigate to Git hooks directory
+cd .git/hooks
+
+# Create Pre-commit hook
+cat > pre-commit << 'EOF'
+#!/bin/bash
+# AIWF Feature-Git Integration Hook
+
+# Commit message file path
+COMMIT_MSG_FILE="$1"
+
+# Execute AIWF commit validation
+node .aiwf/scripts/validate-commit.js "$COMMIT_MSG_FILE"
+
+# Return validation result
+exit $?
+EOF
+
+# Grant execution permission
+chmod +x pre-commit
+```
+
+### 2. Configuration File Setup
+
+`.aiwf/config/git-integration.json`:
+```json
+{
+  "featureGitIntegration": {
+    "enabled": true,
+    "autoLinkCommits": true,
+    "updateFeatureStatus": true,
+    "commitMessagePattern": "^(feat|fix|docs|style|refactor|test|chore)\\(([A-Z]\\d{3})\\): .+$",
+    "featureIdPattern": "[A-Z]\\d{3}",
+    "hooks": {
+      "preCommit": true,
+      "postCommit": true,
+      "prePush": false
+    },
+    "statusMapping": {
+      "feat": "in_progress",
+      "fix": "in_progress",
+      "docs": "in_progress",
+      "test": "testing",
+      "chore": "in_progress",
+      "refactor": "in_progress",
+      "style": "in_progress"
+    }
+  }
+}
+```
+
+### 3. Feature Ledger Initialization
+
+```bash
+/project:aiwf:init_feature_ledger
+# or
+/프로젝트:aiwf:기능_원장_초기화
+```
+
+## Commit Message Format
+
+### Basic Format
+```
+<type>(<feature-id>): <description>
+
+[optional body]
+
+[optional footer]
+```
+
+### Type Categories
+- `feat`: Add new feature
+- `fix`: Fix bug
+- `docs`: Modify documentation
+- `style`: Code formatting, missing semicolons, etc.
+- `refactor`: Code refactoring
+- `test`: Add or modify tests
+- `chore`: Build process or auxiliary tool changes
+
+### Feature ID Format
+- Format: `[A-Z][0-9]{3}` (e.g., F001, B023, T456)
+- Customizable per project
+
+### Examples
+
+**Basic commit**:
+```bash
+git commit -m "feat(F001): Implement user authentication system"
+```
+
+**With detailed description**:
+```bash
+git commit -m "fix(B023): Resolve session persistence issue on login
+
+- Fixed session timeout settings
+- Added cookie domain configuration
+- Improved refresh token logic"
+```
+
+**Multiple Feature references**:
+```bash
+git commit -m "refactor(F001,F002): Integrate authentication modules
+
+Integrated login logic from F001 and permission system from F002
+to eliminate code duplication and improve maintainability."
+```
+
+## link_feature_commit Command
+
+### Basic Usage
+```bash
+/project:aiwf:link_feature_commit <commit-hash> <feature-id>
+# or
+/프로젝트:aiwf:기능_커밋_연결 <커밋해시> <기능ID>
+```
+
+### Examples
+```bash
+# Link specific commit to Feature
+/project:aiwf:link_feature_commit abc123def F001
+
+# Link recent commit
+/project:aiwf:link_feature_commit HEAD F002
+
+# Link range of commits
+/project:aiwf:link_feature_commit abc123..def456 F003
+```
+
+### Batch Linking
+```bash
+# Link multiple commits at once
+/project:aiwf:link_feature_commits --batch
+"abc123 -> F001
+ def456 -> F002
+ ghi789 -> F003"
+```
+
+## Automatic Feature Status Updates
+
+### Status Transition Rules
+
+1. **First commit**: `planned` → `in_progress`
+2. **Test type commit**: → `testing`
+3. **Fix followed by test pass**: → `ready_for_review`
+4. **PR merge**: → `completed`
+
+### Custom Rule Configuration
+```json
+{
+  "stateTransitions": {
+    "planned": {
+      "feat": "in_progress",
+      "fix": "in_progress"
+    },
+    "in_progress": {
+      "test": "testing",
+      "docs": "documenting"
+    },
+    "testing": {
+      "fix": "in_progress",
+      "feat": "ready_for_review"
+    }
+  }
+}
+```
+
+## Advanced Configuration
+
+### 1. Commit Message Template
+
+Create `.gitmessage` file:
+```
+# <type>(<feature-id>): <subject>
+# 
+# <body>
+# 
+# Feature: <feature-description>
+# Related: <related-features>
+# Closes: <issue-numbers>
+```
+
+Git configuration:
+```bash
+git config commit.template .gitmessage
+```
+
+### 2. Automatic Feature ID Suggestion
+
+```bash
+# Extract Feature ID from current branch name
+/project:aiwf:suggest_feature_id
+```
+
+### 3. Post-commit Automation
+
+`.aiwf/hooks/post-commit`:
+```bash
+#!/bin/bash
+# Update Feature Ledger
+node .aiwf/scripts/update-feature-ledger.js
+
+# Calculate progress
+node .aiwf/scripts/calculate-progress.js
+
+# Notify team (optional)
+# node .aiwf/scripts/notify-team.js
+```
+
+## Workflow Integration
+
+### 1. Branch Strategy Integration
+
+**Feature Branch Creation**:
+```bash
+# Create branch with Feature ID
+git checkout -b feature/F001-user-authentication
+
+# AIWF automatically recognizes Feature ID
+```
+
+**Branch Rules**:
+- `feature/[FEATURE-ID]-description`
+- `bugfix/[BUG-ID]-description`
+- `hotfix/[HOTFIX-ID]-description`
+
+### 2. PR/MR Integration
+
+**PR Template** (`.github/pull_request_template.md`):
+```markdown
+## Feature ID: [FEATURE-ID]
+
+### Changes
+- [ ] Feature implementation completed
+- [ ] Tests written and completed
+- [ ] Documentation updated
+
+### Feature Ledger Update
+- Current status: `in_progress`
+- Target status: `completed`
+- Progress: X%
+
+### Related Commits
+- commit1: description
+- commit2: description
+```
+
+### 3. CI/CD Pipeline Integration
+
+**GitHub Actions Example**:
+```yaml
+name: AIWF Feature Tracking
+
+on:
+  push:
+    branches: [ main, develop ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  feature-tracking:
+    runs-on: ubuntu-latest
+    steps:
+    - uses: actions/checkout@v2
+    
+    - name: Validate Commit Message
+      run: |
+        node .aiwf/scripts/validate-commit.js ${{ github.event.head_commit.message }}
+    
+    - name: Update Feature Ledger
+      run: |
+        node .aiwf/scripts/update-feature-ledger.js \
+          --commit ${{ github.sha }} \
+          --message "${{ github.event.head_commit.message }}"
+    
+    - name: Calculate Progress
+      run: |
+        node .aiwf/scripts/calculate-progress.js
+    
+    - name: Generate Report
+      run: |
+        node .aiwf/scripts/generate-feature-report.js
+```
+
+## Reports and Analytics
+
+### 1. Feature Progress Report
+
+```bash
+/project:aiwf:feature_report
+# or
+/프로젝트:aiwf:기능_보고서
+```
+
+**Example Output**:
+```
+Feature Progress Report
+=======================
+
+Active Features:
+- F001: User Authentication (75% complete)
+  - 12 commits, 3 contributors
+  - Status: testing
+  - Last update: 2 hours ago
+
+- F002: Payment Integration (45% complete)
+  - 8 commits, 2 contributors
+  - Status: in_progress
+  - Last update: 1 day ago
+
+Completed Features (Last 7 days):
+- F003: Dashboard UI (100% complete)
+- F004: API Documentation (100% complete)
+
+Team Velocity: 4.5 features/week
+```
+
+### 2. Commit Analysis
+
+```bash
+/project:aiwf:analyze_commits --period 7d
+```
+
+**Analysis Content**:
+- Commit frequency
+- Commit distribution by Feature
+- Contribution by developer
+- Activity patterns by time
+
+## Troubleshooting
+
+### 1. Hook Not Working
+
+**Check Items**:
+```bash
+# Check if hook file exists
+ls -la .git/hooks/pre-commit
+
+# Check execution permission
+test -x .git/hooks/pre-commit && echo "Executable" || echo "Not executable"
+
+# Check hook content
+cat .git/hooks/pre-commit
+```
+
+**Solutions**:
+```bash
+# Reset permissions
+chmod +x .git/hooks/pre-commit
+
+# Reinstall hook
+/project:aiwf:reinstall_hooks
+```
+
+### 2. Feature ID Recognition Failure
+
+**Symptoms**: Commit succeeds but Feature is not updated
+
+**Solutions**:
+1. Check commit message format
+2. Check Feature ID pattern configuration
+3. Check Feature Ledger file permissions
+
+### 3. Status Update Errors
+
+**Check Logs**:
+```bash
+tail -f .aiwf/logs/git-integration.log
+```
+
+**Manual Update**:
+```bash
+/project:aiwf:update_feature_status F001 in_progress
+```
+
+## Best Practices
+
+### 1. Consistent Commit Messages
+- Use the same format across the entire team
+- Always include Feature ID
+- Write clear and descriptive messages
+
+### 2. Small Unit Commits
+- One commit for one logical change
+- Easy to review and track
+- Easy to rollback when issues occur
+
+### 3. Regular Synchronization
+```bash
+# Daily Feature Ledger synchronization
+/project:aiwf:sync_features
+
+# Weekly report generation
+/project:aiwf:weekly_feature_report
+```
+
+### 4. Branch and Feature Mapping
+- Include Feature ID in branch names
+- Specify Feature ID in PR titles
+- Maintain Feature ID in merge commits
+
+## Team Collaboration Scenarios
+
+### 1. Starting New Feature
+```bash
+# 1. Create Feature
+/project:aiwf:create_feature "User Profile Feature"
+# Returns: F005 created
+
+# 2. Create Branch
+git checkout -b feature/F005-user-profile
+
+# 3. First Commit
+git commit -m "feat(F005): Create basic user profile structure"
+```
+
+### 2. Collaborative Development
+```bash
+# Developer A
+git commit -m "feat(F005): Implement profile image upload"
+
+# Developer B
+git commit -m "test(F005): Add profile upload tests"
+
+# Check progress
+/project:aiwf:feature_status F005
+```
+
+### 3. Completion and Merge
+```bash
+# When creating PR
+# Title: "feat(F005): Complete user profile feature"
+
+# After merge, automatically
+# - Feature status → completed
+# - Progress → 100%
+# - Completion time recorded
+```
+
+## Conclusion
+
+The Feature-Git integration system effectively combines development processes with project management. Through automated tracking and reporting capabilities, it improves team productivity and enables real-time monitoring of project progress.
+
+We encourage you to continuously improve and optimize your workflow through ongoing use and team feedback.

package/docs/lightweight-evaluation.md

@@ -0,0 +1,198 @@
+# 경량 평가 시스템
+
+## 개요
+
+AIWF의 경량 평가 시스템은 AI 응답 품질을 간단하고 효율적으로 모니터링합니다. 복잡한 수동 평가 대신 백그라운드 자동 평가를 통해 사용자 작업 흐름을 방해하지 않으면서도 품질을 유지합니다.
+
+## 핵심 원칙
+
+### 1. Invisible by Default
+- 평가는 백그라운드에서 자동 실행
+- 사용자가 인지하지 못하도록 설계
+- 필요할 때만 피드백 제공
+
+### 2. Simple Metrics
+- 3가지 핵심 지표만 사용
+- 복잡한 계산 없이 빠른 평가
+- 실용적인 피드백 중심
+
+### 3. Non-Intrusive
+- 품질이 낮을 때만 알림 (60% 미만)
+- 간단한 한 줄 피드백
+- 작업 흐름을 방해하지 않음
+
+## 평가 지표
+
+### 1. 역할 일치도 (Role Alignment) - 50%
+페르소나의 핵심 키워드가 응답에 포함되었는지 확인합니다.
+
+```javascript
+// 페르소나별 핵심 키워드
+architect: ['시스템', '설계', '구조', '아키텍처']
+security: ['보안', '취약점', '암호화', '위협']
+frontend: ['UI', 'UX', '사용자', '화면']
+backend: ['API', '데이터베이스', '서버', '성능']
+data_analyst: ['데이터', '분석', '통계', '인사이트']
+```
+
+### 2. 작업 관련성 (Task Relevance) - 30%
+응답의 길이와 내용으로 작업 관련성을 간단히 평가합니다.
+- 50자 미만: 0.3
+- 50-200자: 0.6
+- 200자 이상: 0.8
+
+### 3. 기본 품질 (Response Quality) - 20%
+응답의 구조와 내용 풍부도를 확인합니다.
+- 구조화된 응답 (줄바꿈, 목록 등): +0.2
+- 충분한 내용 (100자 이상): +0.2
+
+## 자동 평가 시점
+
+### 1. 페르소나 전환 시
+```bash
+$ aiwf persona architect
+✓ Architect 페르소나 활성화
+# (백그라운드에서 자동 평가 시작)
+```
+
+### 2. 컨텍스트 압축 시
+```bash
+$ aiwf compress-with-persona
+✓ 압축 완료!
+# (압축 품질 자동 체크)
+💡 시스템 설계 관점을 더 포함해보세요  # 품질이 낮을 때만
+```
+
+## 수동 평가 명령어
+
+필요할 때 수동으로 평가 정보를 확인할 수 있습니다.
+
+### 빠른 확인
+```bash
+$ aiwf evaluate
+🔍 최근 응답 평가
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+현재 페르소나: architect
+평균 점수: 0.75
+평가 횟수: 23
+추세: 📈 개선 중
+```
+
+### 상세 분석
+```bash
+$ aiwf evaluate --detailed
+📊 상세 평가 분석
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+전체 통계:
+- 총 평가: 47회
+- 평균 점수: 0.72
+- 추세: 📈 개선 중
+
+페르소나별 성과:
+- 아키텍트: 0.85 (15회)
+- 보안 전문가: 0.62 (8회)
+- 프론트엔드: 0.74 (12회)
+- 백엔드: 0.70 (9회)
+- 데이터 분석가: 0.58 (3회)
+
+개선 제안:
+📊 데이터 기반 인사이트를 더 제공해보세요
+```
+
+### 평가 히스토리
+```bash
+$ aiwf evaluate --history
+📈 평가 히스토리
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+14:32 | 아키텍트 | 0.85
+14:25 | 프론트엔드 | 0.72
+14:18 | 아키텍트 | 0.90
+...
+```
+
+### 주간 통계
+```bash
+$ aiwf evaluate --stats
+📊 주간 통계
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+평가 횟수: 142회
+평균 점수: 0.74
+추세: 📈 개선 중
+
+페르소나별 활용도:
+아키텍트    ████████████ 45회
+프론트엔드  ████████ 32회
+백엔드      ██████ 28회
+보안 전문가  ████ 20회
+데이터 분석가 ████ 17회
+```
+
+## 피드백 메시지
+
+각 페르소나별로 간단한 피드백 메시지가 준비되어 있습니다:
+
+- **Architect**: "💡 시스템 설계 관점을 더 포함해보세요"
+- **Security**: "🔒 보안 측면을 좀 더 고려해보세요"
+- **Frontend**: "🎨 사용자 경험 관점을 추가해보세요"
+- **Backend**: "⚙️ 서버/데이터 처리 관점을 강화해보세요"
+- **Data Analyst**: "📊 데이터 기반 인사이트를 더 제공해보세요"
+
+## 데이터 저장
+
+평가 데이터는 `.aiwf/.evaluation-stats.json`에 자동 저장됩니다:
+
+```json
+{
+  "recentEvaluations": [
+    {
+      "persona": "architect",
+      "score": 0.85,
+      "timestamp": "2024-01-10T14:32:00Z",
+      "responseLength": 350
+    }
+  ],
+  "lastUpdated": "2024-01-10T14:32:00Z"
+}
+```
+
+## 구현 세부사항
+
+### SimplifiedEvaluator 클래스
+- 200줄 이하의 간단한 구현
+- 빠른 평가 알고리즘
+- 최소한의 의존성
+
+### BackgroundMonitor 클래스
+- 싱글톤 패턴으로 리소스 효율성
+- 비동기 평가로 성능 영향 최소화
+- 자동 데이터 정리 (최대 100개 기록)
+
+## 마이그레이션 가이드
+
+### 기존 시스템에서 전환
+1. 기존 평가 명령어들이 자동으로 제거됨
+2. 새로운 `aiwf evaluate` 명령어만 사용
+3. 대부분의 평가는 자동으로 백그라운드에서 수행
+
+### 주요 변경사항
+- 5개 지표 → 3개 지표
+- 수동 평가 → 자동 평가
+- 5개 명령어 → 1개 명령어
+- 복잡한 리포트 → 간단한 피드백
+
+## 성능 영향
+
+- **CPU 사용**: 거의 없음 (< 0.1%)
+- **메모리 사용**: 최소 (< 5MB)
+- **평가 시간**: 즉시 (< 10ms)
+- **저장 공간**: 작음 (< 100KB)
+
+## 향후 계획
+
+1. **AI 응답 후 자동 평가**: Claude API 응답 후킹
+2. **주간 리포트 자동 생성**: 매주 월요일 아침
+3. **팀 통계 공유**: 팀원 간 평가 통계 공유 기능
+
+## 결론
+
+경량 평가 시스템은 "적을수록 좋다"는 철학을 따릅니다. 필수적인 기능만 유지하면서도 AI 응답 품질을 효과적으로 모니터링할 수 있습니다. 사용자는 평가 시스템의 존재를 거의 인지하지 못하면서도 품질 개선의 혜택을 받습니다.