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

moai_adk/templates/.claude/commands/moai/9-feedback.md

@@ -0,0 +1,314 @@
+---
+name: moai:9-feedback
+description: "Submit feedback or report issues"
+argument-hint: "[issue|suggestion|question]"
+allowed-tools: Read, Write, Edit, Grep, Glob, WebFetch, WebSearch, Bash, TodoWrite, AskUserQuestion, Task, Skill
+model: haiku
+---
+
+##  Pre-execution Context
+
+!git status --porcelain
+!git branch --show-current
+!git log --oneline -1
+
+##  Essential Files
+
+@.moai/config/config.yaml
+
+---
+
+#  MoAI-ADK Step 9: Feedback Loop
+
+> Architecture: Commands → Agents → Skills. This command orchestrates ONLY through `Task()` tool.
+> Delegation Model: Feedback collection delegated to `manager-quality` agent.
+
+Workflow Integration: This command implements the feedback loop of the MoAI workflow, allowing users to report issues or suggestions directly from the CLI.
+
+---
+
+##  Command Purpose
+
+Collect user feedback, bug reports, or feature suggestions and create GitHub issues automatically.
+
+Run on: `$ARGUMENTS` (Feedback type)
+
+---
+
+##  Execution Philosophy
+
+`/moai:9-feedback` performs feedback collection through agent delegation:
+
+```
+User Command: /moai:9-feedback [type]
+    ↓
+Phase 1: Task(subagent_type="manager-quality")
+    → Analyze feedback type
+    → Collect details via AskUserQuestion
+    → Create GitHub Issue via Skill
+    ↓
+Output: Issue created with link
+```
+
+### Key Principle: Full Delegation Pattern
+
+This command exclusively uses these tools:
+
+- [HARD] Task() for agent delegation
+  WHY: Task orchestration ensures feedback collection responsibility lies with specialized agents
+  IMPACT: Direct tool usage bypasses quality assurance and agent expertise
+
+- [HARD] AskUserQuestion() for user interaction AT COMMAND LEVEL ONLY
+  WHY: Subagents via Task() are stateless and cannot interact with users directly
+  IMPACT: Expecting agents to use AskUserQuestion causes workflow failures
+  CORRECT: Command collects feedback type and details, passes to agent as parameters
+
+- [HARD] Delegate all Bash operations to manager-quality agent
+  WHY: Agent context ensures proper error handling and feedback capture
+  IMPACT: Direct Bash execution loses feedback traceability and error context
+
+---
+
+##  Associated Agents & Skills
+
+| Agent/Skill     | Purpose                                       |
+| --------------- | --------------------------------------------- |
+| manager-quality | Feedback collection and GitHub issue creation |
+
+---
+
+## Agent Invocation Patterns (CLAUDE.md Compliance)
+
+This command uses agent execution patterns defined in CLAUDE.md (lines 96-120).
+
+### Sequential Phase-Based Chaining ✅
+
+Command implements simple sequential execution through 2 phases:
+
+Phase Flow:
+- Phase 1: Feedback Collection (manager-quality analyzes type and collects details)
+- Phase 2: GitHub Issue Creation (manager-quality creates issue with collected information)
+
+Each phase receives outputs from previous phase as context.
+
+WHY: Sequential execution ensures complete feedback capture before submission
+- Phase 2 requires validated feedback details from Phase 1
+- Issue creation requires all user input to be collected
+
+IMPACT: Skipping Phase 1 would create incomplete GitHub issues
+
+### Parallel Execution ❌
+
+Not applicable - simple linear workflow
+
+WHY: Feedback workflow has minimal complexity
+- Only one agent (manager-quality) handles entire process
+- Single feedback submission at a time
+- No independent operations to parallelize
+
+IMPACT: Parallel execution unnecessary for single-agent linear workflow
+
+### Resumable Agent Support ❌
+
+Not applicable - command completes in single execution
+
+WHY: Feedback submission is fast atomic operation
+- Typical execution completes in under 30 seconds
+- GitHub API calls are atomic and fast
+- No long-running processes requiring checkpoints
+
+IMPACT: Resume pattern unnecessary for simple feedback workflows
+
+---
+
+Refer to CLAUDE.md "Agent Chaining Patterns" (lines 96-120) for complete pattern architecture.
+
+---
+
+##  Execution Process
+
+### Step 1: Delegate to Quality Gate Agent
+
+Use the manager-quality subagent to collect and submit user feedback:
+
+Task: Collect user feedback and create a GitHub issue.
+
+Context:
+
+- Feedback Type: $ARGUMENTS (default to 'issue' if empty)
+- Conversation Language: {{CONVERSATION_LANGUAGE}}
+
+Instructions:
+
+1. Determine Feedback Type:
+
+   [HARD] Resolve feedback type from $ARGUMENTS if provided
+   WHY: Pre-specified type accelerates feedback collection
+   IMPACT: Skipping argument check forces unnecessary user interaction
+
+   [HARD] Prompt user to select type when $ARGUMENTS is empty
+   WHY: Interactive selection ensures proper categorization
+   IMPACT: Assuming default type may misclassify feedback
+
+   Supported Feedback Types:
+   - Bug Report: Technical issues or errors
+   - Feature Request: Suggestions for improvements
+   - Question/Other: Clarifications or general feedback
+
+2. Collect Details:
+
+   [HARD] Solicit feedback title from user
+   WHY: Title establishes feedback summary for issue search and triage
+   IMPACT: Missing title reduces issue discoverability
+
+   [HARD] Solicit detailed description from user
+   WHY: Description provides context for developers to understand and respond
+   IMPACT: Vague descriptions create follow-up communication overhead
+
+   [SOFT] Solicit priority level from user (Low/Medium/High)
+   WHY: Priority directs team resource allocation
+   IMPACT: Missing priority defaults to normal urgency
+
+3. Create GitHub Issue:
+
+   [HARD] Execute GitHub CLI (gh issue create) command with collected feedback
+   WHY: GitHub integration ensures feedback enters official issue tracking system
+   IMPACT: Untracked feedback is lost to follow-up and implementation
+
+   [HARD] Apply appropriate labels based on feedback type
+   WHY: Labels enable automated triage and dashboard organization
+   IMPACT: Untagged issues are invisible to responsible team members
+
+   [SOFT] Format issue body using consistent template
+   WHY: Standardized templates improve issue clarity and consistency
+   IMPACT: Inconsistent formatting wastes developer time parsing issues
+
+4. Report Result:
+   [HARD] Provide user with created issue URL
+   WHY: Direct issue link enables immediate user access and tracking
+   IMPACT: Missing link requires users to manually search for their feedback
+
+   [HARD] Confirm successful feedback submission to user
+   WHY: Confirmation provides closure and acknowledgment of user contribution
+   IMPACT: Silent completion leaves user uncertain about feedback status
+
+Language and Accessibility:
+
+- [HARD] Use conversation_language for all user-facing interactions
+  WHY: User language ensures comprehension and accessibility
+  IMPACT: Wrong language creates friction and reduces usability
+
+- [HARD] Provide text-based options in AskUserQuestion (exclude emojis)
+  WHY: Text options ensure consistency across all platforms and locales
+  IMPACT: Emoji options are platform-dependent and may not display correctly
+
+---
+
+##  Summary: Execution Verification Checklist
+
+Before considering command execution complete, verify all requirements:
+
+- [HARD] Agent Invoked: manager-quality agent executed with feedback details
+  Verification: Confirm agent Task() call with feedback context
+  Acceptance Criteria: Agent response confirms feedback reception
+
+- [HARD] Feedback Collected: User provided title, description, and type
+  Verification: Confirm all required fields captured
+  Acceptance Criteria: No empty or null feedback fields
+
+- [HARD] Issue Created: GitHub issue successfully submitted to repository
+  Verification: Confirm gh issue create command executed successfully
+  Acceptance Criteria: GitHub API response contains issue ID and URL
+
+- [HARD] Link Provided: User received direct URL to created issue
+  Verification: Confirm issue URL displayed in user response
+  Acceptance Criteria: User can click URL and access their feedback immediately
+
+---
+
+##  Quick Reference
+
+| Scenario         | Entry Point                   | Expected Outcome                            |
+| ---------------- | ----------------------------- | ------------------------------------------- |
+| Report bug       | `/moai:9-feedback issue`      | GitHub issue created with bug label         |
+| Request feature  | `/moai:9-feedback suggestion` | GitHub issue created with enhancement label |
+| Ask question     | `/moai:9-feedback question`   | GitHub issue created with question label    |
+| General feedback | `/moai:9-feedback`            | Interactive feedback collection             |
+
+Associated Agent:
+
+- `manager-quality` - Feedback manager and GitHub issue creator
+
+Feedback Types:
+
+- Bug Report: Technical issues or errors
+- Feature Request: Suggestions for improvements
+- Question: Clarifications or help needed
+- Other: General feedback
+
+Version: 1.0.0 (Agent-Delegated Pattern)
+Last Updated: 2025-11-25
+Architecture: Commands → Agents → Skills (Complete delegation)
+
+---
+
+## Output Format
+
+Structure agent responses with semantic sections for clarity and consistency:
+
+Response Structure:
+
+The agent response must include these sections:
+
+Feedback Summary:
+Concise recap of feedback type, title, and key points submitted
+
+GitHub Integration:
+Confirmation that feedback was submitted to GitHub with issue URL and ID
+
+User Language:
+Response provided in user's conversation_language configuration
+
+Next Actions:
+Clear options for user to continue workflow or submit additional feedback
+
+WHY: Semantic structure ensures consistent response quality and user experience
+IMPACT: Unstructured responses create ambiguity and require user clarification
+
+---
+
+## Post-Submission User Direction
+
+After successful feedback submission, present user with next action options:
+
+[HARD] Display post-submission summary to user
+WHY: Summary confirms successful completion and provides issue reference
+IMPACT: Missing summary leaves user uncertain about submission status
+
+[SOFT] Offer user next step choices via AskUserQuestion
+WHY: Guided choices help users continue productive workflows
+IMPACT: Abrupt completion requires user to determine next actions
+
+Next Step Options:
+- Continue Development: Return to current development workflow
+- Submit Additional Feedback: Report another issue or suggestion
+- View Issue: Open created GitHub issue in browser
+
+Requirements:
+
+- [HARD] Use conversation_language for all post-submission messaging
+  WHY: Consistent language maintains user context
+  IMPACT: Language switching disorients users
+
+- [HARD] Express all options as text labels without emoji characters
+  WHY: Text-only labels ensure universal platform compatibility
+  IMPACT: Emojis may fail to display across different systems
+
+---
+
+##  EXECUTION DIRECTIVE
+
+You must NOW execute the command following the "Execution Process" described above.
+
+1. Use the manager-quality subagent.
+2. Do NOT just describe what you will do. DO IT.

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

