moai-adk 0.9.0__py3-none-any.whl → 0.15.1__py3-none-any.whl

moai_adk/templates/.claude/hooks/alfred/shared/handlers/notification.py

@@ -4,21 +4,150 @@
 Notification, Stop, SubagentStop event handling
 """
 
+import json
+from datetime import datetime
+from pathlib import Path
+
 from core import HookPayload, HookResult
 
 
+def _get_command_state_file(cwd: str) -> Path:
+    """Get the path to command state tracking file"""
+    state_dir = Path(cwd) / ".moai" / "memory"
+    state_dir.mkdir(parents=True, exist_ok=True)
+    return state_dir / "command-execution-state.json"
+
+
+def _load_command_state(cwd: str) -> dict:
+    """Load current command execution state"""
+    try:
+        state_file = _get_command_state_file(cwd)
+        if state_file.exists():
+            with open(state_file, "r", encoding="utf-8") as f:
+                return json.load(f)
+    except Exception:
+        pass
+    return {"last_command": None, "last_timestamp": None, "is_running": False}
+
+
+def _save_command_state(cwd: str, state: dict) -> None:
+    """Save command execution state"""
+    try:
+        state_file = _get_command_state_file(cwd)
+        with open(state_file, "w", encoding="utf-8") as f:
+            json.dump(state, f, indent=2)
+    except Exception:
+        pass
+
+
+def _is_duplicate_command(current_cmd: str, last_cmd: str, last_timestamp: str) -> bool:
+    """Check if current command is a duplicate of the last one within 3 seconds"""
+    if not last_cmd or not last_timestamp or current_cmd != last_cmd:
+        return False
+
+    try:
+        last_time = datetime.fromisoformat(last_timestamp)
+        current_time = datetime.now()
+        time_diff = (current_time - last_time).total_seconds()
+        # Consider it a duplicate if same command within 3 seconds
+        return time_diff < 3
+    except Exception:
+        return False
+
+
 def handle_notification(payload: HookPayload) -> HookResult:
-    """Notification event handler (default implementation)"""
+    """Notification event handler
+
+    Detects and warns about duplicate command executions
+    (When the same /alfred: command is triggered multiple times within 3 seconds)
+    """
+    cwd = payload.get("cwd", ".")
+    notification = payload.get("notification", {})
+
+    # Extract command information from notification
+    current_cmd = None
+    if isinstance(notification, dict):
+        # Check if notification contains command information
+        text = notification.get("text", "") or str(notification)
+        if "/alfred:" in text:
+            # Extract /alfred: command
+            import re
+
+            match = re.search(r"/alfred:\S+", text)
+            if match:
+                current_cmd = match.group()
+
+    if not current_cmd:
+        return HookResult()
+
+    # Load current state
+    state = _load_command_state(cwd)
+    last_cmd = state.get("last_command")
+    last_timestamp = state.get("last_timestamp")
+
+    # Check for duplicate
+    if _is_duplicate_command(current_cmd, last_cmd, last_timestamp):
+        warning_msg = (
+            f"⚠️ Duplicate command detected: '{current_cmd}' "
+            f"is running multiple times within 3 seconds.\n"
+            f"This may indicate a system issue. Check logs in `.moai/logs/command-invocations.log`"
+        )
+
+        # Update state - mark as duplicate detected
+        state["duplicate_detected"] = True
+        state["duplicate_command"] = current_cmd
+        state["duplicate_timestamp"] = datetime.now().isoformat()
+        _save_command_state(cwd, state)
+
+        return HookResult(system_message=warning_msg, continue_execution=True)
+
+    # Update state with current command
+    state["last_command"] = current_cmd
+    state["last_timestamp"] = datetime.now().isoformat()
+    state["is_running"] = True
+    state["duplicate_detected"] = False
+    _save_command_state(cwd, state)
+
     return HookResult()
 
 
 def handle_stop(payload: HookPayload) -> HookResult:
-    """Stop event handler (default implementation)"""
+    """Stop event handler
+
+    Marks command execution as complete
+    """
+    cwd = payload.get("cwd", ".")
+    state = _load_command_state(cwd)
+    state["is_running"] = False
+    state["last_timestamp"] = datetime.now().isoformat()
+    _save_command_state(cwd, state)
+
     return HookResult()
 
 
 def handle_subagent_stop(payload: HookPayload) -> HookResult:
-    """SubagentStop event handler (default implementation)"""
+    """SubagentStop event handler
+
+    Records when a sub-agent finishes execution
+    """
+    cwd = payload.get("cwd", ".")
+
+    # Extract subagent name if available
+    subagent_name = (
+        payload.get("subagent", {}).get("name")
+        if isinstance(payload.get("subagent"), dict)
+        else None
+    )
+
+    try:
+        state_file = _get_command_state_file(cwd).parent / "subagent-execution.log"
+        timestamp = datetime.now().isoformat()
+
+        with open(state_file, "a", encoding="utf-8") as f:
+            f.write(f"{timestamp} | Subagent Stop | {subagent_name}\n")
+    except Exception:
+        pass
+
     return HookResult()
 
 

moai_adk/templates/.claude/hooks/alfred/shared/handlers/session.py

@@ -6,7 +6,7 @@ SessionStart, SessionEnd event handling
 
 from core import HookPayload, HookResult
 from core.checkpoint import list_checkpoints
-from core.project import count_specs, detect_language, get_git_info, get_package_version_info
+from core.project import count_specs, get_git_info, get_package_version_info
 
 
 def handle_session_start(payload: HookPayload) -> HookResult:
@@ -25,14 +25,14 @@ def handle_session_start(payload: HookPayload) -> HookResult:
 
     Message Format:
         🚀 MoAI-ADK Session Started
-           Language: {language}
+           [Version: {version}] - optional if version check fails
            [Branch: {branch} ({commit hash})] - optional if git fails
            [Changes: {Number of Changed Files}] - optional if git fails
            [SPEC Progress: {Complete}/{Total} ({percent}%)] - optional if specs fail
            [Checkpoints: {number} available] - optional if checkpoint list fails
 
     Graceful Degradation Strategy:
-        - CRITICAL: Language detection (must succeed - no try-except)
+        - OPTIONAL: Version info (skip if timeout/failure)
         - OPTIONAL: Git info (skip if timeout/failure)
         - OPTIONAL: SPEC progress (skip if timeout/failure)
         - OPTIONAL: Checkpoint list (skip if timeout/failure)
@@ -66,9 +66,6 @@ def handle_session_start(payload: HookPayload) -> HookResult:
 
     cwd = payload.get("cwd", ".")
 
-    # CRITICAL: Language detection - MUST succeed (no try-except)
-    language = detect_language(cwd)
-
     # OPTIONAL: Git info - skip if timeout/failure
     git_info = {}
     try:
@@ -119,13 +116,17 @@ def handle_session_start(payload: HookPayload) -> HookResult:
             # Check if this is a major version update
             if version_info.get("is_major_update"):
                 # Major version warning
-                lines.append(f"   ⚠️  Major version update available: {version_info['current']} → {version_info['latest']}")
+                lines.append(
+                    f"   ⚠️  Major version update available: {version_info['current']} → {version_info['latest']}"
+                )
                 lines.append("   Breaking changes detected. Review release notes:")
                 if version_info.get("release_notes_url"):
                     lines.append(f"   📝 {version_info['release_notes_url']}")
             else:
                 # Regular update
-                lines.append(f"   🗿 MoAI-ADK Ver: {version_info['current']} → {version_info['latest']} available ✨")
+                lines.append(
+                    f"   🗿 MoAI-ADK Ver: {version_info['current']} → {version_info['latest']} available ✨"
+                )
                 if version_info.get("release_notes_url"):
                     lines.append(f"   📝 Release Notes: {version_info['release_notes_url']}")
 
@@ -136,8 +137,6 @@ def handle_session_start(payload: HookPayload) -> HookResult:
             # No update available - show current version only
             lines.append(f"   🗿 MoAI-ADK Ver: {version_info['current']}")
 
-    # Add language info
-    lines.append(f"   🐍 Language: {language}")
 
     # Add Git info only if available (not degraded)
     if git_info:

moai_adk/templates/.claude/hooks/alfred/shared/handlers/tool.py

@@ -54,8 +54,7 @@ def handle_pre_tool_use(payload: HookPayload) -> HookResult:
             checkpoint_branch = create_checkpoint(cwd, operation_type)
             if checkpoint_branch != "checkpoint-failed":
                 system_message = (
-                    f"🛡️ Checkpoint created: {checkpoint_branch}\n"
-                    f"   Operation: {operation_type}"
+                    f"🛡️ Checkpoint created: {checkpoint_branch}\n   Operation: {operation_type}"
                 )
                 return HookResult(system_message=system_message, continue_execution=True)
     except Exception:
@@ -66,10 +65,8 @@ def handle_pre_tool_use(payload: HookPayload) -> HookResult:
     issues = scan_recent_changes_for_missing_tags(cwd)
     if issues:
         # Summarize first few issues for display
-        preview = "\n".join(
-            f" - {i.path} → 기대 태그: {i.expected}" for i in issues[:5]
-        )
-        more = "" if len(issues) <= 5 else f"\n (외 {len(issues)-5}건 더 존재)"
+        preview = "\n".join(f" - {i.path} → 기대 태그: {i.expected}" for i in issues[:5])
+        more = "" if len(issues) <= 5 else f"\n (외 {len(issues) - 5}건 더 존재)"
         msg = (
             "⚠️ TAG 누락 감지: 생성/수정한 파일 중 @TAG가 없는 항목이 있습니다.\n"
             f"{preview}{more}\n"

moai_adk/templates/.claude/hooks/alfred/shared/handlers/user.py

@@ -4,6 +4,9 @@
 Handling the UserPromptSubmit event
 """
 
