aiwf 0.1.0 → 0.3.0

package/claude-code/aiwf/ko/.claude/commands/aiwf/aiwf_project_review.md

@@ -0,0 +1,261 @@
+# 프로젝트 리뷰 - 탑 다운 실행
+
+Perform a comprehensive project-level review focusing on architecture, progress, and technical decisions.
+
+**IMPORTANT:**
+
+- This is a high-level review of overall project state, not recent changes.
+- Unless clearly mentioned in project documents, there is no timeline and schedule is irrelevant
+
+## Create a TODO with EXACTLY these 9 Items
+
+1. Analyze review scope and timing
+2. Execute and assess test infrastructure health
+3. Assess project documentation alignment
+4. Review milestone and sprint progress
+5. Analyze codebase architecture and structure
+6. Audit file organization and workflow compliance
+7. Evaluate technical decisions and complexity
+8. Critique implementation quality (John Carmack perspective)
+9. Provide comprehensive assessment with recommendations
+
+Follow step by step and adhere closely to the following instructions for each step.
+
+## DETAILS on every TODO item
+
+### 1. Analyze review scope and timing
+
+Check: <$ARGUMENTS>
+
+If empty, perform full project review. Otherwise interpret <$ARGUMENTS> to identify specific focus areas (milestone, sprint, architecture component, etc.). Unless stated in Argument do not compare to previews project reviews in `.aiwf/10_STATE_OF_PROJECT`.
+
+**IMPORTANT:** This review looks at overall project state in context of recent changes.
+
+**CRITICAL:** Read `.aiwf/00_PROJECT_MANIFEST.md` FIRST to understand:
+
+- Current milestone and sprint status
+- What work is complete vs in-progress vs planned
+- Active sprint objectives and deliverables
+
+**CONTEXT CHECK:** Before evaluating functionality:
+
+- Navigate to `.aiwf/03_SPRINTS/` to find the current sprint
+- Read the sprint meta file to understand what's in scope
+- Check completed vs planned tasks within the sprint
+- Understand what future sprints will deliver
+
+**REVIEW PRINCIPLE:** Evaluate against CURRENT SPRINT deliverables, not full milestone scope.
+
+### 2. Execute and assess test infrastructure health
+
+**CRITICAL:** Test infrastructure health is a BLOCKING criteria for sprint/milestone progression.
+
+- USE test.md command to execute full test suite (@.claude/commands/aiwf/aiwf_test.md)
+- ANALYZE test results: passed/failed/skipped counts and failure categories
+- CALCULATE test health score (0-10 scale):
+  - 10: 100% pass rate, no infrastructure issues
+  - 8-9: >95% pass rate, minor issues only
+  - 6-7: 80-95% pass rate, some non-critical failures
+  - 4-5: 60-80% pass rate, significant issues
+  - 0-3: <60% pass rate, critical infrastructure problems
+- CATEGORIZE failures:
+  - Infrastructure: Import errors, missing modules
+  - Configuration: Environment variables, database connections
+  - Logic: Assertion failures, actual bugs
+  - Flaky: Intermittent failures
+- DETERMINE blocking status:
+  - Score < 6: BLOCKS sprint progression
+  - Score < 8: BLOCKS milestone completion
+  - Score < 4: TRIGGERS emergency escalation
+- IDENTIFY root causes of any infrastructure failures
+- TRACK trend vs previous review (improvement/degradation)
+- ASSESS test strategy validity for scope of the project. Tests should be pragmatic and help assuring functionality but not get in the way of development progress too much.
+
+### 3. Assess project documentation alignment
+
+**USE PARALLEL AGENTS** to follow these steps:
+
+- READ all core documents in `.aiwf/01_PROJECT_DOCS/` especially ARCHITECTURE.md
+- READ current milestone requirements in `.aiwf/02_REQUIREMENTS/`
+- READ architecture decisions in `.aiwf/05_ARCHITECTURE_DECISIONS` as they might extend/contradict other documents
+- IDENTIFY any gaps between documentation and current implementation
+- CHECK if the project is still following the documented architecture vision
+- VERIFY that current code structure matches documented patterns
+
+**IMPORTANT:** Documentation is our source of truth. Any deviation needs justification.
+
+### 4. Review milestone and sprint progress
+
+**USE PARALLEL AGENTS** to follow these steps:
+
+- READ `.aiwf/00_PROJECT_MANIFEST.md` for current status
+- ANALYZE completed sprints in `.aiwf/03_SPRINTS/`
+- COMPARE actual progress against CURRENT SPRINT deliverables (not full milestone)
+- DISTINGUISH between sprint-level tasks vs milestone-level features
+- ASSESS if current sprint focus aligns with milestone goals
+
+### 5. Analyze codebase architecture and structure
+
+#
+
+**USE PARALLEL AGENTS** to follow these steps:
+
+- EXAMINE overall project structure and organization
+- ANALYZE import patterns and dependency relationships
+- REVIEW database models and API structure for consistency
+- CHECK for architectural patterns: are we following DDD, clean architecture, etc.?
+- IDENTIFY any architectural debt or inconsistencies
+
+**Focus areas:**
+
+- **Directory structure** — logical organization, separation of concerns
+- **Dependencies** — are we over-engineering? unnecessary libraries?
+- **Models/Schemas** — consistency, proper relationships, normalization
+- **APIs** — RESTful design, proper HTTP methods, consistent patterns
+- **Configuration** — environment management, secrets handling
+
+### 6. Audit file organization and workflow compliance
+
+**IMPORTANT:** Check for workflow discipline and architectural boundary violations.
+
+- **Root directory audit** — identify files that don't belong in project root
+- **Development scripts** — verify all dev scripts follow `run_dev.py` pattern
+- **Test file organization** — check tests are in `tests/` directory, not scattered
+- **Documentation placement** — verify docs are in proper locations
+- **Temporary/experimental files** — flag any `.py` files that look ad-hoc or experimental
+
+**File Organization Rules to Enforce:**
+
+- **Development scripts** — MUST go through `run_dev.py`, not standalone files
+- **Test files** — MUST be in `tests/` directory with proper naming (`test_*.py`)
+- **Documentation** — MUST be in `docs/` or `.aiwf/01_PROJECT_DOCS/`
+- **Configuration** — MUST follow established patterns (`.env.example`, `pyproject.toml`)
+- **Temporary files** — SHOULD NOT exist in committed code
+
+**Red Flags to Identify:**
+
+- Multiple scripts doing similar things (duplicate functionality)
+- Random `.py` files in root directory
+- Test files outside `tests/` directory
+- Development scripts bypassing `run_dev.py`
+- Unclear file purposes or experimental code
+
+**CRITICAL:** File proliferation indicates workflow breakdown. Flag for immediate cleanup task creation.
+
+### 7. Evaluate technical decisions and complexity
+
+- ASSESS complexity vs. business value ratio
+- REVIEW choice of frameworks, libraries, and tools
+- ANALYZE if current patterns will scale with project growth
+- IDENTIFY areas where we might be over-complicating simple problems
+- CHECK for premature optimization or under-optimization
+
+**IMPORTANT:** Think like an experienced developer. Are we solving the right problems the right way?
+
+### 8. Critique implementation quality (John Carmack perspective)
+
+Think as John Carmack would: focus on simplicity, performance, and maintainability, but keep the projects goal in mind. Especially long term vision as well. Don't over simplify.
+
+- **Simplicity:** Are we solving problems in the most straightforward way?
+- **Performance:** Are there obvious performance issues or bottlenecks?
+- **Maintainability:** Will a new developer understand this code in 6 months?
+- **Robustness:** How does the system handle edge cases and failures?
+- **Technical debt:** What shortcuts are we taking that will hurt us later?
+
+Be **brutally honest**. Carmack-level critique means no sugar-coating but still staying true to the project's reality.
+Be thorough and **go above and beyond** in your analysis - leave no stone unturned.
+
+### 9. Provide comprehensive assessment with recommendations
+
+**IMPORTANT:** Get current timestamp and create output file
+
+- Get current timestamp using system date command
+- Create filename: `YYYY-MM-DD-HH-MM-<judgment-slug>.md` in `.aiwf/10_STATE_OF_PROJECT/`
+- Judgment slug should be 2-3 words describing overall project health (e.g., "solid-progress", "needs-focus", "critical-issues", "doing-great", "on-track")
+
+**IMPORTANT:** Write full report to the timestamped file with this format:
+
+```markdown
+# Project Review - [YYYY-MM-DD HH:MM]
+
+## 🎭 Review Sentiment
+
+[3 emojis only - no explanations]
+
+## Executive Summary
+
+- **Result:** EXCELLENT | GOOD | NEEDS_WORK | CRITICAL_ISSUES
+- **Scope:** What areas were reviewed
+- **Overall Judgment:** [2-3 word assessment used in filename]
+
+## Test Infrastructure Assessment
+
+- **Test Suite Status**: [PASSING/FAILING/BLOCKED] (X/Y tests)
+- **Test Pass Rate**: X% (Y passed, Z failed)
+- **Test Health Score**: X/10
+- **Infrastructure Health**: [HEALTHY/DEGRADED/BROKEN]
+  - Import errors: [count]
+  - Configuration errors: [count]
+  - Fixture issues: [count]
+- **Test Categories**:
+  - Unit Tests: X/Y passing
+  - Integration Tests: X/Y passing
+  - API Tests: X/Y passing
+- **Critical Issues**:
+  - [List of blocking test infrastructure problems]
+  - [Module import mismatches]
+  - [Environment configuration failures]
+- **Sprint Coverage**: [% of sprint deliverables with passing tests]
+- **Blocking Status**: [CLEAR/BLOCKED - reason]
+- **Recommendations**:
+  - [Immediate fixes required]
+  - [Test infrastructure improvements needed]
+
+## Development Context
+
+- **Current Milestone:** [ID and status from manifest]
+- **Current Sprint:** [ID and focus]
+- **Expected Completeness:** [what SHOULD be done at this stage]
+
+## Progress Assessment
+
+- **Milestone Progress:** [percentage complete]
+- **Sprint Status:** [current sprint assessment]
+- **Deliverable Tracking:** [what's done vs planned]
+
+## Architecture & Technical Assessment
+
+- **Architecture Score:** 1-10 rating with explanation
+- **Technical Debt Level:** LOW | MEDIUM | HIGH with specific examples
+- **Code Quality:** [overall assessment with examples]
+
+## File Organization Audit
+
+- **Workflow Compliance:** GOOD | NEEDS_ATTENTION | CRITICAL_VIOLATIONS
+- **File Organization Issues:** [list any misplaced files, duplicate scripts, etc.]
+- **Cleanup Tasks Needed:** [specific file moves/deletions/consolidations required]
+
+## Critical Findings
+
+### Critical Issues (Severity 8-10)
+
+[Lists of must-fix problems headed with #### heading, one empty line and then list of details]
+
+### Improvement Opportunities (Severity 4-7)
+
+[List of recommended enhancements headed with #### heading, one empty line and then list of details]
+
+## John Carmack Critique 🔥
+
+[Top 3 brutally honest observations about technical decisions]
+
+## Recommendations
+
+Based on your findings recommend Action items - chose whatever fits your findings
+
+- **Important fixes:** What needs to be fixed immediately?
+- **Optional fixes/changes:** What would still be recommended though optional?
+- **Next Sprint Focus:** Can the user move to the next sprint?
+```
+
+**IMPORTANT:** Be specific with file paths and line numbers. This review should be actionable and permanently archived.

