1# Advanced Plugin Example
2 
3A complex, enterprise-grade plugin with MCP integration and advanced organization.
4 
5## Directory Structure
6 
7```
8enterprise-devops/
9├── .claude-plugin/
10│   └── plugin.json
11├── commands/
12│   ├── ci/
13│   │   ├── build.md
14│   │   ├── test.md
15│   │   └── deploy.md
16│   ├── monitoring/
17│   │   ├── status.md
18│   │   └── logs.md
19│   └── admin/
20│       ├── configure.md
21│       └── manage.md
22├── agents/
23│   ├── orchestration/
24│   │   ├── deployment-orchestrator.md
25│   │   └── rollback-manager.md
26│   └── specialized/
27│       ├── kubernetes-expert.md
28│       ├── terraform-expert.md
29│       └── security-auditor.md
30├── skills/
31│   ├── kubernetes-ops/
32│   │   ├── SKILL.md
33│   │   ├── references/
34│   │   │   ├── deployment-patterns.md
35│   │   │   ├── troubleshooting.md
36│   │   │   └── security.md
37│   │   ├── examples/
38│   │   │   ├── basic-deployment.yaml
39│   │   │   ├── stateful-set.yaml
40│   │   │   └── ingress-config.yaml
41│   │   └── scripts/
42│   │       ├── validate-manifest.sh
43│   │       └── health-check.sh
44│   ├── terraform-iac/
45│   │   ├── SKILL.md
46│   │   ├── references/
47│   │   │   └── best-practices.md
48│   │   └── examples/
49│   │       └── module-template/
50│   └── ci-cd-pipelines/
51│       ├── SKILL.md
52│       └── references/
53│           └── pipeline-patterns.md
54├── hooks/
55│   ├── hooks.json
56│   └── scripts/
57│       ├── security/
58│       │   ├── scan-secrets.sh
59│       │   ├── validate-permissions.sh
60│       │   └── audit-changes.sh
61│       ├── quality/
62│       │   ├── check-config.sh
63│       │   └── verify-tests.sh
64│       └── workflow/
65│           ├── notify-team.sh
66│           └── update-status.sh
67├── .mcp.json
68├── servers/
69│   ├── kubernetes-mcp/
70│   │   ├── index.js
71│   │   ├── package.json
72│   │   └── lib/
73│   ├── terraform-mcp/
74│   │   ├── main.py
75│   │   └── requirements.txt
76│   └── github-actions-mcp/
77│       ├── server.js
78│       └── package.json
79├── lib/
80│   ├── core/
81│   │   ├── logger.js
82│   │   ├── config.js
83│   │   └── auth.js
84│   ├── integrations/
85│   │   ├── slack.js
86│   │   ├── pagerduty.js
87│   │   └── datadog.js
88│   └── utils/
89│       ├── retry.js
90│       └── validation.js
91└── config/
92    ├── environments/
93    │   ├── production.json
94    │   ├── staging.json
95    │   └── development.json
96    └── templates/
97        ├── deployment.yaml
98        └── service.yaml
99```
100 
101## File Contents
102 
103### .claude-plugin/plugin.json
104 
105```json
106{
107  "name": "enterprise-devops",
108  "version": "2.3.1",
109  "description": "Comprehensive DevOps automation for enterprise CI/CD pipelines, infrastructure management, and monitoring",
110  "author": {
111    "name": "DevOps Platform Team",
112    "email": "[email protected]",
113    "url": "https://company.com/teams/devops"
114  },
115  "homepage": "https://docs.company.com/plugins/devops",
116  "repository": {
117    "type": "git",
118    "url": "https://github.com/company/devops-plugin.git"
119  },
120  "license": "Apache-2.0",
121  "keywords": [
122    "devops",
123    "ci-cd",
124    "kubernetes",
125    "terraform",
126    "automation",
127    "infrastructure",
128    "deployment",
129    "monitoring"
130  ],
131  "commands": [
132    "./commands/ci",
133    "./commands/monitoring",
134    "./commands/admin"
135  ],
136  "agents": [
137    "./agents/orchestration",
138    "./agents/specialized"
139  ],
140  "hooks": "./hooks/hooks.json",
141  "mcpServers": "./.mcp.json"
142}
143```
144 
145### .mcp.json
146 
147```json
148{
149  "mcpServers": {
150    "kubernetes": {
151      "command": "node",
152      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/kubernetes-mcp/index.js"],
153      "env": {
154        "KUBECONFIG": "${KUBECONFIG}",
155        "K8S_NAMESPACE": "${K8S_NAMESPACE:-default}"
156      }
157    },
158    "terraform": {
159      "command": "python",
160      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/terraform-mcp/main.py"],
161      "env": {
162        "TF_STATE_BUCKET": "${TF_STATE_BUCKET}",
163        "AWS_REGION": "${AWS_REGION}"
164      }
165    },
166    "github-actions": {
167      "command": "node",
168      "args": ["${CLAUDE_PLUGIN_ROOT}/servers/github-actions-mcp/server.js"],
169      "env": {
170        "GITHUB_TOKEN": "${GITHUB_TOKEN}",
171        "GITHUB_ORG": "${GITHUB_ORG}"
172      }
173    }
174  }
175}
176```
177 
178### commands/ci/build.md
179 
180```markdown
181---
182name: build
183description: Trigger and monitor CI build pipeline
184---
185 
186# Build Command
187 
188Trigger CI/CD build pipeline and monitor progress in real-time.
189 
190## Process
191 
1921. **Validation**: Check prerequisites
193   - Verify branch status
194   - Check for uncommitted changes
195   - Validate configuration files
196 
1972. **Trigger**: Start build via MCP server
198   \`\`\`javascript
199   // Uses github-actions MCP server
200   const build = await tools.github_actions_trigger_workflow({
201     workflow: 'build.yml',
202     ref: currentBranch
203   })
204   \`\`\`
205 
2063. **Monitor**: Track build progress
207   - Display real-time logs
208   - Show test results as they complete
209   - Alert on failures
210 
2114. **Report**: Summarize results
212   - Build status
213   - Test coverage
214   - Performance metrics
215   - Deploy readiness
216 
217## Integration
218 
219After successful build:
220- Offer to deploy to staging
221- Suggest performance optimizations
222- Generate deployment checklist
223```
224 
225### agents/orchestration/deployment-orchestrator.md
226 
227```markdown
228---
229description: Orchestrates complex multi-environment deployments with rollback capabilities and health monitoring
230capabilities:
231  - Plan and execute multi-stage deployments
232  - Coordinate service dependencies
233  - Monitor deployment health
234  - Execute automated rollbacks
235  - Manage deployment approvals
236---
237 
238# Deployment Orchestrator Agent
239 
240Specialized agent for orchestrating complex deployments across multiple environments.
241 
242## Expertise
243 
244- **Deployment strategies**: Blue-green, canary, rolling updates
245- **Dependency management**: Service startup ordering, dependency injection
246- **Health monitoring**: Service health checks, metric validation
247- **Rollback automation**: Automatic rollback on failure detection
248- **Approval workflows**: Multi-stage approval processes
249 
250## Orchestration Process
251 
2521. **Planning Phase**
253   - Analyze deployment requirements
254   - Identify service dependencies
255   - Generate deployment plan
256   - Calculate rollback strategy
257 
2582. **Validation Phase**
259   - Verify environment readiness
260   - Check resource availability
261   - Validate configurations
262   - Run pre-deployment tests
263 
2643. **Execution Phase**
265   - Deploy services in dependency order
266   - Monitor health after each stage
267   - Validate metrics and logs
268   - Proceed to next stage on success
269 
2704. **Verification Phase**
271   - Run smoke tests
272   - Validate service integration
273   - Check performance metrics
274   - Confirm deployment success
275 
2765. **Rollback Phase** (if needed)
277   - Detect failure conditions
278   - Execute rollback plan
279   - Restore previous state
280   - Notify stakeholders
281 
282## MCP Integration
283 
284Uses multiple MCP servers:
285- `kubernetes`: Deploy and manage containers
286- `terraform`: Provision infrastructure
287- `github-actions`: Trigger deployment pipelines
288 
289## Monitoring Integration
290 
291Integrates with monitoring tools via lib:
292\`\`\`javascript
293const { DatadogClient } = require('${CLAUDE_PLUGIN_ROOT}/lib/integrations/datadog')
294const metrics = await DatadogClient.getMetrics(service, timeRange)
295\`\`\`
296 
297## Notification Integration
298 
299Sends updates via Slack and PagerDuty:
300\`\`\`javascript
301const { SlackClient } = require('${CLAUDE_PLUGIN_ROOT}/lib/integrations/slack')
302await SlackClient.notify({
303  channel: '#deployments',
304  message: 'Deployment started',
305  metadata: deploymentPlan
306})
307\`\`\`
308```
309 
310### skills/kubernetes-ops/SKILL.md
311 
312```markdown
313---
314name: Kubernetes Operations
315description: 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.
316version: 2.0.0
317---
318 
319# Kubernetes Operations
320 
321Comprehensive operational knowledge for managing Kubernetes clusters and workloads.
322 
323## Overview
324 
325Manage Kubernetes infrastructure effectively through:
326- Deployment strategies and patterns
327- Resource configuration and optimization
328- Troubleshooting and debugging
329- Security best practices
330- Performance tuning
331 
332## Core Concepts
333 
334### Resource Management
335 
336**Deployments**: Use for stateless applications
337- Rolling updates for zero-downtime deployments
338- Rollback capabilities for failed deployments
339- Replica management for scaling
340 
341**StatefulSets**: Use for stateful applications
342- Stable network identities
343- Persistent storage
344- Ordered deployment and scaling
345 
346**DaemonSets**: Use for node-level services
347- Log collectors
348- Monitoring agents
349- Network plugins
350 
351### Configuration
352 
353**ConfigMaps**: Store non-sensitive configuration
354- Environment-specific settings
355- Application configuration files
356- Feature flags
357 
358**Secrets**: Store sensitive data
359- API keys and tokens
360- Database credentials
361- TLS certificates
362 
363Use external secret management (Vault, AWS Secrets Manager) for production.
364 
365### Networking
366 
367**Services**: Expose applications internally
368- ClusterIP for internal communication
369- NodePort for external access (non-production)
370- LoadBalancer for external access (production)
371 
372**Ingress**: HTTP/HTTPS routing
373- Path-based routing
374- Host-based routing
375- TLS termination
376- Load balancing
377 
378## Deployment Strategies
379 
380### Rolling Update
381 
382Default strategy, gradual replacement:
383\`\`\`yaml
384strategy:
385  type: RollingUpdate
386  rollingUpdate:
387    maxSurge: 1
388    maxUnavailable: 0
389\`\`\`
390 
391**When to use**: Standard deployments, minor updates
392 
393### Recreate
394 
395Stop all pods, then create new ones:
396\`\`\`yaml
397strategy:
398  type: Recreate
399\`\`\`
400 
401**When to use**: Stateful apps that can't run multiple versions
402 
403### Blue-Green
404 
405Run two complete environments, switch traffic:
4061. Deploy new version (green)
4072. Test green environment
4083. Switch traffic to green
4094. Keep blue for quick rollback
410 
411**When to use**: Critical services, need instant rollback
412 
413### Canary
414 
415Gradually roll out to subset of users:
4161. Deploy canary version (10% traffic)
4172. Monitor metrics and errors
4183. Increase traffic gradually
4194. Complete rollout or rollback
420 
421**When to use**: High-risk changes, want gradual validation
422 
423## Resource Configuration
424 
425### Resource Requests and Limits
426 
427Always set for production workloads:
428\`\`\`yaml
429resources:
430  requests:
431    memory: "256Mi"
432    cpu: "250m"
433  limits:
434    memory: "512Mi"
435    cpu: "500m"
436\`\`\`
437 
438**Requests**: Guaranteed resources
439**Limits**: Maximum allowed resources
440 
441### Health Checks
442 
443Essential for reliability:
444\`\`\`yaml
445livenessProbe:
446  httpGet:
447    path: /health
448    port: 8080
449  initialDelaySeconds: 30
450  periodSeconds: 10
451 
452readinessProbe:
453  httpGet:
454    path: /ready
455    port: 8080
456  initialDelaySeconds: 5
457  periodSeconds: 5
458\`\`\`
459 
460**Liveness**: Restart unhealthy pods
461**Readiness**: Remove unready pods from service
462 
463## Troubleshooting
464 
465### Common Issues
466 
4671. **Pods not starting**
468   - Check: `kubectl describe pod <name>`
469   - Look for: Image pull errors, resource constraints
470   - Fix: Verify image name, increase resources
471 
4722. **Service not reachable**
473   - Check: `kubectl get svc`, `kubectl get endpoints`
474   - Look for: No endpoints, wrong selector
475   - Fix: Verify pod labels match service selector
476 
4773. **High memory usage**
478   - Check: `kubectl top pods`
479   - Look for: Pods near memory limit
480   - Fix: Increase limits, optimize application
481 
4824. **Frequent restarts**
483   - Check: `kubectl get pods`, `kubectl logs <name>`
484   - Look for: Liveness probe failures, OOMKilled
485   - Fix: Adjust health checks, increase memory
486 
487### Debugging Commands
488 
489Get pod details:
490\`\`\`bash
491kubectl describe pod <name>
492kubectl logs <name>
493kubectl logs <name> --previous  # logs from crashed container
494\`\`\`
495 
496Execute commands in pod:
497\`\`\`bash
498kubectl exec -it <name> -- /bin/sh
499kubectl exec <name> -- env
500\`\`\`
501 
502Check resource usage:
503\`\`\`bash
504kubectl top nodes
505kubectl top pods
506\`\`\`
507 
508## Security Best Practices
509 
510### Pod Security
511 
512- Run as non-root user
513- Use read-only root filesystem
514- Drop unnecessary capabilities
515- Use security contexts
516 
517Example:
518\`\`\`yaml
519securityContext:
520  runAsNonRoot: true
521  runAsUser: 1000
522  readOnlyRootFilesystem: true
523  capabilities:
524    drop:
525      - ALL
526\`\`\`
527 
528### Network Policies
529 
530Restrict pod communication:
531\`\`\`yaml
532apiVersion: networking.k8s.io/v1
533kind: NetworkPolicy
534metadata:
535  name: api-allow
536spec:
537  podSelector:
538    matchLabels:
539      app: api
540  ingress:
541    - from:
542      - podSelector:
543          matchLabels:
544            app: frontend
545\`\`\`
546 
547### Secrets Management
548 
549- Never commit secrets to git
550- Use external secret managers
551- Rotate secrets regularly
552- Limit secret access with RBAC
553 
554## Performance Optimization
555 
556### Resource Tuning
557 
5581. **Start conservative**: Set low limits initially
5592. **Monitor usage**: Track actual resource consumption
5603. **Adjust gradually**: Increase based on metrics
5614. **Set appropriate requests**: Match typical usage
5625. **Set safe limits**: 2x requests for headroom
563 
564### Horizontal Pod Autoscaling
565 
566Automatically scale based on metrics:
567\`\`\`yaml
568apiVersion: autoscaling/v2
569kind: HorizontalPodAutoscaler
570metadata:
571  name: api-hpa
572spec:
573  scaleTargetRef:
574    apiVersion: apps/v1
575    kind: Deployment
576    name: api
577  minReplicas: 2
578  maxReplicas: 10
579  metrics:
580    - type: Resource
581      resource:
582        name: cpu
583        target:
584          type: Utilization
585          averageUtilization: 70
586\`\`\`
587 
588## MCP Server Integration
589 
590This skill works with the kubernetes MCP server for operations:
591 
592**List pods**:
593\`\`\`javascript
594const pods = await tools.k8s_list_pods({ namespace: 'default' })
595\`\`\`
596 
597**Get pod logs**:
598\`\`\`javascript
599const logs = await tools.k8s_get_logs({ pod: 'api-xyz', container: 'app' })
600\`\`\`
601 
602**Apply manifests**:
603\`\`\`javascript
604const result = await tools.k8s_apply_manifest({ file: 'deployment.yaml' })
605\`\`\`
606 
607## Detailed References
608 
609For in-depth information:
610- **Deployment patterns**: `references/deployment-patterns.md`
611- **Troubleshooting guide**: `references/troubleshooting.md`
612- **Security hardening**: `references/security.md`
613 
614## Example Manifests
615 
616For copy-paste examples:
617- **Basic deployment**: `examples/basic-deployment.yaml`
618- **StatefulSet**: `examples/stateful-set.yaml`
619- **Ingress config**: `examples/ingress-config.yaml`
620 
621## Validation Scripts
622 
623For manifest validation:
624\`\`\`bash
625bash ${CLAUDE_PLUGIN_ROOT}/skills/kubernetes-ops/scripts/validate-manifest.sh deployment.yaml
626\`\`\`
627```
628 
629### hooks/hooks.json
630 
631```json
632{
633  "PreToolUse": [
634    {
635      "matcher": "Write|Edit",
636      "hooks": [
637        {
638          "type": "command",
639          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security/scan-secrets.sh",
640          "timeout": 30
641        }
642      ]
643    },
644    {
645      "matcher": "Bash",
646      "hooks": [
647        {
648          "type": "prompt",
649          "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.",
650          "timeout": 20
651        }
652      ]
653    }
654  ],
655  "PostToolUse": [
656    {
657      "matcher": "Bash",
658      "hooks": [
659        {
660          "type": "command",
661          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow/update-status.sh",
662          "timeout": 15
663        }
664      ]
665    }
666  ],
667  "Stop": [
668    {
669      "matcher": ".*",
670      "hooks": [
671        {
672          "type": "command",
673          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/quality/check-config.sh",
674          "timeout": 45
675        },
676        {
677          "type": "command",
678          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/workflow/notify-team.sh",
679          "timeout": 30
680        }
681      ]
682    }
683  ],
684  "SessionStart": [
685    {
686      "matcher": ".*",
687      "hooks": [
688        {
689          "type": "command",
690          "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/scripts/security/validate-permissions.sh",
691          "timeout": 20
692        }
693      ]
694    }
695  ]
696}
697```
698 
699## Key Features
700 
701### Multi-Level Organization
702 
703**Commands**: Organized by function (CI, monitoring, admin)
704**Agents**: Separated by role (orchestration vs. specialized)
705**Skills**: Rich resources (references, examples, scripts)
706 
707### MCP Integration
708 
709Three custom MCP servers:
710- **Kubernetes**: Cluster operations
711- **Terraform**: Infrastructure provisioning
712- **GitHub Actions**: CI/CD automation
713 
714### Shared Libraries
715 
716Reusable code in `lib/`:
717- **Core**: Common utilities (logging, config, auth)
718- **Integrations**: External services (Slack, Datadog)
719- **Utils**: Helper functions (retry, validation)
720 
721### Configuration Management
722 
723Environment-specific configs in `config/`:
724- **Environments**: Per-environment settings
725- **Templates**: Reusable deployment templates
726 
727### Security Automation
728 
729Multiple security hooks:
730- Secret scanning before writes
731- Permission validation on session start
732- Configuration auditing on completion
733 
734### Monitoring Integration
735 
736Built-in monitoring via lib integrations:
737- Datadog for metrics
738- PagerDuty for alerts
739- Slack for notifications
740 
741## Use Cases
742 
7431. **Multi-environment deployments**: Orchestrated rollouts across dev/staging/prod
7442. **Infrastructure as code**: Terraform automation with state management
7453. **CI/CD automation**: Build, test, deploy pipelines
7464. **Monitoring and observability**: Integrated metrics and alerting
7475. **Security enforcement**: Automated security scanning and validation
7486. **Team collaboration**: Slack notifications and status updates
749 
750## When to Use This Pattern
751 
752- Large-scale enterprise deployments
753- Multiple environment management
754- Complex CI/CD workflows
755- Integrated monitoring requirements
756- Security-critical infrastructure
757- Team collaboration needs
758 
759## Scaling Considerations
760 
761- **Performance**: Separate MCP servers for parallel operations
762- **Organization**: Multi-level directories for scalability
763- **Maintainability**: Shared libraries reduce duplication
764- **Flexibility**: Environment configs enable customization
765- **Security**: Layered security hooks and validation
766