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

moai_adk/templates/.claude/skills/moai-cc-commands/SKILL.md

@@ -0,0 +1,287 @@
+---
+name: "Designing Slash Commands for Claude Code"
+description: "Create and optimize slash commands with proper argument parsing, tool permissions, and agent orchestration. Use when building workflow entry points, automation commands, or user-facing shortcuts."
+allowed-tools: "Read, Write, Edit, Glob, Bash"
+---
+
+# Designing Slash Commands
+
+Slash commands are user-facing entry points that orchestrate sub-agents, manage approvals, and coordinate multi-step workflows. They follow the Plan → Execute → Sync cadence.
+
+## Command File Structure
+
+**Location**: `.claude/commands/`
+
+```yaml
+---
+name: command-name
+description: Brief description of what the command does
+argument-hint: "[param1] [param2] [optional-param]"
+tools: Read, Write, Task, Bash(git:*)
+model: sonnet
+---
+
+# Command Title
+
+Brief description of functionality.
+
+## Usage
+
+- `/command-name param1 param2` — Basic usage
+- Parameter descriptions
+- Expected behavior
+
+## Agent Orchestration
+
+1. Call specific agent for task
+2. Handle results
+3. Provide user feedback
+```
+
+## Command Design Patterns
+
+### Pattern 1: Planning Command
+```yaml
+---
+name: /alfred:1-plan
+description: Write SPEC requirements in EARS syntax
+argument-hint: "[title]"
+tools: Read, Write, Task
+model: sonnet
+---
+
+# SPEC Planning Command
+
+Initiates SPEC authoring via spec-builder sub-agent.
+
+## Usage
+
+`/alfred:1-plan "User authentication system"`
+
+## Agent Orchestration
+
+1. Invoke spec-builder agent
+2. Gather requirements via EARS patterns
+3. Create SPEC file in `.moai/specs/`
+4. Suggest next step: `/alfred:2-run`
+```
+
+### Pattern 2: Code Review Command
+```yaml
+---
+name: /review-code
+description: Trigger automated code review with quality analysis
+argument-hint: "[file-pattern] [--strict]"
+tools: Read, Glob, Grep, Task
+model: sonnet
+---
+
+# Code Review Command
+
+Analyzes code quality against TRUST 5 principles.
+
+## Usage
+
+- `/review-code src/**/*.ts` — Review TypeScript files
+- `/review-code . --strict` — Strict mode (fail on warnings)
+
+## Agent Orchestration
+
+1. Scan files matching pattern
+2. Invoke code-reviewer agent
+3. Generate report with findings
+4. Suggest fixes with severity levels
+```
+
+### Pattern 3: Deployment Command
+```yaml
+---
+name: /deploy
+description: Deploy application with safety gates
+argument-hint: "[env] [--force]"
+tools: Read, Write, Task, Bash(git:*)
+model: haiku
+---
+
+# Deployment Command
+
+Orchestrates multi-step deployment with approval gates.
+
+## Usage
+
+- `/deploy staging` — Deploy to staging
+- `/deploy production --force` — Force production deploy
+
+## Agent Orchestration
+
+1. Validate deployment readiness
+2. Run pre-deployment checks
+3. Ask for user approval
+4. Execute deployment
+5. Monitor post-deployment
+```
+
+## Argument Parsing Pattern
+
+```bash
+# Inside command execution
+$ARGUMENTS              # Entire argument string
+$1, $2, $3            # Individual arguments
+$@                    # All arguments as array
+
+# Example: /my-command arg1 arg2 --flag
+# $ARGUMENTS = "arg1 arg2 --flag"
+# $1 = "arg1"
+# $2 = "arg2"
+# $3 = "--flag"
+```
+
+## High-Freedom: Orchestration Strategies
+
+### Sequential Execution
+```
+Command: /plan-and-implement
+├─ Phase 1: spec-builder (SPEC creation)
+└─ Phase 2: code-builder (TDD implementation)
+```
+
+### Parallel Execution
+```
+Command: /analyze-project
+├─ Agent 1: security-auditor (vulnerability scan)
+├─ Agent 2: performance-analyzer (bottleneck detection)
+└─ Agent 3: architecture-reviewer (design review)
+```
+
+### Conditional Branching
+```
+Command: /fix-errors
+├─ Check: Are tests failing?
+│  ├─ YES → debug-helper agent
+│  └─ NO → suggest next steps
+```
+
+## Medium-Freedom: Command Templates
+
+### Status Check Command
+```yaml
+name: /status
+description: Show project status summary
+argument-hint: "[--verbose]"
+tools: Read, Bash(git:*)
+model: haiku
+---
+
+# Status Check
+
+Displays project health: SPEC status, test results, Git state.
+
+## Checks
+
+1. SPEC completeness
+2. Test coverage
+3. Git branch status
+4. Recent commits
+5. TODO items
+```
+
+### Bulk Operation Command
+```yaml
+name: /migrate
+description: Run migration across multiple files
+argument-hint: "[from] [to] [--preview]"
+tools: Read, Glob, Bash
+model: sonnet
+---
+
+# Migration Command
+
+Migrates code patterns across project.
+
+## Usage
+
+- `/migrate v1-api v2-api --preview` — Show changes without applying
+- `/migrate v1-api v2-api` — Apply migration
+```
+
+## Low-Freedom: Safety & Approval Patterns
+
+### Approval Gate Pattern
+```bash
+# Inside command execution
+
+echo "🔴 This action is destructive. Review carefully:"
+echo "  • Will delete 10 files"
+echo "  • Cannot be undone"
+echo ""
+read -p "Type 'yes' to confirm: " confirm
+
+if [[ "$confirm" != "yes" ]]; then
+  echo "❌ Cancelled"
+  exit 1
+fi
+
+# Execute dangerous operation
+```
+
+### Dry-Run Pattern
+```bash
+if [[ "${3:-}" == "--preview" ]]; then
+  echo "🔍 Preview mode (no changes)"
+  # Show what would happen
+  exit 0
+fi
+
+# Execute actual changes
+```
+
+## Command Registry
+
+```bash
+# List all commands
+/commands
+
+# View command details
+/commands view /deploy
+
+# Create new command
+/commands create
+
+# Edit command
+/commands edit /deploy
+
+# Delete command
+/commands delete /deploy
+```
+
+## Command Validation Checklist
+
+- [ ] `name` is kebab-case (e.g., `/review-code`)
+- [ ] `description` clearly explains purpose
+- [ ] `argument-hint` shows expected parameters
+- [ ] `tools` list is minimal and justified
+- [ ] `model` is `haiku` or `sonnet`
+- [ ] Agent orchestration is clearly defined
+- [ ] Arguments are properly parsed
+- [ ] Safety gates are in place for dangerous operations
+- [ ] Feedback to user is clear and actionable
+
+## Best Practices
+
+✅ **DO**:
+- Design commands around workflows, not tools
+- Use agents for complex logic
+- Include preview/dry-run modes for risky operations
+- Provide clear feedback at each step
+- Link to next command in suggestions
+
+❌ **DON'T**:
+- Make commands do too much (limit to 1 coherent workflow)
+- Require multiple parameters without defaults
+- Skip approval gates for destructive operations
+- Leave users guessing what happened
+
+---
+
+**Reference**: Claude Code Slash Commands documentation
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-cc-commands/templates/command-template.md

