moai-adk 0.4.0__py3-none-any.whl → 0.4.1__py3-none-any.whl

moai_adk/templates/.claude/hooks/alfred/README.md

@@ -2,7 +2,7 @@
 
 **Event-Driven Context Management for MoAI-ADK**
 
-Alfred Hooks는 Claude Code의 이벤트 시스템과 통합되어 프로젝트 컨텍스트를 자동으로 관리하고, 위험한 작업 전에 checkpoint를 생성하며, JIT (Just-in-Time) 문서 로딩을 제공합니다.
+Alfred Hooks integrates with Claude Code's event system to automatically manage project context, create checkpoints before risky operations, and provide just-in-time (JIT) document loading.
 
 ---
 
@@ -29,10 +29,10 @@ Alfred Hooks는 Claude Code의 이벤트 시스템과 통합되어 프로젝트
 
 ### Design Principles
 
-- **Single Responsibility**: 각 모듈은 하나의 명확한 책임
-- **Separation of Concerns**: core (비즈니스 로직) vs handlers (이벤트 처리)
-- **CODE-FIRST**: 중간 캐시 없이 코드 직접 스캔 (mtime 기반 무효화)
-- **Context Engineering**: JIT Retrieval로 초기 컨텍스트 부담 최소화
+- **Single Responsibility**: Each module has one clear responsibility
+- **Separation of Concerns**: core (business logic) vs handlers (event processing)
+- **CODE-FIRST**: Scan code directly without intermediate cache (mtime Based invalidation)
+- **Context Engineering**: Minimize initial context burden with JIT Retrieval
 
 ---
 
@@ -40,7 +40,7 @@ Alfred Hooks는 Claude Code의 이벤트 시스템과 통합되어 프로젝트
 
 ### `core/project.py` (284 LOC)
 
-**프로젝트 메타데이터 및 언어 감지**
+**Project metadata and language detection**
 
 ```python
 # Public API
@@ -51,14 +51,14 @@ count_specs(cwd: str) -> dict[str, int]
 ```
 
 **Features**:
-- 20개 언어 자동 감지 (Python, TypeScript, Java, Go, Rust, etc.)
-- `.moai/config.json` 우선, fallback to auto-detection
-- Git 정보 조회 (branch, commit, changes)
-- SPEC 진행도 계산 (total, completed, percentage)
+- Automatic detection of 20 languages ​​(Python, TypeScript, Java, Go, Rust, etc.)
+- `.moai/config.json` First, fallback to auto-detection
+- Check Git information (branch, commit, changes)
+- SPEC progress calculation (total, completed, percentage)
 
 ### `core/context.py` (110 LOC)
 
-**JIT Context Retrieval 및 워크플로우 관리**
+**JIT Context Retrieval and Workflow Management**
 
 ```python
 # Public API
@@ -69,15 +69,15 @@ clear_workflow_context()
 ```
 
 **Features**:
-- 프롬프트 분석 기반 문서 자동 추천
-  - `/alfred:1-spec` → `spec-metadata.md`
-  - `/alfred:2-build` → `development-guide.md`
-- 워크플로우 단계별 컨텍스트 캐싱 (TTL 10분)
-- Anthropic Context Engineering 원칙 준수
+- Automatically recommend documents based on prompt analysis
+  - `/alfred:1-plan` → `spec-metadata.md`
+  - `/alfred:2-run` → `development-guide.md`
+- Context caching for each workflow step (TTL 10 minutes)
+- Compliance with Anthropic Context Engineering principles
 
 ### `core/checkpoint.py` (244 LOC)
 
-**Event-Driven Checkpoint 자동화**
+**Event-Driven Checkpoint Automation**
 
 ```python
 # Public API
@@ -88,16 +88,16 @@ list_checkpoints(cwd: str, max_count: int = 10) -> list[dict]
 ```
 
 **Features**:
-- 위험한 작업 자동 감지:
+- Automatic detection of dangerous tasks:
   - Bash: `rm -rf`, `git merge`, `git reset --hard`
   - Edit/Write: `CLAUDE.md`, `config.json`
   - MultiEdit: ≥10 files
-- Git checkpoint 자동 생성: `checkpoint/before-{operation}-{timestamp}`
-- checkpoint 이력 관리 및 복구 가이드
+- Automatic creation of Git checkpoint: `checkpoint/before-{operation}-{timestamp}`
+- Checkpoint history management and recovery guide
 
 ### `core/tags.py` (244 LOC)
 
-**CODE-FIRST TAG 시스템**
+**CODE-FIRST TAG SYSTEM**
 
 ```python
 # Public API
@@ -110,10 +110,10 @@ set_library_version(library: str, version: str)
 ```
 
 **Features**:
