moai-adk 0.4.5__py3-none-any.whl → 0.4.8__py3-none-any.whl

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

@@ -4,8 +4,8 @@
 Common type definitions and utility functions
 """
 
-from dataclasses import asdict, dataclass, field
-from typing import Any, NotRequired, TypedDict
+from dataclasses import dataclass, field
+from typing import Any, Literal, NotRequired, TypedDict
 
 
 class HookPayload(TypedDict):
@@ -16,63 +16,145 @@ class HookPayload(TypedDict):
     """
 
     cwd: str
-    userPrompt: NotRequired[str] # Includes only UserPromptSubmit events
+    userPrompt: NotRequired[str]  # Includes only UserPromptSubmit events
     tool: NotRequired[str]  # PreToolUse/PostToolUse events
     arguments: NotRequired[dict[str, Any]]  # Tool arguments
 
 
 @dataclass
 class HookResult:
-    """Hook execution result"""
+    """Hook execution result following Claude Code standard schema.
+
+    Attributes conform to Claude Code Hook output specification:
+    https://docs.claude.com/en/docs/claude-code/hooks
+
+    Standard Fields (Claude Code schema):
+        continue_execution: Allow execution to continue (default True)
+        suppress_output: Suppress hook output display (default False)
+        decision: "approve" or "block" operation (optional)
+        reason: Explanation for decision (optional)
+        permission_decision: "allow", "deny", or "ask" (optional)
+
+    MoAI-ADK Fields (wrapped in hookSpecificOutput):
+        system_message: Message displayed to user
+        context_files: List of context files to load
+        suggestions: Suggestions for user
+        exit_code: Exit code (for diagnostics)
+    """
+
+    # Claude Code standard fields
+    continue_execution: bool = True
+    suppress_output: bool = False
+    decision: Literal["approve", "block"] | None = None
+    reason: str | None = None
+    permission_decision: Literal["allow", "deny", "ask"] | None = None
 
-    message: 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)  # noqa: N815
+    # MoAI-ADK custom fields (wrapped in hookSpecificOutput)
+    system_message: str | None = None
+    context_files: list[str] = field(default_factory=list)
     suggestions: list[str] = field(default_factory=list)
-    exitCode: int = 0  # noqa: N815
+    exit_code: int = 0
 
     def to_dict(self) -> dict[str, Any]:
-        """Dictionary conversion for general Hook"""
-        return asdict(self)
+        """Convert to Claude Code standard Hook output schema.
+
+        Returns:
+            Dictionary conforming to Claude Code Hook specification with:
+            - Top-level fields: continue, suppressOutput, decision, reason, permissionDecision
+            - Nested field: hookSpecificOutput containing MoAI-ADK-specific data
+
+        Examples:
+            >>> result = HookResult(continue_execution=True)
+            >>> result.to_dict()
+            {'continue': True}
+
+            >>> result = HookResult(decision="block", reason="Dangerous")
+            >>> result.to_dict()
+            {'decision': 'block', 'reason': 'Dangerous'}
+
+            >>> result = HookResult(system_message="Test", context_files=["a.txt"])
+            >>> result.to_dict()
+            {'continue': True, 'hookSpecificOutput': {'systemMessage': 'Test', 'contextFiles': ['a.txt']}}
+        """
+        output: dict[str, Any] = {}
+
+        # Add decision or continue flag
+        if self.decision:
+            output["decision"] = self.decision
+            if self.reason:
+                output["reason"] = self.reason
+        else:
+            output["continue"] = self.continue_execution
+
+        # Add suppressOutput if True
+        if self.suppress_output:
+            output["suppressOutput"] = True
+
+        # Add permissionDecision if set
+        if self.permission_decision:
+            output["permissionDecision"] = self.permission_decision
+
+        # Wrap MoAI-ADK custom fields in hookSpecificOutput
+        hook_output: dict[str, Any] = {}
+
+        if self.system_message:
+            hook_output["systemMessage"] = self.system_message
+
+        if self.context_files:
+            hook_output["contextFiles"] = self.context_files
+
+        if self.suggestions:
+            hook_output["suggestions"] = self.suggestions
+
+        if self.exit_code != 0:
+            hook_output["exitCode"] = self.exit_code
+
+        # Only add hookSpecificOutput if there's custom data
+        if hook_output:
+            output["hookSpecificOutput"] = hook_output
+
+        return output
 
     def to_user_prompt_submit_dict(self) -> dict[str, Any]:
