moai-adk 0.25.4__py3-none-any.whl → 0.41.0__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-plugin-builder/modules/migration.md

@@ -0,0 +1,341 @@
+# Plugin Migration Guide
+
+## Converting Standalone Configurations to Plugin Format
+
+### Overview
+
+This guide covers migrating existing `.claude/` configurations to distributable plugin format.
+
+### Before Migration
+
+Existing Standalone Structure:
+```
+project/
+  .claude/
+    commands/
+      my-command.md
+    agents/
+      my-agent.md
+    skills/
+      my-skill/
+        SKILL.md
+    settings.json
+    settings.local.json
+```
+
+### After Migration
+
+Plugin Structure:
+```
+my-plugin/
+  .claude-plugin/
+    plugin.json
+  commands/
+    my-command.md
+  agents/
+    my-agent.md
+  skills/
+    my-skill/
+      SKILL.md
+  hooks/
+    hooks.json
+  README.md
+```
+
+### Migration Steps
+
+Step 1: Create Plugin Directory
+
+Create new directory for the plugin at desired location:
+```bash
+mkdir -p my-plugin/.claude-plugin
+mkdir -p my-plugin/commands
+mkdir -p my-plugin/agents
+mkdir -p my-plugin/skills
+mkdir -p my-plugin/hooks
+```
+
+Step 2: Create plugin.json
+
+Create the plugin manifest file:
+```json
+{
+  "name": "my-plugin",
+  "version": "1.0.0",
+  "description": "Migrated plugin from standalone configuration",
+  "commands": ["./commands"],
+  "agents": ["./agents"],
+  "skills": ["./skills"],
+  "hooks": ["./hooks/hooks.json"]
+}
+```
+
+Step 3: Copy Components
+
+Copy existing components to plugin:
+```bash
+# Copy commands
+cp .claude/commands/*.md my-plugin/commands/
+
+# Copy agents
+cp .claude/agents/*.md my-plugin/agents/
+
+# Copy skills
+cp -r .claude/skills/* my-plugin/skills/
+```
+
+Step 4: Extract Hooks from settings.json
+
+If settings.json contains hooks, extract to hooks.json:
+
+Original settings.json hooks:
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "validate-write.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+New hooks/hooks.json:
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/validate-write.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Step 5: Update Path References
+
+Update all hardcoded paths to use environment variables:
+
+Before:
+```bash
+command: "/path/to/project/.claude/scripts/validate.sh"
+```
+
+After:
+```bash
+command: "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
+```
+
+Step 6: Copy Supporting Scripts
+
+Copy any script files referenced by hooks or commands:
+```bash
+mkdir -p my-plugin/scripts
+cp .claude/scripts/*.sh my-plugin/scripts/
+chmod +x my-plugin/scripts/*.sh
+```
+
+Step 7: Create Documentation
+
+Create README.md for the plugin:
+```markdown
+# My Plugin
+
+## Description
+
+Plugin description and purpose.
+
+## Installation
+
+claude plugin install ./my-plugin
+
+## Commands
+
+- /my-plugin:command-name - Command description
+
+## Agents
+
+- my-agent - Agent description
+
+## Skills
+
+- my-skill - Skill description
+
+## Configuration
+
+Required environment variables or configuration.
+```
+
+### Path Reference Updates
+
+Command Files:
+
+Before migration:
+```markdown
+Reference: @.claude/config.yaml
+Script: /project/.claude/scripts/run.sh
+```
+
+After migration:
+```markdown
+Reference: @${CLAUDE_PLUGIN_ROOT}/config.yaml
+Script: ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh
+```
+
+Agent Files:
+
+Before migration:
+```yaml
+---
+skills:
+  - /project/.claude/skills/my-skill
+---
+```
+
+After migration:
+```yaml
+---
+skills:
+  - my-skill
+---
+```
+
+Hook Commands:
+
+Before migration:
+```json
+{
+  "command": "/project/.claude/hooks/validate.sh"
+}
+```
+
+After migration:
+```json
+{
+  "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/validate.sh"
+}
+```
+
+### Preserving Existing Functionality
+
+Environment Variables:
+
+If original scripts used project-specific variables:
+```bash
+# Original
+API_URL="$PROJECT_API_URL"
+
+# Migrated - use plugin-safe defaults
+API_URL="${PROJECT_API_URL:-https://api.example.com}"
+```
+
+File References:
+
+If commands referenced project files:
+```markdown
+# Original
+Load config: @project-config.yaml
+
+# Migrated - use CLAUDE_PROJECT_DIR
+Load config: @${CLAUDE_PROJECT_DIR}/project-config.yaml
+```
+
+### Testing Migration
+
+Validate Plugin Structure:
+```bash
+claude plugin validate ./my-plugin
+```
+
+Test Plugin Loading:
+```bash
+claude --plugin-dir ./my-plugin
+```
+
+Test Commands:
+```bash
+# Inside claude session
+/my-plugin:command-name
+```
+
+Test Agents:
+```bash
+# Inside claude session
+/agents
+# Then invoke agent by name
+```
+
+### Common Migration Issues
+
+Issue: Commands Not Found
+
+Symptom: Plugin loads but commands unavailable
+
+Resolution:
+- Verify commands path in plugin.json: `"commands": ["./commands"]`
+- Confirm .md extension on command files
+- Check YAML frontmatter has description
+
+Issue: Hooks Not Triggering
+
+Symptom: Hook events not executing scripts
+
+Resolution:
+- Use full command with bash: `"bash ${CLAUDE_PLUGIN_ROOT}/hooks/script.sh"`
+- Verify script is executable: `chmod +x script.sh`
+- Check hooks.json syntax
+
+Issue: Skills Not Loading
+
+Symptom: Agent cannot find skills
+
+Resolution:
+- Verify skills path: `"skills": ["./skills"]`
+- Confirm SKILL.md exists in skill directory
+- Check skill name in agent matches directory name
+
+Issue: Path Resolution Failures
+
+Symptom: File not found errors
+
+Resolution:
+- Replace hardcoded paths with `${CLAUDE_PLUGIN_ROOT}`
+- Verify referenced files exist in plugin
+- Use absolute paths in hook commands
+
+### Rollback Plan
+
+Keep original configuration until migration verified:
+```bash
+# Backup original
+cp -r .claude .claude.backup
+
+# Test plugin
+claude --plugin-dir ./my-plugin
+
+# If issues, restore original
+cp -r .claude.backup .claude
+```
+
+### Post-Migration Cleanup
+
+After successful migration:
+1. Remove migrated files from .claude/ (if not needed)
+2. Update project documentation
+3. Add plugin to version control
+4. Create CHANGELOG.md for plugin
+5. Consider publishing to marketplace