package/claude-code/aiwf/ko/.claude/commands/aiwf/aiwf_test.md

@@ -0,0 +1,125 @@
+# 테스트 실행 및 일반적인 문제 수정
+
+Follow these instructions from top to bottom.
+
+## Create a TODO with EXACTLY these 4 items
+
+1. Execute test suite
+2. Analyze results and identify issues
+3. Fix common problems if found
+4. Provide test summary
+
+---
+
+## 1 · Execute test suite
+
+### First, detect the project's test runner:
+
+1. **Python projects:**
+
+   - If `pyproject.toml` exists with `[tool.poetry]`: Try `poetry run pytest`
+   - If `setup.py` or `requirements.txt`: Try `pytest` or `python -m pytest`
+   - If custom test script exists (e.g., `run_tests.py`, `run_dev.py`): Use that
+   - Add common flags: `--tb=short` for pytest
+
+2. **JavaScript/TypeScript projects:**
+
+   - If `package.json` exists: Check "scripts" section for "test" command
+   - Common: `npm test`, `npm run test`, `yarn test`, `pnpm test`
+   - Framework specific: `jest`, `vitest`, `mocha`
+
+3. **Other languages:**
+   - Rust: `cargo test`
+   - Go: `go test ./...`
+   - Java: `mvn test` or `gradle test`
+   - Ruby: `bundle exec rspec` or `rake test`
+   - PHP: `composer test` or `phpunit`
+
+### Execute the detected test command:
+
+- RUN the appropriate test command
+- CAPTURE full output including any errors
+- NOTE execution time and test counts
+
+**If no test runner is found:** Report this to the user and ask for the correct test command.
+
+## 2 · Analyze results and identify issues
+
+Check for common issues in this order:
+
+### Language-specific issues:
+
+**Python:**
+
+- Missing **init**.py files (import errors, tests not discovered)
+- Import path problems
+- Fixture issues (pytest)
+- Virtual environment problems
+
+**JavaScript/TypeScript:**
+
+- Module resolution errors
+- Missing dependencies in node_modules
+- Jest/Vitest configuration issues
+- TypeScript compilation errors
+
+**Common across languages:**
+
+- Environment variable issues (missing config)
+- Database/external service connection errors
+- File path problems (absolute vs relative)
+- Permission issues
+
+## 3 · Fix common problems if found
+
+**ONLY** fix these specific issues automatically:\*\*
+
+### Python-specific fixes:
+
+- CREATE empty `__init__.py` files where needed
+- FIX simple import path issues
+- ADD missing test directory to Python path if needed
+
+### JavaScript/TypeScript fixes:
+
+- RUN `npm install` if node_modules missing
+- FIX simple module resolution in jest.config.js
+- CREATE missing test setup files
+
+### General fixes:
+
+- CREATE missing test directories
+- FIX file permissions if possible
+- IDENTIFY missing env vars and inform user
+
+**DO NOT** fix:
+
+- Actual test logic failures
+- Business logic bugs
+- Complex configuration issues
+- Database schema problems
+- External service dependencies
+
+## 4 · Provide test summary
+
+Create a brief summary:
+
+```
+Test Results:
+- Total: X tests
+- Passed: Y (Z%)
+- Failed: A
+- Skipped: B
+- Time: C seconds
+
+Issues Fixed:
+- [List any fixes applied]
+
+Issues Found (requires manual fix):
+- [List problems that need attention]
+
+Status: PASSING | FAILING | BLOCKED
+```
+
+**IMPORTANT:** Keep it concise. This command should be quick and focused on running tests, not detailed analysis.
+EOF < /dev/null