@@ -0,0 +1,8 @@
+"""
+Claude Hooks Package
+
+This package contains hook scripts for Claude Code integration.
+"""
+
+__version__ = "1.0.0"
+__author__ = "MoAI-ADK Team"

moai_adk/templates/.claude/hooks/moai/__init__.py

@@ -0,0 +1,8 @@
+"""
+Alfred Hooks Package
+
+This package contains Alfred-specific hook scripts for MoAI-ADK integration.
+"""
+
+__version__ = "1.0.0"
+__author__ = "MoAI-ADK Team"

moai_adk/templates/.claude/hooks/moai/lib/__init__.py

@@ -0,0 +1,85 @@
+"""
+Hook utilities library - Optimized and consolidated
+
+This module provides centralized access to all hook-related utilities:
+- Configuration management (ConfigManager)
+- Core utilities (timeout, common utilities)
+- Data models (HookPayload, HookResult)
+- Project utilities (language detection, git info, SPEC counting)
+- Checkpoint utilities (risky operation detection, checkpoint creation)
+"""
+
+try:
+    # Import core components
+    # Import checkpoint utilities
+    from lib.checkpoint import (
+        create_checkpoint,
+        detect_risky_operation,
+        list_checkpoints,
+    )
+
+    # Import utilities
+    from lib.common import (
+        format_duration,
+        get_file_pattern_category,
+        get_summary_stats,
+        is_root_whitelisted,
+        suggest_moai_location,
+    )
+    from lib.config_manager import (
+        ConfigManager,
+        get_config,
+        get_config_manager,
+        get_exit_code,
+        get_graceful_degradation,
+        get_timeout_seconds,
+    )
+
+    # Import models
+    from lib.models import HookPayload, HookResult
+
+    # Import project utilities
+    from lib.project import (
+        count_specs,
+        find_project_root,
+        get_git_info,
+    )
+    from lib.timeout import CrossPlatformTimeout, TimeoutError, timeout_context
+
+    __all__ = [
+        # Core - Timeout
+        "CrossPlatformTimeout",
+        "TimeoutError",
+        "timeout_context",
+        # Core - Configuration
+        "ConfigManager",
+        "get_config_manager",
+        "get_config",
+        "get_timeout_seconds",
+        "get_graceful_degradation",
+        "get_exit_code",
+        # Common utilities
+        "format_duration",
+        "get_summary_stats",
+        "is_root_whitelisted",
+        "get_file_pattern_category",
+        "suggest_moai_location",
+        # Models
+        "HookPayload",
+        "HookResult",
+        # Checkpoint
+        "create_checkpoint",
+        "detect_risky_operation",
+        "list_checkpoints",
+        # Project
+        "find_project_root",
+        "get_git_info",
+        "count_specs",
+    ]
+
+except ImportError:
+    # Fallback if not all imports are available
+    __all__ = []
+
+__version__ = "1.0.0"
+__author__ = "MoAI-ADK Team"