-        """UserPromptSubmit Hook-specific output format
+        """UserPromptSubmit Hook-specific output format.
 
-        Claude Code requires a special schema for UserPromptSubmit:
-        {
-            "hookEventName": "UserPromptSubmit",
-            "additionalContext": "string (required)"
-        }
+        Claude Code requires a special schema for UserPromptSubmit events.
+        The result is wrapped in the standard Hook schema with hookSpecificOutput.
 
         Returns:
-            Claude Code UserPromptSubmit Hook Dictionary matching schema
+            Claude Code UserPromptSubmit Hook Dictionary matching schema:
+            {
+                "continue": true,
+                "hookSpecificOutput": {
+                    "hookEventName": "UserPromptSubmit",
+                    "additionalContext": "string"
+                }
+            }
 
         Examples:
-            >>> result = HookResult(contextFiles=["tests/"])
+            >>> result = HookResult(context_files=["tests/"])
             >>> result.to_user_prompt_submit_dict()
-            {'hookEventName': 'UserPromptSubmit', 'additionalContext': '📎 Context: tests/'}
+            {'continue': True, 'hookSpecificOutput': {'hookEventName': 'UserPromptSubmit', 'additionalContext': '📎 Context: tests/'}}
         """
-        # Convert contextFiles to additionalContext string
-        if self.contextFiles:
-            context_str = "\n".join([f"📎 Context: {f}" for f in self.contextFiles])
+        # Convert context_files to additionalContext string
+        if self.context_files:
+            context_str = "\n".join([f"📎 Context: {f}" for f in self.context_files])
         else:
             context_str = ""
 
-        # Add message if there is one
-        if self.message:
+        # Add system_message if there is one
+        if self.system_message:
             if context_str:
-                context_str = f"{self.message}\n\n{context_str}"
+                context_str = f"{self.system_message}\n\n{context_str}"
             else:
-                context_str = self.message
-
-        # If the string is empty, use default
-        if not context_str:
-            context_str = ""
+                context_str = self.system_message
 
         return {
-            "hookEventName": "UserPromptSubmit",
-            "additionalContext": context_str
+            "continue": self.continue_execution,
+            "hookSpecificOutput": {
+                "hookEventName": "UserPromptSubmit",
+                "additionalContext": context_str
+            }
         }
 
 

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

@@ -19,7 +19,7 @@ def handle_session_start(payload: HookPayload) -> HookResult:
         payload: Claude Code event payload (cwd key required)
 
     Returns:
-        HookResult(message=project status summary message, systemMessage=for user display)
+        HookResult(system_message=project status summary message)
 
     Message Format:
         🚀 MoAI-ADK Session Started
@@ -31,14 +31,15 @@ def handle_session_start(payload: HookPayload) -> HookResult:
 
     Note:
         - Claude Code processes SessionStart in several stages (clear → compact)
-        - Display message only at “compact” stage to prevent duplicate output
-        - "clear" step returns empty result (invisible to user)
+        - Display message only at "compact" stage to prevent duplicate output
+        - "clear" step returns minimal result (empty hookSpecificOutput)
 
     TDD History:
         - RED: Session startup message format test
         - GREEN: Generate status message by combining helper functions
         - REFACTOR: Improved message format, improved readability, added checkpoint list
         - FIX: Prevent duplicate output of clear step (only compact step is displayed)
+        - UPDATE: Migrated to Claude Code standard Hook schema
 
     @TAG:CHECKPOINT-EVENT-001
     """
@@ -46,7 +47,8 @@ def handle_session_start(payload: HookPayload) -> HookResult:
     # Ignore the "clear" stage and output messages only at the "compact" stage
     event_phase = payload.get("phase", "")
     if event_phase == "clear":
-        return HookResult() # returns an empty result (prevents duplicate output)
+        # Return minimal valid Hook result for clear phase
+        return HookResult(continue_execution=True)
 
     cwd = payload.get("cwd", ".")
     language = detect_language(cwd)
@@ -59,7 +61,7 @@ def handle_session_start(payload: HookPayload) -> HookResult:
     changes = git_info.get("changes", 0)
     spec_progress = f"{specs['completed']}/{specs['total']}"
 
