# 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 ` - 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 ` - Look for: Liveness probe failures, OOMKilled - Fix: Adjust health checks, increase memory ### Debugging Commands Get pod details: \`\`\`bash kubectl describe pod kubectl logs kubectl logs --previous # logs from crashed container \`\`\` Execute commands in pod: \`\`\`bash kubectl exec -it -- /bin/sh kubectl exec -- 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