moai_adk/templates/.claude/skills/moai-plugin-builder/modules/validation.md

@@ -0,0 +1,373 @@
+# Plugin Validation Guide
+
+## Validation Commands
+
+### CLI Validation
+
+Basic Validation:
+```bash
+claude plugin validate ./my-plugin
+```
+
+Verbose Validation:
+```bash
+claude plugin validate ./my-plugin --verbose
+```
+
+Strict Mode:
+```bash
+claude plugin validate ./my-plugin --strict
+```
+
+### Validation Output
+
+Success Output:
+```
+Plugin validation passed: my-plugin
+  - plugin.json: valid
+  - commands: 3 found
+  - agents: 2 found
+  - skills: 1 found
+  - hooks: valid
+```
+
+Error Output:
+```
+Plugin validation failed: my-plugin
+  ERROR: plugin.json missing required field 'name'
+  ERROR: commands/invalid.md missing frontmatter
+  WARNING: agent tools reference unknown tool 'CustomTool'
+```
+
+## Validation Rules by Component
+
+### plugin.json Validation
+
+Required Checks:
+- File exists at .claude-plugin/plugin.json
+- Valid JSON syntax
+- Contains "name" field
+- Name is kebab-case format
+
+Name Validation:
+- Lowercase letters, numbers, hyphens only
+- Must start with letter
+- No consecutive hyphens
+- Maximum 64 characters
+
+Optional Field Checks:
+- version: Valid semver (X.Y.Z)
+- author.email: Valid email format
+- author.url: Valid URL
+- homepage: Valid URL
+- repository: Valid URL
+- license: Valid SPDX identifier
+- keywords: Array of strings
+
+Path Reference Checks:
+- All paths start with "./"
+- Referenced paths exist
+- No path traversal (..)
+- Paths are relative to plugin root
+
+### Command Validation
+
+File Requirements:
+- Extension is .md
+- File is readable
+- File is not empty
+
+Frontmatter Validation:
+- YAML frontmatter present (between --- delimiters)
+- Contains description field
+- Description is non-empty string
+
+Content Validation:
+- Body content exists after frontmatter
+- No syntax errors in markdown
+- Argument references are valid ($1, $2, $ARGUMENTS)
+
+### Agent Validation
+
+File Requirements:
+- Extension is .md
+- File is readable
+
+Frontmatter Validation:
+- Contains name field
+- Name is valid identifier
+- Description is present (recommended)
+
+Tool Validation:
+- All listed tools are valid tool names
+- Valid tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, Task, TodoWrite
+
+Model Validation:
+- If specified, must be: sonnet, opus, haiku, inherit
+- Default is inherit
+
+Permission Mode Validation:
+- If specified, must be: default, bypassPermissions, plan, passthrough
+- Default is default
+
+Skill References:
+- Referenced skills exist in plugin or project
+- Skill names are valid identifiers
+
+### Skill Validation
+
+Directory Requirements:
+- Skill directory exists
+- SKILL.md file present in directory
+
+Frontmatter Validation:
+- Contains name field
+- Contains description field
+- allowed-tools contains valid tool names
+
+Content Validation:
+- File is under 500 lines
+- Contains Quick Reference section
+- Contains Implementation Guide section
+
+### Hook Validation
+
+File Requirements:
+- hooks.json is valid JSON
+- hooks.json contains "hooks" object
+
+Event Validation:
+- Event names are valid hook events
+- Valid events: PreToolUse, PostToolUse, PermissionRequest, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStop, Notification, PreCompact
+
+Hook Entry Validation:
+- Each entry has valid structure
+- Matcher is string or array
+- hooks array is present
+
+Hook Definition Validation:
+- type is "command" or "prompt"
+- If command: command field is string
+- If prompt: prompt field is string
+
+Command Path Validation:
+- Script paths are valid
+- Referenced scripts exist
+- Scripts are executable
+
+### MCP Server Validation
+
+File Requirements:
+- .mcp.json is valid JSON
+- Contains mcpServers object
+
+Server Entry Validation:
+- Each server has unique name
+- Contains command field
+- Command is string
+
+Args Validation:
+- If present, is array
+- All elements are strings
+
+Env Validation:
+- If present, is object
+- All values are strings
+- Environment variables properly formatted
+
+Transport Validation:
+- If type specified, is: stdio, http, sse
+- If http/sse: url field required
+- URL is valid format
+
+### LSP Server Validation
+
+File Requirements:
+- .lsp.json is valid JSON
+- Contains lspServers object
+
+Server Entry Validation:
+- Each server has unique name
+- Contains command field
+- Contains extensionToLanguage mapping
+
+Extension Mapping Validation:
+- Keys start with "."
+- Values are non-empty strings
+- At least one mapping present
+
+## Common Validation Errors
+
+### plugin.json Errors
+
+Error: Invalid plugin name
+```
+ERROR: Plugin name 'My_Plugin' is invalid
+  - Must be kebab-case
+  - Use lowercase letters, numbers, hyphens
+  Fix: Rename to 'my-plugin'
+```
+
+Error: Missing name field
+```
+ERROR: plugin.json missing required field 'name'
+  Fix: Add "name": "plugin-name" to plugin.json
+```
+
+Error: Invalid version format
+```
+ERROR: Version '1.0' is not valid semver
+  Fix: Use format X.Y.Z (e.g., "1.0.0")
+```
+
+Error: Path does not exist
+```
+ERROR: Path './commands' does not exist
+  Fix: Create commands directory or remove from plugin.json
+```
+
+### Command Errors
+
+Error: Missing frontmatter
+```
+ERROR: commands/test.md missing YAML frontmatter
+  Fix: Add frontmatter with description:
+  ---
+  description: Command description
+  ---
+```
+
+Error: Missing description
+```
+ERROR: commands/test.md frontmatter missing 'description'
+  Fix: Add description field to frontmatter
+```
+
+### Agent Errors
+
+Error: Invalid tool reference
+```
+ERROR: agents/helper.md references invalid tool 'Execute'
+  Valid tools: Read, Write, Edit, Grep, Glob, Bash, WebFetch, WebSearch, Task, TodoWrite
+  Fix: Use valid tool name
+```
+
+Error: Invalid model
+```
+ERROR: agents/helper.md has invalid model 'gpt4'
+  Valid models: sonnet, opus, haiku, inherit
+  Fix: Use valid model name
+```
+
+### Hook Errors
+
+Error: Invalid event name
+```
+ERROR: hooks.json contains invalid event 'BeforeWrite'
+  Valid events: PreToolUse, PostToolUse, PermissionRequest, UserPromptSubmit, SessionStart, SessionEnd, Stop, SubagentStop, Notification, PreCompact
+  Fix: Use valid event name
+```
+
+Error: Invalid hook type
+```
+ERROR: Hook type 'script' is invalid
+  Valid types: command, prompt
+  Fix: Use 'command' or 'prompt'
+```
+
+Error: Script not found
+```
+ERROR: Hook script './hooks/validate.sh' not found
+  Fix: Create script or update path
+```
+
+### MCP Server Errors
+
+Error: Missing command
+```
+ERROR: MCP server 'my-server' missing 'command' field
+  Fix: Add command field with executable path
+```
+
+Error: Invalid args type
+```
+ERROR: MCP server 'my-server' args must be array
+  Fix: Change args to array format: ["arg1", "arg2"]
+```
+
+### LSP Server Errors
+
+Error: Missing extensionToLanguage
+```
+ERROR: LSP server 'python' missing 'extensionToLanguage'
+  Fix: Add extension mapping: {".py": "python"}
+```
+
+Error: Invalid extension format
+```
+ERROR: Extension 'py' should start with '.'
+  Fix: Change to '.py'
+```
+
+## Validation Best Practices
+
+Pre-Submission Checklist:
+1. Run `claude plugin validate` before distribution
+2. Test plugin locally with `--plugin-dir`
+3. Verify all paths resolve correctly
+4. Test all commands work as expected
+5. Confirm hooks trigger on events
+6. Validate MCP/LSP servers connect
+
+Automated Validation:
+
+Add to CI/CD pipeline:
+```yaml
+# GitHub Actions example
+- name: Validate Plugin
+  run: claude plugin validate ./my-plugin --strict
+```
+
+Version Control Hooks:
+
+Add pre-commit validation:
+```bash
+#!/bin/bash
+# .git/hooks/pre-commit
+claude plugin validate . --strict
+if [ $? -ne 0 ]; then
+  echo "Plugin validation failed"
+  exit 1
+fi
+```
+
+## Validation Levels
+
+Level 1 - Syntax:
+- JSON/YAML validity
+- Required fields present
+- Basic type checking
+
+Level 2 - Semantic:
+- Path references exist
+- Tool names valid
+- Event names valid
+- Model names valid
+
+Level 3 - Functional:
+- Scripts executable
+- Commands invocable
+- Servers connectable
+- Hooks triggerable
+
+Running Different Levels:
+
+Syntax only:
+```bash
+claude plugin validate ./my-plugin --level syntax
+```
+
+Full validation:
+```bash
+claude plugin validate ./my-plugin --level full
+```