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

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)

moai_adk/templates/.claude/skills/moai-cc-mcp-plugins/SKILL.md

@@ -0,0 +1,179 @@
+---
+name: "Configuring MCP Servers & Plugins for Claude Code"
+description: "Set up Model Context Protocol servers (GitHub, Filesystem, Brave Search, SQLite). Configure OAuth, manage permissions, validate MCP structure. Use when integrating external tools, APIs, or expanding Claude Code capabilities."
+allowed-tools: "Read, Write, Edit, Bash, Glob"
+---
+
+# Configuring MCP Servers & Plugins
+
+MCP servers extend Claude Code with external tool integrations. Each server provides tools that Claude can invoke directly.
+
+## MCP Server Setup in settings.json
+
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-server-github"],
+      "oauth": {
+        "clientId": "your-client-id",
+        "clientSecret": "your-client-secret",
+        "scopes": ["repo", "issues", "pull_requests"]
+      }
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/allowed/files"]
+    },
+    "sqlite": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/database.db"]
+    },
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": {
+        "BRAVE_SEARCH_API_KEY": "${BRAVE_SEARCH_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+## Common MCP Servers
+
+| Server | Purpose | Installation | Config |
+|--------|---------|--------------|--------|
+| **GitHub** | PR/issue management, code search | `@anthropic-ai/mcp-server-github` | OAuth required |
+| **Filesystem** | Safe file access with path restrictions | `@modelcontextprotocol/server-filesystem` | Path whitelist required |
+| **SQLite** | Database queries & migrations | `@modelcontextprotocol/server-sqlite` | DB file path |
+| **Brave Search** | Web search integration | `@modelcontextprotocol/server-brave-search` | API key required |
+
+## OAuth Configuration Pattern
+
+```json
+{
+  "oauth": {
+    "clientId": "your-client-id",
+    "clientSecret": "your-client-secret",
+    "scopes": ["repo", "issues"]
+  }
+}
+```
+
+**Scope Minimization** (principle of least privilege):
+- GitHub: `repo` (code access), `issues` (PR/issue access)
+- NOT `admin`, NOT `delete_repo`
+
+## Filesystem MCP: Path Whitelisting
+
+```json
+{
+  "filesystem": {
+    "command": "npx",
+    "args": [
+      "-y",
+      "@modelcontextprotocol/server-filesystem",
+      "${CLAUDE_PROJECT_DIR}/.moai",
+      "${CLAUDE_PROJECT_DIR}/src",
+      "${CLAUDE_PROJECT_DIR}/tests"
+    ]
+  }
+}
+```
+
+**Security Principle**: Explicitly list allowed directories, no wildcards.
+
+## Plugin Marketplace Integration
+
+```json
+{
+  "extraKnownMarketplaces": [
+    {
+      "name": "company-plugins",
+      "url": "https://github.com/your-org/claude-plugins"
+    },
+    {
+      "name": "community-plugins",
+      "url": "https://glama.ai/mcp/servers"
+    }
+  ]
+}
+```
+
+## MCP Health Check
+
+```bash
+# Inside Claude Code terminal
+/mcp                    # List active MCP servers
+/plugin validate        # Validate plugin structure
+/plugin install         # Install from marketplace
+/plugin enable github   # Enable specific server
+/plugin disable github  # Disable specific server
+```
+
+## Environment Variables for MCP
+
+```bash
+# Set in ~/.bash_profile or .claude/config.json
+export GITHUB_TOKEN="gh_xxxx..."
+export BRAVE_SEARCH_API_KEY="xxxx..."
+export ANTHROPIC_API_KEY="sk-ant-..."
+
+# Launch Claude Code with env
+GITHUB_TOKEN=gh_xxxx claude
+```
+
+## MCP Troubleshooting
+
+| Issue | Cause | Fix |
+|-------|-------|-----|
+| Server not connecting | Invalid JSON in mcpServers | Validate with `jq .mcpServers settings.json` |
+| OAuth error | Token expired or invalid scopes | Check `claude /usage`, regenerate token |
+| Permission denied | Path not whitelisted | Add to Filesystem MCP args |
+| Slow response | Network latency or server overload | Check server logs, reduce scope |
+
+## Best Practices
+
+✅ **DO**:
+- Use environment variables for secrets
+- Whitelist Filesystem paths explicitly
+- Start with minimal scopes, expand only if needed
+- Test MCP connection: `/mcp` command
+
+❌ **DON'T**:
+- Hardcode credentials in settings.json
+- Use wildcard paths (`/` in Filesystem MCP)
+- Install untrusted plugins
+- Give admin scopes unnecessarily
+
+## Plugin Custom Directory Structure
+
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   ├── deploy.md
+│   └── rollback.md
+├── agents/
+│   └── reviewer.md
+└── hooks/
+    └── pre-deploy-check.sh
+```
+
+## Validation Checklist
+
+- [ ] All server paths are absolute
+- [ ] OAuth secrets stored in env vars
+- [ ] Filesystem paths are whitelisted
+- [ ] No hardcoded tokens or credentials
+- [ ] MCP server installed: `which npx`
+- [ ] Health check passes: `/mcp`
+- [ ] Scopes follow least-privilege principle
+
+---
+
+**Reference**: Claude Code MCP documentation
+**Version**: 1.0.0

moai_adk/templates/.claude/skills/moai-cc-mcp-plugins/templates/settings-mcp-template.json

@@ -0,0 +1,39 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@anthropic-ai/mcp-server-github"],
+      "oauth": {
+        "clientId": "${GITHUB_CLIENT_ID}",
+        "clientSecret": "${GITHUB_CLIENT_SECRET}",
+        "scopes": ["repo", "issues"]
+      }
+    },
+    "filesystem": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@modelcontextprotocol/server-filesystem",
+        "${CLAUDE_PROJECT_DIR}/.moai",
+        "${CLAUDE_PROJECT_DIR}/src"
+      ]
+    },
+    "sqlite": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-sqlite", "/path/to/db.sqlite"]
+    },
+    "brave-search": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-brave-search"],
+      "env": {
+        "BRAVE_SEARCH_API_KEY": "${BRAVE_SEARCH_API_KEY}"
+      }
+    }
+  },
+  "extraKnownMarketplaces": [
+    {
+      "name": "company-plugins",
+      "url": "https://github.com/your-org/claude-plugins"
+    }
+  ]
+}