moai-adk 0.4.5__py3-none-any.whl → 0.20.1__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-alfred-code-reviewer/SKILL.md

@@ -1,112 +1,212 @@
 ---
-
 name: moai-alfred-code-reviewer
-description: Automated code review with language-specific best practices, SOLID principles, and actionable improvement suggestions. Use when reviewing code changes for issues and strengths.
-allowed-tools:
-  - Read
-  - Write
-  - Edit
-  - Bash
-  - TodoWrite
+description: "Systematic code review guidance and automation. Apply TRUST 5 principles, check code quality, validate SOLID principles, identify security issues, and ensure maintainability. Use when conducting code reviews, setting review standards, or implementing review automation."
+allowed-tools: "Read, Write, Edit, Glob, Bash"
 ---
 
-# Alfred Code Reviewer
-
 ## Skill Metadata
+
 | Field | Value |
 | ----- | ----- |
-| Allowed tools | Read (read_file), Write (write_file), Edit (edit_file), Bash (terminal), TodoWrite (todo_write) |
-| Auto-load | /alfred:3-sync review phase |
-| Trigger cues | Alfred-driven review summaries, diff inspection, merge gate decisions. |
+| Version | 1.0.0 |
+| Tier | Quality |
+| Auto-load | When conducting code reviews or quality checks |
 
-## What it does
+## What It Does
 
-Automated code review with language-specific best practices, SOLID principles verification, and code smell detection.
+체계적인 코드 리뷰 프로세스와 자동화 가이드를 제공합니다. TRUST 5 원칙 적용, 코드 품질 검증, SOLID 원칙 준수, 보안 이슈 식별, 유지보수성 보장을 다룹니다.
 
-## When to use
+## When to Use
 
-- Activates when Alfred needs to summarize diffs or prepare merge feedback.
-- “Please review the code”, “How can this code be improved?”, “Check the code quality”
-- Optionally invoked after `/alfred:3-sync`
-- Before merging PR
+- 코드 리뷰를 수행할 때
+- 리뷰 표준과 가이드라인을 설정할 때
+- 코드 품질 자동화를 구현할 때
+- 팀의 코드 리뷰 문화를 개선할 때
 
-## How it works
 
-**Code Constraints Check**:
-- File ≤300 LOC
-- Function ≤50 LOC
-- Parameters ≤5
-- Cyclomatic complexity ≤10
+# Systematic Code Review with TRUST 5 Principles
 
-**SOLID Principles**:
-- Single Responsibility
-- Open/Closed
-- Liskov Substitution
-- Interface Segregation
-- Dependency Inversion
+Code review is a quality assurance process that ensures code meets standards, follows best practices, and maintains long-term maintainability. This skill provides systematic guidance for conducting thorough, effective code reviews.
 
-**Code Smell Detection**:
-- Long Method
-- Large Class
-- Duplicate Code
-- Dead Code
-- Magic Numbers
+## Code Review Framework
 
-**Language-specific Best Practices**:
-- Python: List comprehension, type hints, PEP 8
-- TypeScript: Strict typing, async/await, error handling
-- Java: Streams API, Optional, Design patterns
+### The TRUST 5 Review Framework
 