package/claude-code/aiwf/ko/.claude/commands/aiwf/aiwf_testing_review.md

@@ -0,0 +1,198 @@
+# 테스팅 리뷰 - 탑 다운 실행
+
+아키텍처, 진행 상황, 기술 결정에 초점을 맞춘 포괄적인 프로젝트 수준 리뷰를 수행합니다.
+
+## Prerequisites Check
+
+**FIRST**, check if a testing strategy document exists:
+
+- CHECK for `.aiwf/01_PROJECT_DOCS/TESTING_STRATEGY.md`
+- If NOT found, inform the user: "No testing strategy document found. Would you like me to help create one, or proceed with a general test quality review?"
+- If user wants to proceed without strategy, adapt the review to focus on general test quality principles
+
+## Create a TODO with EXACTLY these 7 Items
+
+1. Load testing strategy document (or define review criteria)
+2. Analyze test implementation structure
+3. Evaluate test-to-code alignment
+4. Identify misaligned or unnecessary tests
+5. Assess critical functionality coverage
+6. Generate modification recommendations
+7. Create alignment report
+
+Follow step by step and adhere closely to the following instructions for each step.
+
+## DETAILS on every TODO item
+
+### 1. Load testing strategy document (or define review criteria)
+
+**Option A - Strategy document exists:**
+
+- LOAD `.aiwf/01_PROJECT_DOCS/TESTING_STRATEGY.md`
+- EXTRACT key principles and priorities
+- IDENTIFY what should and shouldn't be tested
+- NOTE coverage expectations and quality gates
+- UNDERSTAND the testing philosophy
+
+**Option B - No strategy document:**
+Use general best practices as review criteria:
+
+- Tests should focus on behavior, not implementation
+- Critical paths must have coverage
+- Tests should be maintainable and clear
+- Avoid over-testing simple getters/setters
+- Balance between coverage and maintenance burden
+
+**DOCUMENT** which approach is being used for this review.
+
+### 2. Analyze test implementation structure
+
+**EXAMINE** the current test codebase:
+
+- USE test.md command to run tests (@.claude/commands/aiwf/aiwf_test.md)
+- EXPLORE test directory structure and organization
+- IDENTIFY test categories and their purposes
+- CHECK test naming conventions and patterns
+- NOTE any test infrastructure or utilities
+
+**Focus on understanding what exists, not counting.**
+
+### 3. Evaluate test-to-code alignment
+
+**COMPARE** tests against actual implementation:
+
+- For each major component, check if tests match functionality
+- IDENTIFY tests that test implementation details vs behavior
+- FIND tests with excessive setup or mocking
+- LOCATE tests that break frequently on refactoring
+- CHECK if test complexity matches code complexity
+
+**Key question:** Do the tests validate what users care about?
+
+### 4. Identify misaligned or unnecessary tests
+
+**SEARCH** for tests that don't provide value:
+
+**If using strategy document:**
+
+- Tests for areas marked as "skip" in strategy
+- Tests outside the defined scope
+- Over-specified tests per strategy guidelines
+
+**If using general principles:**
+
+- Over-engineered tests for simple functionality
+- Tests that break on every refactor
+- Edge case tests for non-critical features
+- Tests with excessive mocking/setup
+- Performance tests without performance requirements
+
+**Create a list of specific tests to modify or remove.**
+
+### 5. Assess critical functionality coverage
+
+**VERIFY** that essential functionality has appropriate tests:
+
+**If using strategy document:**
+
+- CHECK coverage of high-priority areas defined in strategy
+- VERIFY strategy-specific requirements are tested
+
+**For all reviews:**
+
+- IDENTIFY gaps in critical path testing
+- CHECK authentication/authorization if applicable
+- VERIFY error handling for important operations
+- ENSURE data integrity tests exist where needed
+- CONFIRM integration points are tested
+
+**Note specific gaps that need addressing.**
+
+### 6. Generate modification recommendations
+
+**CREATE** specific, actionable recommendations:
+
+For each finding:
+
+- SPECIFY the test file and function
+- EXPLAIN why it needs modification
+- SUGGEST the specific change (remove, simplify, add)
+- PROVIDE example of the improved approach if helpful
+
+**Format:**
+
+```
+File: tests/test_example.py::test_function_name
+Issue: [What's wrong]
+Action: [What to do]
+Reason: [Why this aligns with strategy]
+```
+
+### 7. Create alignment report
+
+**GENERATE** a focused report on test-strategy alignment:
+
+- Get current timestamp using system date command
+- Create report in `.aiwf/10_STATE_OF_PROJECT/YYYY-MM-DD-HH-MM-test-alignment.md`
+
+**Report structure:**
+
+```markdown
+# Test-Strategy Alignment Review - [YYYY-MM-DD HH:MM]
+
+## Alignment Summary
+
+Overall alignment with testing strategy: [EXCELLENT | GOOD | NEEDS WORK | POOR]
+
+Key findings:
+
+- [Major finding about test suite health]
+- [Major finding about coverage]
+- [Major finding about maintenance burden]
+
+## Tests Requiring Modification
+
+### Remove (Over-engineered/Out of scope)
+
+[List specific tests with reasons]
+
+### Simplify (Too complex for purpose)
+
+[List specific tests with simplification approach]
+
+### Add (Critical gaps)
+
+[List specific missing tests for critical paths]
+
+## Recommended Actions
+
+### Immediate (Blocking issues)
+
+- [ ] [Specific action with file/test reference]
+
+### Short-term (Quality improvements)
+
+- [ ] [Specific action with file/test reference]
+
+### Long-term (Technical debt)
+
+- [ ] [Specific action with file/test reference]
+
+## Test Health Indicators
+
+- Tests align with code purpose: [YES | PARTIALLY | NO]
+- Critical paths covered: [YES | PARTIALLY | NO]
+- Maintenance burden reasonable: [YES | PARTIALLY | NO]
+- Tests support development velocity: [YES | PARTIALLY | NO]
+
+## Implementation Examples
+
+[If needed, show before/after examples of test improvements]
+
+## Next Review
+
+Recommended review in: [X weeks/sprints]
+Focus areas for next review: [Specific areas to monitor]
+```
+
+**IMPORTANT:** Focus on alignment and balance, not metrics. The goal is tests that serve the project's actual needs.