-- ripgrep 기반 TAG 검색 (JSON 출력 파싱)
-- mtime 기반 캐시 무효화 (CODE-FIRST 보장)
-- TAG 체인 검증 (@SPEC → @TEST → @CODE 완전성 확인)
-- 라이브러리 버전 캐싱 (TTL 24시간)
+- ripgrep-based TAG search (parsing JSON output)
+- mtime-based cache invalidation (CODE-FIRST guaranteed)
+- TAG chain verification (@SPEC → @TEST → @CODE completeness check)
+- Library version caching (TTL 24 hours)
 
 ---
 
@@ -121,32 +121,32 @@ set_library_version(library: str, version: str)
 
 ### `handlers/session.py`
 
-**SessionStart, SessionEnd 핸들러**
+**SessionStart, SessionEnd handlers**
 
-- **SessionStart**: 프로젝트 정보 표시
-  - 언어, Git 상태, SPEC 진행도, 최근 checkpoint
-  - `systemMessage` 필드로 사용자에게 직접 표시
-- **SessionEnd**: 정리 작업 (stub)
+- **SessionStart**: Display project information
+ - Language, Git status, SPEC progress, recent checkpoint
+ - Display directly to user with `systemMessage` field
+- **SessionEnd**: Cleanup task (stub)
 
 ### `handlers/user.py`
 
-**UserPromptSubmit 핸들러**
+**UserPromptSubmit Handler**
 
-- JIT Context 추천 문서 리스트 반환
-- 사용자 프롬프트 패턴 분석 및 관련 문서 로드
+- Return list of JIT Context recommended documents
+- Analyze user prompt patterns and load related documents
 
 ### `handlers/tool.py`
 
-**PreToolUse, PostToolUse 핸들러**
+**PreToolUse, PostToolUse handlers**
 
-- **PreToolUse**: 위험한 작업 감지 시 자동 checkpoint 생성
-- **PostToolUse**: 후처리 작업 (stub)
+- **PreToolUse**: Automatic checkpoint creation when dangerous operation is detected
+- **PostToolUse**: Post-processing operation (stub)
 
 ### `handlers/notification.py`
 
-**Notification, Stop, SubagentStop 핸들러**
+**Notification, Stop, SubagentStop handlers**
 
-- 기본 구현 (stub, 향후 확장 가능)
+- Basic implementation (stub, can be expanded in the future)
 
 ---
 
@@ -166,9 +166,9 @@ uv run pytest tests/unit/test_alfred_hooks_core_project.py -v
 
 ### Test Coverage (18 tests)
 
-- ✅ **tags.py**: 7 tests (캐시, TAG 검증, 버전 관리)
-- ✅ **context.py**: 5 tests (JIT, 워크플로우 컨텍스트)
-- ✅ **project.py**: 6 tests (언어 감지, Git, SPEC 카운트)
+- ✅ **tags.py**: 7 tests (cache, TAG verification, version management)
+- ✅ **context.py**: 5 tests (JIT, workflow context)
+- ✅ **project.py**: 6 tests (language detection, Git, SPEC count)
 
 ### Test Structure
 
@@ -192,22 +192,22 @@ def _load_{module}_module(module_name: str):
 
 - **1 file**: 1233 LOC
 - **Issues**: 
-  - 모든 기능이 하나의 파일에 집중
-  - 테스트 어려움, 유지보수 복잡
-  - 책임 분리 불명확
+- All functions concentrated in one file
+ - Difficult to test, complex to maintain
+ - Unclear separation of responsibilities
 
 ### After (Modular)
 
 - **9 files**: ≤284 LOC each
 - **Benefits**:
-  - 명확한 책임 분리 (SRP)
-  - 독립적인 모듈 테스트 가능
-  - 확장 용이, 유지보수 간편
-  - Context Engineering 원칙 준수
+- Clear separation of responsibilities (SRP)
+ - Independent module testing possible
+ - Easy to expand, easy to maintain
+ - Compliance with Context Engineering principles
 
 ### Breaking Changes
 
-**없음** - 외부 API는 동일하게 유지됩니다.
+**None** - External APIs remain the same.
 
 ---
 
@@ -215,9 +215,9 @@ def _load_{module}_module(module_name: str):
 
 ### Internal Documents
 
-- **CLAUDE.md**: MoAI-ADK 사용자 가이드
-- **.moai/memory/development-guide.md**: SPEC-First TDD 워크플로우
-- **.moai/memory/spec-metadata.md**: SPEC 메타데이터 표준
+- **CLAUDE.md**: MoAI-ADK User Guide
+- **.moai/memory/development-guide.md**: SPEC-First TDD Workflow
+- **.moai/memory/spec-metadata.md**: SPEC metadata standard
 
 ### External Resources
 

moai_adk/templates/.claude/hooks/alfred/alfred_hooks.py

