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

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

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

@@ -0,0 +1,62 @@
+# Agent Selection Examples
+
+## Example 1: New Feature Request
+
+**User**: "Add two-factor authentication"
+
+**Decision Tree**:
+```
+Task = Feature Implementation
+  ↓
+Create SPEC first? → YES
+Invoke: spec-builder
+  ↓
+Write Tests? → YES
+Invoke: tdd-implementer
+  ↓
+Need Code Review? → YES
+Invoke: quality-gate + Skill("moai-foundation-trust")
+  ↓
+Update Documentation? → YES
+Invoke: doc-syncer
+```
+
+**Result**: Proper agent sequence avoids rework
+
+---
+
+## Example 2: Bug Fix Triage
+
+**Error**: "TypeError: undefined is not a function"
+
+**Agent Sequence**:
+1. Invoke: debug-helper
+   - Analyze stack trace
+   - Identify root cause
+2. Invoke: tdd-implementer
+   - Write regression test
+   - Fix implementation
+3. Invoke: git-manager
+   - Commit with @TAG
+
+---
+
+## Example 3: Large Codebase Exploration
+
+**Task**: "How is authentication implemented?"
+
+✅ Correct:
+```
+Invoke: Explore(prompt="Find auth flow, entry points, models")
+Result: Clear architecture map
+```
+
+❌ Wrong:
+```
+Manual grep for 20+ files
+Result: Bloated context, still confused
+```
+
+---
+
+Learn more in `reference.md` for complete decision tree and multi-agent patterns.

moai_adk/templates/{.moai/memory/CLAUDE-AGENTS-GUIDE.md → .claude/skills/moai-alfred-agent-guide/reference.md}

@@ -68,6 +68,40 @@ The **code-builder pipeline** runs two Sonnet specialists in sequence: **impleme
 
 ---
 
+## Expert Agents (Proactively Triggered by SPEC Keywords)
+
+| Expert Agent            | Model  | Specialty                                                                           | Trigger Keywords                                                                                   | Trigger Source      |
+| ----------------------- | ------ | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------- |
+| **backend-expert** 🔧   | Sonnet | Backend architecture, API design, database schema, microservices, authentication    | 'backend', 'api', 'server', 'database', 'microservice', 'deployment', 'authentication'            | implementation-planner |
+| **frontend-expert** 💻  | Sonnet | Frontend architecture, component design, state management, UI/UX implementation     | 'frontend', 'ui', 'page', 'component', 'client-side', 'browser', 'web interface'                  | implementation-planner |
+| **devops-expert** 🚀    | Sonnet | DevOps strategy, deployment automation, containerization, CI/CD, cloud infrastructure | 'deployment', 'docker', 'kubernetes', 'ci/cd', 'pipeline', 'infrastructure', 'railway', 'vercel', 'aws' | implementation-planner |
+| **ui-ux-expert** 🎨     | Sonnet | UI/UX design, accessibility (WCAG 2.1 AA/AAA), design systems, Figma MCP, design-to-code | 'design', 'ux', 'ui', 'accessibility', 'a11y', 'user experience', 'wireframe', 'prototype', 'design system', 'figma', 'user research', 'persona', 'journey map' | implementation-planner |
+
+### How Expert Agents Work
+
+1. **Automatic Keyword Detection**: When `implementation-planner` analyzes a SPEC, it scans for expert trigger keywords
+2. **Proactive Delegation**: If keywords match, `implementation-planner` automatically invokes the relevant expert agent(s)
+3. **Expert Consultation**: Each expert provides domain-specific architecture guidance, technology recommendations, and risk analysis
+4. **Integration**: Expert feedback is integrated into the implementation plan and tagged with `@EXPERT:DOMAIN` for traceability
+
+### Example: Full-Stack Authentication SPEC
+
+```
+SPEC Keywords: 'api', 'authentication', 'design', 'accessibility'
+
+→ Trigger backend-expert (for API & auth architecture)
+→ Trigger ui-ux-expert (for login UI & accessibility)
+
+Result:
+@SPEC:AUTH-001 | @EXPERT:BACKEND | @EXPERT:UIUX
+
+Implementation Plan includes:
+- Backend: JWT token strategy, rate limiting, audit logging
+- UI/UX: Accessible login form (WCAG 2.1 AA), error messaging
+```
+
+---
+
 ## Zero-project Specialists
 
 | Sub-agent                  | Model  | Focus                                                       | Trigger                         |

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

@@ -0,0 +1,56 @@
+---
+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.7.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
+  },
+  "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
+- **tag**: TAG system configuration
+
+---
+
+Learn more in `reference.md` for complete schema reference, validation rules, and migration examples.
+
+**Related Skills**: moai-alfred-dev-guide, 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`.