@@ -0,0 +1,21 @@
+---
+name: command-name
+description: Brief description of what the command does
+argument-hint: "[param1] [param2]"
+tools: Read, Write, Task
+model: sonnet
+---
+
+# Command Title
+
+Brief description of functionality.
+
+## Usage
+
+`/command-name param1 param2` — Basic usage
+
+## Agent Orchestration
+
+1. Call specific agent for task
+2. Handle results
+3. Provide user feedback

moai_adk/templates/.claude/skills/moai-cc-hooks/SKILL.md

@@ -0,0 +1,232 @@
+---
+name: "Configuring Claude Code Hooks System"
+description: "Design, implement, and manage PreToolUse/PostToolUse/SessionStart/Notification/Stop hooks. Use when enforcing safety checks, auto-formatting, running linters, or triggering automated workflows based on development events."
+allowed-tools: "Read, Write, Edit, Glob, Bash"
+---
+
+# Configuring Claude Code Hooks System
+
+Hooks are lightweight (<100ms) automated scripts triggered by Claude Code lifecycle events. They enforce guardrails, run quality checks, and seed context without blocking user workflow.
+
+## Hook Types & Events
+
+| Hook Type | Trigger Event | Execution Time | Use Cases |
+|-----------|---------------|-----------------|-----------|
+| **PreToolUse** | Before tool execution (Read, Edit, Bash, etc.) | <100ms | Command validation, permission checks, safety gates |
+| **PostToolUse** | After tool execution succeeds | <100ms | Auto-formatting, linting, permission restoration |
+| **SessionStart** | Session initialization | <500ms | Project summary, context seeding, status card |
+| **Notification** | User notification event | N/A | macOS notifications, alerts, wait status |
+| **Stop** | Session termination | N/A | Cleanup, final checks, task summary |
+
+## Hook Configuration in settings.json
+
+### High-Freedom Approach: Events-Driven Hooks
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/pre-bash-validator.js"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/pre-edit-guard.sh"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ~/.claude/hooks/post-edit-lint.sh"
+          }
+        ]
+      }
+    ],
+    "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node ~/.claude/hooks/session-status-card.js"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Medium-Freedom: Hook Patterns
+
+### Pattern 1: Pre-Command Validation
+```bash
+#!/bin/bash
+# pre-bash-validator.sh: Block dangerous patterns
+
+FORBIDDEN_PATTERNS=(
+  "rm -rf /"
+  "sudo rm"
+  "chmod 777 /"
+  "eval \$(curl"
+)
+
+COMMAND="$1"
+for pattern in "${FORBIDDEN_PATTERNS[@]}"; do
+  if [[ "$COMMAND" =~ $pattern ]]; then
+    echo "🔴 Blocked: $pattern detected" >&2
+    exit 2  # Block execution
+  fi
+done
+
+exit 0  # Allow execution
+```
+
+### Pattern 2: Post-Edit Auto-Formatting
+```bash
+#!/bin/bash
+# post-edit-format.sh: Auto-format after edits
+
+FILE="$1"
+EXT="${FILE##*.}"
+
+case "$EXT" in
+  js|ts)
+    npx prettier --write "$FILE" 2>/dev/null
+    ;;
+  py)
+    python3 -m black "$FILE" 2>/dev/null
+    ;;
+  go)
+    gofmt -w "$FILE" 2>/dev/null
+    ;;
+esac
+
+exit 0
+```
+
+### Pattern 3: SessionStart Status Card
+```bash
+#!/bin/bash
+# session-status-card.sh: Show project status
+
+echo "🚀 Claude Code Session Started"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+if [ -f ".moai/config.json" ]; then
+  PROJECT=$(jq -r '.name' .moai/config.json 2>/dev/null || echo "Unknown")
+  echo "📦 Project: $PROJECT"
+  echo "🏗️  Framework: $(jq -r '.tech_stack' .moai/config.json 2>/dev/null || echo "Auto-detect")"
+fi
+
+echo "📋 Recent SPECS:"
+ls .moai/specs/ 2>/dev/null | head -3 | sed 's/^/  ✓ /'
+
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+```
+
+## Low-Freedom: Security-Focused Hook Scripts
+
+### Permission Preservation Hook
+```bash
+#!/bin/bash
+set -euo pipefail
+# preserve-permissions.sh: Save/restore file permissions
+
+HOOK_TYPE="${1:-pre}"  # 'pre' or 'post'
+FILE="${2:-.}"
+
+PERMS_FILE="/tmp/perms_${FILE//\//_}.txt"
+
+if [[ "$HOOK_TYPE" == "pre" ]]; then
+  stat -c "%a %u:%g" "$FILE" > "$PERMS_FILE" 2>/dev/null || true
+  exit 0
+elif [[ "$HOOK_TYPE" == "post" ]]; then
+  if [[ -f "$PERMS_FILE" ]]; then
+    SAVED_PERMS=$(cat "$PERMS_FILE")
+    chmod ${SAVED_PERMS%% *} "$FILE" 2>/dev/null || true
+    rm "$PERMS_FILE"
+  fi
+  exit 0
+fi
+```
+
+### Dangerous Command Blocker
+```python
+#!/usr/bin/env python3
+import json
+import sys
+import re
+
+BLOCKED_PATTERNS = [
+    (r"rm\s+-rf\s+/", "Blocking rm -rf /"),
+    (r"sudo\s+rm", "Blocking sudo rm without confirmation"),
+    (r">\s*/etc/\w+", "Blocking writes to system files"),
+    (r"curl.*\|\s*bash", "Blocking curl | bash (code injection risk)"),
+]
+
+try:
+    data = json.load(sys.stdin)
+    command = data.get("tool_input", {}).get("command", "")
+
+    for pattern, msg in BLOCKED_PATTERNS:
+        if re.search(pattern, command):
+            print(f"🔴 BLOCKED: {msg}", file=sys.stderr)
+            sys.exit(2)  # Block
+
+    sys.exit(0)  # Allow
+except Exception as e:
+    print(f"Hook error: {e}", file=sys.stderr)
+    sys.exit(0)  # Allow on error (fail open)
+```
+
+## Hook Exit Codes
+
+| Code | Meaning | Behavior |
+|------|---------|----------|
+| `0` | Success | Tool proceeds normally |
+| `1` | Warning + Stderr | Warning logged, tool proceeds |
+| `2` | Blocked + Error | Tool execution blocked |
+
+## Best Practices
+
+✅ **DO**:
+- Keep hook scripts < 100ms execution time
+- Use specific matchers (not wildcard `*` unless necessary)
+- Log errors clearly to stderr
+- Test hooks before deploying to team
+
+❌ **DON'T**:
+- Make network calls in PreToolUse hooks
+- Block common operations (use warnings instead)
+- Write to user files from hooks
+- Create complex logic (delegate to sub-agents)
+
+## Hook Validation Checklist
+
+- [ ] All scripts have proper shebang (`#!/bin/bash` or `#!/usr/bin/env python3`)
+- [ ] Scripts are executable: `chmod +x hook.sh`
+- [ ] Exit codes are correct (0, 1, or 2)
+- [ ] Paths are absolute (not relative)
+- [ ] Tested for < 100ms latency
+- [ ] Error messages are user-friendly
+- [ ] No hardcoded secrets or credentials
+
+---
+
+**Reference**: Context7 Claude Code Hooks documentation
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-cc-hooks/scripts/pre-bash-check.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# Pre-Bash Command Validator (from Context7 official docs)
+set -euo pipefail
+
+FORBIDDEN=(
+  "rm -rf /"
+  "sudo rm"
+  "chmod 777"
+  "eval.*curl"
+)
+
+COMMAND="${1:-}"
+for pattern in "${FORBIDDEN[@]}"; do
+  if [[ "$COMMAND" =~ $pattern ]]; then
+    echo "🔴 BLOCKED: $pattern" >&2
+    exit 2
+  fi
+done
+exit 0