moai_adk/templates/.claude/hooks/{alfred/shared/core → moai/lib}/checkpoint.py

@@ -2,41 +2,14 @@
 """Event-Driven Checkpoint system
 
 Detect risky tasks and create automatic checkpoints
-@TAG:CHECKPOINT-EVENT-001
 """
 
 import json
-import re
 import subprocess
 from datetime import datetime
 from pathlib import Path
 from typing import Any
 
-# Script execution pattern for each language supported by MoAI-ADK
-# Python, TypeScript, Java, Go, Rust, Dart, Swift, Kotlin + Shell
-SCRIPT_EXECUTION_PATTERN = re.compile(
-    r"\b("
-    # Python ecosystem
-    r"python3?|pytest|pip|uv|"
-    # JavaScript/TypeScript ecosystem
-    r"node|npm|npx|yarn|bun|tsx|ts-node|vitest|jest|"
-    # Java ecosystem
-    r"java|javac|mvn|gradle|"
-    # Go
-    r"go|"
-    # Rust
-    r"cargo|"
-    # Dart/Flutter
-    r"dart|flutter|"
-    # Swift
-    r"swift|xcodebuild|"
-    # Kotlin
-    r"kotlinc?|"
-    # Shell scripts and build tools
-    r"bash|sh|zsh|fish|make"
-    r")\b"
-)
-
 
 def detect_risky_operation(tool_name: str, tool_args: dict[str, Any], cwd: str) -> tuple[bool, str]:
     """Risk task detection (for Event-Driven Checkpoint)
@@ -73,7 +46,6 @@ def detect_risky_operation(tool_name: str, tool_args: dict[str, Any], cwd: str)
         - Performance: lightweight string matching (< 1ms)
         - Extensibility: Easily added to the patterns dictionary
 
-    @TAG:CHECKPOINT-EVENT-001
     """
     # Bash tool: Detect dangerous commands
     if tool_name == "Bash":