-**Review Report**:
-```markdown
-## Code Review Report
+| Principle | Review Focus | Key Questions | Tools |
+|-----------|--------------|---------------|-------|
+| **T** - Test First | Test coverage & quality | Are tests comprehensive? Do they test edge cases? | pytest coverage, jest --coverage |
+| **R** - Readable | Code clarity & maintainability | Is code self-documenting? Are names meaningful? | linters, code formatters |
+| **U** - Unified | Consistency & standards | Does it follow team patterns? Is it cohesive? | style guides, architectural patterns |
+| **S** - Secured | Security & vulnerabilities | Are inputs validated? Are secrets handled properly? | security scanners, static analysis |
+| **T** - Trackable | Documentation & traceability | Is code linked to requirements? Are changes documented? | @TAG system, git history |
 
-### 🔴 Critical Issues (3)
-1. **src/auth/service.py:45** - Function too long (85 > 50 LOC)
-2. **src/api/handler.ts:120** - Missing error handling
-3. **src/db/repository.java:200** - Magic number
+## High-Freedom: Review Strategy & Philosophy
 
-### ⚠️ Warnings (5)
-1. **src/utils/helper.py:30** - Unused import
+### When to Review vs When to Trust
 
-### ✅ Good Practices Found
-- Test coverage: 92%
-- Consistent naming
+```markdown
+## Review Decision Matrix
+
+| Change Type | Review Level | Automation | Focus Areas |
+|-------------|--------------|------------|-------------|
+| Critical security | 🔴 Mandatory | Full scan | Vulnerabilities, input validation |
+| Core architecture | 🟡 Deep review | Partial | Design patterns, scalability |
+| Bug fixes | 🟢 Standard | Automated | Root cause, test coverage |
+| Documentation | 🟢 Light | Basic | Accuracy, completeness |
+| Configuration | 🟢 Automated | Full | Security, best practices |
 ```
 
-## Best Practices
-- The text shown to the user is written using TUI/report expressions.
-- When running the tool, a summary of commands and results are recorded.
+### Review Culture Principles
+
+✅ **Psychological Safety**: Reviews are about code, not people  
+✅ **Learning Opportunity**: Reviews transfer knowledge and standards  
+✅ **Constructive Feedback**: Focus on improvement, not criticism  
+✅ **Consistent Standards**: Apply same criteria to all code  
+✅ **Efficient Process**: Automated checks first, human review for value-add  
+
+### Review Anti-patterns to Avoid
+
+❌ **Nitpicking**: Focus on style over substance  
+❌ **Authoritarian**: "Do it this way because I said so"  
+❌ **Incomplete**: "Looks good" without specific feedback  
+❌ **Delayed**: Reviews blocking progress for days  
+❌ **Inconsistent**: Different standards for different people  
+
+## Medium-Freedom: Review Process & Checklists
+
+### Structured Review Process
+
+```pseudocode
+## Review Workflow
+
+1. PRE-REVIEW AUTOMATION (2-5 min)
+   a. Run linters and formatters
+   b. Execute test suite with coverage
+   c. Scan for security vulnerabilities
+   d. Check for @TAG compliance
+   
+2. CODE COMPREHENSION (5-10 min)
+   a. Read commit message and PR description
+   b. Understand the problem being solved
+   c. Identify affected components
+   d. Review test changes first
+   
+3. DETAILED REVIEW (10-20 min)
+   a. Apply TRUST 5 framework systematically
+   b. Check architectural consistency
+   c. Validate error handling
+   d. Assess performance implications
+   
+4. FEEDBACK SYNTHESIS (5 min)
+   a. Categorize issues: Must-fix, Should-fix, Nice-to-have
+   b. Provide specific, actionable feedback
+   c. Explain reasoning behind suggestions
+   d. Offer to discuss complex changes
+```
+
+### Code Review Checklist Template
 
-## Examples
 ```markdown
-- Call this skill inside the /alfred command to generate a report.
-- Add summary to Completion Report.
+## Code Review Checklist
+
+### 🧪 Test Coverage (T)
+- [ ] New features have corresponding tests
+- [ ] Test coverage ≥ 85% (or team standard)
+- [ ] Edge cases and error conditions tested
+- [ ] Integration tests included where appropriate
+- [ ] Tests are readable and maintainable
+
+### 📖 Readability (R)
+- [ ] Function and variable names are descriptive
+- [ ] Complex logic is commented or extracted
+- [ ] File length ≤ 300 LOC (or team standard)
+- [ ] Function length ≤ 50 LOC (or team standard)
+- [ ] No magic numbers or hardcoded values
+
+### 🔗 Unity (U)
+- [ ] Follows established team patterns
+- [ ] Consistent with existing codebase style
+- [ ] Uses shared utilities and libraries
+- [ ] Architecture aligns with project structure
+- [ ] Imports and dependencies are organized
+
+### 🔒 Security (S)
+- [ ] Input validation for all user inputs
+- [ ] No hardcoded secrets or credentials
+- [ ] Proper error handling without information leakage
+- [ ] Authentication and authorization checked
+- [ ] SQL injection and XSS protection in place
+
+### 🏷️ Traceability (T)
+- [ ] Code changes linked to SPEC or issue
+- [ ] @TAG references are correct and complete
+- [ ] Commit message is clear and descriptive
+- [ ] Documentation updated as needed
+- [ ] Breaking changes are documented
 ```
 
-## Inputs
-- MoAI-ADK project context (`.moai/project/`, `.claude/` templates, etc.).
-- Parameters passed from user commands or higher commands.
+## Low-Freedom: Automated Review Scripts
+
+### Pre-commit Review Automation
+
+```bash
+#!/bin/bash
+# .claude/skills/moai-alfred-code-reviewer/scripts/pre-review-check.sh
 
