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

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

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+# @CODE:HOOKS-CLARITY-DOCS | SPEC: Individual hook files for better UX
+"""UserPromptSubmit Hook: Just-In-Time Document Loading
+
+Claude Code Event: UserPromptSubmit
+Purpose: Analyze user prompt and recommend relevant documents to load into context
+Execution: Triggered when user submits a prompt
+
+Output: additionalContext with document path suggestions
+"""
+
+import json
+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"
+if str(SHARED_DIR) not in sys.path:
+    sys.path.insert(0, str(SHARED_DIR))
+
+from handlers import handle_user_prompt_submit
+
+
+def main() -> None:
+    """Main entry point for UserPromptSubmit hook
+
+    Analyzes user prompt patterns and recommends relevant documents:
+    - /alfred:1-plan → spec-metadata.md
+    - /alfred:2-run → development-guide.md
+    - @TAG mentions → TAG documentation
+    - SPEC references → related SPEC files
+
+    Exit Codes:
+        0: Success
+        1: Error (timeout, JSON parse failure, handler exception)
+
+    Note: Uses special output schema for UserPromptSubmit:
+    {
+        "continue": true,
+        "hookSpecificOutput": {
+            "hookEventName": "UserPromptSubmit",
+            "additionalContext": "Document path suggestions..."
+        }
+    }
+    """
+    # Set 5-second timeout
+    timeout = CrossPlatformTimeout(5)
+    timeout.start()
+
+    try:
+        # Read JSON payload from stdin
+        input_data = sys.stdin.read()
+        data = json.loads(input_data) if input_data.strip() else {}
+
+        # Call handler
+        result = handle_user_prompt_submit(data)
+
+        # Output result using UserPromptSubmit-specific schema
+        print(json.dumps(result.to_user_prompt_submit_dict()))
+        sys.exit(0)
+
+    except PlatformTimeoutError:
+        # Timeout - return minimal valid response
+        timeout_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": "⚠️ JIT context timeout - continuing without suggestions",
+            },
+        }
+        print(json.dumps(timeout_response))
+        print("UserPromptSubmit hook timeout after 5 seconds", file=sys.stderr)
+        sys.exit(1)
+
+    except json.JSONDecodeError as e:
+        # JSON parse error
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "error": f"JSON parse error: {e}",
+            },
+        }
+        print(json.dumps(error_response))
+        print(f"UserPromptSubmit JSON parse error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    except Exception as e:
+        # Unexpected error
+        error_response: dict[str, Any] = {
+            "continue": True,
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "error": f"UserPromptSubmit error: {e}",
+            },
+        }
+        print(json.dumps(error_response))
+        print(f"UserPromptSubmit unexpected error: {e}", file=sys.stderr)
+        sys.exit(1)
+
+    finally:
+        # Always cancel alarm
+        timeout.cancel()
+
+
+if __name__ == "__main__":
+    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/hooks/alfred/alfred_hooks.py SessionStart",
+            "command": "uv run .claude/hooks/alfred/session_start__show_project_info.py",
             "type": "command"
           }
         ]
@@ -20,7 +20,7 @@
       {
         "hooks": [
           {
-            "command": "uv run .claude/hooks/alfred/alfred_hooks.py PreToolUse",
+            "command": "uv run .claude/hooks/alfred/pre_tool__auto_checkpoint.py",
             "type": "command"
           }
         ],
@@ -31,7 +31,7 @@
       {
         "hooks": [
           {
-            "command": "uv run .claude/hooks/alfred/alfred_hooks.py UserPromptSubmit",
+            "command": "uv run .claude/hooks/alfred/user_prompt__jit_load_docs.py",
             "type": "command"
           }
         ]
@@ -41,7 +41,7 @@
       {
         "hooks": [
           {
-            "command": "uv run .claude/hooks/alfred/alfred_hooks.py SessionEnd",
+            "command": "uv run .claude/hooks/alfred/session_end__cleanup.py",
             "type": "command"
           }
         ]
@@ -51,7 +51,7 @@
       {
         "hooks": [
           {
-            "command": "uv run .claude/hooks/alfred/alfred_hooks.py PostToolUse",
+            "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`.

moai_adk/templates/.claude/skills/moai-alfred-context-budget/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: moai-alfred-context-budget
+description: "Claude Code context window optimization strategies, JIT retrieval, progressive loading, memory file patterns, and cleanup practices. Use when optimizing context usage, managing large projects, or implementing efficient workflows."
+allowed-tools: "Read, Grep"
+---
+
+## What It Does
+
+Claude Code context budget (100K-200K tokens)의 효율적 관리 전략, progressive disclosure, JIT retrieval, memory file 구조화 방법을 제공합니다.
+
+## When to Use
+
+- ✅ Context limit 도달 위험성 있을 때
+- ✅ 대규모 프로젝트의 context 관리 필요
+- ✅ Session handoff 준비
+- ✅ Memory file 구조 설계/정리
+
+## Context Budget Overview
+
+```
+Total: 100K-200K tokens
+├── System Prompt: ~2K
+├── Tools & Instructions: ~5K
+├── Session History: ~30K
+├── Project Context: ~40K
+└── Available for Response: ~23K
+```
+
+## Progressive Disclosure Pattern
+
+1. **Metadata** (always): Skill name, description, triggers
+2. **Content** (on-demand): Full SKILL.md when invoked
+3. **Supporting** (JIT): Examples, templates when referenced
+
+## JIT Retrieval Principles
+
+- Pull only what you need for immediate step
+- Prefer `Explore` over manual file hunting
+- Cache critical insights for reuse
+- Remove unnecessary files regularly
+
+## Best Practices
+
+✅ DO:
+- Use Explore for large searches
+- Cache results in memory files
+- Keep memory files < 500 lines each
+- Update session-summary.md before task switches
+- Archive completed work
+
+❌ DON'T:
+- Load entire src/ directory upfront
+- Duplicate context between files
+- Store memory files outside `.moai/memory/`
+- Leave stale session notes (archive or delete)
+- Cache raw code (summarize instead)
+
+---
+
+Learn more in `reference.md` for detailed JIT strategy, memory patterns, context budget calculations, and management practices.
+
+**Related Skills**: moai-alfred-practices, moai-cc-memory

moai_adk/templates/.claude/skills/moai-alfred-context-budget/examples.md

@@ -0,0 +1,28 @@
+# Context Budget Optimization Examples
+
+## Memory File Structure
+
+```
+.moai/memory/
+├── session-summary.md      # Current task, key files, assumptions
+├── architecture.md         # System design reference
+├── gotchas.md             # Common pitfalls
+└── archive/               # Completed sessions
+    ├── feature-auth-*
+    └── feature-api-*
+```
+
+## JIT Retrieval Example
+
+**Task**: Add email verification
+
+**JIT Loading**:
+- Read: User model (src/domain/user.ts)
+- Read: Signup endpoint (src/api/auth.ts)
+- Cache: Signup flow summary in memory
+
+**Result**: Context efficiency, clear understanding
+
+---
+
+Learn more in `reference.md`.