diff options
Diffstat (limited to '')
3 files changed, 1435 insertions, 0 deletions
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 |