moai_adk/templates/.claude/skills/moai-cc-hooks/scripts/preserve-permissions.sh

@@ -0,0 +1,19 @@
+#!/bin/bash
+# Preserve file permissions (from Context7 official docs)
+set -euo pipefail
+
+HOOK_TYPE="${1:-pre}"
+FILE="${2:-.}"
+PERMS_FILE="/tmp/perms_${FILE//\//_}.txt"
+
+if [[ "$HOOK_TYPE" == "pre" ]]; then
+  stat -c "%a %u:%g" "$FILE" > "$PERMS_FILE" 2>/dev/null || true
+  exit 0
+elif [[ "$HOOK_TYPE" == "post" ]]; then
+  if [[ -f "$PERMS_FILE" ]]; then
+    SAVED=$(cat "$PERMS_FILE")
+    chmod ${SAVED%% *} "$FILE" 2>/dev/null || true
+    rm "$PERMS_FILE"
+  fi
+  exit 0
+fi

moai_adk/templates/.claude/skills/moai-cc-hooks/scripts/validate-bash-command.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+# Bash command validator (from Context7 official docs)
+import json
+import re
+import sys
+
+BLOCKED = [
+    (r"rm\s+-rf\s+/", "Blocking rm -rf /"),
+    (r"sudo\s+rm", "Blocking sudo rm"),
+    (r">\s*/etc/\w+", "Blocking writes to /etc"),
+    (r"curl.*\|\s*bash", "Blocking curl | bash"),
+]
+
+try:
+    data = json.load(sys.stdin)
+    cmd = data.get("tool_input", {}).get("command", "")
+    
+    for pattern, msg in BLOCKED:
+        if re.search(pattern, cmd):
+            print(f"🔴 {msg}", file=sys.stderr)
+            sys.exit(2)
+    sys.exit(0)
+except:
+    sys.exit(0)