aiwf 0.1.0 → 0.3.1

package/claude-code/aiwf/en/.claude/commands/aiwf/aiwf_mermaid.md

@@ -0,0 +1,272 @@
+# Mermaid 다이어그램 유지 관리
+
+Instructions for generating, maintaining and updating the mermaid diagrams in the current project's architecture documentation.
+
+## 📋 Overview
+
+The architecture documentation should include comprehensive mermaid diagrams that illustrate:
+
+- System context and component relationships
+- Module dependencies and data flows (150+ modules)
+- Class hierarchies and interactions
+- Service layer patterns and UI architecture
+
+## 📂 Diagram Locations
+
+All architecture diagrams are to be stored in `/docs/architecture/`:
+
+```
+docs/architecture/
+├── README.md                           # Main architecture overview
+├── context_diagram.md                  # System context & data flow
+├── module_overview.md                  # Module relationships (150+ modules)
+└── class_diagrams/
+    ├── core_classes.md                 # Database, DAOs, data processing
+    ├── data_models.md                  # Domain models & database schema
+    └── service_layer.md                # UI architecture & service coordination
+```
+
+## 🛠️ Update Process
+
+### Step 1: Identify Affected Diagrams
+
+Determine which diagrams need updates based on your changes:
+
+| Change Type            | Primary Diagram    | Secondary Diagrams |
+| ---------------------- | ------------------ | ------------------ |
+| New analytics module   | module_overview.md | context_diagram.md |
+| Database schema change | data_models.md     | core_classes.md    |
+| New UI component       | service_layer.md   | module_overview.md |
+| New service/manager    | service_layer.md   | module_overview.md |
+| Architecture refactor  | context_diagram.md | All others         |
+
+### Step 2: Update Mermaid Code
+
+Edit the relevant `.md` files to update mermaid diagram code:
+
+```mermaid
+# Example: Adding a new class to core_classes.md
+class NewAnalyticsService {
+    -CacheManager cache_manager
+    -Logger logger
+    +calculate_advanced_metrics() Dict
+    +generate_insights() List[str]
+}
+
+# Add relationships
+NewAnalyticsService --> CacheManager : uses
+NewAnalyticsService --> DatabaseManager : queries
+```
+
+### Step 3: Validate Diagrams
+
+Test diagram syntax and rendering:
+
+1. **Online validation**: Copy mermaid code to [Mermaid Live Editor](https://mermaid.live/)
+2. **Local preview**: Use VS Code Mermaid extensions
+3. **Check syntax**: Ensure proper mermaid formatting
+
+### Step 4: Update Cross-References
+
+Update any cross-references in documentation:
+
+- Update `docs/architecture/README.md` if adding new diagrams
+- Update navigation links between diagram files
+- Update main project README if architecture changes significantly
+
+## 📝 Mermaid Syntax Guidelines
+
+### Class Diagrams
+
+```mermaid
+classDiagram
+    class ClassName {
+        -private_field: Type
+        +public_method() ReturnType
+        #protected_method(param: Type) void
+    }
+
+    %% Relationships
+    ClassA <|-- ClassB : inherits
+    ClassA *-- ClassC : composition
+    ClassA --> ClassD : uses
+    ClassA ..> ClassE : depends on
+
+    %% Notes
+    note for ClassName "Important implementation details"
+```
+
+### Flowcharts
+
+```mermaid
+flowchart TD
+    A[Start] --> B{Decision}
+    B -->|Yes| C[Action 1]
+    B -->|No| D[Action 2]
+    C --> E[End]
+    D --> E
+
+    %% Styling
+    style A fill:#e1f5fe
+    style E fill:#e8f5e8
+```
+
+### Sequence Diagrams
+
+```mermaid
+sequenceDiagram
+    participant A as Actor
+    participant B as System
+
+    A->>B: Request
+    B->>B: Process
+    B-->>A: Response
+
+    Note over A,B: Important interaction
+```
+
+## 🎨 Styling Guidelines
+
+### Color Scheme
+
+Use consistent colors across all diagrams:
+
+```mermaid
+%% Standard color palette
+style MainComponents fill:#4ecdc4,color:#fff
+style DataLayer fill:#f3e5f5
+style CacheLayer fill:#fff8e1
+style UILayer fill:#e8f5e8
+style ExternalSystems fill:#e1f5fe
+```
+
+### Component Categories
+
+- **🏗️ Core Infrastructure**: `#4ecdc4` (teal)
+- **📊 Analytics/Data**: `#f3e5f5` (light purple)
+- **⚡ Caching/Performance**: `#fff8e1` (light yellow)
+- **🎨 UI Components**: `#e8f5e8` (light green)
+- **🔗 External Systems**: `#e1f5fe` (light blue)
+
+## 📋 Common Update Scenarios
+
+### Adding a New Analytics Module
+
+1. **Update module_overview.md**: Add to Analytics Engine section
+2. **Update class diagrams**: Add detailed class structure if significant
+3. **Update context_diagram.md**: Add if it's a major new capability
+
+```mermaid
+# Example: New trend analysis module
+TREND_ANALYZER[trend_analyzer.py<br/>📈 Advanced Trends]
+TREND_ANALYZER --> DAILY_CALC
+TREND_ANALYZER --> CACHE
+```
+
+### New UI Component or Widget
+
+1. **Update service_layer.md**: Add class definition and relationships
+2. **Update module_overview.md**: Add to UI Layer section
+3. **Consider component factory updates**
+
+```mermaid
+# Example: New dashboard widget
+class NewDashboardWidget {
+    -MetricsCalculator calculator
+    -ComponentFactory factory
+    +setup_ui() void
+    +refresh_data() void
+}
+QWidget <|-- NewDashboardWidget : inherits
+```
+
+### Database Schema Changes
+
+1. **Update data_models.md**: Modify ER diagram and class definitions
+2. **Update core_classes.md**: Update DAO methods if needed
+3. **Document migration requirements**
+
+### New Service or Manager Class
+
+1. **Update service_layer.md**: Add to appropriate service category
+2. **Update relationships**: Show dependencies and usage patterns
+3. **Update module_overview.md**: Add service layer connections
+
+## 🔍 Validation Checklist
+
+Before committing diagram updates:
+
+- [ ] **Syntax Valid**: Diagram renders without errors
+- [ ] **Consistent Styling**: Uses standard color scheme
+- [ ] **Accurate Relationships**: Reflects actual code relationships
+- [ ] **Clear Labels**: All components clearly labeled
+- [ ] **Cross-References Updated**: Navigation links work
+- [ ] **README Updated**: Main architecture README reflects changes
+
+## 🤖 Automation & Maintenance Scripts
+
+### Useful Commands for Analysis
+
+```bash
+# Find all Python classes in the codebase
+find src/ -name "*.py" -exec grep -l "^class " {} \; | sort
+
+# Check module imports to understand dependencies
+grep -r "^from src\." src/ | cut -d: -f2 | sort | uniq
+
+# Find new files since last commit
+git diff --name-only HEAD~1 | grep "\.py$"
+
+# Count modules by package
+find src/ -name "*.py" | cut -d/ -f2 | sort | uniq -c
+```
+
+### Maintenance Tasks
+
+1. **Quarterly Review**: Compare diagrams against actual codebase structure
+2. **Release Preparation**: Ensure all diagrams reflect release state
+3. **Refactoring Support**: Update diagrams during major refactors
+4. **New Developer Onboarding**: Keep diagrams current for documentation
+
+## 🚨 Best Practices
+
+### Do's
+
+- ✅ **Keep diagrams focused**: One primary concept per diagram
+- ✅ **Use consistent naming**: Match actual class/module names
+- ✅ **Add explanatory notes**: Include important design decisions
+- ✅ **Regular updates**: Keep diagrams current with code changes
+- ✅ **Validate syntax**: Always test before committing
+
+### Don'ts
+
+- ❌ **Avoid over-complexity**: Don't include every minor detail
+- ❌ **Don't duplicate**: Each relationship should appear in most appropriate diagram
+- ❌ **Avoid generic names**: Use specific, meaningful component names
+- ❌ **Don't ignore styling**: Consistent colors improve readability
+- ❌ **Don't skip validation**: Always check diagram rendering
+
+## 📞 Support & Resources
+
+### Documentation Resources
+
+- [Mermaid Documentation](https://mermaid-js.github.io/mermaid/)
+- [Mermaid Live Editor](https://mermaid.live/) - For testing diagrams
+- [VS Code Mermaid Extension](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-mermaid)
+
+### Quick Reference
+
+- **Architecture overview**: `/docs/architecture/README.md`
+- **System context**: `/docs/architecture/context_diagram.md`
+- **Module relationships**: `/docs/architecture/module_overview.md`
+- **Class details**: `/docs/architecture/class_diagrams/`
+
+### Getting Help
+
+1. **Reference existing patterns**: Look at similar components in current diagrams
+2. **Check diagram history**: Use git to see how similar changes were handled
+3. **Ask in code review**: Get feedback on architectural accuracy
+
+---
+
+_Keep architecture diagrams accurate, useful, and maintainable as the project evolves. Focus on clarity and consistency to support both current development and future maintenance._

package/claude-code/aiwf/en/.claude/commands/aiwf/aiwf_pr_create.md

@@ -0,0 +1,76 @@
+# Create Pull Request After Task Completion
+
+Create a GitHub Pull Request after task completion and link it with related issues.
+
+## Create TODO with EXACTLY these 6 items
+
+1. Check current branch and changes
+2. Generate PR body template
+3. Create GitHub PR
+4. Link issue with PR
+5. Assign reviewers
+6. Report results
+
+## 1 · Check Branch and Changes
+
+Run in parallel:
+- `git branch --show-current`: Check current branch
+- `git log main..HEAD --oneline`: Commit history
+- `git diff main...HEAD --stat`: Changed files statistics
+
+Extract GitHub issue number from task file
+
+## 2 · Generate PR Body Template
+
+```markdown
+## 🎯 Overview
+Completed implementation of {task_title}.
+
+## 📝 Changes
+{commit_list}
+
+## 📊 Changed Files
+{file_statistics}
+
+## ✅ Checklist
+- [ ] Tests pass
+- [ ] Code review completed
+- [ ] Documentation updated
+
+## 🔗 Related Information
+- Closes #{issue_number}
+- Task: {task_id}
+```
+
+## 3 · Create GitHub PR
+
+```bash
+gh pr create \
+  --title "{task_id}: {task_title}" \
+  --body "$(cat <<'EOF'
+{pr_body}
+EOF
+)" \
+  --base main \
+  --head {branch_name}
+```
+
+## 4 · Link Issue with PR
+
+Automatically included in PR body:
+- `Closes #{issue_number}`: Auto-close issue
+- `Relates to #{issue_number}`: Show relationship
+
+## 5 · Assign Reviewers
+
+```bash
+gh pr edit {pr_number} \
+  --add-reviewer {reviewer_username}
+```
+
+## 6 · Report Results
+
+✅ **PR Created**: #{pr_number}
+🔗 **Link**: {pr_url}
+🎯 **Linked Issue**: #{issue_number}
+👥 **Reviewers**: {reviewers}

package/claude-code/aiwf/en/.claude/commands/aiwf/aiwf_prime.md

@@ -0,0 +1,9 @@
+# Prime Knowledge
+
+Prime yourself with basic information about this project.
+Make sure you are aware of the environment.
+
+## USE **PARALLEL AGENTS** to
+
+- READ .aiwf/01_PROJECT_DOCS/ARCHITECTURE.md for basic Project Information
+- READ .aiwf/00_PROJECT_MANIFEST.md for the Project status

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

@@ -0,0 +1,261 @@
+# Project Review - Top-Down Execution
+
+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.