@@ -98,9 +70,9 @@ def detect_risky_operation(tool_name: str, tool_args: dict[str, Any], cwd: str)
         critical_files = [
             "CLAUDE.md",
             "config.json",
-            ".claude/skills/moai-alfred-dev-guide/reference.md",
-            ".claude/skills/moai-alfred-spec-metadata-extended/reference.md",
-            ".moai/config.json",
+            ".claude/skills/moai-core-dev-guide/reference.md",
+            ".claude/skills/moai-core-spec-metadata-extended/reference.md",
+            ".moai/config/config.json",
         ]
 
         if any(cf in file_path for cf in critical_files):
@@ -143,7 +115,6 @@ def create_checkpoint(cwd: str, operation_type: str) -> str:
         - Do not check dirty working directory (allow uncommitted changes)
         - Automatically record checkpoint logs (.moai/checkpoints.log)
 
-    @TAG:CHECKPOINT-EVENT-001
     """
     timestamp = datetime.now().strftime("%Y%m%d-%H%M%S")
     branch_name = f"before-{operation_type}-{timestamp}"
@@ -164,7 +135,11 @@ def create_checkpoint(cwd: str, operation_type: str) -> str:
 
         return branch_name
 
-    except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError):
+    except (
+        subprocess.CalledProcessError,
+        subprocess.TimeoutExpired,
+        FileNotFoundError,
+    ):
         # Fallback (ignore) in case of Git error
         return "checkpoint-failed"
 
@@ -192,7 +167,6 @@ def log_checkpoint(cwd: str, branch_name: str, operation_type: str) -> None:
         - Record in append mode (preserve existing logs)
         - Ignored in case of failure (not critical)
 
-    @TAG:CHECKPOINT-EVENT-001
     """
     log_file = Path(cwd) / ".moai" / "checkpoints.log"
 