-    # systemMessage: displayed directly to the user
+    # system_message: displayed directly to the user
     lines = [
         "🚀 MoAI-ADK Session Started",
         f"   Language: {language}",
@@ -78,10 +80,7 @@ def handle_session_start(payload: HookPayload) -> HookResult:
 
     system_message = "\n".join(lines)
 
-    return HookResult(
-        message=system_message, # for Claude context
-        systemMessage=system_message, # For user display
-    )
+    return HookResult(system_message=system_message)
 
 
 def handle_session_end(payload: HookPayload) -> HookResult:

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

@@ -20,8 +20,8 @@ def handle_pre_tool_use(payload: HookPayload) -> HookResult:
 
     Returns:
         HookResult(
-            message=checkpoint creation notification (when danger is detected);
-            blocked=False (always continue operation)
+            system_message=checkpoint creation notification (when danger is detected);
+            continue_execution=True (always continue operation)
         )
 
     Checkpoint Triggers:
@@ -34,7 +34,7 @@ def handle_pre_tool_use(payload: HookPayload) -> HookResult:
         → "🛡️ Checkpoint created: before-delete-20251015-143000"
 
     Notes:
-        - Return blocked=False even after detection of danger (continue operation)
+        - Return continue_execution=True even after detection of danger (continue operation)
         - Work continues even when checkpoint fails (ignores)
         - Transparent background operation
 
@@ -52,14 +52,14 @@ def handle_pre_tool_use(payload: HookPayload) -> HookResult:
         checkpoint_branch = create_checkpoint(cwd, operation_type)
 
         if checkpoint_branch != "checkpoint-failed":
-            message = (
+            system_message = (
                 f"🛡️ Checkpoint created: {checkpoint_branch}\n"
                 f"   Operation: {operation_type}"
             )
 
-            return HookResult(message=message, blocked=False)
+            return HookResult(system_message=system_message, continue_execution=True)
 
-    return HookResult(blocked=False)
+    return HookResult(continue_execution=True)
 
 
 def handle_post_tool_use(payload: HookPayload) -> HookResult:

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

@@ -20,22 +20,23 @@ def handle_user_prompt_submit(payload: HookPayload) -> HookResult:
 
     Returns:
         HookResult(
-            message=Number of Files loaded (or None),
-            contextFiles=Recommended document path list
+            system_message=Number of Files loaded (or None),
+            context_files=Recommended document path list
         )
 
     TDD History:
         - RED: JIT document loading scenario testing
         - 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
     """
     user_prompt = payload.get("userPrompt", "")
     cwd = payload.get("cwd", ".")
     context_files = get_jit_context(user_prompt, cwd)
 
-    message = f"📎 Loaded {len(context_files)} context file(s)" if context_files else None
+    system_message = f"📎 Loaded {len(context_files)} context file(s)" if context_files else None
 
-    return HookResult(message=message, contextFiles=context_files)
+    return HookResult(system_message=system_message, context_files=context_files)
 
 
 __all__ = ["handle_user_prompt_submit"]

moai_adk/templates/.claude/output-styles/alfred/agentic-coding.md

@@ -4,7 +4,7 @@ description: Agent-based coding mode that integrates hands-on development and co
 ---
 
 # Agentic Coding
-> Interactive prompts rely on `Skill("moai-alfred-tui-survey")` so AskUserQuestion renders TUI selection menus for user surveys and approvals.
+> Interactive prompts rely on `Skill("moai-alfred-interactive-questions")` so AskUserQuestion renders TUI selection menus for user surveys and approvals.
 
 **Audience**: Professional developers, team leaders, architects
 

moai_adk/templates/.claude/output-styles/alfred/moai-adk-learning.md

@@ -4,7 +4,7 @@ description: Learning mode to easily learn MoAI-ADK concepts and workflow
 ---
 
 # MoAI ADK Learning
-> Interactive prompts rely on `Skill("moai-alfred-tui-survey")` so AskUserQuestion renders TUI selection menus for user surveys and approvals.
+> Interactive prompts rely on `Skill("moai-alfred-interactive-questions")` so AskUserQuestion renders TUI selection menus for user surveys and approvals.
 
 **Audience**: Developers new to MoAI-ADK
 

moai_adk/templates/.claude/output-styles/alfred/study-with-alfred.md

@@ -4,7 +4,7 @@ description: Learning mode to easily learn new skills with Alfred
 ---
 
 # Study with Alfred
-> Interactive prompts rely on `Skill("moai-alfred-tui-survey")` so AskUserQuestion renders TUI selection menus for user surveys and approvals.
+> Interactive prompts rely on `Skill("moai-alfred-interactive-questions")` so AskUserQuestion renders TUI selection menus for user surveys and approvals.
 
 **Audience**: Developers looking to learn new technologies/languages/frameworks
 

moai_adk/templates/.claude/settings.json

@@ -6,18 +6,58 @@
     "PYTHON_ENV": "{{PROJECT_MODE}}"
   },
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/alfred_hooks.py SessionStart",
+            "type": "command"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "hooks": [
           {
-            "command": "uv run .claude/hooks/alfred/alfred_hooks.py PreToolUse",
+            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/alfred_hooks.py PreToolUse",
             "type": "command"
           }
         ],
         "matcher": "Edit|Write|MultiEdit"
       }
     ],
-    "PostToolUse": []
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/alfred_hooks.py UserPromptSubmit",
+            "type": "command"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/alfred_hooks.py SessionEnd",
+            "type": "command"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "hooks": [
+          {
+            "command": "uv run \"$CLAUDE_PROJECT_DIR\"/.claude/hooks/alfred/alfred_hooks.py PostToolUse",
+            "type": "command"
+          }
+        ],
+        "matcher": "Edit|Write|MultiEdit"
+      }
+    ]
   },
   "permissions": {
     "defaultMode": "default",

moai_adk/templates/.claude/skills/moai-alfred-ears-authoring/SKILL.md

@@ -1,103 +1,113 @@
 ---
-
 name: moai-alfred-ears-authoring
-description: EARS (Easy Approach to Requirements Syntax) authoring guide with 5 statement patterns for clear, testable requirements. Use when generating EARS-style requirement sentences.
+version: 2.0.0
+created: 2025-10-22
+updated: 2025-10-22
+status: active
+description: EARS (Easy Approach to Requirements Syntax) authoring with 5 statement patterns for clear requirements.
+keywords: ['ears', 'requirements', 'specs', 'authoring']
 allowed-tools:
   - Read
-  - Write
-  - Edit
   - Bash
-  - TodoWrite
 ---
 
-# Alfred EARS Authoring Guide
+# Alfred Ears Authoring Skill
 
 ## Skill Metadata
+
 | Field | Value |
 | ----- | ----- |
-| Allowed tools | Read (read_file), Write (write_file), Edit (edit_file), Bash (terminal), TodoWrite (todo_write) |
-| Auto-load | /alfred:1-plan requirements phase |
-| Trigger cues | Plan board EARS drafting, requirement interviews, structured SPEC authoring. |
+| **Skill Name** | moai-alfred-ears-authoring |
+| **Version** | 2.0.0 (2025-10-22) |
+| **Allowed tools** | Read (read_file), Bash (terminal) |
+| **Auto-load** | On demand when keywords detected |
+| **Tier** | Alfred |
 
-## What it does
+---
 
-EARS (Easy Approach to Requirements Syntax) authoring guide for writing clear, testable requirements using 5 statement patterns.
+## What It Does
 
-## When to use
+EARS (Easy Approach to Requirements Syntax) authoring with 5 statement patterns for clear requirements.
 
-- Activates when Alfred is asked to capture requirements using the EARS patterns.
-- “Writing SPEC”, “Requirements summary”, “EARS syntax”
-- Automatically invoked by `/alfred:1-plan`
-- When writing or refining SPEC documents
+**Key capabilities**:
+- ✅ Best practices enforcement for alfred domain
+- ✅ TRUST 5 principles integration
+- ✅ Latest tool versions (2025-10-22)
+- ✅ TDD workflow support
 
-## How it works
+---
 
-EARS provides 5 statement patterns for structured requirements:
+## When to Use
 
-### 1. Ubiquitous (Basic Requirements)
-**Format**: The system must provide [function]
-**Example**: The system must provide user authentication function
+**Automatic triggers**:
+- Related code discussions and file patterns
+- SPEC implementation (`/alfred:2-run`)
+- Code review requests
 
-### 2. Event-driven (event-based)
-**Format**: WHEN If [condition], the system must [operate]
-**Example**: WHEN When the user logs in, the system must issue a JWT token
+**Manual invocation**:
+- Review code for TRUST 5 compliance
+- Design new features
+- Troubleshoot issues
 
-### 3. State-driven
-**Format**: WHILE When in [state], the system must [operate]
-**Example**: WHILE When the user is authenticated, the system must allow access to protected resources
+---
 
-### 4. Optional (Optional function)
-**Format**: If WHERE [condition], the system can [operate]
-**Example**: If WHERE refresh token is provided, the system can issue a new access token
+## Inputs
 
-### 5. Constraints
-**Format**: IF [condition], the system SHOULD [constrain]
-**Example**: IF an invalid token is provided, the system SHOULD deny access
+- Language-specific source directories
+- Configuration files
+- Test suites and sample data
 
-## Writing Tips
+## Outputs
 
-✅ Be specific and measurable
-✅ Avoid vague terms (“adequate”, “sufficient”, “fast”)
-✅ One requirement per statement
-✅ Make it testable
+- Test/lint execution plan
+- TRUST 5 review checkpoints
+- Migration guidance
 
-## Best Practices
-- The text shown to the user is written using TUI/report expressions.
-- When running the tool, a summary of commands and results are recorded.
+## Failure Modes
 
-## Examples
-```markdown
-- Call this skill inside the /alfred command to generate a report.
-- Add summary to Completion Report.
-```
+- When required tools are not installed
+- When dependencies are missing
+- When test coverage falls below 85%
 
-## Inputs
-- MoAI-ADK project context (`.moai/project/`, `.claude/` templates, etc.).
-- Parameters passed from user commands or higher commands.
+## Dependencies
 
-## Outputs
-- Reports, checklists or recommendations for your Alfred workflow.
-- Structured data for subsequent subagent calls.
+- Access to project files via Read/Bash tools
+- Integration with `moai-foundation-langs` for language detection
+- Integration with `moai-foundation-trust` for quality gates
 
-## Failure Modes
-- When required input documents are missing or permissions are limited.
-- When disruptive changes are required without user approval.
+---
 
-## Dependencies
-- Cooperation with higher-level agents such as cc-manager and project-manager is required.
+## References (Latest Documentation)
 
-## References
-- Mavin, A., et al. "Easy Approach to Requirements Syntax (EARS)." IEEE RE, 2009.
-- INCOSE. "Guide for Writing Requirements." INCOSE-TP-2010-006-02 (accessed 2025-03-29).
+_Documentation links updated 2025-10-22_
+
+---
 
 ## Changelog
-- 2025-03-29: Added input/output/failure response to Alfred-specific skills.
 
-## Works well with
+- **v2.0.0** (2025-10-22): Major update with latest tool versions, comprehensive best practices, TRUST 5 integration
+- **v1.0.0** (2025-03-29): Initial Skill release
 
-- alfred-spec-metadata-validation
-- alfred-trust-validation
+---
 
-## Reference
+## Works Well With
+
+- `moai-foundation-trust` (quality gates)
+- `moai-alfred-code-reviewer` (code review)
+- `moai-essentials-debug` (debugging support)
+
+---
+
+## Best Practices
 
-`.moai/memory/development-guide.md#ears-requirements-how-to`
+✅ **DO**:
+- Follow alfred best practices
+- Use latest stable tool versions
+- Maintain test coverage ≥85%
+- Document all public APIs
+
+❌ **DON'T**:
+- Skip quality gates
+- Use deprecated tools
+- Ignore security warnings
+- Mix testing frameworks

moai_adk/templates/.claude/skills/moai-alfred-ears-authoring/examples.md

@@ -0,0 +1,29 @@
+# moai-alfred-ears-authoring - Working Examples
+
+_Last updated: 2025-10-22_
+
+## Example 1: Basic Setup
+
+```bash
+# Setup commands
+# ...
+```
+
+## Example 2: TDD Workflow
+
+```bash
+# RED: Write failing test
+# GREEN: Implement feature
+# REFACTOR: Improve code
+```
+
+## Example 3: Quality Gate
+
+```bash
+# Run quality checks
+# Verify coverage ≥85%
+```
+
+---
+
+_For more examples, see SKILL.md reference section_

moai_adk/templates/.claude/skills/moai-alfred-ears-authoring/reference.md

@@ -0,0 +1,28 @@
+# moai-alfred-ears-authoring - CLI Reference
+
+_Last updated: 2025-10-22_
+
+## Quick Reference
+
+### Installation
+
+```bash
+# Installation commands
+```
+
+### Common Commands
+
+```bash
+# Test
+# Lint
+# Format
+# Build
+```
+
+## Tool Versions (2025-10-22)
+
+_No specific tool versions (workflow/process Skill)_
+
+---
+
+_For detailed usage, see SKILL.md_