@amsterdamdatalabs/enact-extensions 0.1.0 → 0.1.3

package/extensions/plugin-dev/skills/plugin-structure/examples/advanced-plugin.md

@@ -0,0 +1,774 @@
+# 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-ops
+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.
+---
+
+# 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
+{
+  "hooks": {
+    "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