@@ -2,22 +2,9 @@
 # @CODE:HOOKS-REFACTOR-001 | SPEC: SPEC-HOOKS-REFACTOR-001.md
 """Alfred Hooks - Main entry point for MoAI-ADK Claude Code Hooks
 
-Claude Code 이벤트를 적절한 핸들러로 라우팅하는 메인 진입점
+A main entry point that routes Claude Code events to the appropriate handlers.
 
-Setup sys.path for package imports
-"""
-import sys
-from pathlib import Path
-
-# Add the hooks directory to sys.path to enable package imports
-HOOKS_DIR = Path(__file__).parent
-if str(HOOKS_DIR) not in sys.path:
-    sys.path.insert(0, str(HOOKS_DIR))
-
-# Now we can import from the package
-
-"""
-Architecture:
+🏗️ Architecture:
 ┌─────────────────────────────────────────────────────────────┐
 │ alfred_hooks.py (Router)                                    │
 ├─────────────────────────────────────────────────────────────┤
@@ -44,26 +31,30 @@ Architecture:
 │ - tags.py: TAG search/verification, library version cache   │
 └─────────────────────────────────────────────────────────────┘
 
-Usage:
+🛠️ Usage:
     python alfred_hooks.py <event_name> < payload.json
 
-Supported Events:
-    - SessionStart: 세션 시작 (프로젝트 상태 표시)
-    - UserPromptSubmit: 프롬프트 제출 (JIT 문서 로딩)
-    - PreToolUse: Tool 사용 전 (Checkpoint 자동 생성)
+📣 Supported Events:
+    - SessionStart: Start Session (display project status)
+    - UserPromptSubmit: Prompt submission (JIT document loading)
+    - PreToolUse: Before using the tool (automatically creates checkpoint)
     - SessionEnd, PostToolUse, Notification, Stop, SubagentStop
 
-Exit Codes:
-    - 0: 성공
-    - 1: 에러 (인수 없음, JSON 파싱 실패, 예외 발생)
+🚦 Exit Codes:
+    - 0: Success
+    - 1: Error (no arguments, JSON parsing failure, exception thrown)
+
+🧪 TDD History:
+    - RED: Module separation design, event routing test
+    - GREEN: 1233 LOC → 9 items Module separation implementation (SRP compliance)
+    - REFACTOR: Import optimization, enhanced error handling
 
-TDD History:
-    - RED: 모듈 분리 설계, 이벤트 라우팅 테스트
-    - GREEN: 1233 LOC → 9개 모듈 분리 구현 (SRP 준수)
-    - REFACTOR: Import 최적화, 에러 처리 강화
+Setup sys.path for package imports
 """
 
 import json