+from datetime import datetime
+from pathlib import Path
+
 from core import HookPayload, HookResult
 from core.context import get_jit_context
 
@@ -29,11 +32,27 @@ def handle_user_prompt_submit(payload: HookPayload) -> HookResult:
         - GREEN: Recommend documents by calling get_jit_context()
         - REFACTOR: Message conditional display (only when there is a file)
         - UPDATE: Migrated to Claude Code standard Hook schema with snake_case fields
+        - FEATURE: Command execution logging for tracking double-run debugging
     """
     user_prompt = payload.get("userPrompt", "")
     cwd = payload.get("cwd", ".")
     context_files = get_jit_context(user_prompt, cwd)
 
+    # Command execution logging (DEBUG feature for tracking invocations)
+    if user_prompt.startswith("/alfred:"):
+        try:
+            log_dir = Path(cwd) / ".moai" / "logs"
+            log_dir.mkdir(parents=True, exist_ok=True)
+
+            log_file = log_dir / "command-invocations.log"
+            timestamp = datetime.now().isoformat()
+
+            with open(log_file, "a", encoding="utf-8") as f:
+                f.write(f"{timestamp} | {user_prompt}\n")
+        except Exception:
+            # Silently fail if logging fails (don't interrupt main flow)
+            pass
+
     system_message = f"📎 Loaded {len(context_files)} context file(s)" if context_files else None
 
     return HookResult(system_message=system_message, context_files=context_files)

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-# @CODE:HOOKS-CLARITY-001 | SPEC: Individual hook files for better UX
+# @CODE:HOOKS-CLARITY-DOCS | SPEC: Individual hook files for better UX
 """UserPromptSubmit Hook: Just-In-Time Document Loading
 
 Claude Code Event: UserPromptSubmit
