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

moai_adk/templates/.claude/skills/moai-foundation-claude/reference/claude-code-plugins-official.md

@@ -0,0 +1,432 @@
+# Claude Code Plugins - Official Documentation Reference
+
+Source: https://code.claude.com/docs/en/plugins
+Related: https://code.claude.com/docs/en/plugins-reference
+Related: https://code.claude.com/docs/en/discover-plugins
+Related: https://code.claude.com/docs/en/plugin-marketplaces
+Updated: 2026-01-06
+
+## What are Claude Code Plugins?
+
+Plugins are reusable extensions that bundle Claude Code configurations for distribution across projects. Unlike standalone configurations in `.claude/` directories, plugins can be installed via marketplaces, shared across teams, and version-controlled independently.
+
+## Plugin vs Standalone Configuration
+
+Standalone Configuration (`.claude/` directory):
+- Scope: Single project only
+- Sharing: Manual copy or git submodules
+- Updates: Manual synchronization
+- Best for: Project-specific customizations
+
+Plugin Configuration:
+- Scope: Reusable across multiple projects
+- Sharing: Installable via marketplaces or git URLs
+- Updates: Automatic or manual via plugin manager
+- Best for: Team standards, reusable workflows, community tools
+
+## Plugin Directory Structure
+
+A plugin is a directory with the following structure:
+
+```
+my-plugin/
+- .claude-plugin/
+  - plugin.json (ONLY file in this directory)
+- commands/ (slash commands, markdown files)
+- agents/ (custom sub-agents, markdown files)
+- skills/ (agent skills with SKILL.md)
+- hooks/
+  - hooks.json (hook definitions)
+- .mcp.json (MCP server configurations)
+- .lsp.json (LSP server configurations)
+```
+
+Critical Rule: Only plugin.json belongs in the .claude-plugin/ directory. All other components are at the plugin root level.
+
+## Plugin Manifest (plugin.json)
+
+The plugin manifest defines metadata and component locations.
+
+### Required Fields
+
+- name: Unique identifier in kebab-case format
+
+### Recommended Fields
+
+- description: Shown in plugin manager and marketplaces
+- version: Semantic versioning (MAJOR.MINOR.PATCH)
+- author: Object with name field, optionally email and url
+- homepage: URL to plugin documentation or landing page
+- repository: Git URL for source code
+- license: SPDX license identifier
+
+### Optional Path Overrides
+
+- commands: Path to commands directory (default: commands/)
+- agents: Path to agents directory (default: agents/)
+- skills: Path to skills directory (default: skills/)
+- hooks: Path to hooks configuration
+- mcpServers: Path to MCP server configuration
+- lspServers: Path to LSP server configuration
+- outputStyles: Path to output styles directory
+
+### Discovery Keywords
+
+- keywords: Array of discovery tags for finding plugins in marketplaces
+
+Example:
+```json
+{
+  "keywords": ["deployment", "ci-cd", "automation", "devops"]
+}
+```
+
+Keywords help users discover plugins through search. Use relevant, descriptive terms that reflect the plugin's functionality and domain.
+
+### Example Plugin Manifest
+
+```json
+{
+  "name": "my-team-plugin",
+  "description": "Team development standards and workflows",
+  "version": "1.0.0",
+  "author": {
+    "name": "Development Team"
+  },
+  "homepage": "https://github.com/org/my-team-plugin",
+  "repository": "https://github.com/org/my-team-plugin.git",
+  "license": "MIT",
+  "keywords": ["team-standards", "workflow", "development"]
+}
+```
+
+## Plugin Components
+
+### Commands
+
+Slash commands are markdown files in the commands/ directory:
+
+```
+commands/
+- review.md (becomes /my-plugin:review)
+- deploy/
+  - staging.md (becomes /my-plugin:deploy/staging)
+  - production.md (becomes /my-plugin:deploy/production)
+```
+
+Plugin commands use the namespace prefix pattern: /plugin-name:command-name
+
+### Agents
+
+Custom sub-agents with markdown definitions:
+
+```
+agents/
+- code-reviewer.md
+- security-analyst.md
+```
+
+Each agent file follows the standard sub-agent format with YAML frontmatter.
+
+### Skills
+
+Agent skills following the standard SKILL.md structure:
+
+```
+skills/
+- my-skill/
+  - SKILL.md
+  - reference.md
+  - examples.md
+```
+
+### Hooks
+
+Hook definitions in hooks/hooks.json:
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Use ${CLAUDE_PLUGIN_ROOT} for absolute paths within the plugin.
+
+### MCP Servers
+
+MCP server configurations in .mcp.json:
+
+```json
+{
+  "mcpServers": {
+    "my-server": {
+      "command": "${CLAUDE_PLUGIN_ROOT}/mcp-server/run.sh",
+      "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"]
+    }
+  }
+}
+```
+
+### LSP Servers
+
+Language server configurations in .lsp.json for code intelligence features.
+
+## Installation Scopes
+
+Plugins can be installed at different scopes:
+
+### User Scope (default)
+
+- Location: ~/.claude/plugins/
+- Availability: All projects for current user
+- Use case: Personal productivity tools
+
+### Project Scope
+
+- Location: .claude/settings.json (reference only, not copied)
+- Availability: Current project only
+- Version controlled: Yes, shareable via git
+- Use case: Project-specific requirements
+
+### Local Scope
+
+- Location: Interactive selection via /plugin command
+- Availability: Current session only
+- Version controlled: No
+- Use case: Testing and evaluation
+
+### Managed Scope
+
+- Location: Enterprise configuration
+- Availability: Enforced across organization
+- Use case: Compliance and security requirements
+
+## Official Anthropic Marketplace
+
+Anthropic maintains an official plugin marketplace with curated, verified plugins.
+
+Marketplace Name: claude-plugins-official
+
+Availability: Automatically available in Claude Code without additional configuration.
+
+Installation Syntax:
+/plugin install plugin-name@claude-plugins-official
+
+The official marketplace contains plugins that have been reviewed for quality and security. For a complete catalog of available plugins, see the discover-plugins reference documentation.
+
+## Interactive Plugin Manager
+
+Access the interactive plugin manager using the /plugin command.
+
+The plugin manager provides four navigation tabs:
+
+- Discover: Browse and search available plugins from configured marketplaces
+- Installed: View and manage currently installed plugins
+- Marketplaces: Configure and manage plugin marketplace sources
+- Errors: View and troubleshoot plugin-related errors
+
+Navigation Controls:
+- Tab key: Cycle forward through tabs
+- Shift+Tab: Cycle backward through tabs
+- Arrow keys: Navigate within tab content
+- Enter: Select or confirm action
+
+## Plugin Management Commands
+
+### Installation
+
+Install from marketplace:
+/plugin install plugin-name
+
+Install from official Anthropic marketplace:
+/plugin install plugin-name@claude-plugins-official
+
+Install from GitHub:
+/plugin install owner/repo
+
+Install from git URL:
+/plugin install https://github.com/owner/repo.git
+
+Install with scope:
+/plugin install plugin-name --scope project
+
+### Other Commands
+
+Uninstall: /plugin uninstall plugin-name
+Enable: /plugin enable plugin-name
+Disable: /plugin disable plugin-name
+Update: /plugin update plugin-name
+Update all: /plugin update
+List installed: /plugin list
+Validate: /plugin validate . (in plugin directory)
+
+## Reserved Names
+
+The following name patterns are reserved and cannot be used:
+
+- claude-code-*
+- anthropic-*
+- official-*
+
+## Environment Variables in Plugins
+
+Use these variables for path resolution:
+
+- ${CLAUDE_PLUGIN_ROOT}: Absolute path to plugin installation directory
+
+Example usage:
+```json
+{
+  "command": "${CLAUDE_PLUGIN_ROOT}/scripts/my-script.sh"
+}
+```
+
+## Plugin Caching Behavior
+
+When a plugin is installed:
+
+1. Plugin files are copied to the cache directory
+2. Symlinks within the plugin are honored
+3. Path traversal (../) does not work post-installation
+4. Updates require re-installation or /plugin update command
+
+## Creating a Plugin
+
+### Step 1: Create Directory Structure
+
+Create the plugin directory with required structure:
+
+```
+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 Manifest
+
+Create .claude-plugin/plugin.json with required metadata.
+
+### Step 3: Add Components
+
+Add commands, agents, skills, hooks, or server configurations as needed.
+
+### Step 4: Validate
+
+Run validation in the plugin directory:
+/plugin validate .
+
+Or via CLI:
+claude plugin validate .
+
+### Step 5: Test Locally
+
+Install from local path for testing:
+/plugin install /path/to/my-plugin
+
+### Step 6: Distribute
+
+Push to git repository and share via:
+- GitHub repository URL
+- Custom marketplace
+- Direct git URL
+
+## Plugin Distribution
+
+### Via GitHub
+
+1. Create a GitHub repository for the plugin
+2. Ensure .claude-plugin/plugin.json exists at root
+3. Share the repository URL: owner/repo
+
+### Via Custom Marketplace
+
+1. Create marketplace.json in .claude-plugin/ directory
+2. List plugins with relative paths or git URLs
+3. Add marketplace to team settings
+
+### Via Direct Git URL
+
+Share the full git URL including protocol:
+- HTTPS: https://github.com/owner/repo.git
+- SSH: git@github.com:owner/repo.git
+
+## Best Practices
+
+### Naming
+
+- Use descriptive, unique names
+- Follow kebab-case convention
+- Avoid reserved prefixes
+
+### Versioning
+
+- Use semantic versioning
+- Update version on each release
+- Document changes in CHANGELOG
+
+### Documentation
+
+- Include comprehensive README
+- Document all commands and their purposes
+- Provide usage examples
+
+### Security
+
+- Review all scripts before distribution
+- Avoid hardcoded credentials
+- Use environment variables for sensitive data
+- Document required permissions
+
+### Testing
+
+- Test on fresh installations
+- Verify all components load correctly
+- Test across different operating systems
+- Validate plugin structure before publishing
+
+## Troubleshooting
+
+### Plugin Not Loading
+
+Check plugin.json is valid JSON
+Verify plugin is enabled: /plugin list
+Check for naming conflicts
+
+### Commands Not Appearing
+
+Verify commands/ directory exists
+Check markdown files have correct format
+Ensure plugin is enabled
+
+### Hooks Not Executing
+
+Verify hooks.json syntax
+Check script permissions
+Use ${CLAUDE_PLUGIN_ROOT} for absolute paths
+
+### MCP Servers Not Connecting
+
+Verify .mcp.json syntax
+Check server command exists
+Review server logs for errors
+
+## Related Reference Files
+
+For comprehensive plugin ecosystem documentation, see:
+
+- claude-code-discover-plugins-official.md - Plugin discovery and installation guide
+- claude-code-plugin-marketplaces-official.md - Creating and hosting custom marketplaces

moai_adk/templates/.claude/skills/moai-foundation-claude/reference/claude-code-sandboxing-official.md

@@ -0,0 +1,282 @@
+# Claude Code Sandboxing - Official Documentation Reference
+
+Source: https://code.claude.com/docs/en/sandboxing
+Updated: 2026-01-06
+
+## Overview
+
+Claude Code provides OS-level sandboxing to restrict file system and network access during code execution. This creates a security boundary that limits potential damage from malicious or buggy code.
+
+## Sandbox Implementation
+
+### Operating System Support
+
+Linux: Uses bubblewrap (bwrap) for namespace-based isolation
+macOS: Uses Seatbelt (sandbox-exec) for profile-based restrictions
+
+### Default Behavior
+
+When sandboxing is enabled:
+
+- File writes are restricted to the current working directory
+- Network access is limited to allowed domains
+- System resources are protected from modification
+
+## Filesystem Isolation
+
+### Default Write Restrictions
+
+By default, sandboxed commands can only write to:
+- Current working directory
+- Subdirectories of current working directory
+
+Reads are generally unrestricted within user-accessible paths.
+
+### Configuring Allowed Paths
+
+Additional write paths can be configured in settings.json:
+
+```json
+{
+  "sandbox": {
+    "allowedPaths": [
+      "/tmp/build-output",
+      "~/project-cache"
+    ],
+    "deniedPaths": [
+      "~/.ssh",
+      "~/.aws"
+    ]
+  }
+}
+```
+
+## Network Isolation
+
+### Domain-Based Restrictions
+
+Network access is filtered by domain. Configure allowed domains:
+
+```json
+{
+  "sandbox": {
+    "allowedDomains": [
+      "api.example.com",
+      "registry.npmjs.org"
+    ],
+    "deniedDomains": [
+      "*.internal.corp"
+    ]
+  }
+}
+```
+
+### Default Allowed Domains
+
+Common development services are typically allowed:
+- npm registry (registry.npmjs.org)
+- GitHub (github.com, api.github.com)
+- Claude API (api.anthropic.com)
+- DNS services
+
+### Port Configuration
+
+Configure network port access:
+
+```json
+{
+  "sandbox": {
+    "allowedPorts": [80, 443, 8080],
+    "deniedPorts": [22, 3306]
+  }
+}
+```
+
+## Auto-Allow Mode
+
+When sandbox is enabled, bash commands that operate within sandbox restrictions can run without permission prompts.
+
+### How Auto-Allow Works
+
+If a command only:
+- Reads from allowed paths
+- Writes to allowed paths
+- Accesses allowed network domains
+
+Then it executes automatically without user confirmation.
+
+### Commands Excluded from Sandbox
+
+Some commands bypass sandbox restrictions:
+
+```json
+{
+  "sandbox": {
+    "excludedCommands": [
+      "docker",
+      "kubectl"
+    ]
+  }
+}
+```
+
+Excluded commands require explicit user permission.
+
+## Security Limitations
+
+### Domain-Only Filtering
+
+Network filtering operates at the domain level only:
+- Cannot inspect traffic content
+- Cannot filter by URL path
+- Cannot decrypt HTTPS traffic
+
+### Unix Socket Access
+
+Unix sockets can grant system access:
+- Docker socket provides host system access
+- Some sockets bypass network restrictions
+- Configure socket permissions carefully
+
+### Permission Implications
+
+Certain permissions grant broader access:
+- Docker socket access equals root-equivalent access
+- Some build tools require expanded permissions
+- Evaluate security tradeoffs carefully
+
+## Configuration Examples
+
+### Restrictive Configuration
+
+For maximum security:
+
+```json
+{
+  "sandbox": {
+    "enabled": true,
+    "allowedPaths": [],
+    "allowedDomains": [],
+    "excludedCommands": []
+  }
+}
+```
+
+### Development Configuration
+
+For typical development workflows:
+
+```json
+{
+  "sandbox": {
+    "enabled": true,
+    "allowedPaths": [
+      "/tmp",
+      "~/.npm",
+      "~/.cache"
+    ],
+    "allowedDomains": [
+      "registry.npmjs.org",
+      "github.com",
+      "api.github.com"
+    ]
+  }
+}
+```
+
+### CI/CD Configuration
+
+For automated pipelines:
+
+```json
+{
+  "sandbox": {
+    "enabled": true,
+    "allowedPaths": [
+      "/workspace",
+      "/build-cache"
+    ],
+    "allowedDomains": [
+      "registry.npmjs.org",
+      "docker.io"
+    ],
+    "excludedCommands": [
+      "docker"
+    ]
+  }
+}
+```
+
+## Monitoring Sandbox Violations
+
+### Identifying Blocked Operations
+
+When sandbox blocks an operation:
+1. Permission dialog appears (if not in auto-allow mode)
+2. Operation is logged
+3. User can choose to allow or deny
+
+### Reviewing Sandbox Logs
+
+Check sandbox violation patterns:
+- Repeated blocks may indicate configuration gaps
+- Unexpected blocks may indicate security issues
+- Review and adjust configuration as needed
+
+## Best Practices
+
+### Start Restrictive
+
+Begin with minimal permissions:
+1. Enable sandbox with default restrictions
+2. Monitor for violations
+3. Add specific allowances as needed
+
+### Document Exceptions
+
+When adding exclusions:
+- Document why each exception is needed
+- Review exceptions periodically
+- Remove unnecessary exceptions
+
+### Combine with IAM
+
+Use sandbox as one layer of defense:
+- Sandbox provides OS-level isolation
+- IAM provides Claude-level permissions
+- Together they create defense-in-depth
+
+### Test Configuration
+
+Before deploying:
+- Test common workflows with sandbox enabled
+- Verify necessary operations succeed
+- Confirm sensitive operations are blocked
+
+## Troubleshooting
+
+### Command Fails in Sandbox
+
+If a legitimate command is blocked:
+1. Check if command needs excluded commands list
+2. Verify path is in allowed paths
+3. Check domain is in allowed domains
+
+### Network Request Blocked
+
+If network request fails:
+1. Verify domain spelling
+2. Check for subdomain requirements
+3. Review port restrictions
+
+### Performance Impact
+
+Sandbox adds minimal overhead:
+- Namespace creation is fast
+- File checks are cached
+- Network filtering is lightweight
+
+If experiencing slowdowns, check:
+- Large allowed paths lists
+- Complex domain patterns
+- Excessive sandbox violations