+import sys
+from pathlib import Path
 
 from core import HookResult
 from handlers import (
@@ -77,39 +68,44 @@ from handlers import (
     handle_user_prompt_submit,
 )
 
+# Add the hooks directory to sys.path to enable package imports
+HOOKS_DIR = Path(__file__).parent
+if str(HOOKS_DIR) not in sys.path:
+    sys.path.insert(0, str(HOOKS_DIR))
+
 
 def main() -> None:
-    """메인 진입점 - Claude Code Hook 스크립트
+    """Main entry point - Claude Code Hook script
 
-    CLI 인수로 이벤트명을 받고, stdin으로 JSON 페이로드를 읽습니다.
-    이벤트에 맞는 핸들러를 호출하고, 결과를 JSON으로 stdout에 출력합니다.
+    Receives the event name as a CLI argument and reads the JSON payload through stdin.
+    Calls the handler appropriate for the event and outputs the results to stdout as JSON.
 
-    Usage:
+    🛠️ Usage:
         python alfred_hooks.py <event_name> < payload.json
 
-    Supported Events:
-        - SessionStart: 세션 시작 (프로젝트 상태 표시)
-        - UserPromptSubmit: 프롬프트 제출 (JIT 문서 로딩)
+    📣 Supported Events:
+        - SessionStart: Start Session (display project status)
+        - UserPromptSubmit: Prompt submission (JIT document loading)
         - SessionEnd, PreToolUse, PostToolUse, Notification, Stop, SubagentStop
 
-    Exit Codes:
-        - 0: 성공
-        - 1: 에러 (인수 없음, JSON 파싱 실패, 예외 발생)
+    🚦 Exit Codes:
+        - 0: Success
+        - 1: Error (no arguments, JSON parsing failure, exception thrown)
 
-    Examples:
+    📝 Examples:
         $ echo '{"cwd": "."}' | python alfred_hooks.py SessionStart
         {"message": "🚀 MoAI-ADK Session Started\\n...", ...}
 
-    Notes:
-        - Claude Code가 자동으로 호출 (사용자 직접 실행 불필요)
-        - stdin/stdout으로 JSON I/O 처리
-        - stderr로 에러 메시지 출력
-        - UserPromptSubmit은 특별한 출력 스키마 사용 (hookEventName + additionalContext)
+    🗒️ Notes:
+        - Claude Code is automatically called (no need for direct user execution)
+        - JSON I/O processing through stdin/stdout
+        - Print error message to stderr
+        - UserPromptSubmit uses a special output schema (hookEventName + additionalContext)
 
-    TDD History:
-        - RED: 이벤트 라우팅, JSON I/O, 에러 처리 테스트
-        - GREEN: 핸들러 맵 기반 라우팅 구현
-        - REFACTOR: 에러 메시지 명확화, exit code 표준화, UserPromptSubmit 스키마 분리
+    🧪 TDD History:
+        - RED: Event routing, JSON I/O, error handling testing
+        - GREEN: Handler map-based routing implementation
+        - REFACTOR: Error message clarification, exit code standardization, UserPromptSubmit schema separation
     """
     # Check for event argument
     if len(sys.argv) < 2:
@@ -140,7 +136,7 @@ def main() -> None:
         handler = handlers.get(event_name)
         result = handler({"cwd": cwd, **data}) if handler else HookResult()
 
-        # UserPromptSubmit은 특별한 출력 스키마 사용
+        # UserPromptSubmit uses a special output schema
         if event_name == "UserPromptSubmit":
             print(json.dumps(result.to_user_prompt_submit_dict()))
         else:

moai_adk/templates/.claude/hooks/alfred/core/__init__.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """Core module for Alfred Hooks
 
-공통 타입 정의 및 유틸리티 함수
+Common type definitions and utility functions
 """
 
 from dataclasses import asdict, dataclass, field
@@ -9,64 +9,64 @@ from typing import Any, NotRequired, TypedDict
 
 
 class HookPayload(TypedDict):
-    """Claude Code Hook 이벤트 페이로드 타입 정의
+    """Claude Code Hook event payload type definition
 
-    Claude Code가 Hook 스크립트에 전달하는 데이터 구조.
-    이벤트에 따라 필드가 다를 수 있으므로 NotRequired 사용.
+    Data structure that Claude Code passes to the Hook script.
+    Use NotRequired because fields may vary depending on the event.
     """
 
     cwd: str
-    userPrompt: NotRequired[str]  # UserPromptSubmit 이벤트만 포함
-    tool: NotRequired[str]  # PreToolUse/PostToolUse 이벤트
+    userPrompt: NotRequired[str] # Includes only UserPromptSubmit events
+    tool: NotRequired[str]  # PreToolUse/PostToolUse events
     arguments: NotRequired[dict[str, Any]]  # Tool arguments
 
 
 @dataclass
 class HookResult:
-    """Hook 실행 결과"""
+    """Hook execution result"""
 
     message: str | None = None
-    systemMessage: str | None = None  # 사용자에게 직접 표시되는 메시지
+    systemMessage: str | None = None  # Message displayed directly to the user  # noqa: N815
     blocked: bool = False
-    contextFiles: list[str] = field(default_factory=list)
+    contextFiles: list[str] = field(default_factory=list)  # noqa: N815
     suggestions: list[str] = field(default_factory=list)
-    exitCode: int = 0
+    exitCode: int = 0  # noqa: N815
 
     def to_dict(self) -> dict[str, Any]:
-        """일반 Hook용 딕셔너리 변환"""
+        """Dictionary conversion for general Hook"""
         return asdict(self)
 
     def to_user_prompt_submit_dict(self) -> dict[str, Any]:
-        """UserPromptSubmit Hook 전용 출력 형식
+        """UserPromptSubmit Hook-specific output format
 
-        Claude Code는 UserPromptSubmit에 대해 특별한 스키마를 요구:
+        Claude Code requires a special schema for UserPromptSubmit:
         {
             "hookEventName": "UserPromptSubmit",
             "additionalContext": "string (required)"
         }
 
         Returns:
-            Claude Code UserPromptSubmit Hook 스키마에 맞는 딕셔너리
+            Claude Code UserPromptSubmit Hook Dictionary matching schema
 
         Examples:
             >>> result = HookResult(contextFiles=["tests/"])
             >>> result.to_user_prompt_submit_dict()
             {'hookEventName': 'UserPromptSubmit', 'additionalContext': '📎 Context: tests/'}
         """
-        # contextFiles를 additionalContext 문자열로 변환
+        # Convert contextFiles to additionalContext string
         if self.contextFiles:
             context_str = "\n".join([f"📎 Context: {f}" for f in self.contextFiles])
         else:
             context_str = ""
 
-        # message가 있으면 추가
+        # Add message if there is one
         if self.message:
             if context_str:
                 context_str = f"{self.message}\n\n{context_str}"
             else:
                 context_str = self.message
 
-        # 빈 문자열이면 기본값 사용
+        # If the string is empty, use default
         if not context_str:
             context_str = ""