@@ -10,11 +10,13 @@ Output: additionalContext with document path suggestions
 """
 
 import json
-import signal
 import sys
 from pathlib import Path
 from typing import Any
 
+from utils.timeout import CrossPlatformTimeout
+from utils.timeout import TimeoutError as PlatformTimeoutError
+
 # Setup import path for shared modules
 HOOKS_DIR = Path(__file__).parent
 SHARED_DIR = HOOKS_DIR / "shared"
@@ -24,16 +26,6 @@ if str(SHARED_DIR) not in sys.path:
 from handlers import handle_user_prompt_submit
 
 
-class HookTimeoutError(Exception):
-    """Hook execution timeout exception"""
-    pass
-
-
-def _timeout_handler(signum, frame):
-    """Signal handler for 5-second timeout"""
-    raise HookTimeoutError("Hook execution exceeded 5-second timeout")
-
-
 def main() -> None:
     """Main entry point for UserPromptSubmit hook
 
@@ -57,8 +49,8 @@ def main() -> None:
     }
     """
     # Set 5-second timeout
-    signal.signal(signal.SIGALRM, _timeout_handler)
-    signal.alarm(5)
+    timeout = CrossPlatformTimeout(5)
+    timeout.start()
 
     try:
         # Read JSON payload from stdin
@@ -72,14 +64,14 @@ def main() -> None:
         print(json.dumps(result.to_user_prompt_submit_dict()))
         sys.exit(0)
 
-    except HookTimeoutError:
+    except PlatformTimeoutError:
         # Timeout - return minimal valid response
         timeout_response: dict[str, Any] = {
             "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "UserPromptSubmit",
-                "additionalContext": "⚠️ JIT context timeout - continuing without suggestions"
-            }
+                "additionalContext": "⚠️ JIT context timeout - continuing without suggestions",
+            },
         }
         print(json.dumps(timeout_response))
         print("UserPromptSubmit hook timeout after 5 seconds", file=sys.stderr)
@@ -91,8 +83,8 @@ def main() -> None:
             "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "UserPromptSubmit",
-                "error": f"JSON parse error: {e}"
-            }
+                "error": f"JSON parse error: {e}",
+            },
         }
         print(json.dumps(error_response))
         print(f"UserPromptSubmit JSON parse error: {e}", file=sys.stderr)
@@ -104,8 +96,8 @@ def main() -> None:
             "continue": True,
             "hookSpecificOutput": {
                 "hookEventName": "UserPromptSubmit",
-                "error": f"UserPromptSubmit error: {e}"
-            }
+                "error": f"UserPromptSubmit error: {e}",
+            },
         }
         print(json.dumps(error_response))
         print(f"UserPromptSubmit unexpected error: {e}", file=sys.stderr)
@@ -113,7 +105,7 @@ def main() -> None:
 
     finally:
         # Always cancel alarm
-        signal.alarm(0)
+        timeout.cancel()
 
 
 if __name__ == "__main__":

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

@@ -0,0 +1 @@
+"""Utility modules for Alfred hooks."""

moai_adk/templates/.claude/hooks/alfred/utils/timeout.py

@@ -0,0 +1,161 @@
+#!/usr/bin/env python3
+# @CODE:TIMEOUT-001 | SPEC: SPEC-TIMEOUT-HANDLING-001
+"""Cross-Platform Timeout Handler for Windows & Unix Compatibility
+
+Provides a unified timeout mechanism that works on both Windows (threading-based)
+and Unix/POSIX systems (signal-based).
+
+Architecture:
+  - Windows: threading.Timer with exception injection
+  - Unix/POSIX: signal.SIGALRM (traditional approach)
+  - Both: Context manager for clean cancellation
+"""
+
+import platform
+import signal
+import threading
+from contextlib import contextmanager
+from typing import Callable, Optional
+
+
+class TimeoutError(Exception):
+    """Timeout exception raised when deadline exceeded"""
+    pass
+
+
+class CrossPlatformTimeout:
+    """Cross-platform timeout handler supporting Windows and Unix.
+
+    Windows: Uses threading.Timer to schedule timeout exception
+    Unix: Uses signal.SIGALRM for timeout handling
+
+    Usage:
+        # Context manager (recommended)
+        with CrossPlatformTimeout(5):
+            long_running_operation()
+
+        # Manual control
+        timeout = CrossPlatformTimeout(5)
+        timeout.start()
+        try:
+            long_running_operation()
+        finally:
+            timeout.cancel()
+    """
+
+    def __init__(self, timeout_seconds: float, callback: Optional[Callable] = None):
+        """Initialize timeout with duration in seconds.
+
+        Args:
+            timeout_seconds: Timeout duration in seconds (float or int)
+            callback: Optional callback to execute before raising TimeoutError
+        """
+        # Convert float to int for signal.alarm()
+        self.timeout_seconds = timeout_seconds
+        self.timeout_seconds_int = max(1, int(timeout_seconds))  # signal.alarm requires >=1
+        self.callback = callback
+        self.timer: Optional[threading.Timer] = None
+        self._is_windows = platform.system() == "Windows"
+        self._old_handler = None
+
+    def start(self) -> None:
+        """Start timeout countdown."""
+        # Handle zero/negative timeouts
+        if self.timeout_seconds <= 0:
+            if self.timeout_seconds == 0:
+                # Zero timeout: raise immediately
+                if self.callback:
+                    self.callback()
+                raise TimeoutError("Timeout of 0 seconds exceeded immediately")
+            else:
+                # Negative timeout: don't timeout at all
+                return
+
+        if self._is_windows:
+            self._start_windows_timeout()
+        else:
+            self._start_unix_timeout()
+
+    def cancel(self) -> None:
+        """Cancel timeout (must call before timeout expires)."""
+        if self._is_windows:
+            self._cancel_windows_timeout()
+        else:
+            self._cancel_unix_timeout()
+
+    def _start_windows_timeout(self) -> None:
+        """Windows: Use threading.Timer to raise exception."""
+        def timeout_handler():
+            if self.callback:
+                self.callback()
+            raise TimeoutError(
+                f"Operation exceeded {self.timeout_seconds}s timeout (Windows threading)"
+            )
+
+        self.timer = threading.Timer(self.timeout_seconds, timeout_handler)
+        self.timer.daemon = True
+        self.timer.start()
+
+    def _cancel_windows_timeout(self) -> None:
+        """Windows: Cancel timer thread."""
+        if self.timer:
+            self.timer.cancel()
+            self.timer = None
+
+    def _start_unix_timeout(self) -> None:
+        """Unix/POSIX: Use signal.SIGALRM for timeout."""
+        def signal_handler(signum, frame):
+            if self.callback:
+                try:
+                    self.callback()
+                except Exception:
+                    # Ignore callback exceptions, timeout error takes precedence
+                    pass
+            raise TimeoutError(
+                f"Operation exceeded {self.timeout_seconds}s timeout (Unix signal)"
+            )
+
+        # Save old handler to restore later
+        self._old_handler = signal.signal(signal.SIGALRM, signal_handler)
+        # Use integer timeout_seconds_int for signal.alarm()
+        signal.alarm(self.timeout_seconds_int)
+
+    def _cancel_unix_timeout(self) -> None:
+        """Unix/POSIX: Cancel alarm and restore old handler."""
+        signal.alarm(0)  # Cancel pending alarm
+        if self._old_handler is not None:
+            signal.signal(signal.SIGALRM, self._old_handler)
+            self._old_handler = None
+
+    def __enter__(self):
+        """Context manager entry."""
+        self.start()
+        return self
+
+    def __exit__(self, exc_type, exc_val, exc_tb):
+        """Context manager exit - always cancel."""
+        self.cancel()
+        return False  # Don't suppress exceptions
+
+
+@contextmanager
+def timeout_context(timeout_seconds: float, callback: Optional[Callable] = None):
+    """Decorator/context manager for timeout.
+
+    Usage:
+        with timeout_context(5):
+            slow_function()
+
+    Args:
+        timeout_seconds: Timeout duration in seconds (float or int)
+        callback: Optional callback to execute before raising TimeoutError
+
+    Yields:
+        CrossPlatformTimeout instance
+    """
+    timeout = CrossPlatformTimeout(timeout_seconds, callback=callback)
+    timeout.start()
+    try:
+        yield timeout
+    finally:
+        timeout.cancel()

moai_adk/templates/.claude/settings.json

@@ -10,7 +10,7 @@
       {
         "hooks": [
           {
-            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/session_start__show_project_info.py",
+            "command": "uv run .claude/hooks/alfred/session_start__show_project_info.py",
             "type": "command"
           }
         ]
@@ -20,7 +20,7 @@
       {
         "hooks": [
           {
-            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/pre_tool__auto_checkpoint.py",
+            "command": "uv run .claude/hooks/alfred/pre_tool__auto_checkpoint.py",
             "type": "command"
           }
         ],
@@ -31,7 +31,7 @@
       {
         "hooks": [
           {
-            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/user_prompt__jit_load_docs.py",
+            "command": "uv run .claude/hooks/alfred/user_prompt__jit_load_docs.py",
             "type": "command"
           }
         ]
@@ -41,7 +41,7 @@
       {
         "hooks": [
           {
-            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/session_end__cleanup.py",
+            "command": "uv run .claude/hooks/alfred/session_end__cleanup.py",
             "type": "command"
           }
         ]
@@ -51,7 +51,7 @@
       {
         "hooks": [
           {
-            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/post_tool__log_changes.py",
+            "command": "uv run .claude/hooks/alfred/post_tool__log_changes.py",
             "type": "command"
           }
         ],

moai_adk/templates/.claude/skills/moai-alfred-agent-guide/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: moai-alfred-agent-guide
+description: "19-agent team structure, decision trees for agent selection, Haiku vs Sonnet model selection, and agent collaboration principles. Use when deciding which sub-agent to invoke, understanding team responsibilities, or learning multi-agent orchestration."
+allowed-tools: "Read, Glob, Grep"
+---
+
+## What It Does
+
+MoAI-ADK의 19개 Sub-agent 아키텍처, 어떤 agent를 선택할지 결정하는 트리, Haiku/Sonnet 모델 선택 기준을 정의합니다.
+
+## When to Use
+
+- ✅ 어떤 sub-agent를 invoke할지 불명확
+- ✅ Agent 책임 범위 학습
+- ✅ Haiku vs Sonnet 모델 선택 필요
+- ✅ Multi-agent 협업 패턴 이해
+
+## Agent Team at a Glance
+
+### 10 Core Sub-agents (Sonnet)
+- spec-builder: SPEC 작성
+- tdd-implementer: TDD 구현 (RED → GREEN → REFACTOR)
+- doc-syncer: 문서 동기화
+- implementation-planner: 구현 전략
+- debug-helper: 오류 분석
+- quality-gate: TRUST 5 검증
+- tag-agent: TAG 체인 검증
+- git-manager: Git 워크플로우
+- Explore: 코드베이스 탐색
+- Plan: 작업 계획
+
+### 4 Expert Agents (Sonnet - Proactively Triggered)
+- **backend-expert**: Backend 아키텍처, API 설계, 데이터베이스
+- **frontend-expert**: Frontend 아키텍처, 컴포넌트 설계, 상태 관리
+- **devops-expert**: DevOps 전략, 배포, 인프라
+- **ui-ux-expert**: UI/UX 설계, 접근성, 디자인 시스템 (Figma MCP)
+
+### 6 Specialist Agents (Haiku)
+- project-manager: 프로젝트 초기화
+- skill-factory: Skill 생성/최적화
+- cc-manager: Claude Code 설정
+- cc-hooks: Hook 시스템
+- cc-mcp-plugins: MCP 서버
+- trust-checker: TRUST 검증
+
+## Agent Selection Decision Tree
+
+```
+Task Type?
+├─ SPEC 작성/검증 → spec-builder
+├─ TDD 구현 → tdd-implementer
+├─ 문서 동기화 → doc-syncer
+├─ 구현 계획 → implementation-planner
+├─ 오류 분석 → debug-helper
+├─ 품질 검증 → quality-gate + Skill("moai-foundation-trust")
+├─ 코드베이스 탐색 → Explore
+├─ Git 워크플로우 → git-manager
+└─ 전체 프로젝트 계획 → Plan
+```
+
+## Model Selection
+
+- **Sonnet**: Complex reasoning (spec-builder, tdd-implementer, implementation-planner)
+- **Haiku**: Fast execution (project-manager, quality-gate, git-manager)
+
+---
+
+Learn more in `reference.md` for complete agent responsibilities, collaboration patterns, and advanced orchestration strategies.
+
+**Related Skills**: moai-alfred-rules, moai-alfred-practices