aiwf 0.3.1 → 0.3.3

package/.aiwf/01_PROJECT_DOCS/FEATURE_LEDGER_API_REFERENCE.md

@@ -0,0 +1,361 @@
+# Feature Ledger API Reference
+
+## Overview
+
+Feature Ledger API는 AIWF 프로젝트에서 기능 개발을 추적하고 관리하는 명령어들을 제공합니다. 모든 명령어는 `/project:aiwf:` 접두사를 사용합니다.
+
+## Core Commands
+
+### 1. create_feature_ledger
+
+새로운 Feature Ledger를 생성합니다.
+
+```bash
+/project:aiwf:create_feature_ledger <feature_name> [options]
+```
+
+#### Parameters
+- `feature_name` (required): 기능 이름 (snake_case 권장)
+
+#### Options
+- `--milestone, -m`: 연결할 마일스톤 ID (예: M02)
+- `--sprint, -s`: 연결할 스프린트 ID (예: S01_M02)
+- `--priority, -p`: 우선순위 (critical|high|medium|low) - 기본값: medium
+- `--complexity, -c`: 복잡도 (simple|moderate|complex) - 기본값: moderate
+- `--assignee, -a`: 담당자 이름
+- `--tags, -t`: 태그 목록 (쉼표로 구분)
+
+#### Example
+```bash
+/project:aiwf:create_feature_ledger user_authentication --milestone M02 --sprint S01_M02 --priority high --complexity complex --assignee "john_doe" --tags "security,backend"
+```
+
+#### Response
+```
+✅ Feature Ledger created successfully!
+Feature ID: FL001
+Title: User Authentication
+Status: active
+Location: .aiwf/06_FEATURE_LEDGERS/active/FL001_User_Authentication.md
+```
+
+### 2. update_feature_status
+
+Feature의 상태를 업데이트합니다.
+
+```bash
+/project:aiwf:update_feature_status <feature_id> <new_status> [options]
+```
+
+#### Parameters
+- `feature_id` (required): Feature ID (예: FL001)
+- `new_status` (required): 새로운 상태 (active|completed|paused|archived)
+
+#### Options
+- `--comment, -c`: 상태 변경 이유나 코멘트
+- `--completion-date`: 완료 날짜 (completed 상태일 때)
+
+#### State Transition Rules
+- `active` → `completed`, `paused`, `archived`
+- `paused` → `active`, `archived`
+- `completed` → `archived`
+- `archived` → 다른 상태로 전환 불가
+
+#### Example
+```bash
+/project:aiwf:update_feature_status FL001 completed --comment "All tests passing, merged to main" --completion-date 2025-07-09
+```
+
+#### Response
+```
+✅ Feature status updated!
+Feature: FL001 - User Authentication
+Previous Status: active → New Status: completed
+File moved to: .aiwf/06_FEATURE_LEDGERS/completed/FL001_User_Authentication.md
+```
+
+### 3. link_feature_commit
+
+현재 Git 커밋을 Feature에 연결합니다.
+
+```bash
+/project:aiwf:link_feature_commit <feature_id> [options]
+```
+
+#### Parameters
+- `feature_id` (required): Feature ID
+
+#### Options
+- `--commit, -c`: 특정 커밋 해시 (기본값: 현재 HEAD)
+- `--auto-progress`: 커밋 메시지 기반 자동 진행률 업데이트
+
+#### Supported Commit Patterns
+- `feat(FL001):` - 기능 추가
+- `fix(FL001):` - 버그 수정
+- `test(FL001):` - 테스트 추가
+- `docs(FL001):` - 문서화
+- `[FL001]` - 일반 참조
+
+#### Example
+```bash
+/project:aiwf:link_feature_commit FL001 --auto-progress
+```
+
+#### Response
+```
+✅ Commit linked to feature!
+Feature: FL001
+Commit: abc123def456
+Message: feat(FL001): Implement JWT token generation
+Progress updated: 45% → 55%
+```
+
+### 4. feature_dashboard
+
+Feature 개발 현황 대시보드를 생성합니다.
+
+```bash
+/project:aiwf:feature_dashboard [options]
+```
+
+#### Options
+- `--milestone, -m`: 특정 마일스톤으로 필터링
+- `--sprint, -s`: 특정 스프린트로 필터링
+- `--assignee, -a`: 담당자로 필터링
+- `--status`: 상태로 필터링
+- `--format, -f`: 출력 형식 (markdown|json|html)
+
+#### Example
+```bash
+/project:aiwf:feature_dashboard --milestone M02 --status active
+```
+
+#### Response
+```markdown
+# Feature Development Dashboard
+
+## Summary
+- Total Features: 12
+- Active: 4 (33%)
+- Completed: 7 (58%)
+- Paused: 1 (8%)
+
+## Active Features (4)
+| ID | Title | Progress | Assignee | Sprint |
+|----|-------|----------|----------|--------|
+| FL001 | User Authentication | 70% | john_doe | S01_M02 |
+| FL002 | Dashboard Redesign | 35% | jane_smith | S01_M02 |
+| FL004 | API Rate Limiting | 15% | bob_jones | S02_M02 |
+| FL005 | Search Enhancement | 50% | alice_wong | S02_M02 |
+
+## Recent Activity
+- FL001: New commit linked (2 hours ago)
+- FL003: Status changed to completed (5 hours ago)
+- FL005: Progress updated to 50% (1 day ago)
+```
+
+### 5. update_feature_progress
+
+Feature의 진행률을 업데이트합니다.
+
+```bash
+/project:aiwf:update_feature_progress <feature_id> <progress_percentage> [options]
+```
+
+#### Parameters
+- `feature_id` (required): Feature ID
+- `progress_percentage` (required): 진행률 (0-100)
+
+#### Options
+- `--update-checklist`: 체크리스트 항목 업데이트
+- `--hours, -h`: 실제 작업 시간 추가
+
+#### Example
+```bash
+/project:aiwf:update_feature_progress FL001 75 --hours 4
+```
+
+### 6. feature_search
+
+Feature를 검색합니다.
+
+```bash
+/project:aiwf:feature_search <query> [options]
+```
+
+#### Parameters
+- `query` (required): 검색어
+
+#### Options
+- `--tags, -t`: 태그로 필터링
+- `--date-range, -d`: 날짜 범위 (예: "2025-07-01:2025-07-31")
+- `--include-archived`: 보관된 feature 포함
+
+#### Example
+```bash
+/project:aiwf:feature_search "authentication" --tags "security" --date-range "2025-07-01:2025-07-31"
+```
+
+### 7. feature_report
+
+Feature 보고서를 생성합니다.
+
+```bash
+/project:aiwf:feature_report <report_type> [options]
+```
+
+#### Report Types
+- `velocity`: 개발 속도 분석
+- `burndown`: 번다운 차트
+- `timeline`: 타임라인 뷰
+- `dependencies`: 의존성 그래프
+
+#### Options
+- `--output, -o`: 출력 파일 경로
+- `--format, -f`: 파일 형식 (pdf|html|markdown)
+
+#### Example
+```bash
+/project:aiwf:feature_report velocity --milestone M02 --output "reports/velocity_M02.pdf"
+```
+
+### 8. link_feature_pr
+
+Pull Request를 Feature에 연결합니다.
+
+```bash
+/project:aiwf:link_feature_pr <feature_id> <pr_number> [options]
+```
+
+#### Parameters
+- `feature_id` (required): Feature ID
+- `pr_number` (required): PR 번호
+
+#### Options
+- `--auto-complete`: PR이 머지되면 자동으로 feature 완료 처리
+
+#### Example
+```bash
+/project:aiwf:link_feature_pr FL001 42 --auto-complete
+```
+
+## Git Integration Commands
+
+### 9. feature_branch
+
+Feature 브랜치를 생성하거나 체크아웃합니다.
+
+```bash
+/project:aiwf:feature_branch <feature_id> [action]
+```
+
+#### Parameters
+- `feature_id` (required): Feature ID
+- `action` (optional): create|checkout|delete (기본값: create)
+
+#### Example
+```bash
+/project:aiwf:feature_branch FL001 create
+# Creates and checks out: feature/FL001-user-authentication
+```
+
+### 10. feature_sync
+
+Feature 정보를 Git과 동기화합니다.
+
+```bash
+/project:aiwf:feature_sync [options]
+```
+
+#### Options
+- `--feature, -f`: 특정 feature만 동기화
+- `--direction, -d`: sync 방향 (git-to-ledger|ledger-to-git|both)
+
+#### Example
+```bash
+/project:aiwf:feature_sync --direction both
+```
+
+## Utility Commands
+
+### 11. feature_template
+
+Feature 템플릿을 관리합니다.
+
+```bash
+/project:aiwf:feature_template <action> [template_name]
+```
+
+#### Actions
+- `list`: 사용 가능한 템플릿 목록
+- `create`: 새 템플릿 생성
+- `apply`: 템플릿 적용
+
+#### Example
+```bash
+/project:aiwf:feature_template apply backend_api FL006
+```
+
+### 12. feature_archive
+
+오래된 Feature를 보관합니다.
+
+```bash
+/project:aiwf:feature_archive [options]
+```
+
+#### Options
+- `--days, -d`: N일 이상 된 completed feature 보관 (기본값: 90)
+- `--dry-run`: 실제 실행 없이 대상 목록만 표시
+
+#### Example
+```bash
+/project:aiwf:feature_archive --days 60 --dry-run
+```
+
+## Error Codes
+
+| Code | Description | Solution |
+|------|-------------|----------|
+| E001 | Feature ID not found | Feature ID가 올바른지 확인 |
+| E002 | Invalid status transition | 허용된 상태 전환 규칙 확인 |
+| E003 | Duplicate feature ID | 다른 ID 사용 또는 기존 feature 업데이트 |
+| E004 | Git integration failed | Git 저장소 상태 확인 |
+| E005 | Permission denied | 파일 권한 확인 |
+| E006 | Invalid parameter | 명령어 파라미터 형식 확인 |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `AIWF_FEATURE_DIR` | Feature Ledger 디렉토리 경로 | `.aiwf/06_FEATURE_LEDGERS` |
+| `AIWF_AUTO_COMMIT` | 변경사항 자동 커밋 여부 | `false` |
+| `AIWF_DEFAULT_PRIORITY` | 기본 우선순위 | `medium` |
+| `AIWF_DEFAULT_COMPLEXITY` | 기본 복잡도 | `moderate` |
+
+## Best Practices
+
+1. **Feature ID 관리**
+   - 순차적 번호 사용 (FL001, FL002, ...)
+   - 재사용 금지
+   - 의미 있는 이름 사용
+
+2. **커밋 메시지**
+   - Feature ID 포함
+   - Conventional Commits 형식 사용
+   - 예: `feat(FL001): Add user login functionality`
+
+3. **진행률 업데이트**
+   - 정기적으로 업데이트
+   - 체크리스트와 동기화
+   - 실제 작업 시간 기록
+
+4. **상태 관리**
+   - 명확한 전환 이유 기록
+   - 완료 기준 명확히 정의
+   - 정기적인 상태 리뷰
+
+5. **통합**
+   - Git 브랜치와 1:1 매핑
+   - PR과 연결
+   - 자동화 활용

