import live www.sillylaird.ca webrootHEADmain

7 files changed, 3139 insertions, 0 deletions

diff --git a/.agents/skills/plugin-structure/README.md b/.agents/skills/plugin-structure/README.md
new file mode 100644
index 0000000..3076046
--- /dev/null
+++ b/.agents/skills/plugin-structure/README.md
@@ -0,0 +1,109 @@
+# Plugin Structure Skill
+
+Comprehensive guidance on Claude Code plugin architecture, directory layout, and best practices.
+
+## Overview
+
+This skill provides detailed knowledge about:
+- Plugin directory structure and organization
+- `plugin.json` manifest configuration
+- Component organization (commands, agents, skills, hooks)
+- Auto-discovery mechanisms
+- Portable path references with `${CLAUDE_PLUGIN_ROOT}`
+- File naming conventions
+
+## Skill Structure
+
+### SKILL.md (1,619 words)
+
+Core skill content covering:
+- Directory structure overview
+- Plugin manifest (plugin.json) fields
+- Component organization patterns
+- ${CLAUDE_PLUGIN_ROOT} usage
+- File naming conventions
+- Auto-discovery mechanism
+- Best practices
+- Common patterns
+- Troubleshooting
+
+### References
+
+Detailed documentation for deep dives:
+
+- **manifest-reference.md**: Complete `plugin.json` field reference
+  - All field descriptions and examples
+  - Path resolution rules
+  - Validation guidelines
+  - Minimal vs. complete manifest examples
+
+- **component-patterns.md**: Advanced organization patterns
+  - Component lifecycle (discovery, activation)
+  - Command organization patterns
+  - Agent organization patterns
+  - Skill organization patterns
+  - Hook organization patterns
+  - Script organization patterns
+  - Cross-component patterns
+  - Best practices for scalability
+
+### Examples
+
+Three complete plugin examples:
+
+- **minimal-plugin.md**: Simplest possible plugin
+  - Single command
+  - Minimal manifest
+  - When to use this pattern
+
+- **standard-plugin.md**: Well-structured production plugin
+  - Multiple components (commands, agents, skills, hooks)
+  - Complete manifest with metadata
+  - Rich skill structure
+  - Integration between components
+
+- **advanced-plugin.md**: Enterprise-grade plugin
+  - Multi-level organization
+  - MCP server integration
+  - Shared libraries
+  - Configuration management
+  - Security automation
+  - Monitoring integration
+
+## When This Skill Triggers
+
+Claude Code activates this skill when users:
+- Ask to "create a plugin" or "scaffold a plugin"
+- Need to "understand plugin structure"
+- Want to "organize plugin components"
+- Need to "set up plugin.json"
+- Ask about "${CLAUDE_PLUGIN_ROOT}" usage
+- Want to "add commands/agents/skills/hooks"
+- Need "configure auto-discovery" help
+- Ask about plugin architecture or best practices
+
+## Progressive Disclosure
+
+The skill uses progressive disclosure to manage context:
+
+1. **SKILL.md** (~1600 words): Core concepts and workflows
+2. **References** (~6000 words): Detailed field references and patterns
+3. **Examples** (~8000 words): Complete working examples
+
+Claude loads references and examples only as needed based on the task.
+
+## Related Skills
+
+This skill works well with:
+- **hook-development**: For creating plugin hooks
+- **mcp-integration**: For integrating MCP servers (when available)
+- **marketplace-publishing**: For publishing plugins (when available)
+
+## Maintenance
+
+To update this skill:
+1. Keep SKILL.md lean and focused on core concepts
+2. Move detailed information to references/
+3. Add new examples/ for common patterns
+4. Update version in SKILL.md frontmatter
+5. Ensure all documentation uses imperative/infinitive form
diff --git a/.agents/skills/plugin-structure/SKILL.md b/.agents/skills/plugin-structure/SKILL.md
new file mode 100644
index 0000000..6bcae94
--- /dev/null
+++ b/.agents/skills/plugin-structure/SKILL.md
@@ -0,0 +1,476 @@
+---
+name: plugin-structure
+description: This skill should be used when the user asks to "create a plugin", "scaffold a plugin", "understand plugin structure", "organize plugin components", "set up plugin.json", "use ${CLAUDE_PLUGIN_ROOT}", "add commands/agents/skills/hooks", "configure auto-discovery", or needs guidance on plugin directory layout, manifest configuration, component organization, file naming conventions, or Claude Code plugin architecture best practices.
+version: 0.1.0
+---
+
+# Plugin Structure for Claude Code
+
+## Overview
+
+Claude Code plugins follow a standardized directory structure with automatic component discovery. Understanding this structure enables creating well-organized, maintainable plugins that integrate seamlessly with Claude Code.
+
+**Key concepts:**
+- Conventional directory layout for automatic discovery
+- Manifest-driven configuration in `.claude-plugin/plugin.json`
+- Component-based organization (commands, agents, skills, hooks)
+- Portable path references using `${CLAUDE_PLUGIN_ROOT}`
+- Explicit vs. auto-discovered component loading
+
+## Directory Structure
+
+Every Claude Code plugin follows this organizational pattern:
+
+```
+plugin-name/
+├── .claude-plugin/
+│   └── plugin.json          # Required: Plugin manifest
+├── commands/                 # Slash commands (.md files)
+├── agents/                   # Subagent definitions (.md files)
+├── skills/                   # Agent skills (subdirectories)
+│   └── skill-name/
+│       └── SKILL.md         # Required for each skill
+├── hooks/
+│   └── hooks.json           # Event handler configuration
+├── .mcp.json                # MCP server definitions
+└── scripts/                 # Helper scripts and utilities
+```
+
+**Critical rules:**
+
+1. **Manifest location**: The `plugin.json` manifest MUST be in `.claude-plugin/` directory
+2. **Component locations**: All component directories (commands, agents, skills, hooks) MUST be at plugin root level, NOT nested inside `.claude-plugin/`
+3. **Optional components**: Only create directories for components the plugin actually uses
+4. **Naming convention**: Use kebab-case for all directory and file names
+
+## Plugin Manifest (plugin.json)
+
+The manifest defines plugin metadata and configuration. Located at `.claude-plugin/plugin.json`:
+
+### Required Fields
+
+```json
+{
+  "name": "plugin-name"
+}
+```
+
+**Name requirements:**
+- Use kebab-case format (lowercase with hyphens)
+- Must be unique across installed plugins
+- No spaces or special characters
+- Example: `code-review-assistant`, `test-runner`, `api-docs`
+
+### Recommended Metadata
+
+```json
+{
+  "name": "plugin-name",
+  "version": "1.0.0",
+  "description": "Brief explanation of plugin purpose",
+  "author": {
+    "name": "Author Name",
+    "email": "author@example.com",
+    "url": "https://example.com"
+  },
+  "homepage": "https://docs.example.com",
+  "repository": "https://github.com/user/plugin-name",
+  "license": "MIT",
+  "keywords": ["testing", "automation", "ci-cd"]
+}
+```
+
+**Version format**: Follow semantic versioning (MAJOR.MINOR.PATCH)
+**Keywords**: Use for plugin discovery and categorization
+
+### Component Path Configuration
+
+Specify custom paths for components (supplements default directories):
+
+```json
+{
+  "name": "plugin-name",
+  "commands": "./custom-commands",
+  "agents": ["./agents", "./specialized-agents"],
+  "hooks": "./config/hooks.json",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+**Important**: Custom paths supplement defaults—they don't replace them. Components in both default directories and custom paths will load.
+
+**Path rules:**
+- Must be relative to plugin root
+- Must start with `./`
+- Cannot use absolute paths
+- Support arrays for multiple locations
+
+## Component Organization
+
+### Commands
+
+**Location**: `commands/` directory
+**Format**: Markdown files with YAML frontmatter
+**Auto-discovery**: All `.md` files in `commands/` load automatically
+
+**Example structure**:
+```
+commands/
+├── review.md        # /review command
+├── test.md          # /test command
+└── deploy.md        # /deploy command
+```
+
+**File format**:
+```markdown
+---
+name: command-name
+description: Command description
+---
+
+Command implementation instructions...
+```
+
+**Usage**: Commands integrate as native slash commands in Claude Code
+
+### Agents
+
+**Location**: `agents/` directory
+**Format**: Markdown files with YAML frontmatter
+**Auto-discovery**: All `.md` files in `agents/` load automatically
+
+**Example structure**:
+```
+agents/
+├── code-reviewer.md
+├── test-generator.md
+└── refactorer.md
+```
+
+**File format**:
+```markdown
+---
+description: Agent role and expertise
+capabilities:
+  - Specific task 1
+  - Specific task 2
+---
+
+Detailed agent instructions and knowledge...
+```
+
+**Usage**: Users can invoke agents manually, or Claude Code selects them automatically based on task context
+
+### Skills
+
+**Location**: `skills/` directory with subdirectories per skill
+**Format**: Each skill in its own directory with `SKILL.md` file
+**Auto-discovery**: All `SKILL.md` files in skill subdirectories load automatically
+
+**Example structure**:
+```
+skills/
+├── api-testing/
+│   ├── SKILL.md
+│   ├── scripts/
+│   │   └── test-runner.py
+│   └── references/
+│       └── api-spec.md
+└── database-migrations/
+    ├── SKILL.md
+    └── examples/
+        └── migration-template.sql
+```
+
+**SKILL.md format**:
+```markdown
+---
+name: Skill Name
+description: When to use this skill
+version: 1.0.0
+---
+
+Skill instructions and guidance...
+```
+
+**Supporting files**: Skills can include scripts, references, examples, or assets in subdirectories
+
+**Usage**: Claude Code autonomously activates skills based on task context matching the description
+
+### Hooks
+
+**Location**: `hooks/hooks.json` or inline in `plugin.json`
+**Format**: JSON configuration defining event handlers
+**Registration**: Hooks register automatically when plugin enables
+
+**Example structure**:
+```
+hooks/
+├── hooks.json           # Hook configuration
+└── scripts/
+    ├── validate.sh      # Hook script
+    └── check-style.sh   # Hook script
+```
+
+**Configuration format**:
+```json
+{
+  "PreToolUse": [{
+    "matcher": "Write|Edit",
+    "hooks": [{
+      "type": "command",
+      "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate.sh",
+      "timeout": 30
+    }]
+  }]
+}
+```
+
+**Available events**: PreToolUse, PostToolUse, Stop, SubagentStop, SessionStart, SessionEnd, UserPromptSubmit, PreCompact, Notification
+
+**Usage**: Hooks execute automatically in response to Claude Code events
+
+### MCP Servers
+
+**Location**: `.mcp.json` at plugin root or inline in `plugin.json`
+**Format**: JSON configuration for MCP server definitions
+**Auto-start**: Servers start automatically when plugin enables
+
+**Example format**:
+```json
+{
+  "mcpServers": {
+    "server-name": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/server.js"],
+      "env": {
+        "API_KEY": "${API_KEY}"
+      }
+    }
+  }
+}
+```
+
+**Usage**: MCP servers integrate seamlessly with Claude Code's tool system
+
+## Portable Path References
+
+### ${CLAUDE_PLUGIN_ROOT}
+
+Use `${CLAUDE_PLUGIN_ROOT}` environment variable for all intra-plugin path references:
+
+```json
+{
+  "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/run.sh"
+}
+```
+
+**Why it matters**: Plugins install in different locations depending on:
+- User installation method (marketplace, local, npm)
+- Operating system conventions
+- User preferences
+
+**Where to use it**:
+- Hook command paths
+- MCP server command arguments
+- Script execution references
+- Resource file paths
+
+**Never use**:
+- Hardcoded absolute paths (`/Users/name/plugins/...`)
+- Relative paths from working directory (`./scripts/...` in commands)
+- Home directory shortcuts (`~/plugins/...`)
+
+### Path Resolution Rules
+
+**In manifest JSON fields** (hooks, MCP servers):
+```json
+"command": "${CLAUDE_PLUGIN_ROOT}/scripts/tool.sh"
+```
+
+**In component files** (commands, agents, skills):
+```markdown
+Reference scripts at: ${CLAUDE_PLUGIN_ROOT}/scripts/helper.py
+```
+
+**In executed scripts**:
+```bash
+#!/bin/bash
+# ${CLAUDE_PLUGIN_ROOT} available as environment variable
+source "${CLAUDE_PLUGIN_ROOT}/lib/common.sh"
+```
+
+## File Naming Conventions
+
+### Component Files
+
+**Commands**: Use kebab-case `.md` files
+- `code-review.md` → `/code-review`
+- `run-tests.md` → `/run-tests`
+- `api-docs.md` → `/api-docs`
+
+**Agents**: Use kebab-case `.md` files describing role
+- `test-generator.md`
+- `code-reviewer.md`
+- `performance-analyzer.md`
+
+**Skills**: Use kebab-case directory names
+- `api-testing/`
+- `database-migrations/`
+- `error-handling/`
+
+### Supporting Files
+
+**Scripts**: Use descriptive kebab-case names with appropriate extensions
+- `validate-input.sh`
+- `generate-report.py`
+- `process-data.js`
+
+**Documentation**: Use kebab-case markdown files
+- `api-reference.md`
+- `migration-guide.md`
+- `best-practices.md`
+
+**Configuration**: Use standard names
+- `hooks.json`
+- `.mcp.json`
+- `plugin.json`
+
+## Auto-Discovery Mechanism
+
+Claude Code automatically discovers and loads components:
+
+1. **Plugin manifest**: Reads `.claude-plugin/plugin.json` when plugin enables
+2. **Commands**: Scans `commands/` directory for `.md` files
+3. **Agents**: Scans `agents/` directory for `.md` files
+4. **Skills**: Scans `skills/` for subdirectories containing `SKILL.md`
+5. **Hooks**: Loads configuration from `hooks/hooks.json` or manifest
+6. **MCP servers**: Loads configuration from `.mcp.json` or manifest
+
+**Discovery timing**:
+- Plugin installation: Components register with Claude Code
+- Plugin enable: Components become available for use
+- No restart required: Changes take effect on next Claude Code session
+
+**Override behavior**: Custom paths in `plugin.json` supplement (not replace) default directories
+
+## Best Practices
+
+### Organization
+
+1. **Logical grouping**: Group related components together
+   - Put test-related commands, agents, and skills together
+   - Create subdirectories in `scripts/` for different purposes
+
+2. **Minimal manifest**: Keep `plugin.json` lean
+   - Only specify custom paths when necessary
+   - Rely on auto-discovery for standard layouts
+   - Use inline configuration only for simple cases
+
+3. **Documentation**: Include README files
+   - Plugin root: Overall purpose and usage
+   - Component directories: Specific guidance
+   - Script directories: Usage and requirements
+
+### Naming
+
+1. **Consistency**: Use consistent naming across components
+   - If command is `test-runner`, name related agent `test-runner-agent`
+   - Match skill directory names to their purpose
+
+2. **Clarity**: Use descriptive names that indicate purpose
+   - Good: `api-integration-testing/`, `code-quality-checker.md`
+   - Avoid: `utils/`, `misc.md`, `temp.sh`
+
+3. **Length**: Balance brevity with clarity
+   - Commands: 2-3 words (`review-pr`, `run-ci`)
+   - Agents: Describe role clearly (`code-reviewer`, `test-generator`)
+   - Skills: Topic-focused (`error-handling`, `api-design`)
+
+### Portability
+
+1. **Always use ${CLAUDE_PLUGIN_ROOT}**: Never hardcode paths
+2. **Test on multiple systems**: Verify on macOS, Linux, Windows
+3. **Document dependencies**: List required tools and versions
+4. **Avoid system-specific features**: Use portable bash/Python constructs
+
+### Maintenance
+
+1. **Version consistently**: Update version in plugin.json for releases
+2. **Deprecate gracefully**: Mark old components clearly before removal
+3. **Document breaking changes**: Note changes affecting existing users
+4. **Test thoroughly**: Verify all components work after changes
+
+## Common Patterns
+
+### Minimal Plugin
+
+Single command with no dependencies:
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json    # Just name field
+└── commands/
+    └── hello.md       # Single command
+```
+
+### Full-Featured Plugin
+
+Complete plugin with all component types:
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/          # User-facing commands
+├── agents/            # Specialized subagents
+├── skills/            # Auto-activating skills
+├── hooks/             # Event handlers
+│   ├── hooks.json
+│   └── scripts/
+├── .mcp.json          # External integrations
+└── scripts/           # Shared utilities
+```
+
+### Skill-Focused Plugin
+
+Plugin providing only skills:
+```
+my-plugin/
+├── .claude-plugin/
+│   └── plugin.json
+└── skills/
+    ├── skill-one/
+    │   └── SKILL.md
+    └── skill-two/
+        └── SKILL.md
+```
+
+## Troubleshooting
+
+**Component not loading**:
+- Verify file is in correct directory with correct extension
+- Check YAML frontmatter syntax (commands, agents, skills)
+- Ensure skill has `SKILL.md` (not `README.md` or other name)
+- Confirm plugin is enabled in Claude Code settings
+
+**Path resolution errors**:
+- Replace all hardcoded paths with `${CLAUDE_PLUGIN_ROOT}`
+- Verify paths are relative and start with `./` in manifest
+- Check that referenced files exist at specified paths
+- Test with `echo $CLAUDE_PLUGIN_ROOT` in hook scripts
+
+**Auto-discovery not working**:
+- Confirm directories are at plugin root (not in `.claude-plugin/`)
+- Check file naming follows conventions (kebab-case, correct extensions)
+- Verify custom paths in manifest are correct
+- Restart Claude Code to reload plugin configuration
+
+**Conflicts between plugins**:
+- Use unique, descriptive component names
+- Namespace commands with plugin name if needed
+- Document potential conflicts in plugin README
+- Consider command prefixes for related functionality
+
+---
+
+For detailed examples and advanced patterns, see files in `references/` and `examples/` directories.
diff --git a/.agents/skills/plugin-structure/examples/advanced-plugin.md b/.agents/skills/plugin-structure/examples/advanced-plugin.md
new file mode 100644
index 0000000..a7c0696
--- /dev/null
+++ b/.agents/skills/plugin-structure/examples/advanced-plugin.md
@@ -0,0 +1,765 @@
+# Advanced Plugin Example
+
+A complex, enterprise-grade plugin with MCP integration and advanced organization.
+
+## Directory Structure
+
+```
+enterprise-devops/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   ├── ci/
+│   │   ├── build.md
+│   │   ├── test.md
+│   │   └── deploy.md
+│   ├── monitoring/
+│   │   ├── status.md
+│   │   └── logs.md
+│   └── admin/
+│       ├── configure.md
+│       └── manage.md
+├── agents/
+│   ├── orchestration/
+│   │   ├── deployment-orchestrator.md
+│   │   └── rollback-manager.md
+│   └── specialized/
+│       ├── kubernetes-expert.md
+│       ├── terraform-expert.md
+│       └── security-auditor.md
+├── skills/
+│   ├── kubernetes-ops/
+│   │   ├── SKILL.md
+│   │   ├── references/
+│   │   │   ├── deployment-patterns.md
+│   │   │   ├── troubleshooting.md
+│   │   │   └── security.md
+│   │   ├── examples/
+│   │   │   ├── basic-deployment.yaml
+│   │   │   ├── stateful-set.yaml
+│   │   │   └── ingress-config.yaml
+│   │   └── scripts/
+│   │       ├── validate-manifest.sh
+│   │       └── health-check.sh
+│   ├── terraform-iac/
+│   │   ├── SKILL.md
+│   │   ├── references/
+│   │   │   └── best-practices.md
+│   │   └── examples/
+│   │       └── module-template/
+│   └── ci-cd-pipelines/
+│       ├── SKILL.md
+│       └── references/
+│           └── pipeline-patterns.md
+├── hooks/
+│   ├── hooks.json
+│   └── scripts/
+│       ├── security/
+│       │   ├── scan-secrets.sh
+│       │   ├── validate-permissions.sh
+│       │   └── audit-changes.sh
+│       ├── quality/
+│       │   ├── check-config.sh
+│       │   └── verify-tests.sh
+│       └── workflow/
+│           ├── notify-team.sh
+│           └── update-status.sh
+├── .mcp.json
+├── servers/
+│   ├── kubernetes-mcp/
+│   │   ├── index.js
+│   │   ├── package.json
+│   │   └── lib/
+│   ├── terraform-mcp/
+│   │   ├── main.py
+│   │   └── requirements.txt
+│   └── github-actions-mcp/
+│       ├── server.js
+│       └── package.json
+├── lib/
+│   ├── core/
+│   │   ├── logger.js
+│   │   ├── config.js
+│   │   └── auth.js
+│   ├── integrations/
+│   │   ├── slack.js
+│   │   ├── pagerduty.js
+│   │   └── datadog.js
+│   └── utils/
+│       ├── retry.js
+│       └── validation.js
+└── config/
+    ├── environments/
+    │   ├── production.json
+    │   ├── staging.json
+    │   └── development.json
+    └── templates/
+        ├── deployment.yaml
+        └── service.yaml
+```
+
+## File Contents
+
+### .claude-plugin/plugin.json
+
+```json
+{
+  "name": "enterprise-devops",
+  "version": "2.3.1",
+  "description": "Comprehensive DevOps automation for enterprise CI/CD pipelines, infrastructure management, and monitoring",
+  "author": {
+    "name": "DevOps Platform Team",
+    "email": "devops-platform@company.com",
+    "url": "https://company.com/teams/devops"
+  },
+  "homepage": "https://docs.company.com/plugins/devops",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/company/devops-plugin.git"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "devops",
+    "ci-cd",
+    "kubernetes",
+    "terraform",
+    "automation",
+    "infrastructure",
+    "deployment",
+    "monitoring"
+  ],
+  "commands": [
+    "./commands/ci",
+    "./commands/monitoring",
+    "./commands/admin"
+  ],
+  "agents": [
+    "./agents/orchestration",
+    "./agents/specialized"
+  ],
+  "hooks": "./hooks/hooks.json",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+### .mcp.json
+
+```json
+{
+  "mcpServers": {
+    "kubernetes": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/kubernetes-mcp/index.js"],
+      "env": {
+        "KUBECONFIG": "${KUBECONFIG}",
+        "K8S_NAMESPACE": "${K8S_NAMESPACE:-default}"
+      }
+    },
+    "terraform": {
+      "command": "python",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/terraform-mcp/main.py"],
+      "env": {
+        "TF_STATE_BUCKET": "${TF_STATE_BUCKET}",
+        "AWS_REGION": "${AWS_REGION}"
+      }
+    },
+    "github-actions": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/github-actions-mcp/server.js"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}",
+        "GITHUB_ORG": "${GITHUB_ORG}"
+      }
+    }
+  }
+}
+```
+
+### commands/ci/build.md
+
+```markdown
+---
+name: build
+description: Trigger and monitor CI build pipeline
+---
+
+# Build Command
+
+Trigger CI/CD build pipeline and monitor progress in real-time.
+
+## Process
+
+1. **Validation**: Check prerequisites
+   - Verify branch status
+   - Check for uncommitted changes
+   - Validate configuration files
+
+2. **Trigger**: Start build via MCP server
+   \`\`\`javascript
+   // Uses github-actions MCP server
+   const build = await tools.github_actions_trigger_workflow({
+     workflow: 'build.yml',
+     ref: currentBranch
+   })
+   \`\`\`
+
+3. **Monitor**: Track build progress
+   - Display real-time logs
+   - Show test results as they complete
+   - Alert on failures
+
+4. **Report**: Summarize results
+   - Build status
+   - Test coverage
+   - Performance metrics
+   - Deploy readiness
+
+## Integration
+
+After successful build:
+- Offer to deploy to staging
+- Suggest performance optimizations
+- Generate deployment checklist
+```
+
+### agents/orchestration/deployment-orchestrator.md
+
+```markdown
+---
+description: Orchestrates complex multi-environment deployments with rollback capabilities and health monitoring
+capabilities:
+  - Plan and execute multi-stage deployments
+  - Coordinate service dependencies
+  - Monitor deployment health
+  - Execute automated rollbacks
+  - Manage deployment approvals
+---
+
+# Deployment Orchestrator Agent
+
+Specialized agent for orchestrating complex deployments across multiple environments.
+
+## Expertise
+
+- **Deployment strategies**: Blue-green, canary, rolling updates
+- **Dependency management**: Service startup ordering, dependency injection
+- **Health monitoring**: Service health checks, metric validation
+- **Rollback automation**: Automatic rollback on failure detection
+- **Approval workflows**: Multi-stage approval processes
+
+## Orchestration Process
+
+1. **Planning Phase**
+   - Analyze deployment requirements
+   - Identify service dependencies
+   - Generate deployment plan
+   - Calculate rollback strategy
+
+2. **Validation Phase**
+   - Verify environment readiness
+   - Check resource availability
+   - Validate configurations
+   - Run pre-deployment tests
+
+3. **Execution Phase**
+   - Deploy services in dependency order
+   - Monitor health after each stage
+   - Validate metrics and logs
+   - Proceed to next stage on success
+
+4. **Verification Phase**
+   - Run smoke tests
+   - Validate service integration
+   - Check performance metrics
+   - Confirm deployment success
+
+5. **Rollback Phase** (if needed)
+   - Detect failure conditions
+   - Execute rollback plan
+   - Restore previous state
+   - Notify stakeholders
+
+## MCP Integration
+
+Uses multiple MCP servers:
+- `kubernetes`: Deploy and manage containers
+- `terraform`: Provision infrastructure
+- `github-actions`: Trigger deployment pipelines
+
+## Monitoring Integration
+
+Integrates with monitoring tools via lib:
+\`\`\`javascript
+const { DatadogClient } = require('${CLAUDE_PLUGIN_ROOT}/lib/integrations/datadog')
+const metrics = await DatadogClient.getMetrics(service, timeRange)
+\`\`\`
+
+## Notification Integration
+
+Sends updates via Slack and PagerDuty:
+\`\`\`javascript
+const { SlackClient } = require('${CLAUDE_PLUGIN_ROOT}/lib/integrations/slack')
+await SlackClient.notify({
+  channel: '#deployments',
+  message: 'Deployment started',
+  metadata: deploymentPlan
+})
+\`\`\`
+```
+
+### skills/kubernetes-ops/SKILL.md
+
+```markdown
+---
+name: Kubernetes Operations
+description: This skill should be used when deploying to Kubernetes, managing K8s resources, troubleshooting cluster issues, configuring ingress/services, scaling deployments, or working with Kubernetes manifests. Provides comprehensive Kubernetes operational knowledge and best practices.
+version: 2.0.0
+---
+
+# Kubernetes Operations
+
+Comprehensive operational knowledge for managing Kubernetes clusters and workloads.
+
+## Overview
+
+Manage Kubernetes infrastructure effectively through:
+- Deployment strategies and patterns
+- Resource configuration and optimization
+- Troubleshooting and debugging
+- Security best practices
+- Performance tuning
+
+## Core Concepts
+
+### Resource Management
+
+**Deployments**: Use for stateless applications
+- Rolling updates for zero-downtime deployments
+- Rollback capabilities for failed deployments
+- Replica management for scaling
+
+**StatefulSets**: Use for stateful applications
+- Stable network identities
+- Persistent storage
+- Ordered deployment and scaling
+
+**DaemonSets**: Use for node-level services
+- Log collectors
+- Monitoring agents
+- Network plugins
+
+### Configuration
+
+**ConfigMaps**: Store non-sensitive configuration
+- Environment-specific settings
+- Application configuration files
+- Feature flags
+
+**Secrets**: Store sensitive data
+- API keys and tokens
+- Database credentials
+- TLS certificates
+
+Use external secret management (Vault, AWS Secrets Manager) for production.
+
+### Networking
+
+**Services**: Expose applications internally
+- ClusterIP for internal communication
+- NodePort for external access (non-production)
+- LoadBalancer for external access (production)
+
+**Ingress**: HTTP/HTTPS routing
+- Path-based routing
+- Host-based routing
+- TLS termination
+- Load balancing
+
+## Deployment Strategies
+
+### Rolling Update
+
+Default strategy, gradual replacement:
+\`\`\`yaml
+strategy:
+  type: RollingUpdate
+  rollingUpdate:
+    maxSurge: 1
+    maxUnavailable: 0
+\`\`\`
+
+**When to use**: Standard deployments, minor updates
+
+### Recreate
+
+Stop all pods, then create new ones:
+\`\`\`yaml
+strategy:
+  type: Recreate
+\`\`\`
+
+**When to use**: Stateful apps that can't run multiple versions
+
+### Blue-Green
+
+Run two complete environments, switch traffic:
+1. Deploy new version (green)
+2. Test green environment
+3. Switch traffic to green
+4. Keep blue for quick rollback
+
+**When to use**: Critical services, need instant rollback
+
+### Canary
+
+Gradually roll out to subset of users:
+1. Deploy canary version (10% traffic)
+2. Monitor metrics and errors
+3. Increase traffic gradually
+4. Complete rollout or rollback
+
+**When to use**: High-risk changes, want gradual validation
+
+## Resource Configuration
+
+### Resource Requests and Limits
+
+Always set for production workloads:
+\`\`\`yaml
+resources:
+  requests:
+    memory: "256Mi"
+    cpu: "250m"
+  limits:
+    memory: "512Mi"
+    cpu: "500m"
+\`\`\`
+
+**Requests**: Guaranteed resources
+**Limits**: Maximum allowed resources
+
+### Health Checks
+
+Essential for reliability:
+\`\`\`yaml
+livenessProbe:
+  httpGet:
+    path: /health
+    port: 8080
+  initialDelaySeconds: 30
+  periodSeconds: 10
+
+readinessProbe:
+  httpGet:
+    path: /ready
+    port: 8080
+  initialDelaySeconds: 5
+  periodSeconds: 5
+\`\`\`
+
+**Liveness**: Restart unhealthy pods
+**Readiness**: Remove unready pods from service
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Pods not starting**
+   - Check: `kubectl describe pod <name>`
+   - Look for: Image pull errors, resource constraints
+   - Fix: Verify image name, increase resources
+
+2. **Service not reachable**
+   - Check: `kubectl get svc`, `kubectl get endpoints`
+   - Look for: No endpoints, wrong selector
+   - Fix: Verify pod labels match service selector
+
+3. **High memory usage**
+   - Check: `kubectl top pods`
+   - Look for: Pods near memory limit
+   - Fix: Increase limits, optimize application
+
+4. **Frequent restarts**
+   - Check: `kubectl get pods`, `kubectl logs <name>`
+   - Look for: Liveness probe failures, OOMKilled
+   - Fix: Adjust health checks, increase memory
+
+### Debugging Commands
+
+Get pod details:
+\`\`\`bash
+kubectl describe pod <name>
+kubectl logs <name>
+kubectl logs <name> --previous  # logs from crashed container
+\`\`\`
+
+Execute commands in pod:
+\`\`\`bash
+kubectl exec -it <name> -- /bin/sh
+kubectl exec <name> -- env
+\`\`\`
+
+Check resource usage:
+\`\`\`bash
+kubectl top nodes
+kubectl top pods
+\`\`\`
+
+## Security Best Practices
+
+### Pod Security
+
+- Run as non-root user
+- Use read-only root filesystem
+- Drop unnecessary capabilities
+- Use security contexts
+
+Example:
+\`\`\`yaml
+securityContext:
+  runAsNonRoot: true
+  runAsUser: 1000
+  readOnlyRootFilesystem: true
+  capabilities:
+    drop:
+      - ALL
+\`\`\`
+
+### Network Policies
+
+Restrict pod communication:
+\`\`\`yaml
+apiVersion: networking.k8s.io/v1
+kind: NetworkPolicy
+metadata:
+  name: api-allow
+spec:
+  podSelector:
+    matchLabels:
+      app: api
+  ingress:
+    - from:
+      - podSelector:
+          matchLabels:
+            app: frontend
+\`\`\`
+
+### Secrets Management
+
+- Never commit secrets to git
+- Use external secret managers
+- Rotate secrets regularly
+- Limit secret access with RBAC
+
+## Performance Optimization
+
+### Resource Tuning
+
+1. **Start conservative**: Set low limits initially
+2. **Monitor usage**: Track actual resource consumption
+3. **Adjust gradually**: Increase based on metrics
+4. **Set appropriate requests**: Match typical usage
+5. **Set safe limits**: 2x requests for headroom
+
+### Horizontal Pod Autoscaling
+
+Automatically scale based on metrics:
+\`\`\`yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: api-hpa
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: api
+  minReplicas: 2
+  maxReplicas: 10
+  metrics:
+    - type: Resource
+      resource:
+        name: cpu
+        target:
+          type: Utilization
+          averageUtilization: 70
+\`\`\`
+
+## MCP Server Integration
+
+This skill works with the kubernetes MCP server for operations:
+
+**List pods**:
+\`\`\`javascript
+const pods = await tools.k8s_list_pods({ namespace: 'default' })
+\`\`\`
+
+**Get pod logs**:
+\`\`\`javascript
+const logs = await tools.k8s_get_logs({ pod: 'api-xyz', container: 'app' })
+\`\`\`
+
+**Apply manifests**:
+\`\`\`javascript
+const result = await tools.k8s_apply_manifest({ file: 'deployment.yaml' })
+\`\`\`
+
+## Detailed References
+
+For in-depth information:
+- **Deployment patterns**: `references/deployment-patterns.md`
+- **Troubleshooting guide**: `references/troubleshooting.md`
+- **Security hardening**: `references/security.md`
+
+## Example Manifests
+
+For copy-paste examples:
+- **Basic deployment**: `examples/basic-deployment.yaml`
+- **StatefulSet**: `examples/stateful-set.yaml`
+- **Ingress config**: `examples/ingress-config.yaml`
+
+## Validation Scripts
+
+For manifest validation:
+\`\`\`bash
+bash ${CLAUDE_PLUGIN_ROOT}/skills/kubernetes-ops/scripts/validate-manifest.sh deployment.yaml
+\`\`\`
+```
+
+### hooks/hooks.json
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security/scan-secrets.sh",
+          "timeout": 30
+        }
+      ]
+    },
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Evaluate if this bash command is safe for production environment. Check for destructive operations, missing safeguards, and potential security issues. Commands should be idempotent and reversible.",
+          "timeout": 20
+        }
+      ]
+    }
+  ],
+  "PostToolUse": [
+    {
+      "matcher": "Bash",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow/update-status.sh",
+          "timeout": 15
+        }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "matcher": ".*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/quality/check-config.sh",
+          "timeout": 45
+        },
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow/notify-team.sh",
+          "timeout": 30
+        }
+      ]
+    }
+  ],
+  "SessionStart": [
+    {
+      "matcher": ".*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security/validate-permissions.sh",
+          "timeout": 20
+        }
+      ]
+    }
+  ]
+}
+```
+
+## Key Features
+
+### Multi-Level Organization
+
+**Commands**: Organized by function (CI, monitoring, admin)
+**Agents**: Separated by role (orchestration vs. specialized)
+**Skills**: Rich resources (references, examples, scripts)
+
+### MCP Integration
+
+Three custom MCP servers:
+- **Kubernetes**: Cluster operations
+- **Terraform**: Infrastructure provisioning
+- **GitHub Actions**: CI/CD automation
+
+### Shared Libraries
+
+Reusable code in `lib/`:
+- **Core**: Common utilities (logging, config, auth)
+- **Integrations**: External services (Slack, Datadog)
+- **Utils**: Helper functions (retry, validation)
+
+### Configuration Management
+
+Environment-specific configs in `config/`:
+- **Environments**: Per-environment settings
+- **Templates**: Reusable deployment templates
+
+### Security Automation
+
+Multiple security hooks:
+- Secret scanning before writes
+- Permission validation on session start
+- Configuration auditing on completion
+
+### Monitoring Integration
+
+Built-in monitoring via lib integrations:
+- Datadog for metrics
+- PagerDuty for alerts
+- Slack for notifications
+
+## Use Cases
+
+1. **Multi-environment deployments**: Orchestrated rollouts across dev/staging/prod
+2. **Infrastructure as code**: Terraform automation with state management
+3. **CI/CD automation**: Build, test, deploy pipelines
+4. **Monitoring and observability**: Integrated metrics and alerting
+5. **Security enforcement**: Automated security scanning and validation
+6. **Team collaboration**: Slack notifications and status updates
+
+## When to Use This Pattern
+
+- Large-scale enterprise deployments
+- Multiple environment management
+- Complex CI/CD workflows
+- Integrated monitoring requirements
+- Security-critical infrastructure
+- Team collaboration needs
+
+## Scaling Considerations
+
+- **Performance**: Separate MCP servers for parallel operations
+- **Organization**: Multi-level directories for scalability
+- **Maintainability**: Shared libraries reduce duplication
+- **Flexibility**: Environment configs enable customization
+- **Security**: Layered security hooks and validation
diff --git a/.agents/skills/plugin-structure/examples/minimal-plugin.md b/.agents/skills/plugin-structure/examples/minimal-plugin.md
new file mode 100644
index 0000000..27591db
--- /dev/null
+++ b/.agents/skills/plugin-structure/examples/minimal-plugin.md
@@ -0,0 +1,83 @@
+# Minimal Plugin Example
+
+A bare-bones plugin with a single command.
+
+## Directory Structure
+
+```
+hello-world/
+├── .claude-plugin/
+│   └── plugin.json
+└── commands/
+    └── hello.md
+```
+
+## File Contents
+
+### .claude-plugin/plugin.json
+
+```json
+{
+  "name": "hello-world"
+}
+```
+
+### commands/hello.md
+
+```markdown
+---
+name: hello
+description: Prints a friendly greeting message
+---
+
+# Hello Command
+
+Print a friendly greeting to the user.
+
+## Implementation
+
+Output the following message to the user:
+
+> Hello! This is a simple command from the hello-world plugin.
+>
+> Use this as a starting point for building more complex plugins.
+
+Include the current timestamp in the greeting to show the command executed successfully.
+```
+
+## Usage
+
+After installing the plugin:
+
+```
+$ claude
+> /hello
+Hello! This is a simple command from the hello-world plugin.
+
+Use this as a starting point for building more complex plugins.
+
+Executed at: 2025-01-15 14:30:22 UTC
+```
+
+## Key Points
+
+1. **Minimal manifest**: Only the required `name` field
+2. **Single command**: One markdown file in `commands/` directory
+3. **Auto-discovery**: Claude Code finds the command automatically
+4. **No dependencies**: No scripts, hooks, or external resources
+
+## When to Use This Pattern
+
+- Quick prototypes
+- Single-purpose utilities
+- Learning plugin development
+- Internal team tools with one specific function
+
+## Extending This Plugin
+
+To add more functionality:
+
+1. **Add commands**: Create more `.md` files in `commands/`
+2. **Add metadata**: Update `plugin.json` with version, description, author
+3. **Add agents**: Create `agents/` directory with agent definitions
+4. **Add hooks**: Create `hooks/hooks.json` for event handling
diff --git a/.agents/skills/plugin-structure/examples/standard-plugin.md b/.agents/skills/plugin-structure/examples/standard-plugin.md
new file mode 100644
index 0000000..d903166
--- /dev/null
+++ b/.agents/skills/plugin-structure/examples/standard-plugin.md
@@ -0,0 +1,587 @@
+# Standard Plugin Example
+
+A well-structured plugin with commands, agents, and skills.
+
+## Directory Structure
+
+```
+code-quality/
+├── .claude-plugin/
+│   └── plugin.json
+├── commands/
+│   ├── lint.md
+│   ├── test.md
+│   └── review.md
+├── agents/
+│   ├── code-reviewer.md
+│   └── test-generator.md
+├── skills/
+│   ├── code-standards/
+│   │   ├── SKILL.md
+│   │   └── references/
+│   │       └── style-guide.md
+│   └── testing-patterns/
+│       ├── SKILL.md
+│       └── examples/
+│           ├── unit-test.js
+│           └── integration-test.js
+├── hooks/
+│   ├── hooks.json
+│   └── scripts/
+│       └── validate-commit.sh
+└── scripts/
+    ├── run-linter.sh
+    └── generate-report.py
+```
+
+## File Contents
+
+### .claude-plugin/plugin.json
+
+```json
+{
+  "name": "code-quality",
+  "version": "1.0.0",
+  "description": "Comprehensive code quality tools including linting, testing, and review automation",
+  "author": {
+    "name": "Quality Team",
+    "email": "quality@example.com"
+  },
+  "homepage": "https://docs.example.com/plugins/code-quality",
+  "repository": "https://github.com/example/code-quality-plugin",
+  "license": "MIT",
+  "keywords": ["code-quality", "linting", "testing", "code-review", "automation"]
+}
+```
+
+### commands/lint.md
+
+```markdown
+---
+name: lint
+description: Run linting checks on the codebase
+---
+
+# Lint Command
+
+Run comprehensive linting checks on the project codebase.
+
+## Process
+
+1. Detect project type and installed linters
+2. Run appropriate linters (ESLint, Pylint, RuboCop, etc.)
+3. Collect and format results
+4. Report issues with file locations and severity
+
+## Implementation
+
+Execute the linting script:
+
+\`\`\`bash
+bash ${CLAUDE_PLUGIN_ROOT}/scripts/run-linter.sh
+\`\`\`
+
+Parse the output and present issues organized by:
+- Critical issues (must fix)
+- Warnings (should fix)
+- Style suggestions (optional)
+
+For each issue, show:
+- File path and line number
+- Issue description
+- Suggested fix (if available)
+```
+
+### commands/test.md
+
+```markdown
+---
+name: test
+description: Run test suite with coverage reporting
+---
+
+# Test Command
+
+Execute the project test suite and generate coverage reports.
+
+## Process
+
+1. Identify test framework (Jest, pytest, RSpec, etc.)
+2. Run all tests
+3. Generate coverage report
+4. Identify untested code
+
+## Output
+
+Present results in structured format:
+- Test summary (passed/failed/skipped)
+- Coverage percentage by file
+- Critical untested areas
+- Failed test details
+
+## Integration
+
+After test completion, offer to:
+- Fix failing tests
+- Generate tests for untested code (using test-generator agent)
+- Update documentation based on test changes
+```
+
+### agents/code-reviewer.md
+
+```markdown
+---
+description: Expert code reviewer specializing in identifying bugs, security issues, and improvement opportunities
+capabilities:
+  - Analyze code for potential bugs and logic errors
+  - Identify security vulnerabilities
+  - Suggest performance improvements
+  - Ensure code follows project standards
+  - Review test coverage adequacy
+---
+
+# Code Reviewer Agent
+
+Specialized agent for comprehensive code review.
+
+## Expertise
+
+- **Bug detection**: Logic errors, edge cases, error handling
+- **Security analysis**: Injection vulnerabilities, authentication issues, data exposure
+- **Performance**: Algorithm efficiency, resource usage, optimization opportunities
+- **Standards compliance**: Style guide adherence, naming conventions, documentation
+- **Test coverage**: Adequacy of test cases, missing scenarios
+
+## Review Process
+
+1. **Initial scan**: Quick pass for obvious issues
+2. **Deep analysis**: Line-by-line review of changed code
+3. **Context evaluation**: Check impact on related code
+4. **Best practices**: Compare against project and language standards
+5. **Recommendations**: Prioritized list of improvements
+
+## Integration with Skills
+
+Automatically loads `code-standards` skill for project-specific guidelines.
+
+## Output Format
+
+For each file reviewed:
+- Overall assessment
+- Critical issues (must fix before merge)
+- Important issues (should fix)
+- Suggestions (nice to have)
+- Positive feedback (what was done well)
+```
+
+### agents/test-generator.md
+
+```markdown
+---
+description: Generates comprehensive test suites from code analysis
+capabilities:
+  - Analyze code structure and logic flow
+  - Generate unit tests for functions and methods
+  - Create integration tests for modules
+  - Design edge case and error condition tests
+  - Suggest test fixtures and mocks
+---
+
+# Test Generator Agent
+
+Specialized agent for generating comprehensive test suites.
+
+## Expertise
+
+- **Unit testing**: Individual function/method tests
+- **Integration testing**: Module interaction tests
+- **Edge cases**: Boundary conditions, error paths
+- **Test organization**: Proper test structure and naming
+- **Mocking**: Appropriate use of mocks and stubs
+
+## Generation Process
+
+1. **Code analysis**: Understand function purpose and logic
+2. **Path identification**: Map all execution paths
+3. **Input design**: Create test inputs covering all paths
+4. **Assertion design**: Define expected outputs
+5. **Test generation**: Write tests in project's framework
+
+## Integration with Skills
+
+Automatically loads `testing-patterns` skill for project-specific test conventions.
+
+## Test Quality
+
+Generated tests include:
+- Happy path scenarios
+- Edge cases and boundary conditions
+- Error handling verification
+- Mock data for external dependencies
+- Clear test descriptions
+```
+
+### skills/code-standards/SKILL.md
+
+```markdown
+---
+name: Code Standards
+description: This skill should be used when reviewing code, enforcing style guidelines, checking naming conventions, or ensuring code quality standards. Provides project-specific coding standards and best practices.
+version: 1.0.0
+---
+
+# Code Standards
+
+Comprehensive coding standards and best practices for maintaining code quality.
+
+## Overview
+
+Enforce consistent code quality through standardized conventions for:
+- Code style and formatting
+- Naming conventions
+- Documentation requirements
+- Error handling patterns
+- Security practices
+
+## Style Guidelines
+
+### Formatting
+
+- **Indentation**: 2 spaces (JavaScript/TypeScript), 4 spaces (Python)
+- **Line length**: Maximum 100 characters
+- **Braces**: Same line for opening brace (K&R style)
+- **Whitespace**: Space after commas, around operators
+
+### Naming Conventions
+
+- **Variables**: camelCase for JavaScript, snake_case for Python
+- **Functions**: camelCase, descriptive verb-noun pairs
+- **Classes**: PascalCase
+- **Constants**: UPPER_SNAKE_CASE
+- **Files**: kebab-case for modules
+
+## Documentation Requirements
+
+### Function Documentation
+
+Every function must include:
+- Purpose description
+- Parameter descriptions with types
+- Return value description with type
+- Example usage (for public functions)
+
+### Module Documentation
+
+Every module must include:
+- Module purpose
+- Public API overview
+- Usage examples
+- Dependencies
+
+## Error Handling
+
+### Required Practices
+
+- Never swallow errors silently
+- Always log errors with context
+- Use specific error types
+- Provide actionable error messages
+- Clean up resources in finally blocks
+
+### Example Pattern
+
+\`\`\`javascript
+async function processData(data) {
+  try {
+    const result = await transform(data)
+    return result
+  } catch (error) {
+    logger.error('Data processing failed', {
+      data: sanitize(data),
+      error: error.message,
+      stack: error.stack
+    })
+    throw new DataProcessingError('Failed to process data', { cause: error })
+  }
+}
+\`\`\`
+
+## Security Practices
+
+- Validate all external input
+- Sanitize data before output
+- Use parameterized queries
+- Never log sensitive information
+- Keep dependencies updated
+
+## Detailed Guidelines
+
+For comprehensive style guides by language, see:
+- `references/style-guide.md`
+```
+
+### skills/code-standards/references/style-guide.md
+
+```markdown
+# Comprehensive Style Guide
+
+Detailed style guidelines for all supported languages.
+
+## JavaScript/TypeScript
+
+### Variable Declarations
+
+Use `const` by default, `let` when reassignment needed, never `var`:
+
+\`\`\`javascript
+// Good
+const MAX_RETRIES = 3
+let currentTry = 0
+
+// Bad
+var MAX_RETRIES = 3
+\`\`\`
+
+### Function Declarations
+
+Use function expressions for consistency:
+
+\`\`\`javascript
+// Good
+const calculateTotal = (items) => {
+  return items.reduce((sum, item) => sum + item.price, 0)
+}
+
+// Bad (inconsistent style)
+function calculateTotal(items) {
+  return items.reduce((sum, item) => sum + item.price, 0)
+}
+\`\`\`
+
+### Async/Await
+
+Prefer async/await over promise chains:
+
+\`\`\`javascript
+// Good
+async function fetchUserData(userId) {
+  const user = await db.getUser(userId)
+  const orders = await db.getOrders(user.id)
+  return { user, orders }
+}
+
+// Bad
+function fetchUserData(userId) {
+  return db.getUser(userId)
+    .then(user => db.getOrders(user.id)
+      .then(orders => ({ user, orders })))
+}
+\`\`\`
+
+## Python
+
+### Import Organization
+
+Order imports: standard library, third-party, local:
+
+\`\`\`python
+# Good
+import os
+import sys
+
+import numpy as np
+import pandas as pd
+
+from app.models import User
+from app.utils import helper
+
+# Bad - mixed order
+from app.models import User
+import numpy as np
+import os
+\`\`\`
+
+### Type Hints
+
+Use type hints for all function signatures:
+
+\`\`\`python
+# Good
+def calculate_average(numbers: list[float]) -> float:
+    return sum(numbers) / len(numbers)
+
+# Bad
+def calculate_average(numbers):
+    return sum(numbers) / len(numbers)
+\`\`\`
+
+## Additional Languages
+
+See language-specific guides for:
+- Go: `references/go-style.md`
+- Rust: `references/rust-style.md`
+- Ruby: `references/ruby-style.md`
+```
+
+### hooks/hooks.json
+
+```json
+{
+  "PreToolUse": [
+    {
+      "matcher": "Write|Edit",
+      "hooks": [
+        {
+          "type": "prompt",
+          "prompt": "Before modifying code, verify it meets our coding standards from the code-standards skill. Check formatting, naming conventions, and documentation. If standards aren't met, suggest improvements.",
+          "timeout": 30
+        }
+      ]
+    }
+  ],
+  "Stop": [
+    {
+      "matcher": ".*",
+      "hooks": [
+        {
+          "type": "command",
+          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/validate-commit.sh",
+          "timeout": 45
+        }
+      ]
+    }
+  ]
+}
+```
+
+### hooks/scripts/validate-commit.sh
+
+```bash
+#!/bin/bash
+# Validate code quality before task completion
+
+set -e
+
+# Check if there are any uncommitted changes
+if [[ -z $(git status -s) ]]; then
+  echo '{"systemMessage": "No changes to validate. Task complete."}'
+  exit 0
+fi
+
+# Run linter on changed files
+CHANGED_FILES=$(git diff --name-only --cached | grep -E '\.(js|ts|py)$' || true)
+
+if [[ -z "$CHANGED_FILES" ]]; then
+  echo '{"systemMessage": "No code files changed. Validation passed."}'
+  exit 0
+fi
+
+# Run appropriate linters
+ISSUES=0
+
+for file in $CHANGED_FILES; do
+  case "$file" in
+    *.js|*.ts)
+      if ! npx eslint "$file" --quiet; then
+        ISSUES=$((ISSUES + 1))
+      fi
+      ;;
+    *.py)
+      if ! python -m pylint "$file" --errors-only; then
+        ISSUES=$((ISSUES + 1))
+      fi
+      ;;
+  esac
+done
+
+if [[ $ISSUES -gt 0 ]]; then
+  echo "{\"systemMessage\": \"Found $ISSUES code quality issues. Please fix before completing.\"}"
+  exit 1
+fi
+
+echo '{"systemMessage": "Code quality checks passed. Ready to commit."}'
+exit 0
+```
+
+## Usage Examples
+
+### Running Commands
+
+```
+$ claude
+> /lint
+Running linter checks...
+
+Critical Issues (2):
+  src/api/users.js:45 - SQL injection vulnerability
+  src/utils/helpers.js:12 - Unhandled promise rejection
+
+Warnings (5):
+  src/components/Button.tsx:23 - Missing PropTypes
+  ...
+
+Style Suggestions (8):
+  src/index.js:1 - Use const instead of let
+  ...
+
+> /test
+Running test suite...
+
+Test Results:
+  ✓ 245 passed
+  ✗ 3 failed
+  ○ 2 skipped
+
+Coverage: 87.3%
+
+Untested Files:
+  src/utils/cache.js - 0% coverage
+  src/api/webhooks.js - 23% coverage
+
+Failed Tests:
+  1. User API › GET /users › should handle pagination
+     Expected 200, received 500
+  ...
+```
+
+### Using Agents
+
+```
+> Review the changes in src/api/users.js
+
+[code-reviewer agent selected automatically]
+
+Code Review: src/api/users.js
+
+Critical Issues:
+  1. Line 45: SQL injection vulnerability
+     - Using string concatenation for SQL query
+     - Replace with parameterized query
+     - Priority: CRITICAL
+
+  2. Line 67: Missing error handling
+     - Database query without try/catch
+     - Could crash server on DB error
+     - Priority: HIGH
+
+Suggestions:
+  1. Line 23: Consider caching user data
+     - Frequent DB queries for same users
+     - Add Redis caching layer
+     - Priority: MEDIUM
+```
+
+## Key Points
+
+1. **Complete manifest**: All recommended metadata fields
+2. **Multiple components**: Commands, agents, skills, hooks
+3. **Rich skills**: References and examples for detailed information
+4. **Automation**: Hooks enforce standards automatically
+5. **Integration**: Components work together cohesively
+
+## When to Use This Pattern
+
+- Production plugins for distribution
+- Team collaboration tools
+- Plugins requiring consistency enforcement
+- Complex workflows with multiple entry points
diff --git a/.agents/skills/plugin-structure/references/component-patterns.md b/.agents/skills/plugin-structure/references/component-patterns.md
new file mode 100644
index 0000000..a58a7b4
--- /dev/null
+++ b/.agents/skills/plugin-structure/references/component-patterns.md
@@ -0,0 +1,567 @@
+# Component Organization Patterns
+
+Advanced patterns for organizing plugin components effectively.
+
+## Component Lifecycle
+
+### Discovery Phase
+
+When Claude Code starts:
+
+1. **Scan enabled plugins**: Read `.claude-plugin/plugin.json` for each
+2. **Discover components**: Look in default and custom paths
+3. **Parse definitions**: Read YAML frontmatter and configurations
+4. **Register components**: Make available to Claude Code
+5. **Initialize**: Start MCP servers, register hooks
+
+**Timing**: Component registration happens during Claude Code initialization, not continuously.
+
+### Activation Phase
+
+When components are used:
+
+**Commands**: User types slash command → Claude Code looks up → Executes
+**Agents**: Task arrives → Claude Code evaluates capabilities → Selects agent
+**Skills**: Task context matches description → Claude Code loads skill
+**Hooks**: Event occurs → Claude Code calls matching hooks
+**MCP Servers**: Tool call matches server capability → Forwards to server
+
+## Command Organization Patterns
+
+### Flat Structure
+
+Single directory with all commands:
+
+```
+commands/
+├── build.md
+├── test.md
+├── deploy.md
+├── review.md
+└── docs.md
+```
+
+**When to use**:
+- 5-15 commands total
+- All commands at same abstraction level
+- No clear categorization
+
+**Advantages**:
+- Simple, easy to navigate
+- No configuration needed
+- Fast discovery
+
+### Categorized Structure
+
+Multiple directories for different command types:
+
+```
+commands/              # Core commands
+├── build.md
+└── test.md
+
+admin-commands/        # Administrative
+├── configure.md
+└── manage.md
+
+workflow-commands/     # Workflow automation
+├── review.md
+└── deploy.md
+```
+
+**Manifest configuration**:
+```json
+{
+  "commands": [
+    "./commands",
+    "./admin-commands",
+    "./workflow-commands"
+  ]
+}
+```
+
+**When to use**:
+- 15+ commands
+- Clear functional categories
+- Different permission levels
+
+**Advantages**:
+- Organized by purpose
+- Easier to maintain
+- Can restrict access by directory
+
+### Hierarchical Structure
+
+Nested organization for complex plugins:
+
+```
+commands/
+├── ci/
+│   ├── build.md
+│   ├── test.md
+│   └── lint.md
+├── deployment/
+│   ├── staging.md
+│   └── production.md
+└── management/
+    ├── config.md
+    └── status.md
+```
+
+**Note**: Claude Code doesn't support nested command discovery automatically. Use custom paths:
+
+```json
+{
+  "commands": [
+    "./commands/ci",
+    "./commands/deployment",
+    "./commands/management"
+  ]
+}
+```
+
+**When to use**:
+- 20+ commands
+- Multi-level categorization
+- Complex workflows
+
+**Advantages**:
+- Maximum organization
+- Clear boundaries
+- Scalable structure
+
+## Agent Organization Patterns
+
+### Role-Based Organization
+
+Organize agents by their primary role:
+
+```
+agents/
+├── code-reviewer.md        # Reviews code
+├── test-generator.md       # Generates tests
+├── documentation-writer.md # Writes docs
+└── refactorer.md          # Refactors code
+```
+
+**When to use**:
+- Agents have distinct, non-overlapping roles
+- Users invoke agents manually
+- Clear agent responsibilities
+
+### Capability-Based Organization
+
+Organize by specific capabilities:
+
+```
+agents/
+├── python-expert.md        # Python-specific
+├── typescript-expert.md    # TypeScript-specific
+├── api-specialist.md       # API design
+└── database-specialist.md  # Database work
+```
+
+**When to use**:
+- Technology-specific agents
+- Domain expertise focus
+- Automatic agent selection
+
+### Workflow-Based Organization
+
+Organize by workflow stage:
+
+```
+agents/
+├── planning-agent.md      # Planning phase
+├── implementation-agent.md # Coding phase
+├── testing-agent.md       # Testing phase
+└── deployment-agent.md    # Deployment phase
+```
+
+**When to use**:
+- Sequential workflows
+- Stage-specific expertise
+- Pipeline automation
+
+## Skill Organization Patterns
+
+### Topic-Based Organization
+
+Each skill covers a specific topic:
+
+```
+skills/
+├── api-design/
+│   └── SKILL.md
+├── error-handling/
+│   └── SKILL.md
+├── testing-strategies/
+│   └── SKILL.md
+└── performance-optimization/
+    └── SKILL.md
+```
+
+**When to use**:
+- Knowledge-based skills
+- Educational or reference content
+- Broad applicability
+
+### Tool-Based Organization
+
+Skills for specific tools or technologies:
+
+```
+skills/
+├── docker/
+│   ├── SKILL.md
+│   └── references/
+│       └── dockerfile-best-practices.md
+├── kubernetes/
+│   ├── SKILL.md
+│   └── examples/
+│       └── deployment.yaml
+└── terraform/
+    ├── SKILL.md
+    └── scripts/
+        └── validate-config.sh
+```
+
+**When to use**:
+- Tool-specific expertise
+- Complex tool configurations
+- Tool best practices
+
+### Workflow-Based Organization
+
+Skills for complete workflows:
+
+```
+skills/
+├── code-review-workflow/
+│   ├── SKILL.md
+│   └── references/
+│       ├── checklist.md
+│       └── standards.md
+├── deployment-workflow/
+│   ├── SKILL.md
+│   └── scripts/
+│       ├── pre-deploy.sh
+│       └── post-deploy.sh
+└── testing-workflow/
+    ├── SKILL.md
+    └── examples/
+        └── test-structure.md
+```
+
+**When to use**:
+- Multi-step processes
+- Company-specific workflows
+- Process automation
+
+### Skill with Rich Resources
+
+Comprehensive skill with all resource types:
+
+```
+skills/
+└── api-testing/
+    ├── SKILL.md              # Core skill (1500 words)
+    ├── references/
+    │   ├── rest-api-guide.md
+    │   ├── graphql-guide.md
+    │   └── authentication.md
+    ├── examples/
+    │   ├── basic-test.js
+    │   ├── authenticated-test.js
+    │   └── integration-test.js
+    ├── scripts/
+    │   ├── run-tests.sh
+    │   └── generate-report.py
+    └── assets/
+        └── test-template.json
+```
+
+**Resource usage**:
+- **SKILL.md**: Overview and when to use resources
+- **references/**: Detailed guides (loaded as needed)
+- **examples/**: Copy-paste code samples
+- **scripts/**: Executable test runners
+- **assets/**: Templates and configurations
+
+## Hook Organization Patterns
+
+### Monolithic Configuration
+
+Single hooks.json with all hooks:
+
+```
+hooks/
+├── hooks.json     # All hook definitions
+└── scripts/
+    ├── validate-write.sh
+    ├── validate-bash.sh
+    └── load-context.sh
+```
+
+**hooks.json**:
+```json
+{
+  "PreToolUse": [...],
+  "PostToolUse": [...],
+  "Stop": [...],
+  "SessionStart": [...]
+}
+```
+
+**When to use**:
+- 5-10 hooks total
+- Simple hook logic
+- Centralized configuration
+
+### Event-Based Organization
+
+Separate files per event type:
+
+```
+hooks/
+├── hooks.json              # Combines all
+├── pre-tool-use.json      # PreToolUse hooks
+├── post-tool-use.json     # PostToolUse hooks
+├── stop.json              # Stop hooks
+└── scripts/
+    ├── validate/
+    │   ├── write.sh
+    │   └── bash.sh
+    └── context/
+        └── load.sh
+```
+
+**hooks.json** (combines):
+```json
+{
+  "PreToolUse": ${file:./pre-tool-use.json},
+  "PostToolUse": ${file:./post-tool-use.json},
+  "Stop": ${file:./stop.json}
+}
+```
+
+**Note**: Use build script to combine files, Claude Code doesn't support file references.
+
+**When to use**:
+- 10+ hooks
+- Different teams managing different events
+- Complex hook configurations
+
+### Purpose-Based Organization
+
+Group by functional purpose:
+
+```
+hooks/
+├── hooks.json
+└── scripts/
+    ├── security/
+    │   ├── validate-paths.sh
+    │   ├── check-credentials.sh
+    │   └── scan-malware.sh
+    ├── quality/
+    │   ├── lint-code.sh
+    │   ├── check-tests.sh
+    │   └── verify-docs.sh
+    └── workflow/
+        ├── notify-team.sh
+        └── update-status.sh
+```
+
+**When to use**:
+- Many hook scripts
+- Clear functional boundaries
+- Team specialization
+
+## Script Organization Patterns
+
+### Flat Scripts
+
+All scripts in single directory:
+
+```
+scripts/
+├── build.sh
+├── test.py
+├── deploy.sh
+├── validate.js
+└── report.py
+```
+
+**When to use**:
+- 5-10 scripts
+- All scripts related
+- Simple plugin
+
+### Categorized Scripts
+
+Group by purpose:
+
+```
+scripts/
+├── build/
+│   ├── compile.sh
+│   └── package.sh
+├── test/
+│   ├── run-unit.sh
+│   └── run-integration.sh
+├── deploy/
+│   ├── staging.sh
+│   └── production.sh
+└── utils/
+    ├── log.sh
+    └── notify.sh
+```
+
+**When to use**:
+- 10+ scripts
+- Clear categories
+- Reusable utilities
+
+### Language-Based Organization
+
+Group by programming language:
+
+```
+scripts/
+├── bash/
+│   ├── build.sh
+│   └── deploy.sh
+├── python/
+│   ├── analyze.py
+│   └── report.py
+└── javascript/
+    ├── bundle.js
+    └── optimize.js
+```
+
+**When to use**:
+- Multi-language scripts
+- Different runtime requirements
+- Language-specific dependencies
+
+## Cross-Component Patterns
+
+### Shared Resources
+
+Components sharing common resources:
+
+```
+plugin/
+├── commands/
+│   ├── test.md        # Uses lib/test-utils.sh
+│   └── deploy.md      # Uses lib/deploy-utils.sh
+├── agents/
+│   └── tester.md      # References lib/test-utils.sh
+├── hooks/
+│   └── scripts/
+│       └── pre-test.sh # Sources lib/test-utils.sh
+└── lib/
+    ├── test-utils.sh
+    └── deploy-utils.sh
+```
+
+**Usage in components**:
+```bash
+#!/bin/bash
+source "${CLAUDE_PLUGIN_ROOT}/lib/test-utils.sh"
+run_tests
+```
+
+**Benefits**:
+- Code reuse
+- Consistent behavior
+- Easier maintenance
+
+### Layered Architecture
+
+Separate concerns into layers:
+
+```
+plugin/
+├── commands/          # User interface layer
+├── agents/            # Orchestration layer
+├── skills/            # Knowledge layer
+└── lib/
+    ├── core/         # Core business logic
+    ├── integrations/ # External services
+    └── utils/        # Helper functions
+```
+
+**When to use**:
+- Large plugins (100+ files)
+- Multiple developers
+- Clear separation of concerns
+
+### Plugin Within Plugin
+
+Nested plugin structure:
+
+```
+plugin/
+├── .claude-plugin/
+│   └── plugin.json
+├── core/              # Core functionality
+│   ├── commands/
+│   └── agents/
+└── extensions/        # Optional extensions
+    ├── extension-a/
+    │   ├── commands/
+    │   └── agents/
+    └── extension-b/
+        ├── commands/
+        └── agents/
+```
+
+**Manifest**:
+```json
+{
+  "commands": [
+    "./core/commands",
+    "./extensions/extension-a/commands",
+    "./extensions/extension-b/commands"
+  ]
+}
+```
+
+**When to use**:
+- Modular functionality
+- Optional features
+- Plugin families
+
+## Best Practices
+
+### Naming
+
+1. **Consistent naming**: Match file names to component purpose
+2. **Descriptive names**: Indicate what component does
+3. **Avoid abbreviations**: Use full words for clarity
+
+### Organization
+
+1. **Start simple**: Use flat structure, reorganize when needed
+2. **Group related items**: Keep related components together
+3. **Separate concerns**: Don't mix unrelated functionality
+
+### Scalability
+
+1. **Plan for growth**: Choose structure that scales
+2. **Refactor early**: Reorganize before it becomes painful
+3. **Document structure**: Explain organization in README
+
+### Maintainability
+
+1. **Consistent patterns**: Use same structure throughout
+2. **Minimize nesting**: Keep directory depth manageable
+3. **Use conventions**: Follow community standards
+
+### Performance
+
+1. **Avoid deep nesting**: Impacts discovery time
+2. **Minimize custom paths**: Use defaults when possible
+3. **Keep configurations small**: Large configs slow loading
diff --git a/.agents/skills/plugin-structure/references/manifest-reference.md b/.agents/skills/plugin-structure/references/manifest-reference.md
new file mode 100644
index 0000000..40c9c2f
--- /dev/null
+++ b/.agents/skills/plugin-structure/references/manifest-reference.md
@@ -0,0 +1,552 @@
+# Plugin Manifest Reference
+
+Complete reference for `plugin.json` configuration.
+
+## File Location
+
+**Required path**: `.claude-plugin/plugin.json`
+
+The manifest MUST be in the `.claude-plugin/` directory at the plugin root. Claude Code will not recognize plugins without this file in the correct location.
+
+## Complete Field Reference
+
+### Core Fields
+
+#### name (required)
+
+**Type**: String
+**Format**: kebab-case
+**Example**: `"test-automation-suite"`
+
+The unique identifier for the plugin. Used for:
+- Plugin identification in Claude Code
+- Conflict detection with other plugins
+- Command namespacing (optional)
+
+**Requirements**:
+- Must be unique across all installed plugins
+- Use only lowercase letters, numbers, and hyphens
+- No spaces or special characters
+- Start with a letter
+- End with a letter or number
+
+**Validation**:
+```javascript
+/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+```
+
+**Examples**:
+- ✅ Good: `api-tester`, `code-review`, `git-workflow-automation`
+- ❌ Bad: `API Tester`, `code_review`, `-git-workflow`, `test-`
+
+#### version
+
+**Type**: String
+**Format**: Semantic versioning (MAJOR.MINOR.PATCH)
+**Example**: `"2.1.0"`
+**Default**: `"0.1.0"` if not specified
+
+Semantic versioning guidelines:
+- **MAJOR**: Incompatible API changes, breaking changes
+- **MINOR**: New functionality, backward-compatible
+- **PATCH**: Bug fixes, backward-compatible
+
+**Pre-release versions**:
+- `"1.0.0-alpha.1"` - Alpha release
+- `"1.0.0-beta.2"` - Beta release
+- `"1.0.0-rc.1"` - Release candidate
+
+**Examples**:
+- `"0.1.0"` - Initial development
+- `"1.0.0"` - First stable release
+- `"1.2.3"` - Patch update to 1.2
+- `"2.0.0"` - Major version with breaking changes
+
+#### description
+
+**Type**: String
+**Length**: 50-200 characters recommended
+**Example**: `"Automates code review workflows with style checks and automated feedback"`
+
+Brief explanation of plugin purpose and functionality.
+
+**Best practices**:
+- Focus on what the plugin does, not how
+- Use active voice
+- Mention key features or benefits
+- Keep under 200 characters for marketplace display
+
+**Examples**:
+- ✅ "Generates comprehensive test suites from code analysis and coverage reports"
+- ✅ "Integrates with Jira for automatic issue tracking and sprint management"
+- ❌ "A plugin that helps you do testing stuff"
+- ❌ "This is a very long description that goes on and on about every single feature..."
+
+### Metadata Fields
+
+#### author
+
+**Type**: Object
+**Fields**: name (required), email (optional), url (optional)
+
+```json
+{
+  "author": {
+    "name": "Jane Developer",
+    "email": "jane@example.com",
+    "url": "https://janedeveloper.com"
+  }
+}
+```
+
+**Alternative format** (string only):
+```json
+{
+  "author": "Jane Developer <jane@example.com> (https://janedeveloper.com)"
+}
+```
+
+**Use cases**:
+- Credit and attribution
+- Contact for support or questions
+- Marketplace display
+- Community recognition
+
+#### homepage
+
+**Type**: String (URL)
+**Example**: `"https://docs.example.com/plugins/my-plugin"`
+
+Link to plugin documentation or landing page.
+
+**Should point to**:
+- Plugin documentation site
+- Project homepage
+- Detailed usage guide
+- Installation instructions
+
+**Not for**:
+- Source code (use `repository` field)
+- Issue tracker (include in documentation)
+- Personal websites (use `author.url`)
+
+#### repository
+
+**Type**: String (URL) or Object
+**Example**: `"https://github.com/user/plugin-name"`
+
+Source code repository location.
+
+**String format**:
+```json
+{
+  "repository": "https://github.com/user/plugin-name"
+}
+```
+
+**Object format** (detailed):
+```json
+{
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/user/plugin-name.git",
+    "directory": "packages/plugin-name"
+  }
+}
+```
+
+**Use cases**:
+- Source code access
+- Issue reporting
+- Community contributions
+- Transparency and trust
+
+#### license
+
+**Type**: String
+**Format**: SPDX identifier
+**Example**: `"MIT"`
+
+Software license identifier.
+
+**Common licenses**:
+- `"MIT"` - Permissive, popular choice
+- `"Apache-2.0"` - Permissive with patent grant
+- `"GPL-3.0"` - Copyleft
+- `"BSD-3-Clause"` - Permissive
+- `"ISC"` - Permissive, similar to MIT
+- `"UNLICENSED"` - Proprietary, not open source
+
+**Full list**: https://spdx.org/licenses/
+
+**Multiple licenses**:
+```json
+{
+  "license": "(MIT OR Apache-2.0)"
+}
+```
+
+#### keywords
+
+**Type**: Array of strings
+**Example**: `["testing", "automation", "ci-cd", "quality-assurance"]`
+
+Tags for plugin discovery and categorization.
+
+**Best practices**:
+- Use 5-10 keywords
+- Include functionality categories
+- Add technology names
+- Use common search terms
+- Avoid duplicating plugin name
+
+**Categories to consider**:
+- Functionality: `testing`, `debugging`, `documentation`, `deployment`
+- Technologies: `typescript`, `python`, `docker`, `aws`
+- Workflows: `ci-cd`, `code-review`, `git-workflow`
+- Domains: `web-development`, `data-science`, `devops`
+
+### Component Path Fields
+
+#### commands
+
+**Type**: String or Array of strings
+**Default**: `["./commands"]`
+**Example**: `"./cli-commands"`
+
+Additional directories or files containing command definitions.
+
+**Single path**:
+```json
+{
+  "commands": "./custom-commands"
+}
+```
+
+**Multiple paths**:
+```json
+{
+  "commands": [
+    "./commands",
+    "./admin-commands",
+    "./experimental-commands"
+  ]
+}
+```
+
+**Behavior**: Supplements default `commands/` directory (does not replace)
+
+**Use cases**:
+- Organizing commands by category
+- Separating stable from experimental commands
+- Loading commands from shared locations
+
+#### agents
+
+**Type**: String or Array of strings
+**Default**: `["./agents"]`
+**Example**: `"./specialized-agents"`
+
+Additional directories or files containing agent definitions.
+
+**Format**: Same as `commands` field
+
+**Use cases**:
+- Grouping agents by specialization
+- Separating general-purpose from task-specific agents
+- Loading agents from plugin dependencies
+
+#### hooks
+
+**Type**: String (path to JSON file) or Object (inline configuration)
+**Default**: `"./hooks/hooks.json"`
+
+Hook configuration location or inline definition.
+
+**File path**:
+```json
+{
+  "hooks": "./config/hooks.json"
+}
+```
+
+**Inline configuration**:
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/scripts/validate.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Use cases**:
+- Simple plugins: Inline configuration (< 50 lines)
+- Complex plugins: External JSON file
+- Multiple hook sets: Separate files for different contexts
+
+#### mcpServers
+
+**Type**: String (path to JSON file) or Object (inline configuration)
+**Default**: `./.mcp.json`
+
+MCP server configuration location or inline definition.
+
+**File path**:
+```json
+{
+  "mcpServers": "./.mcp.json"
+}
+```
+
+**Inline configuration**:
+```json
+{
+  "mcpServers": {
+    "github": {
+      "command": "node",
+      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/github-mcp.js"],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+**Use cases**:
+- Simple plugins: Single inline server (< 20 lines)
+- Complex plugins: External `.mcp.json` file
+- Multiple servers: Always use external file
+
+## Path Resolution
+
+### Relative Path Rules
+
+All paths in component fields must follow these rules:
+
+1. **Must be relative**: No absolute paths
+2. **Must start with `./`**: Indicates relative to plugin root
+3. **Cannot use `../`**: No parent directory navigation
+4. **Forward slashes only**: Even on Windows
+
+**Examples**:
+- ✅ `"./commands"`
+- ✅ `"./src/commands"`
+- ✅ `"./configs/hooks.json"`
+- ❌ `"/Users/name/plugin/commands"`
+- ❌ `"commands"` (missing `./`)
+- ❌ `"../shared/commands"`
+- ❌ `".\\commands"` (backslash)
+
+### Resolution Order
+
+When Claude Code loads components:
+
+1. **Default directories**: Scans standard locations first
+   - `./commands/`
+   - `./agents/`
+   - `./skills/`
+   - `./hooks/hooks.json`
+   - `./.mcp.json`
+
+2. **Custom paths**: Scans paths specified in manifest
+   - Paths from `commands` field
+   - Paths from `agents` field
+   - Files from `hooks` and `mcpServers` fields
+
+3. **Merge behavior**: Components from all locations load
+   - No overwriting
+   - All discovered components register
+   - Name conflicts cause errors
+
+## Validation
+
+### Manifest Validation
+
+Claude Code validates the manifest on plugin load:
+
+**Syntax validation**:
+- Valid JSON format
+- No syntax errors
+- Correct field types
+
+**Field validation**:
+- `name` field present and valid format
+- `version` follows semantic versioning (if present)
+- Paths are relative with `./` prefix
+- URLs are valid (if present)
+
+**Component validation**:
+- Referenced paths exist
+- Hook and MCP configurations are valid
+- No circular dependencies
+
+### Common Validation Errors
+
+**Invalid name format**:
+```json
+{
+  "name": "My Plugin"  // ❌ Contains spaces
+}
+```
+Fix: Use kebab-case
+```json
+{
+  "name": "my-plugin"  // ✅
+}
+```
+
+**Absolute path**:
+```json
+{
+  "commands": "/Users/name/commands"  // ❌ Absolute path
+}
+```
+Fix: Use relative path
+```json
+{
+  "commands": "./commands"  // ✅
+}
+```
+
+**Missing ./ prefix**:
+```json
+{
+  "hooks": "hooks/hooks.json"  // ❌ No ./
+}
+```
+Fix: Add ./ prefix
+```json
+{
+  "hooks": "./hooks/hooks.json"  // ✅
+}
+```
+
+**Invalid version**:
+```json
+{
+  "version": "1.0"  // ❌ Not semantic versioning
+}
+```
+Fix: Use MAJOR.MINOR.PATCH
+```json
+{
+  "version": "1.0.0"  // ✅
+}
+```
+
+## Minimal vs. Complete Examples
+
+### Minimal Plugin
+
+Bare minimum for a working plugin:
+
+```json
+{
+  "name": "hello-world"
+}
+```
+
+Relies entirely on default directory discovery.
+
+### Recommended Plugin
+
+Good metadata for distribution:
+
+```json
+{
+  "name": "code-review-assistant",
+  "version": "1.0.0",
+  "description": "Automates code review with style checks and suggestions",
+  "author": {
+    "name": "Jane Developer",
+    "email": "jane@example.com"
+  },
+  "homepage": "https://docs.example.com/code-review",
+  "repository": "https://github.com/janedev/code-review-assistant",
+  "license": "MIT",
+  "keywords": ["code-review", "automation", "quality", "ci-cd"]
+}
+```
+
+### Complete Plugin
+
+Full configuration with all features:
+
+```json
+{
+  "name": "enterprise-devops",
+  "version": "2.3.1",
+  "description": "Comprehensive DevOps automation for enterprise CI/CD pipelines",
+  "author": {
+    "name": "DevOps Team",
+    "email": "devops@company.com",
+    "url": "https://company.com/devops"
+  },
+  "homepage": "https://docs.company.com/plugins/devops",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/company/devops-plugin.git"
+  },
+  "license": "Apache-2.0",
+  "keywords": [
+    "devops",
+    "ci-cd",
+    "automation",
+    "kubernetes",
+    "docker",
+    "deployment"
+  ],
+  "commands": [
+    "./commands",
+    "./admin-commands"
+  ],
+  "agents": "./specialized-agents",
+  "hooks": "./config/hooks.json",
+  "mcpServers": "./.mcp.json"
+}
+```
+
+## Best Practices
+
+### Metadata
+
+1. **Always include version**: Track changes and updates
+2. **Write clear descriptions**: Help users understand plugin purpose
+3. **Provide contact information**: Enable user support
+4. **Link to documentation**: Reduce support burden
+5. **Choose appropriate license**: Match project goals
+
+### Paths
+
+1. **Use defaults when possible**: Minimize configuration
+2. **Organize logically**: Group related components
+3. **Document custom paths**: Explain why non-standard layout used
+4. **Test path resolution**: Verify on multiple systems
+
+### Maintenance
+
+1. **Bump version on changes**: Follow semantic versioning
+2. **Update keywords**: Reflect new functionality
+3. **Keep description current**: Match actual capabilities
+4. **Maintain changelog**: Track version history
+5. **Update repository links**: Keep URLs current
+
+### Distribution
+
+1. **Complete metadata before publishing**: All fields filled
+2. **Test on clean install**: Verify plugin works without dev environment
+3. **Validate manifest**: Use validation tools
+4. **Include README**: Document installation and usage
+5. **Specify license file**: Include LICENSE file in plugin root