@@ -217,7 +191,7 @@ def list_checkpoints(cwd: str, max_count: int = 10) -> list[dict[str, str]]:
     """Checkpoint list (parsing .moai/checkpoints.log)
 
     Returns a list of recently created checkpoints.
-    Used in the SessionStart, /alfred:0-project restore command.
+    Used in the SessionStart, /moai:0-project restore command.
 
     Args:
         cwd: Project root directory path
@@ -239,7 +213,6 @@ def list_checkpoints(cwd: str, max_count: int = 10) -> list[dict[str, str]]:
         - Ignore lines where JSON parsing fails
         - Return only the latest max_count
 
-    @TAG:CHECKPOINT-EVENT-001
     """
     log_file = Path(cwd) / ".moai" / "checkpoints.log"
 

moai_adk/templates/.claude/hooks/moai/lib/common.py

@@ -0,0 +1,131 @@
+"""Common utility functions for MoAI hooks
+
+Consolidated fallback implementations used across multiple hooks.
+"""
+
+import re
+import statistics
+from typing import Any, Dict, List, Optional, Tuple
+
+
+def format_duration(seconds: float) -> str:
+    """Format duration in seconds to readable string.
+
+    Converts seconds to human-readable format (s, m, h).
+
+    Args:
+        seconds: Duration in seconds
+
+    Returns:
+        Formatted duration string (e.g., "2.5m", "1.3h")
+    """
+    if seconds < 60:
+        return f"{seconds:.1f}s"
+    minutes = seconds / 60
+    if minutes < 60:
+        return f"{minutes:.1f}m"
+    hours = minutes / 60
+    return f"{hours:.1f}h"
+
+
+def get_summary_stats(values: List[float]) -> Dict[str, float]:
+    """Get summary statistics for a list of values.
+
+    Calculates mean, min, max, and standard deviation.
+
+    Args:
+        values: List of numeric values
+
+    Returns:
+        Dictionary with keys: mean, min, max, std
+    """
+    if not values:
+        return {"mean": 0, "min": 0, "max": 0, "std": 0}
+
+    return {
+        "mean": statistics.mean(values),
+        "min": min(values),
+        "max": max(values),
+        "std": statistics.stdev(values) if len(values) > 1 else 0,
+    }
+
+
+def is_root_whitelisted(filename: str, config: Dict[str, Any]) -> bool:
+    """Check if file is allowed in project root.
+
+    Consolidated from pre_tool__document_management.py and session_end__auto_cleanup.py
+
+    Args:
+        filename: Name of the file
+        config: Configuration dictionary
+
+    Returns:
+        True if file is whitelisted for root directory
+    """
+    whitelist = config.get("document_management", {}).get("root_whitelist", [])
+
+    for pattern in whitelist:
+        # Convert glob pattern to regex
+        regex = pattern.replace("*", ".*").replace("?", ".")
+        if re.match(f"^{regex}$", filename):
+            return True
+
+    return False
+
+
+def get_file_pattern_category(filename: str, config: Dict[str, Any]) -> Optional[Tuple[str, str]]:
+    """Match filename against patterns to determine category.
+
+    Consolidated from pre_tool__document_management.py and session_end__auto_cleanup.py
+
+    Args:
+        filename: Name of the file to categorize
+        config: Configuration dictionary
+
+    Returns:
+        Tuple of (directory_type, category) or None if no match
+    """
+    patterns = config.get("document_management", {}).get("file_patterns", {})
+
+    for dir_type, categories in patterns.items():
+        for category, pattern_list in categories.items():
+            for pattern in pattern_list:
+                # Convert glob pattern to regex
+                regex = pattern.replace("*", ".*").replace("?", ".")
+                if re.match(f"^{regex}$", filename):
+                    return (dir_type, category)
+
+    return None
+
+
+def suggest_moai_location(filename: str, config: Dict[str, Any]) -> str:
+    """Suggest appropriate .moai/ location based on file pattern.
+
+    Consolidated from pre_tool__document_management.py and session_end__auto_cleanup.py
+
+    Args:
+        filename: Name of the file
+        config: Configuration dictionary
+
+    Returns:
+        Suggested .moai/ path
+    """
+    # Try pattern matching first
+    match = get_file_pattern_category(filename, config)
+
+    if match:
+        dir_type, category = match
+        base_dir = config.get("document_management", {}).get("directories", {}).get(dir_type, {}).get("base", "")
+        if base_dir:
+            return f"{base_dir}{category}/"
+
+    # Default fallback suggestions
+    if filename.endswith(".md"):
+        return ".moai/temp/work/"
+    elif filename.endswith((".sh", ".py", ".js")):
+        return ".moai/scripts/dev/"
+    elif filename.endswith((".tmp", ".temp", ".bak")):
+        return ".moai/temp/work/"
+
+    # Ultimate fallback
+    return ".moai/temp/work/"