-## Outputs
-- Reports, checklists or recommendations for your Alfred workflow.
-- Structured data for subsequent subagent calls.
+set -e
 
-## Failure Modes
-- When required input documents are missing or permissions are limited.
-- When disruptive changes are required without user approval.
+echo "🔍 Running automated code review checks..."
 
-## Dependencies
-- Cooperation with higher-level agents such as cc-manager and project-manager is required.
+# Test Coverage Check
+echo "📊 Checking test coverage..."
+python -m pytest --cov=src --cov-fail-under=85 --cov-report=term-missing
 
-## References
-- Google. "Code Review Developer Guide." https://google.github.io/eng-practices/review/ (accessed 2025-03-29).
-- IEEE. "Code Review Best Practices." IEEE Software, 2022.
+# Code Quality Checks
+echo "🧹 Running linters..."
+python -m ruff check src/ --show-source
+python -m mypy src/ --strict
 
-## Changelog
-- 2025-03-29: Added input/output/failure response to Alfred-specific skills.
+# Security Scanning
+echo "🔒 Scanning for security issues..."
+python -m bandit -r src/ -f json -o bandit-report.json
 
-## Works well with
+echo "✅ All automated checks passed!"
+```
+
+## Integration with Development Workflow
+
+### Pre-commit Integration
+
+```yaml
+# .pre-commit-config.yaml
+repos:
+  - repo: local
+    hooks:
+      - id: security-review
+        name: Security Review
+        entry: .claude/skills/moai-alfred-code-reviewer/scripts/security_review.py
+        language: script
+        args: [src/]
+        pass_filenames: false
+```
+
+## Review Best Practices Summary
+
+### For Reviewers
+✅ **Start with understanding**: Read the PR description first  
+✅ **Automate first**: Let tools catch the obvious issues  
+✅ **Focus on value**: Spend time on architectural and security concerns  
+✅ **Be specific**: Provide exact locations and suggestions  
+✅ **Explain why**: Help the author understand the reasoning  
+
+### For Authors
+✅ **Self-review first**: Run all automated checks before submitting  
+✅ **Write clear descriptions**: Explain what and why  
+✅ **Keep PRs small**: Large changes are harder to review effectively  
+✅ **Respond promptly**: Address feedback in a timely manner  
+✅ **Learn from feedback**: Use reviews as learning opportunities  
+
+---
 
-- alfred-trust-validation
-- alfred-refactoring-coach
+**Reference**: Code Review Best Practices, TRUST 5 Principles  
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-alfred-code-reviewer/examples.md

@@ -0,0 +1,117 @@
+# Code Review Examples
+
+## Example 1: Basic Code Review Process
+
+```python
+# Before invoking the skill
+# You have a pull request that needs review
+
+# Invoke the skill
+Skill("moai-alfred-code-reviewer")
+
+# The skill provides:
+# 1. Automated review checklist
+# 2. TRUST 5 framework guidance
+# 3. Security review scripts
+# 4. Review comment templates
+
+# Run automated checks
+bash .claude/skills/moai-alfred-code-reviewer/scripts/pre-review-check.sh
+
+# Review output example:
+# 🔍 Running automated code review checks...
+# 📊 Checking test coverage...
+# ✅ Test coverage meets requirements (92%)
+# 🧹 Running ruff linter...
+# ✅ Ruff checks passed
+# 🔍 Running type checks...
+# ✅ Type checks passed
+# 🔒 Scanning for security issues...
+# ✅ Security scan completed
+# 🎉 Automated review checks completed!
+```
+
+## Example 2: Security-focused Review
+
+```python
+# When reviewing code with security implications
+Skill("moai-alfred-code-reviewer")
+
+# Focus on security checklist items:
+# - Input validation for all user inputs
+# - No hardcoded secrets or credentials  
+# - Proper error handling without information leakage
+# - Authentication and authorization checked
+# - SQL injection and XSS protection in place
+
+# Example security issues found:
+# ❌ Potential SQL injection in user_query() function
+# ❌ Hardcoded API key in config.py
+# ❌ Debug mode enabled in production
+```
+
+## Example 3: Integration with GitHub Actions
+
+```yaml
+# .github/workflows/code-review.yml
+name: Automated Code Review
+
+on:
+  pull_request:
+    types: [opened, synchronize]
+
+jobs:
+  automated-review:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      
+      - name: Run Code Review Skill
+        run: |
+          # Skill provides automation scripts
+          bash .claude/skills/moai-alfred-code-reviewer/scripts/pre-review-check.sh
+      
+      - name: Security Review
+        run: |
+          python .claude/skills/moai-alfred-code-reviewer/scripts/security_review.py src/
+```
+
+## Example 4: Team Review Standards
+
+```python
+# Setting up team review standards
+Skill("moai-alfred-code-reviewer")
+
+# Provides templates for:
+# 1. Review checklist customization
+# 2. Comment templates by severity
+# 3. Review metrics tracking
+# 4. Quality gates automation
+
+# Custom checklist example:
+## Frontend Review Standards
+- [ ] Component follows design system
+- [ ] Accessibility (WCAG 2.1) compliance
+- [ ] Performance metrics met (Lighthouse score > 90)
+- [ ] Responsive design tested
+- [ ] Cross-browser compatibility verified
+```
+
+## Example 5: Review Quality Metrics
+
+```python
+# Track review quality over time
+Skill("moai-alfred-code-reviewer")
+
+# Provides metrics calculation:
+# - Review coverage percentage
+# - Average review time
+# - Issue detection rate
+# - Reviewer consistency
+
+# Example metrics dashboard:
+Review Coverage: 95% ✅
+Average Review Time: 4.2 hours
+Critical Issues Found: 12
+Quality Score: 8.7/10
+```

moai_adk/templates/.claude/skills/moai-alfred-code-reviewer/scripts/pre-review-check.sh

@@ -0,0 +1,62 @@
+#!/bin/bash
+# Pre-review automation script for code quality checks
+
+set -e
+
+echo "🔍 Running automated code review checks..."
+
+# Check if we're in a git repository
+if ! git rev-parse --git-dir > /dev/null 2>&1; then
+    echo "❌ Not in a git repository"
+    exit 1
+fi
+
+# Test Coverage Check (if pytest available)
+if command -v pytest &> /dev/null; then
+    echo "📊 Checking test coverage..."
+    if pytest --cov=src --cov-fail-under=85 --cov-report=term-missing 2>/dev/null; then
+        echo "✅ Test coverage meets requirements"
+    else
+        echo "⚠️ Test coverage below 85% or pytest configuration missing"
+    fi
+else
+    echo "⚠️ pytest not available, skipping coverage check"
+fi
+
+# Code Quality Checks (if ruff available)
+if command -v ruff &> /dev/null; then
+    echo "🧹 Running ruff linter..."
+    if ruff check src/ --show-source; then
+        echo "✅ Ruff checks passed"
+    else
+        echo "⚠️ Ruff found issues"
+    fi
+else
+    echo "⚠️ ruff not available, skipping linting"
+fi
+
+# Type checking (if mypy available)
+if command -v mypy &> /dev/null; then
+    echo "🔍 Running type checks..."
+    if mypy src/ --strict 2>/dev/null; then
+        echo "✅ Type checks passed"
+    else
+        echo "⚠️ Type checking found issues"
+    fi
+else
+    echo "⚠️ mypy not available, skipping type checking"
+fi
+
+# Security Scanning (if bandit available)
+if command -v bandit &> /dev/null; then
+    echo "🔒 Scanning for security issues..."
+    if bandit -r src/ -f json -o bandit-report.json 2>/dev/null; then
+        echo "✅ Security scan completed"
+    else
+        echo "⚠️ Security scanner found issues or failed to run"
+    fi
+else
+    echo "⚠️ bandit not available, skipping security scan"
+fi
+
+echo "🎉 Automated review checks completed!"

moai_adk/templates/.claude/skills/moai-alfred-config-schema/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: moai-alfred-config-schema
+description: ".moai/config.json official schema documentation, structure validation, project metadata, language settings, and configuration migration guide. Use when setting up project configuration or understanding config.json structure."
+allowed-tools: "Read, Grep"
+---
+
+## What It Does
+
+`.moai/config.json` 파일의 공식 스키마와 각 필드의 목적, 유효한 값, 마이그레이션 규칙을 정의합니다.
+
+## When to Use
+
+- ✅ Project 초기화 후 config.json 설정
+- ✅ config.json 스키마 이해
+- ✅ Language settings, git strategy, TAG configuration 변경
+- ✅ Legacy config 마이그레이션
+
+## Schema Overview
+
+```json
+{
+  "version": "0.17.0",
+  "project": {
+    "name": "ProjectName",
+    "codebase_language": "python",
+    "conversation_language": "ko",
+    "conversation_language_name": "Korean"
+  },
+  "language": {
+    "conversation_language": "ko",
+    "conversation_language_name": "Korean"
+  },
+  "git": {
+    "strategy": "github-pr",
+    "main_branch": "main",
+    "protected": true,
+    "auto_delete_branches": true,
+    "spec_git_workflow": "feature_branch"
+  },
+  "report_generation": {
+    "enabled": true,
+    "auto_create": false,
+    "warn_user": true
+  },
+  "tag": {
+    "prefix_style": "DOMAIN-###"
+  }
+}
+```
+
+## Top-Level Sections
+
+- **version**: Configuration version (do not edit)
+- **project**: Name, codebase language, conversation language
+- **language**: Multi-language support settings
+- **git**: GitHub workflow strategy, branch auto-cleanup, SPEC workflow mode
+- **report_generation**: Document generation frequency control (v0.17.0+)
+- **tag**: TAG system configuration
+
+---
+
+## v0.17.0 New Features
+
+### 1. Report Generation Control
+
+**Section**: `report_generation` (new in v0.17.0)
+
+Controls automatic document generation frequency to manage token usage:
+
+```json
+{
+  "report_generation": {
+    "enabled": true,
+    "auto_create": false,
+    "warn_user": true,
+    "user_choice": "Minimal",
+    "allowed_locations": [
+      ".moai/docs/",
+      ".moai/reports/",
+      ".moai/analysis/",
+      ".moai/specs/SPEC-*/"
+    ]
+  }
+}
+```
+
+**Fields**:
+- `enabled` (boolean): Turn report generation on/off (0 tokens when disabled)
+- `auto_create` (boolean): Auto-create full reports vs essential only
+- `warn_user` (boolean): Show token/time warnings in surveys
+- `user_choice` (string): User's selected level (Enable/Minimal/Disable)
+- `allowed_locations` (array): Where auto-generated reports are placed
+
+**Token Savings**:
+- Enable (full reports): 50-60 tokens per report
+- Minimal (essential only): 20-30 tokens per report
+- Disable (no reports): 0 tokens (100% savings)
+
+### 2. SPEC Git Workflow Mode (Team Mode)
+
+**Section**: `git.spec_git_workflow` (new in v0.17.0)
+
+Controls how features are developed in team mode:
+
+```json
+{
+  "git": {
+    "spec_git_workflow": "feature_branch"
+  }
+}
+```
+
+**Valid Values**:
+1. **`feature_branch`** (recommended for team mode)
+   - Create feature/SPEC-{ID} branch
+   - PR to develop with review
+   - Auto-merge after approval
+
+2. **`develop_direct`** (recommended for rapid development)
+   - Skip branching, commit directly to develop
+   - No PR review needed
+   - Fastest path to integration
+
+3. **`per_spec`** (maximum flexibility)
+   - Ask user per SPEC which workflow to use
+   - Combine both approaches in single project
+
+---
+
+Learn more in `reference.md` for complete schema reference, validation rules, and migration examples.
+
+**Related Skills**: moai-foundation-git, moai-foundation-specs

moai_adk/templates/.claude/skills/moai-alfred-config-schema/examples.md

@@ -0,0 +1,28 @@
+# Config.json Examples
+
+## Example: Korean Project Setup
+
+```json
+{
+  "version": "0.7.0",
+  "project": {
+    "name": "MyKoreanProject",
+    "codebase_language": "python",
+    "conversation_language": "ko",
+    "conversation_language_name": "Korean"
+  },
+  "language": {
+    "conversation_language": "ko",
+    "conversation_language_name": "Korean"
+  },
+  "git": {
+    "strategy": "github-pr",
+    "main_branch": "main",
+    "protected": true
+  }
+}
+```
+
+---
+
+Learn more in `reference.md`.