package/.aiwf/01_PROJECT_DOCS/FEATURE_LEDGER_COMMANDS_GUIDE.md

@@ -0,0 +1,254 @@
+# Feature Ledger 명령어 사용 가이드
+
+Feature Ledger 시스템을 효과적으로 사용하기 위한 Claude Code 명령어 가이드입니다.
+
+## 명령어 개요
+
+Feature Ledger 시스템은 다음 5개의 핵심 명령어를 제공합니다:
+
+1. **create_feature_ledger** - 새로운 Feature 생성
+2. **update_feature_status** - Feature 상태 변경
+3. **list_features** - Feature 목록 조회
+4. **get_feature_details** - Feature 상세 정보 확인
+5. **link_feature_to_milestone** - Feature를 마일스톤에 연결
+
+## 명령어 상세 사용법
+
+### 1. create_feature_ledger - Feature 생성
+
+새로운 기능 개발을 시작할 때 Feature Ledger를 생성합니다.
+
+**사용법:**
+```
+/project:aiwf:create_feature_ledger <feature_name>
+```
+
+**예시:**
+```
+/project:aiwf:create_feature_ledger user_authentication
+/project:aiwf:create_feature_ledger "Dashboard Redesign"
+```
+
+**대화형 모드:**
+인수 없이 실행하면 대화형으로 정보를 입력받습니다:
+```
+/project:aiwf:create_feature_ledger
+```
+
+**생성 과정:**
+1. 자동으로 다음 Feature ID 할당 (FL001, FL002...)
+2. `.aiwf/06_FEATURE_LEDGERS/active/` 디렉토리에 파일 생성
+3. FEATURE_LEDGER_INDEX.md 자동 업데이트
+4. Git 브랜치 생성 명령어 제안
+
+### 2. update_feature_status - 상태 업데이트
+
+Feature의 개발 상태를 변경합니다.
+
+**사용법:**
+```
+/project:aiwf:update_feature_status <feature_id> <new_status>
+```
+
+**지원 상태:**
+- `active` - 현재 개발 중
+- `completed` - 개발 완료
+- `paused` - 일시 중지
+- `archived` - 보관됨
+
+**예시:**
+```
+/project:aiwf:update_feature_status FL001 completed
+/project:aiwf:update_feature_status FL002 paused
+```
+
+**상태 전이 규칙:**
+- active → completed, paused, archived
+- paused → active, archived  
+- completed → archived
+- archived → (전이 불가)
+
+### 3. list_features - Feature 목록 조회
+
+Feature들을 다양한 필터로 조회합니다.
+
+**사용법:**
+```
+/project:aiwf:list_features [옵션들]
+```
+
+**필터 옵션:**
+- `--status=<status>` - 상태별 필터 (active, completed, paused, archived, all)
+- `--milestone=<milestone>` - 마일스톤별 필터 (예: M02)
+- `--assignee=<assignee>` - 담당자별 필터
+- `--priority=<priority>` - 우선순위별 필터 (critical, high, medium, low)
+- `--category=<category>` - 카테고리별 필터 (feature, enhancement, bugfix, refactor)
+
+**출력 형식:**
+- `--format=table` - 테이블 형식 (기본값)
+- `--format=list` - 리스트 형식
+- `--format=dashboard` - 대시보드 형식
+
+**정렬 옵션:**
+- `--sort=id` - Feature ID 순 (기본값)
+- `--sort=title` - 제목 순
+- `--sort=updated` - 최근 업데이트 순
+- `--sort=priority` - 우선순위 순
+- `--sort=progress` - 진행률 순
+
+**예시:**
+```
+# 모든 active Feature 조회
+/project:aiwf:list_features
+
+# M02 마일스톤의 high 우선순위 Feature
+/project:aiwf:list_features --milestone=M02 --priority=high
+
+# 대시보드 형식으로 전체 현황 보기
+/project:aiwf:list_features --status=all --format=dashboard
+
+# 최근 업데이트 순으로 정렬
+/project:aiwf:list_features --sort=updated
+```
+
+### 4. get_feature_details - 상세 정보 조회
+
+특정 Feature의 상세 정보를 확인합니다.
+
+**사용법:**
+```
+/project:aiwf:get_feature_details <feature_id> [--format=<format>]
+```
+
+**출력 형식:**
+- `--format=full` - 전체 정보 (기본값)
+- `--format=summary` - 요약 정보
+- `--format=technical` - 기술적 세부사항
+- `--format=progress` - 진행 상황 중심
+
+**예시:**
+```
+# 전체 상세 정보
+/project:aiwf:get_feature_details FL001
+
+# 요약 정보만 보기
+/project:aiwf:get_feature_details FL001 --format=summary
+
+# 기술적 세부사항 확인
+/project:aiwf:get_feature_details FL001 --format=technical
+```
+
+### 5. link_feature_to_milestone - 마일스톤 연결
+
+Feature를 마일스톤 및 스프린트와 연결합니다.
+
+**사용법:**
+```
+/project:aiwf:link_feature_to_milestone <feature_id> <milestone_id> [옵션]
+```
+
+**옵션:**
+- `--sprint=<sprint_id>` - 스프린트 연결 (복수 가능)
+- `--tasks=<task_ids>` - 태스크 연결 (쉼표로 구분)
+
+**예시:**
+```
+# 기본 마일스톤 연결
+/project:aiwf:link_feature_to_milestone FL001 M02
+
+# 스프린트와 함께 연결
+/project:aiwf:link_feature_to_milestone FL001 M02 --sprint=S01_M02 --sprint=S02_M02
+
+# 태스크까지 연결
+/project:aiwf:link_feature_to_milestone FL001 M02 --tasks=T01_S01,T02_S01
+```
+
+## 워크플로우 예시
+
+### 새 기능 개발 시작
+
+1. Feature 생성:
+```
+/project:aiwf:create_feature_ledger authentication_system
+```
+
+2. Git 브랜치 생성:
+```bash
+git checkout -b feature/FL001-authentication-system
+```
+
+3. 마일스톤 연결:
+```
+/project:aiwf:link_feature_to_milestone FL001 M02 --sprint=S01_M02
+```
+
+### 진행 상황 관리
+
+1. Feature 목록 확인:
+```
+/project:aiwf:list_features --status=active --sort=progress
+```
+
+2. 상세 진행 상황 확인:
+```
+/project:aiwf:get_feature_details FL001 --format=progress
+```
+
+3. 완료 시 상태 업데이트:
+```
+/project:aiwf:update_feature_status FL001 completed
+```
+
+### 프로젝트 현황 파악
+
+1. 전체 대시보드 보기:
+```
+/project:aiwf:list_features --status=all --format=dashboard
+```
+
+2. 특정 마일스톤 현황:
+```
+/project:aiwf:list_features --milestone=M02 --format=list
+```
+
+3. 우선순위별 정렬:
+```
+/project:aiwf:list_features --sort=priority --status=active
+```
+
+## 팁과 모범 사례
+
+### Feature 생성 시
+- 명확하고 구체적인 이름 사용
+- 적절한 우선순위 설정
+- 관련 마일스톤과 즉시 연결
+
+### 상태 관리
+- 정기적으로 진행 상황 업데이트
+- paused 상태 사용 시 이유 명시
+- completed 전에 모든 체크리스트 확인
+
+### 협업
+- 담당자와 기여자 명확히 구분
+- PR 생성 시 Feature ID 포함
+- 커밋 메시지에 Feature ID 참조
+
+### Git 통합
+- 브랜치명 규칙 준수: `feature/FL###-feature-name`
+- 커밋 메시지에 Feature ID 포함: `[FL001] Add login API`
+- PR 제목에 Feature 참조: `FL001: Implement user authentication`
+
+## 문제 해결
+
+### Feature를 찾을 수 없을 때
+```
+/project:aiwf:list_features --status=all
+```
+
+### 상태 전이가 거부될 때
+- 상태 전이 규칙 확인
+- 필수 조건 충족 여부 검증
+
+### 인덱스 불일치 시
+- 수동으로 인덱스 재생성 필요
+- 백업 후 진행 권장