dpnmw/agents
1
0
Fork 0
mirror of https://github.com/wshobson/agents.git synced 2026-03-18 09:37:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #74 from wshobson/feature/consolidate-commands

Browse Source 
Repository Consolidation: Merge Commands into Agents
This commit is contained in:
Seth Hobson
2025-10-08 19:16:12 -04:00
committed by GitHub
parent a80cfd0f53 ad8792253d
commit bcaf626904
144 changed files with 37482 additions and 447 deletions
Download Patch File Download Diff File Expand all files Collapse all files

233
MIGRATION.md Normal file
View File

@@ -0,0 +1,233 @@
# Migration Guide
## Repository Consolidation
This guide helps you migrate from the previous repository structure to the new unified `agents` repository.
## What Changed?
### Repository Structure
**Previous Structure** (before consolidation):
```
~/.claude/
├── agents/ # wshobson/agents (agents only)
│ ├── backend-architect.md
│ ├── frontend-developer.md
│ └── ... (83 agent files in root)
└── commands/ # wshobson/commands (separate repo)
├── feature-development.md
├── api-scaffold.md
└── ... (workflow and tool files)
```
**New Unified Structure** (current):
```
~/.claude/
└── agents/ # wshobson/agents (everything unified)
├── agents/ # All agent definitions
│ ├── backend-architect.md
│ ├── frontend-developer.md
│ └── ... (83 files)
├── workflows/ # Multi-agent orchestrators
│ ├── feature-development.md
│ ├── security-hardening.md
│ └── ... (15 files)
├── tools/ # Development utilities
│ ├── api-scaffold.md
│ ├── security-scan.md
│ └── ... (42 files)
└── README.md
```
### Key Changes Summary
| What Changed | Before | After |
|--------------|--------|-------|
| **Agents location** | Root of `agents/` repo | `agents/agents/` subdirectory |
| **Workflows location** | Separate `commands/` repo | `agents/workflows/` subdirectory |
| **Tools location** | Separate `commands/` repo | `agents/tools/` subdirectory |
| **Repository count** | 2 repositories | 1 unified repository |
## Migration Steps
### Step 1: Update Your Agents Repository
```bash
cd ~/.claude/agents
git pull origin main
```
This will:
- Move all agent files into the `agents/` subdirectory
- Add the `workflows/` directory with 15 workflow orchestrators
- Add the `tools/` directory with 42 development tools
### Step 2: Remove Old Commands Repository (If Installed)
If you previously had the `commands` repository installed:
```bash
# Check if it exists
ls ~/.claude/commands
# If it exists, remove it
rm -rf ~/.claude/commands
```
The `commands` repository is now deprecated. All functionality has been moved to the unified `agents` repository.
### Step 3: Verify Installation
Check that your directory structure is correct:
```bash
ls -la ~/.claude/agents
```
You should see:
```
agents/
workflows/
tools/
README.md
LICENSE
```
### Step 4: Update Your Workflow
No changes needed for agent invocations, but workflows and tools now use prefixed commands.
## Command Syntax Changes
### Workflows (formerly in commands repo)
**Old Syntax**:
```bash
/feature-development implement user authentication
/commands:feature-development implement user authentication
```
**New Syntax**:
```bash
/workflows:feature-development implement user authentication
```
### Tools (formerly in commands repo)
**Old Syntax**:
```bash
/api-scaffold create user endpoints
/commands:api-scaffold create user endpoints
```
**New Syntax**:
```bash
/tools:api-scaffold create user endpoints
```
### Agents (no change)
Agent invocations work exactly as before:
```bash
"Use backend-architect to design the API"
"Have security-auditor review this code"
"Get performance-engineer to optimize this query"
```
## What Stays the Same?
✅ All 83 agents work identically
✅ Agent capabilities unchanged
✅ Direct agent invocation syntax unchanged
✅ All workflow and tool functionality preserved
✅ Multi-agent orchestration patterns unchanged
## What's Different?
⚠️ Agent files moved to `agents/` subdirectory
⚠️ Workflow command prefix changed to `/workflows:`
⚠️ Tool command prefix changed to `/tools:`
⚠️ Commands repository deprecated
## Common Migration Issues
### Issue: "Command not found" errors
**Symptom**: `/feature-development` no longer works
**Solution**: Use the new prefix syntax:
```bash
/workflows:feature-development
```
### Issue: Agents not loading
**Symptom**: Claude Code doesn't recognize agents
**Solution**:
1. Verify structure: `ls ~/.claude/agents/agents/`
2. Restart Claude Code
3. Check for errors in Claude Code logs
### Issue: Both repos installed
**Symptom**: Duplicate commands showing up
**Solution**: Remove the old commands repository:
```bash
rm -rf ~/.claude/commands
```
## Testing Your Migration
After migrating, test these commands to verify everything works:
### Test Workflows
```bash
/workflows:feature-development test feature
/workflows:security-hardening scan project
```
### Test Tools
```bash
/tools:api-scaffold create test endpoint
/tools:code-explain describe this function
```
### Test Agents
```bash
"Use backend-architect to review the architecture"
"Have frontend-developer suggest improvements"
```
## Rollback Instructions
If you need to rollback to the previous structure:
```bash
cd ~/.claude/agents
git checkout <previous-commit-hash>
```
Or reinstall the old commands repository:
```bash
cd ~/.claude
git clone https://github.com/wshobson/commands.git
```
Note: The `commands` repository is deprecated and won't receive updates.
## Need Help?
- **Documentation**: [README.md](README.md)
- **Issues**: https://github.com/wshobson/agents/issues
- **Claude Code Docs**: https://docs.anthropic.com/en/docs/claude-code
## Timeline
- **Before**: Two separate repositories (`agents` + `commands`)
- **Now**: One unified repository (`agents` with subdirectories)
- **Future**: Plugin marketplace integration (coming soon)

746
README.md
View File

@@ -1,526 +1,379 @@
# Claude Code Subagents Collection # Claude Code Workflows & Agents
A comprehensive collection of 83 specialized AI subagents for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), providing domain-specific expertise across software development, infrastructure, and business operations. A comprehensive production-ready system combining **83 specialized AI agents**, **15 multi-agent workflow orchestrators**, and **42 development tools** for [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
> **⚠️ Major Update**: This repository has been restructured. If you're upgrading from a previous version, see the [Migration Guide](#migration-guide) below.
## Quick Links
- [Installation](#installation) - New users start here
- [Migration Guide](#migration-guide) - **Upgrading from previous version? Read this first**
- [Workflow Commands](#workflow-commands) - Multi-agent orchestration
- [Development Tools](#development-tools) - Single-purpose utilities
- [Agent Categories](#agent-categories) - All 83 agents organized by domain
## Overview ## Overview
This repository provides production-ready subagents that extend Claude Code's capabilities with specialized knowledge. Each subagent incorporates: This unified repository provides everything needed for intelligent automation and multi-agent orchestration across modern software development:
- Current industry best practices and standards (2024/2025) - **83 Specialized Agents** - Domain experts with deep knowledge (architecture, languages, infrastructure, quality, data/AI, business)
- Production-ready patterns and enterprise architectures - **15 Workflow Orchestrators** - Multi-agent coordination systems for complex operations
- Deep domain expertise with 8-12 capability areas per agent - **42 Development Tools** - Focused utilities for specific tasks
- Modern technology stacks and frameworks
- Optimized model selection based on task complexity
## Agent Categories ## System Requirements
### Architecture & System Design - [Claude Code](https://docs.anthropic.com/en/docs/claude-code) installed and configured
- Git for repository management
#### Core Architecture
| Agent | Model | Description |
|-------|-------|-------------|
| [backend-architect](backend-architect.md) | opus | RESTful API design, microservice boundaries, database schemas |
| [frontend-developer](frontend-developer.md) | sonnet | React components, responsive layouts, client-side state management |
| [graphql-architect](graphql-architect.md) | opus | GraphQL schemas, resolvers, federation architecture |
| [architect-reviewer](architect-review.md) | opus | Architectural consistency analysis and pattern validation |
| [cloud-architect](cloud-architect.md) | opus | AWS/Azure/GCP infrastructure design and cost optimization |
| [hybrid-cloud-architect](hybrid-cloud-architect.md) | opus | Multi-cloud strategies across cloud and on-premises environments |
| [kubernetes-architect](kubernetes-architect.md) | opus | Cloud-native infrastructure with Kubernetes and GitOps |
#### UI/UX & Mobile
| Agent | Model | Description |
|-------|-------|-------------|
| [ui-ux-designer](ui-ux-designer.md) | sonnet | Interface design, wireframes, design systems |
| [ui-visual-validator](ui-visual-validator.md) | sonnet | Visual regression testing and UI verification |
| [mobile-developer](mobile-developer.md) | sonnet | React Native and Flutter application development |
| [ios-developer](ios-developer.md) | sonnet | Native iOS development with Swift/SwiftUI |
| [flutter-expert](flutter-expert.md) | sonnet | Advanced Flutter development with state management |
### Programming Languages
#### Systems & Low-Level
| Agent | Model | Description |
|-------|-------|-------------|
| [c-pro](c-pro.md) | sonnet | System programming with memory management and OS interfaces |
| [cpp-pro](cpp-pro.md) | sonnet | Modern C++ with RAII, smart pointers, STL algorithms |
| [rust-pro](rust-pro.md) | sonnet | Memory-safe systems programming with ownership patterns |
| [golang-pro](golang-pro.md) | sonnet | Concurrent programming with goroutines and channels |
#### Web & Application
| Agent | Model | Description |
|-------|-------|-------------|
| [javascript-pro](javascript-pro.md) | sonnet | Modern JavaScript with ES6+, async patterns, Node.js |
| [typescript-pro](typescript-pro.md) | sonnet | Advanced TypeScript with type systems and generics |
| [python-pro](python-pro.md) | sonnet | Python development with advanced features and optimization |
| [ruby-pro](ruby-pro.md) | sonnet | Ruby with metaprogramming, Rails patterns, gem development |
| [php-pro](php-pro.md) | sonnet | Modern PHP with frameworks and performance optimization |
#### Enterprise & JVM
| Agent | Model | Description |
|-------|-------|-------------|
| [java-pro](java-pro.md) | sonnet | Modern Java with streams, concurrency, JVM optimization |
| [scala-pro](scala-pro.md) | sonnet | Enterprise Scala with functional programming and distributed systems |
| [csharp-pro](csharp-pro.md) | sonnet | C# development with .NET frameworks and patterns |
#### Specialized Platforms
| Agent | Model | Description |
|-------|-------|-------------|
| [elixir-pro](elixir-pro.md) | sonnet | Elixir with OTP patterns and Phoenix frameworks |
| [unity-developer](unity-developer.md) | sonnet | Unity game development and optimization |
| [minecraft-bukkit-pro](minecraft-bukkit-pro.md) | sonnet | Minecraft server plugin development |
| [sql-pro](sql-pro.md) | sonnet | Complex SQL queries and database optimization |
### Infrastructure & Operations
#### DevOps & Deployment
| Agent | Model | Description |
|-------|-------|-------------|
| [devops-troubleshooter](devops-troubleshooter.md) | sonnet | Production debugging, log analysis, deployment troubleshooting |
| [deployment-engineer](deployment-engineer.md) | sonnet | CI/CD pipelines, containerization, cloud deployments |
| [terraform-specialist](terraform-specialist.md) | opus | Infrastructure as Code with Terraform modules and state management |
| [dx-optimizer](dx-optimizer.md) | sonnet | Developer experience optimization and tooling improvements |
#### Database Management
| Agent | Model | Description |
|-------|-------|-------------|
| [database-optimizer](database-optimizer.md) | opus | Query optimization, index design, migration strategies |
| [database-admin](database-admin.md) | sonnet | Database operations, backup, replication, monitoring |
#### Incident Response & Network
| Agent | Model | Description |
|-------|-------|-------------|
| [incident-responder](incident-responder.md) | opus | Production incident management and resolution |
| [network-engineer](network-engineer.md) | sonnet | Network debugging, load balancing, traffic analysis |
### Quality Assurance & Security
#### Code Quality & Review
| Agent | Model | Description |
|-------|-------|-------------|
| [code-reviewer](code-reviewer.md) | opus | Code review with security focus and production reliability |
| [security-auditor](security-auditor.md) | opus | Vulnerability assessment and OWASP compliance |
| [backend-security-coder](backend-security-coder.md) | opus | Secure backend coding practices, API security implementation |
| [frontend-security-coder](frontend-security-coder.md) | opus | XSS prevention, CSP implementation, client-side security |
| [mobile-security-coder](mobile-security-coder.md) | opus | Mobile security patterns, WebView security, biometric auth |
| [architect-reviewer](architect-review.md) | opus | Architectural consistency and pattern validation |
#### Testing & Debugging
| Agent | Model | Description |
|-------|-------|-------------|
| [test-automator](test-automator.md) | sonnet | Comprehensive test suite creation (unit, integration, e2e) |
| [tdd-orchestrator](tdd-orchestrator.md) | sonnet | Test-Driven Development methodology guidance |
| [debugger](debugger.md) | sonnet | Error resolution and test failure analysis |
| [error-detective](error-detective.md) | sonnet | Log analysis and error pattern recognition |
#### Performance & Observability
| Agent | Model | Description |
|-------|-------|-------------|
| [performance-engineer](performance-engineer.md) | opus | Application profiling and optimization |
| [observability-engineer](observability-engineer.md) | opus | Production monitoring, distributed tracing, SLI/SLO management |
| [search-specialist](search-specialist.md) | haiku | Advanced web research and information synthesis |
### Data & AI
#### Data Engineering & Analytics
| Agent | Model | Description |
|-------|-------|-------------|
| [data-scientist](data-scientist.md) | opus | Data analysis, SQL queries, BigQuery operations |
| [data-engineer](data-engineer.md) | sonnet | ETL pipelines, data warehouses, streaming architectures |
#### Machine Learning & AI
| Agent | Model | Description |
|-------|-------|-------------|
| [ai-engineer](ai-engineer.md) | opus | LLM applications, RAG systems, prompt pipelines |
| [ml-engineer](ml-engineer.md) | opus | ML pipelines, model serving, feature engineering |
| [mlops-engineer](mlops-engineer.md) | opus | ML infrastructure, experiment tracking, model registries |
| [prompt-engineer](prompt-engineer.md) | opus | LLM prompt optimization and engineering |
### Documentation & Technical Writing
| Agent | Model | Description |
|-------|-------|-------------|
| [docs-architect](docs-architect.md) | opus | Comprehensive technical documentation generation |
| [api-documenter](api-documenter.md) | sonnet | OpenAPI/Swagger specifications and developer docs |
| [reference-builder](reference-builder.md) | haiku | Technical references and API documentation |
| [tutorial-engineer](tutorial-engineer.md) | sonnet | Step-by-step tutorials and educational content |
| [mermaid-expert](mermaid-expert.md) | sonnet | Diagram creation (flowcharts, sequences, ERDs) |
### Business & Operations
#### Business Analysis & Finance
| Agent | Model | Description |
|-------|-------|-------------|
| [business-analyst](business-analyst.md) | sonnet | Metrics analysis, reporting, KPI tracking |
| [quant-analyst](quant-analyst.md) | opus | Financial modeling, trading strategies, market analysis |
| [risk-manager](risk-manager.md) | sonnet | Portfolio risk monitoring and management |
#### Marketing & Sales
| Agent | Model | Description |
|-------|-------|-------------|
| [content-marketer](content-marketer.md) | sonnet | Blog posts, social media, email campaigns |
| [sales-automator](sales-automator.md) | haiku | Cold emails, follow-ups, proposal generation |
#### Support & Legal
| Agent | Model | Description |
|-------|-------|-------------|
| [customer-support](customer-support.md) | sonnet | Support tickets, FAQ responses, customer communication |
| [hr-pro](hr-pro.md) | opus | HR operations, policies, employee relations |
| [legal-advisor](legal-advisor.md) | opus | Privacy policies, terms of service, legal documentation |
### Specialized Domains
| Agent | Model | Description |
|-------|-------|-------------|
| [blockchain-developer](blockchain-developer.md) | sonnet | Web3 apps, smart contracts, DeFi protocols |
| [payment-integration](payment-integration.md) | sonnet | Payment processor integration (Stripe, PayPal) |
| [legacy-modernizer](legacy-modernizer.md) | sonnet | Legacy code refactoring and modernization |
| [context-manager](context-manager.md) | haiku | Multi-agent context management |
### SEO & Content Optimization
| Agent | Model | Description |
|-------|-------|-------------|
| [seo-content-auditor](seo-content-auditor.md) | sonnet | Content quality analysis, E-E-A-T signals assessment |
| [seo-meta-optimizer](seo-meta-optimizer.md) | haiku | Meta title and description optimization |
| [seo-keyword-strategist](seo-keyword-strategist.md) | haiku | Keyword analysis and semantic variations |
| [seo-structure-architect](seo-structure-architect.md) | haiku | Content structure and schema markup |
| [seo-snippet-hunter](seo-snippet-hunter.md) | haiku | Featured snippet formatting |
| [seo-content-refresher](seo-content-refresher.md) | haiku | Content freshness analysis |
| [seo-cannibalization-detector](seo-cannibalization-detector.md) | haiku | Keyword overlap detection |
| [seo-authority-builder](seo-authority-builder.md) | sonnet | E-E-A-T signal analysis |
| [seo-content-writer](seo-content-writer.md) | sonnet | SEO-optimized content creation |
| [seo-content-planner](seo-content-planner.md) | haiku | Content planning and topic clusters |
## Model Configuration
Agents are assigned to specific Claude models based on task complexity and computational requirements. The system uses three model tiers:
### Model Distribution Summary
| Model | Agent Count | Use Case |
|-------|-------------|----------|
| Haiku | 11 | Quick, focused tasks with minimal computational overhead |
| Sonnet | 46 | Standard development and specialized engineering tasks |
| Opus | 22 | Complex reasoning, architecture, and critical analysis |
### Haiku Model Agents
| Category | Agents |
|----------|--------|
| Context & Reference | `context-manager`, `reference-builder`, `sales-automator`, `search-specialist` |
| SEO Optimization | `seo-meta-optimizer`, `seo-keyword-strategist`, `seo-structure-architect`, `seo-snippet-hunter`, `seo-content-refresher`, `seo-cannibalization-detector`, `seo-content-planner` |
### Sonnet Model Agents
| Category | Count | Agents |
|----------|-------|--------|
| Programming Languages | 18 | All language-specific agents (JavaScript, Python, Java, C++, etc.) |
| Frontend & UI | 5 | `frontend-developer`, `ui-ux-designer`, `ui-visual-validator`, `mobile-developer`, `ios-developer` |
| Infrastructure | 8 | `devops-troubleshooter`, `deployment-engineer`, `dx-optimizer`, `database-admin`, `network-engineer`, `flutter-expert`, `api-documenter`, `tutorial-engineer` |
| Quality & Testing | 4 | `test-automator`, `tdd-orchestrator`, `debugger`, `error-detective` |
| Business & Support | 6 | `business-analyst`, `risk-manager`, `content-marketer`, `customer-support`, `mermaid-expert`, `legacy-modernizer` |
| Data & Content | 5 | `data-engineer`, `payment-integration`, `seo-content-auditor`, `seo-authority-builder`, `seo-content-writer` |
### Opus Model Agents
| Category | Count | Agents |
|----------|-------|--------|
| Architecture & Design | 7 | `architect-reviewer`, `backend-architect`, `cloud-architect`, `hybrid-cloud-architect`, `kubernetes-architect`, `graphql-architect`, `terraform-specialist` |
| Critical Analysis | 6 | `code-reviewer`, `security-auditor`, `performance-engineer`, `observability-engineer`, `incident-responder`, `database-optimizer` |
| AI/ML Complex | 5 | `ai-engineer`, `ml-engineer`, `mlops-engineer`, `data-scientist`, `prompt-engineer` |
| Business Critical | 4 | `docs-architect`, `hr-pro`, `legal-advisor`, `quant-analyst` |
## Installation ## Installation
Clone the repository to the Claude agents directory: ### New Installation
```bash ```bash
cd ~/.claude cd ~/.claude
git clone https://github.com/wshobson/agents.git git clone https://github.com/wshobson/agents.git
``` ```
The subagents will be automatically available to Claude Code once placed in the `~/.claude/agents/` directory. All agents, workflows, and tools will be automatically available to Claude Code.
### Updating from Previous Version
If you previously had the `agents` repository installed:
```bash
cd ~/.claude/agents
git pull origin main
```
**Important**: The repository structure has changed. All agent files have been moved to the `agents/` subdirectory. Claude Code will automatically detect the new structure.
## Repository Structure
```
agents/
├── agents/ # 83 specialized AI agents
│ ├── backend-architect.md
│ ├── frontend-developer.md
│ └── ... (all agent definitions)
├── workflows/ # 15 multi-agent orchestrators
│ ├── feature-development.md
│ ├── full-stack-feature.md
│ ├── security-hardening.md
│ └── ... (workflow commands)
├── tools/ # 42 development utilities
│ ├── api-scaffold.md
│ ├── security-scan.md
│ └── ... (tool commands)
└── README.md
```
## Workflow Commands
Multi-agent orchestration systems that coordinate complex, cross-domain tasks:
### Core Development Workflows
| Command | Purpose | Agent Coordination |
|---------|---------|-------------------|
| `feature-development` | End-to-end feature implementation | Backend, frontend, testing, deployment |
| `full-stack-feature` | Complete multi-tier implementation | Backend API, frontend UI, mobile, database |
| `full-review` | Multi-perspective code analysis | Architecture, security, performance, quality |
| `smart-fix` | Intelligent problem resolution | Dynamic agent selection based on issue type |
| `tdd-cycle` | Test-driven development orchestration | Test writer, implementer, refactoring specialist |
### Process Automation Workflows
| Command | Purpose | Scope |
|---------|---------|-------|
| `git-workflow` | Version control process automation | Branching strategies, commit standards, PR templates |
| `improve-agent` | Agent optimization | Prompt engineering, performance tuning |
| `legacy-modernize` | Codebase modernization | Architecture migration, dependency updates |
| `multi-platform` | Cross-platform development | Web, mobile, desktop coordination |
| `workflow-automate` | CI/CD pipeline automation | Build, test, deploy, monitor |
### Advanced Orchestration Workflows
| Command | Primary Focus | Specialized Agents |
|---------|---------------|-------------------|
| `security-hardening` | Security-first development | Threat modeling, vulnerability assessment |
| `data-driven-feature` | ML-powered functionality | Data science, feature engineering, model deployment |
| `ml-pipeline` | End-to-end ML infrastructure | MLOps, data engineering, model serving |
| `performance-optimization` | System-wide optimization | Profiling, caching, query optimization |
| `incident-response` | Production issue resolution | Diagnostics, root cause analysis, hotfix deployment |
## Development Tools
Focused, single-purpose utilities for specific development operations:
### AI and Machine Learning
- `langchain-agent` - LangChain agent development
- `ai-assistant` - AI-powered development assistance
- `ai-review` - AI-based code review
### API Development
- `api-scaffold` - API endpoint scaffolding
- `api-mock` - API mocking and testing
### Testing & Quality
- `tdd-red` - Red phase (failing tests)
- `tdd-green` - Green phase (passing implementation)
- `tdd-refactor` - Refactor phase
- `test-harness` - Test infrastructure setup
### Security & Compliance
- `security-scan` - Vulnerability scanning
- `compliance-check` - Compliance validation
### Infrastructure & Operations
- `k8s-manifest` - Kubernetes manifest generation
- `docker-optimize` - Docker optimization
- `monitor-setup` - Monitoring infrastructure
- `deploy-checklist` - Deployment validation
### Code Quality
- `code-explain` - Code explanation
- `code-migrate` - Code migration
- `refactor-clean` - Code refactoring
- `pr-enhance` - Pull request enhancement
### And 20+ more tools for debugging, documentation, data validation, cost optimization, and developer workflows
## Usage ## Usage
### Automatic Delegation ### Workflow Invocation
Claude Code automatically selects the appropriate subagent based on task context and requirements. The system analyzes your request and delegates to the most suitable specialist.
### Explicit Invocation ```bash
Specify a subagent by name to use a particular specialist: # Full-stack feature development
/workflows:feature-development implement OAuth2 authentication
# Security hardening
/workflows:security-hardening perform security audit and remediation
# ML pipeline
/workflows:ml-pipeline build recommendation system with monitoring
# Incident response
/workflows:incident-response debug production memory leak
``` ```
"Use code-reviewer to analyze the recent changes"
"Have security-auditor scan for vulnerabilities" ### Tool Invocation
```bash
# API scaffolding
/tools:api-scaffold create user management endpoints
# Security scanning
/tools:security-scan perform vulnerability assessment
# Documentation generation
/tools:doc-generate create API documentation
```
### Direct Agent Access
Agents are automatically available and can be explicitly invoked:
```bash
"Use backend-architect to design the authentication API"
"Have security-auditor scan for OWASP vulnerabilities"
"Get performance-engineer to optimize this bottleneck" "Get performance-engineer to optimize this bottleneck"
``` ```
## Usage Examples ## Agent Categories
### Code Quality & Security ### Architecture & System Design (7 agents)
``` backend-architect, cloud-architect, kubernetes-architect, hybrid-cloud-architect, graphql-architect, terraform-specialist, architect-review
code-reviewer: Analyze component for best practices
security-auditor: Check for OWASP compliance
tdd-orchestrator: Implement feature with test-first approach
performance-engineer: Profile and optimize bottlenecks
```
### Development & Architecture ### Programming Languages (15 agents)
``` javascript-pro, typescript-pro, python-pro, golang-pro, rust-pro, java-pro, csharp-pro, c-pro, cpp-pro, ruby-pro, php-pro, scala-pro, elixir-pro, django-pro, fastapi-pro
backend-architect: Design authentication API
frontend-developer: Create responsive dashboard
graphql-architect: Design federated GraphQL schema
mobile-developer: Build cross-platform mobile app
```
### Infrastructure & Operations ### Infrastructure & Operations (9 agents)
devops-troubleshooter, deployment-engineer, database-admin, database-optimizer, database-architect, network-engineer, incident-responder, performance-engineer, observability-engineer
### Security & Quality (9 agents)
code-reviewer, security-auditor, backend-security-coder, frontend-security-coder, mobile-security-coder, test-automator, tdd-orchestrator, debugger, error-detective
### Frontend & Mobile (7 agents)
frontend-developer, ui-ux-designer, ui-visual-validator, mobile-developer, ios-developer, flutter-expert, unity-developer
### Data & AI (6 agents)
data-scientist, data-engineer, ml-engineer, mlops-engineer, ai-engineer, prompt-engineer
### Documentation (5 agents)
docs-architect, api-documenter, reference-builder, tutorial-engineer, mermaid-expert
### Business & Operations (6 agents)
business-analyst, hr-pro, legal-advisor, customer-support, sales-automator, content-marketer
### SEO & Content (10 agents)
seo-content-writer, seo-content-auditor, seo-keyword-strategist, seo-meta-optimizer, seo-structure-architect, seo-snippet-hunter, seo-content-refresher, seo-cannibalization-detector, seo-authority-builder, seo-content-planner
### Specialized Domains (7 agents)
blockchain-developer, quant-analyst, risk-manager, payment-integration, minecraft-bukkit-pro, legacy-modernizer, context-manager
### Utilities (3 agents)
search-specialist, dx-optimizer, sql-pro
## Multi-Agent Orchestration Examples
### Full-Stack Development
```bash
/workflows:full-stack-feature implement user dashboard with analytics
``` ```
devops-troubleshooter: Analyze production logs **Orchestrates**: backend-architect → graphql-architect → frontend-developer → mobile-developer → test-automator → security-auditor → performance-engineer → deployment-engineer
cloud-architect: Design scalable AWS architecture
network-engineer: Debug SSL certificate issues ### Security Hardening
database-admin: Configure backup and replication ```bash
terraform-specialist: Write infrastructure modules /workflows:security-hardening implement security best practices
``` ```
**Orchestrates**: security-auditor → backend-security-coder → frontend-security-coder → mobile-security-coder → test-automator
### Data & Machine Learning ### Data/ML Pipeline
```bash
/workflows:ml-pipeline build customer churn prediction model
``` ```
data-scientist: Analyze customer behavior dataset **Orchestrates**: data-scientist → data-engineer → ml-engineer → mlops-engineer → ai-engineer → performance-engineer
ai-engineer: Build RAG system for document search
mlops-engineer: Set up experiment tracking ### Incident Response
ml-engineer: Deploy model to production ```bash
/workflows:incident-response debug high CPU usage in production
``` ```
**Orchestrates**: incident-responder → devops-troubleshooter → debugger → error-detective → observability-engineer
### Business & Documentation ## Model Configuration
```
business-analyst: Create metrics dashboard
docs-architect: Generate technical documentation
api-documenter: Write OpenAPI specifications
content-marketer: Create SEO-optimized content
```
## Multi-Agent Workflows Agents are assigned to specific Claude models based on task complexity:
Subagents coordinate automatically for complex tasks. The system intelligently sequences multiple specialists based on task requirements. | Model | Count | Use Cases |
|-------|-------|-----------|
| **Opus** | 22 | Complex architecture, critical analysis, security audits, business operations |
| **Sonnet** | 50 | Standard development, engineering tasks, quality assurance |
| **Haiku** | 11 | Quick focused tasks, SEO optimization, reference building |
### Common Workflow Patterns ## Multi-Agent Orchestration Patterns
**Feature Development**
```
"Implement user authentication"
→ backend-architect → frontend-developer → test-automator → security-auditor
```
**Performance Optimization**
```
"Optimize checkout process"
→ performance-engineer → database-optimizer → frontend-developer
```
**Production Incidents**
```
"Debug high memory usage"
→ incident-responder → devops-troubleshooter → error-detective → performance-engineer
```
**Infrastructure Setup**
```
"Set up disaster recovery"
→ database-admin → database-optimizer → terraform-specialist
```
**ML Pipeline Development**
```
"Build ML pipeline with monitoring"
→ mlops-engineer → ml-engineer → data-engineer → performance-engineer
```
### Integration with Claude Code Commands
For sophisticated multi-agent orchestration, use the [Claude Code Commands](https://github.com/wshobson/commands) collection which provides 52 pre-built slash commands:
```
/full-stack-feature # Coordinates 8+ agents for complete feature development
/incident-response # Activates incident management workflow
/ml-pipeline # Sets up end-to-end ML infrastructure
/security-hardening # Implements security best practices across stack
```
## Subagent Format
Each subagent is defined as a Markdown file with frontmatter:
```markdown
---
name: subagent-name
description: Activation criteria for this subagent
model: haiku|sonnet|opus # Optional: Model selection
tools: tool1, tool2 # Optional: Tool restrictions
---
System prompt defining the subagent's expertise and behavior
```
### Model Selection Criteria
- **haiku**: Simple, deterministic tasks with minimal reasoning
- **sonnet**: Standard development and engineering tasks
- **opus**: Complex analysis, architecture, and critical operations
## Agent Orchestration Patterns
### Sequential Processing ### Sequential Processing
Agents execute in sequence, passing context forward:
``` ```
backend-architect → frontend-developer → test-automator → security-auditor backend-architect → frontend-developer → test-automator → security-auditor
``` ```
### Parallel Execution ### Parallel Execution
Multiple agents work simultaneously on different aspects:
``` ```
performance-engineer + database-optimizer → Merged analysis performance-engineer + database-optimizer → Merged optimization
``` ```
### Conditional Routing ### Conditional Routing
Dynamic agent selection based on analysis:
``` ```
debugger → [backend-architect | frontend-developer | devops-troubleshooter] debugger → [backend-architect | frontend-developer | devops-troubleshooter]
``` ```
### Validation Pipeline ### Validation Pipeline
Primary work followed by specialized review:
``` ```
payment-integration → security-auditor → Validated implementation feature-development → security-auditor → performance-engineer → Validated release
``` ```
## Agent Selection Guide ## Migration Guide
### Architecture & Planning ### What Changed?
| Task | Recommended Agent | Key Capabilities | **Major Update**: This repository has been restructured to consolidate all Claude Code extensions in one place:
|------|------------------|------------------|
| API Design | `backend-architect` | RESTful APIs, microservices, database schemas |
| Cloud Infrastructure | `cloud-architect` | AWS/Azure/GCP design, scalability planning |
| UI/UX Design | `ui-ux-designer` | Interface design, wireframes, design systems |
| System Architecture | `architect-reviewer` | Pattern validation, consistency analysis |
### Development by Language 1. **Repository Structure**: All agents moved from root to `agents/` subdirectory
2. **Workflows Added**: 15 multi-agent workflow orchestrators (previously in separate `commands` repo)
3. **Tools Added**: 42 development utilities (previously in separate `commands` repo)
4. **Unified Experience**: Everything now accessible from a single repository
| Language Category | Agents | Primary Use Cases | ### Migrating from Commands Repository
|-------------------|--------|-------------------|
| Systems Programming | `c-pro`, `cpp-pro`, `rust-pro`, `golang-pro` | OS interfaces, embedded systems, high performance |
| Web Development | `javascript-pro`, `typescript-pro`, `python-pro`, `ruby-pro`, `php-pro` | Full-stack web applications, APIs, scripting |
| Enterprise | `java-pro`, `csharp-pro`, `scala-pro` | Large-scale applications, enterprise systems |
| Mobile | `ios-developer`, `flutter-expert`, `mobile-developer` | Native and cross-platform mobile apps |
| Specialized | `elixir-pro`, `unity-developer`, `minecraft-bukkit-pro` | Domain-specific development |
### Operations & Infrastructure If you previously used the separate `commands` repository (`wshobson/commands`):
| Task | Recommended Agent | Key Capabilities | **Before** (old structure):
|------|------------------|------------------| ```
| Production Issues | `devops-troubleshooter` | Log analysis, deployment debugging | ~/.claude/
| Critical Incidents | `incident-responder` | Outage response, immediate mitigation | ├── agents/ # Agents repository
| Database Performance | `database-optimizer` | Query optimization, indexing strategies | │ └── *.md files
| Database Operations | `database-admin` | Backup, replication, disaster recovery | └── commands/ # Commands repository (DEPRECATED)
| Infrastructure as Code | `terraform-specialist` | Terraform modules, state management | └── *.md files
| Network Issues | `network-engineer` | Network debugging, load balancing | ```
### Quality & Security **After** (new unified structure):
```
~/.claude/
└── agents/ # Unified repository
├── agents/
├── workflows/
└── tools/
```
| Task | Recommended Agent | Key Capabilities | #### Migration Steps
|------|------------------|------------------|
| Code Review | `code-reviewer` | Security focus, best practices |
| Security Audit | `security-auditor` | Vulnerability scanning, OWASP compliance |
| Test Creation | `test-automator` | Unit, integration, E2E test suites |
| Performance Issues | `performance-engineer` | Profiling, optimization |
| Bug Investigation | `debugger` | Error resolution, root cause analysis |
### Data & Machine Learning 1. **Update the agents repository**:
```bash
cd ~/.claude/agents
git pull origin main
```
| Task | Recommended Agent | Key Capabilities | 2. **Remove the old commands repository** (if installed):
|------|------------------|------------------| ```bash
| Data Analysis | `data-scientist` | SQL queries, statistical analysis | rm -rf ~/.claude/commands
| LLM Applications | `ai-engineer` | RAG systems, prompt pipelines | ```
| ML Development | `ml-engineer` | Model training, feature engineering |
| ML Operations | `mlops-engineer` | ML infrastructure, experiment tracking |
### Documentation & Business 3. **Verify installation**:
```bash
ls ~/.claude/agents
# Should show: agents/ workflows/ tools/ README.md
```
| Task | Recommended Agent | Key Capabilities | 4. **Update your workflow**:
|------|------------------|------------------| - Old: `/feature-development` or `/commands:feature-development`
| Technical Docs | `docs-architect` | Comprehensive documentation generation | - New: `/workflows:feature-development`
| API Documentation | `api-documenter` | OpenAPI/Swagger specifications |
| Business Metrics | `business-analyst` | KPI tracking, reporting |
| Legal Compliance | `legal-advisor` | Privacy policies, terms of service |
## Best Practices - Old: `/api-scaffold` or `/commands:api-scaffold`
- New: `/tools:api-scaffold`
### Task Delegation ### What Stays the Same?
1. **Automatic selection** - Let Claude Code analyze context and select optimal agents
2. **Clear requirements** - Specify constraints, tech stack, and quality standards
3. **Trust specialization** - Each agent is optimized for their specific domain
### Multi-Agent Workflows - All 83 agents work exactly as before (no command syntax changes)
1. **High-level requests** - Allow agents to coordinate complex multi-step tasks - Agent definitions and capabilities unchanged
2. **Context preservation** - Ensure agents have necessary background information - Direct agent invocation still works: "Use backend-architect to..."
3. **Integration review** - Verify how different agents' outputs work together
### Explicit Control ### Breaking Changes
1. **Direct invocation** - Specify agents when you need particular expertise
2. **Strategic combination** - Use multiple specialists for validation
3. **Review patterns** - Request specific review workflows (e.g., "security-auditor reviews API design")
### Performance Optimization ⚠️ **Command Invocation Syntax**:
1. **Monitor effectiveness** - Track which agents work best for your use cases - Workflows now use `/workflows:` prefix instead of just `/`
2. **Iterative refinement** - Use agent feedback to improve requirements - Tools now use `/tools:` prefix instead of just `/`
3. **Complexity matching** - Align task complexity with agent capabilities
**Old syntax** (deprecated):
```bash
/feature-development implement auth
/api-scaffold create endpoints
```
**New syntax** (current):
```bash
/workflows:feature-development implement auth
/tools:api-scaffold create endpoints
```
### Need Help?
For detailed migration instructions and troubleshooting, see [MIGRATION.md](MIGRATION.md).
If you encounter issues after migrating:
1. Verify directory structure: `ls -la ~/.claude/agents`
2. Check git status: `cd ~/.claude/agents && git status`
3. Review common issues in [MIGRATION.md](MIGRATION.md)
4. Report issues at: https://github.com/wshobson/agents/issues
## Contributing ## Contributing
To add a new subagent: To add new agents, workflows, or tools:
1. Create a new `.md` file with appropriate frontmatter 1. Place agent definitions in `agents/` directory
2. Use lowercase, hyphen-separated naming convention 2. Place workflow orchestrators in `workflows/` directory
3. Write clear activation criteria in the description 3. Place tool commands in `tools/` directory
4. Define comprehensive system prompt with expertise areas 4. Follow existing naming conventions (lowercase, hyphen-separated)
5. Include proper frontmatter in markdown files
## Troubleshooting
### Agent Not Activating
- Ensure request clearly indicates the domain
- Be specific about task type and requirements
- Use explicit invocation if automatic selection fails
### Unexpected Agent Selection
- Provide more context about tech stack
- Include specific requirements in request
- Use direct agent naming for precise control
### Conflicting Recommendations
- Normal behavior - specialists have different priorities
- Request reconciliation between specific agents
- Consider trade-offs based on project requirements
### Missing Context
- Include background information in requests
- Reference previous work or patterns
- Provide project-specific constraints
## License ## License
@@ -531,4 +384,3 @@ MIT License - see [LICENSE](LICENSE) file for details.
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code) - [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
- [Subagents Documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents) - [Subagents Documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents)
- [Claude Code GitHub](https://github.com/anthropics/claude-code) - [Claude Code GitHub](https://github.com/anthropics/claude-code)
- [Claude Code Commands](https://github.com/wshobson/commands)

534
agents/README.md Normal file
View File

@@ -0,0 +1,534 @@
# Claude Code Subagents Collection
A comprehensive collection of 83 specialized AI subagents for [Claude Code](https://docs.anthropic.com/en/docs/claude-code), providing domain-specific expertise across software development, infrastructure, and business operations.
## Overview
This repository provides production-ready subagents that extend Claude Code's capabilities with specialized knowledge. Each subagent incorporates:
- Current industry best practices and standards (2024/2025)
- Production-ready patterns and enterprise architectures
- Deep domain expertise with 8-12 capability areas per agent
- Modern technology stacks and frameworks
- Optimized model selection based on task complexity
## Agent Categories
### Architecture & System Design
#### Core Architecture
| Agent | Model | Description |
|-------|-------|-------------|
| [backend-architect](backend-architect.md) | opus | RESTful API design, microservice boundaries, database schemas |
| [frontend-developer](frontend-developer.md) | sonnet | React components, responsive layouts, client-side state management |
| [graphql-architect](graphql-architect.md) | opus | GraphQL schemas, resolvers, federation architecture |
| [architect-reviewer](architect-review.md) | opus | Architectural consistency analysis and pattern validation |
| [cloud-architect](cloud-architect.md) | opus | AWS/Azure/GCP infrastructure design and cost optimization |
| [hybrid-cloud-architect](hybrid-cloud-architect.md) | opus | Multi-cloud strategies across cloud and on-premises environments |
| [kubernetes-architect](kubernetes-architect.md) | opus | Cloud-native infrastructure with Kubernetes and GitOps |
#### UI/UX & Mobile
| Agent | Model | Description |
|-------|-------|-------------|
| [ui-ux-designer](ui-ux-designer.md) | sonnet | Interface design, wireframes, design systems |
| [ui-visual-validator](ui-visual-validator.md) | sonnet | Visual regression testing and UI verification |
| [mobile-developer](mobile-developer.md) | sonnet | React Native and Flutter application development |
| [ios-developer](ios-developer.md) | sonnet | Native iOS development with Swift/SwiftUI |
| [flutter-expert](flutter-expert.md) | sonnet | Advanced Flutter development with state management |
### Programming Languages
#### Systems & Low-Level
| Agent | Model | Description |
|-------|-------|-------------|
| [c-pro](c-pro.md) | sonnet | System programming with memory management and OS interfaces |
| [cpp-pro](cpp-pro.md) | sonnet | Modern C++ with RAII, smart pointers, STL algorithms |
| [rust-pro](rust-pro.md) | sonnet | Memory-safe systems programming with ownership patterns |
| [golang-pro](golang-pro.md) | sonnet | Concurrent programming with goroutines and channels |
#### Web & Application
| Agent | Model | Description |
|-------|-------|-------------|
| [javascript-pro](javascript-pro.md) | sonnet | Modern JavaScript with ES6+, async patterns, Node.js |
| [typescript-pro](typescript-pro.md) | sonnet | Advanced TypeScript with type systems and generics |
| [python-pro](python-pro.md) | sonnet | Python development with advanced features and optimization |
| [ruby-pro](ruby-pro.md) | sonnet | Ruby with metaprogramming, Rails patterns, gem development |
| [php-pro](php-pro.md) | sonnet | Modern PHP with frameworks and performance optimization |
#### Enterprise & JVM
| Agent | Model | Description |
|-------|-------|-------------|
| [java-pro](java-pro.md) | sonnet | Modern Java with streams, concurrency, JVM optimization |
| [scala-pro](scala-pro.md) | sonnet | Enterprise Scala with functional programming and distributed systems |
| [csharp-pro](csharp-pro.md) | sonnet | C# development with .NET frameworks and patterns |
#### Specialized Platforms
| Agent | Model | Description |
|-------|-------|-------------|
| [elixir-pro](elixir-pro.md) | sonnet | Elixir with OTP patterns and Phoenix frameworks |
| [unity-developer](unity-developer.md) | sonnet | Unity game development and optimization |
| [minecraft-bukkit-pro](minecraft-bukkit-pro.md) | sonnet | Minecraft server plugin development |
| [sql-pro](sql-pro.md) | sonnet | Complex SQL queries and database optimization |
### Infrastructure & Operations
#### DevOps & Deployment
| Agent | Model | Description |
|-------|-------|-------------|
| [devops-troubleshooter](devops-troubleshooter.md) | sonnet | Production debugging, log analysis, deployment troubleshooting |
| [deployment-engineer](deployment-engineer.md) | sonnet | CI/CD pipelines, containerization, cloud deployments |
| [terraform-specialist](terraform-specialist.md) | opus | Infrastructure as Code with Terraform modules and state management |
| [dx-optimizer](dx-optimizer.md) | sonnet | Developer experience optimization and tooling improvements |
#### Database Management
| Agent | Model | Description |
|-------|-------|-------------|
| [database-optimizer](database-optimizer.md) | opus | Query optimization, index design, migration strategies |
| [database-admin](database-admin.md) | sonnet | Database operations, backup, replication, monitoring |
#### Incident Response & Network
| Agent | Model | Description |
|-------|-------|-------------|
| [incident-responder](incident-responder.md) | opus | Production incident management and resolution |
| [network-engineer](network-engineer.md) | sonnet | Network debugging, load balancing, traffic analysis |
### Quality Assurance & Security
#### Code Quality & Review
| Agent | Model | Description |
|-------|-------|-------------|
| [code-reviewer](code-reviewer.md) | opus | Code review with security focus and production reliability |
| [security-auditor](security-auditor.md) | opus | Vulnerability assessment and OWASP compliance |
| [backend-security-coder](backend-security-coder.md) | opus | Secure backend coding practices, API security implementation |
| [frontend-security-coder](frontend-security-coder.md) | opus | XSS prevention, CSP implementation, client-side security |
| [mobile-security-coder](mobile-security-coder.md) | opus | Mobile security patterns, WebView security, biometric auth |
| [architect-reviewer](architect-review.md) | opus | Architectural consistency and pattern validation |
#### Testing & Debugging
| Agent | Model | Description |
|-------|-------|-------------|
| [test-automator](test-automator.md) | sonnet | Comprehensive test suite creation (unit, integration, e2e) |
| [tdd-orchestrator](tdd-orchestrator.md) | sonnet | Test-Driven Development methodology guidance |
| [debugger](debugger.md) | sonnet | Error resolution and test failure analysis |
| [error-detective](error-detective.md) | sonnet | Log analysis and error pattern recognition |
#### Performance & Observability
| Agent | Model | Description |
|-------|-------|-------------|
| [performance-engineer](performance-engineer.md) | opus | Application profiling and optimization |
| [observability-engineer](observability-engineer.md) | opus | Production monitoring, distributed tracing, SLI/SLO management |
| [search-specialist](search-specialist.md) | haiku | Advanced web research and information synthesis |
### Data & AI
#### Data Engineering & Analytics
| Agent | Model | Description |
|-------|-------|-------------|
| [data-scientist](data-scientist.md) | opus | Data analysis, SQL queries, BigQuery operations |
| [data-engineer](data-engineer.md) | sonnet | ETL pipelines, data warehouses, streaming architectures |
#### Machine Learning & AI
| Agent | Model | Description |
|-------|-------|-------------|
| [ai-engineer](ai-engineer.md) | opus | LLM applications, RAG systems, prompt pipelines |
| [ml-engineer](ml-engineer.md) | opus | ML pipelines, model serving, feature engineering |
| [mlops-engineer](mlops-engineer.md) | opus | ML infrastructure, experiment tracking, model registries |
| [prompt-engineer](prompt-engineer.md) | opus | LLM prompt optimization and engineering |
### Documentation & Technical Writing
| Agent | Model | Description |
|-------|-------|-------------|
| [docs-architect](docs-architect.md) | opus | Comprehensive technical documentation generation |
| [api-documenter](api-documenter.md) | sonnet | OpenAPI/Swagger specifications and developer docs |
| [reference-builder](reference-builder.md) | haiku | Technical references and API documentation |
| [tutorial-engineer](tutorial-engineer.md) | sonnet | Step-by-step tutorials and educational content |
| [mermaid-expert](mermaid-expert.md) | sonnet | Diagram creation (flowcharts, sequences, ERDs) |
### Business & Operations
#### Business Analysis & Finance
| Agent | Model | Description |
|-------|-------|-------------|
| [business-analyst](business-analyst.md) | sonnet | Metrics analysis, reporting, KPI tracking |
| [quant-analyst](quant-analyst.md) | opus | Financial modeling, trading strategies, market analysis |
| [risk-manager](risk-manager.md) | sonnet | Portfolio risk monitoring and management |
#### Marketing & Sales
| Agent | Model | Description |
|-------|-------|-------------|
| [content-marketer](content-marketer.md) | sonnet | Blog posts, social media, email campaigns |
| [sales-automator](sales-automator.md) | haiku | Cold emails, follow-ups, proposal generation |
#### Support & Legal
| Agent | Model | Description |
|-------|-------|-------------|
| [customer-support](customer-support.md) | sonnet | Support tickets, FAQ responses, customer communication |
| [hr-pro](hr-pro.md) | opus | HR operations, policies, employee relations |
| [legal-advisor](legal-advisor.md) | opus | Privacy policies, terms of service, legal documentation |
### Specialized Domains
| Agent | Model | Description |
|-------|-------|-------------|
| [blockchain-developer](blockchain-developer.md) | sonnet | Web3 apps, smart contracts, DeFi protocols |
| [payment-integration](payment-integration.md) | sonnet | Payment processor integration (Stripe, PayPal) |
| [legacy-modernizer](legacy-modernizer.md) | sonnet | Legacy code refactoring and modernization |
| [context-manager](context-manager.md) | haiku | Multi-agent context management |
### SEO & Content Optimization
| Agent | Model | Description |
|-------|-------|-------------|
| [seo-content-auditor](seo-content-auditor.md) | sonnet | Content quality analysis, E-E-A-T signals assessment |
| [seo-meta-optimizer](seo-meta-optimizer.md) | haiku | Meta title and description optimization |
| [seo-keyword-strategist](seo-keyword-strategist.md) | haiku | Keyword analysis and semantic variations |
| [seo-structure-architect](seo-structure-architect.md) | haiku | Content structure and schema markup |
| [seo-snippet-hunter](seo-snippet-hunter.md) | haiku | Featured snippet formatting |
| [seo-content-refresher](seo-content-refresher.md) | haiku | Content freshness analysis |
| [seo-cannibalization-detector](seo-cannibalization-detector.md) | haiku | Keyword overlap detection |
| [seo-authority-builder](seo-authority-builder.md) | sonnet | E-E-A-T signal analysis |
| [seo-content-writer](seo-content-writer.md) | sonnet | SEO-optimized content creation |
| [seo-content-planner](seo-content-planner.md) | haiku | Content planning and topic clusters |
## Model Configuration
Agents are assigned to specific Claude models based on task complexity and computational requirements. The system uses three model tiers:
### Model Distribution Summary
| Model | Agent Count | Use Case |
|-------|-------------|----------|
| Haiku | 11 | Quick, focused tasks with minimal computational overhead |
| Sonnet | 46 | Standard development and specialized engineering tasks |
| Opus | 22 | Complex reasoning, architecture, and critical analysis |
### Haiku Model Agents
| Category | Agents |
|----------|--------|
| Context & Reference | `context-manager`, `reference-builder`, `sales-automator`, `search-specialist` |
| SEO Optimization | `seo-meta-optimizer`, `seo-keyword-strategist`, `seo-structure-architect`, `seo-snippet-hunter`, `seo-content-refresher`, `seo-cannibalization-detector`, `seo-content-planner` |
### Sonnet Model Agents
| Category | Count | Agents |
|----------|-------|--------|
| Programming Languages | 18 | All language-specific agents (JavaScript, Python, Java, C++, etc.) |
| Frontend & UI | 5 | `frontend-developer`, `ui-ux-designer`, `ui-visual-validator`, `mobile-developer`, `ios-developer` |
| Infrastructure | 8 | `devops-troubleshooter`, `deployment-engineer`, `dx-optimizer`, `database-admin`, `network-engineer`, `flutter-expert`, `api-documenter`, `tutorial-engineer` |
| Quality & Testing | 4 | `test-automator`, `tdd-orchestrator`, `debugger`, `error-detective` |
| Business & Support | 6 | `business-analyst`, `risk-manager`, `content-marketer`, `customer-support`, `mermaid-expert`, `legacy-modernizer` |
| Data & Content | 5 | `data-engineer`, `payment-integration`, `seo-content-auditor`, `seo-authority-builder`, `seo-content-writer` |
### Opus Model Agents
| Category | Count | Agents |
|----------|-------|--------|
| Architecture & Design | 7 | `architect-reviewer`, `backend-architect`, `cloud-architect`, `hybrid-cloud-architect`, `kubernetes-architect`, `graphql-architect`, `terraform-specialist` |
| Critical Analysis | 6 | `code-reviewer`, `security-auditor`, `performance-engineer`, `observability-engineer`, `incident-responder`, `database-optimizer` |
| AI/ML Complex | 5 | `ai-engineer`, `ml-engineer`, `mlops-engineer`, `data-scientist`, `prompt-engineer` |
| Business Critical | 4 | `docs-architect`, `hr-pro`, `legal-advisor`, `quant-analyst` |
## Installation
Clone the repository to the Claude agents directory:
```bash
cd ~/.claude
git clone https://github.com/wshobson/agents.git
```
The subagents will be automatically available to Claude Code once placed in the `~/.claude/agents/` directory.
## Usage
### Automatic Delegation
Claude Code automatically selects the appropriate subagent based on task context and requirements. The system analyzes your request and delegates to the most suitable specialist.
### Explicit Invocation
Specify a subagent by name to use a particular specialist:
```
"Use code-reviewer to analyze the recent changes"
"Have security-auditor scan for vulnerabilities"
"Get performance-engineer to optimize this bottleneck"
```
## Usage Examples
### Code Quality & Security
```
code-reviewer: Analyze component for best practices
security-auditor: Check for OWASP compliance
tdd-orchestrator: Implement feature with test-first approach
performance-engineer: Profile and optimize bottlenecks
```
### Development & Architecture
```
backend-architect: Design authentication API
frontend-developer: Create responsive dashboard
graphql-architect: Design federated GraphQL schema
mobile-developer: Build cross-platform mobile app
```
### Infrastructure & Operations
```
devops-troubleshooter: Analyze production logs
cloud-architect: Design scalable AWS architecture
network-engineer: Debug SSL certificate issues
database-admin: Configure backup and replication
terraform-specialist: Write infrastructure modules
```
### Data & Machine Learning
```
data-scientist: Analyze customer behavior dataset
ai-engineer: Build RAG system for document search
mlops-engineer: Set up experiment tracking
ml-engineer: Deploy model to production
```
### Business & Documentation
```
business-analyst: Create metrics dashboard
docs-architect: Generate technical documentation
api-documenter: Write OpenAPI specifications
content-marketer: Create SEO-optimized content
```
## Multi-Agent Workflows
Subagents coordinate automatically for complex tasks. The system intelligently sequences multiple specialists based on task requirements.
### Common Workflow Patterns
**Feature Development**
```
"Implement user authentication"
→ backend-architect → frontend-developer → test-automator → security-auditor
```
**Performance Optimization**
```
"Optimize checkout process"
→ performance-engineer → database-optimizer → frontend-developer
```
**Production Incidents**
```
"Debug high memory usage"
→ incident-responder → devops-troubleshooter → error-detective → performance-engineer
```
**Infrastructure Setup**
```
"Set up disaster recovery"
→ database-admin → database-optimizer → terraform-specialist
```
**ML Pipeline Development**
```
"Build ML pipeline with monitoring"
→ mlops-engineer → ml-engineer → data-engineer → performance-engineer
```
### Integration with Claude Code Commands
For sophisticated multi-agent orchestration, use the [Claude Code Commands](https://github.com/wshobson/commands) collection which provides 52 pre-built slash commands:
```
/full-stack-feature # Coordinates 8+ agents for complete feature development
/incident-response # Activates incident management workflow
/ml-pipeline # Sets up end-to-end ML infrastructure
/security-hardening # Implements security best practices across stack
```
## Subagent Format
Each subagent is defined as a Markdown file with frontmatter:
```markdown
---
name: subagent-name
description: Activation criteria for this subagent
model: haiku|sonnet|opus # Optional: Model selection
tools: tool1, tool2 # Optional: Tool restrictions
---
System prompt defining the subagent's expertise and behavior
```
### Model Selection Criteria
- **haiku**: Simple, deterministic tasks with minimal reasoning
- **sonnet**: Standard development and engineering tasks
- **opus**: Complex analysis, architecture, and critical operations
## Agent Orchestration Patterns
### Sequential Processing
Agents execute in sequence, passing context forward:
```
backend-architect → frontend-developer → test-automator → security-auditor
```
### Parallel Execution
Multiple agents work simultaneously on different aspects:
```
performance-engineer + database-optimizer → Merged analysis
```
### Conditional Routing
Dynamic agent selection based on analysis:
```
debugger → [backend-architect | frontend-developer | devops-troubleshooter]
```
### Validation Pipeline
Primary work followed by specialized review:
```
payment-integration → security-auditor → Validated implementation
```
## Agent Selection Guide
### Architecture & Planning
| Task | Recommended Agent | Key Capabilities |
|------|------------------|------------------|
| API Design | `backend-architect` | RESTful APIs, microservices, database schemas |
| Cloud Infrastructure | `cloud-architect` | AWS/Azure/GCP design, scalability planning |
| UI/UX Design | `ui-ux-designer` | Interface design, wireframes, design systems |
| System Architecture | `architect-reviewer` | Pattern validation, consistency analysis |
### Development by Language
| Language Category | Agents | Primary Use Cases |
|-------------------|--------|-------------------|
| Systems Programming | `c-pro`, `cpp-pro`, `rust-pro`, `golang-pro` | OS interfaces, embedded systems, high performance |
| Web Development | `javascript-pro`, `typescript-pro`, `python-pro`, `ruby-pro`, `php-pro` | Full-stack web applications, APIs, scripting |
| Enterprise | `java-pro`, `csharp-pro`, `scala-pro` | Large-scale applications, enterprise systems |
| Mobile | `ios-developer`, `flutter-expert`, `mobile-developer` | Native and cross-platform mobile apps |
| Specialized | `elixir-pro`, `unity-developer`, `minecraft-bukkit-pro` | Domain-specific development |
### Operations & Infrastructure
| Task | Recommended Agent | Key Capabilities |
|------|------------------|------------------|
| Production Issues | `devops-troubleshooter` | Log analysis, deployment debugging |
| Critical Incidents | `incident-responder` | Outage response, immediate mitigation |
| Database Performance | `database-optimizer` | Query optimization, indexing strategies |
| Database Operations | `database-admin` | Backup, replication, disaster recovery |
| Infrastructure as Code | `terraform-specialist` | Terraform modules, state management |
| Network Issues | `network-engineer` | Network debugging, load balancing |
### Quality & Security
| Task | Recommended Agent | Key Capabilities |
|------|------------------|------------------|
| Code Review | `code-reviewer` | Security focus, best practices |
| Security Audit | `security-auditor` | Vulnerability scanning, OWASP compliance |
| Test Creation | `test-automator` | Unit, integration, E2E test suites |
| Performance Issues | `performance-engineer` | Profiling, optimization |
| Bug Investigation | `debugger` | Error resolution, root cause analysis |
### Data & Machine Learning
| Task | Recommended Agent | Key Capabilities |
|------|------------------|------------------|
| Data Analysis | `data-scientist` | SQL queries, statistical analysis |
| LLM Applications | `ai-engineer` | RAG systems, prompt pipelines |
| ML Development | `ml-engineer` | Model training, feature engineering |
| ML Operations | `mlops-engineer` | ML infrastructure, experiment tracking |
### Documentation & Business
| Task | Recommended Agent | Key Capabilities |
|------|------------------|------------------|
| Technical Docs | `docs-architect` | Comprehensive documentation generation |
| API Documentation | `api-documenter` | OpenAPI/Swagger specifications |
| Business Metrics | `business-analyst` | KPI tracking, reporting |
| Legal Compliance | `legal-advisor` | Privacy policies, terms of service |
## Best Practices
### Task Delegation
1. **Automatic selection** - Let Claude Code analyze context and select optimal agents
2. **Clear requirements** - Specify constraints, tech stack, and quality standards
3. **Trust specialization** - Each agent is optimized for their specific domain
### Multi-Agent Workflows
1. **High-level requests** - Allow agents to coordinate complex multi-step tasks
2. **Context preservation** - Ensure agents have necessary background information
3. **Integration review** - Verify how different agents' outputs work together
### Explicit Control
1. **Direct invocation** - Specify agents when you need particular expertise
2. **Strategic combination** - Use multiple specialists for validation
3. **Review patterns** - Request specific review workflows (e.g., "security-auditor reviews API design")
### Performance Optimization
1. **Monitor effectiveness** - Track which agents work best for your use cases
2. **Iterative refinement** - Use agent feedback to improve requirements
3. **Complexity matching** - Align task complexity with agent capabilities
## Contributing
To add a new subagent:
1. Create a new `.md` file with appropriate frontmatter
2. Use lowercase, hyphen-separated naming convention
3. Write clear activation criteria in the description
4. Define comprehensive system prompt with expertise areas
## Troubleshooting
### Agent Not Activating
- Ensure request clearly indicates the domain
- Be specific about task type and requirements
- Use explicit invocation if automatic selection fails
### Unexpected Agent Selection
- Provide more context about tech stack
- Include specific requirements in request
- Use direct agent naming for precise control
### Conflicting Recommendations
- Normal behavior - specialists have different priorities
- Request reconciliation between specific agents
- Consider trade-offs based on project requirements
### Missing Context
- Include background information in requests
- Reference previous work or patterns
- Provide project-specific constraints
## License
MIT License - see [LICENSE](LICENSE) file for details.
## Resources
- [Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code)
- [Subagents Documentation](https://docs.anthropic.com/en/docs/claude-code/sub-agents)
- [Claude Code GitHub](https://github.com/anthropics/claude-code)
- [Claude Code Commands](https://github.com/wshobson/commands)

0
ai-engineer.md → agents/ai-engineer.md
View File

0
api-documenter.md → agents/api-documenter.md
View File

0
architect-review.md → agents/architect-review.md
View File

0
backend-architect.md → agents/backend-architect.md
View File

0
backend-security-coder.md → agents/backend-security-coder.md
View File

0
blockchain-developer.md → agents/blockchain-developer.md
View File

0
business-analyst.md → agents/business-analyst.md
View File

0
c-pro.md → agents/c-pro.md
View File

0
cloud-architect.md → agents/cloud-architect.md
View File

0
code-reviewer.md → agents/code-reviewer.md
View File

0
content-marketer.md → agents/content-marketer.md
View File

0
context-manager.md → agents/context-manager.md
View File

0
cpp-pro.md → agents/cpp-pro.md
View File

0
csharp-pro.md → agents/csharp-pro.md
View File

0
customer-support.md → agents/customer-support.md
View File

0
data-engineer.md → agents/data-engineer.md
View File

0
data-scientist.md → agents/data-scientist.md
View File

0
database-admin.md → agents/database-admin.md
View File

0
database-architect.md → agents/database-architect.md
View File

0
database-optimizer.md → agents/database-optimizer.md
View File

0
debugger.md → agents/debugger.md
View File

0
deployment-engineer.md → agents/deployment-engineer.md
View File

0
devops-troubleshooter.md → agents/devops-troubleshooter.md
View File

0
django-pro.md → agents/django-pro.md
View File

0
docs-architect.md → agents/docs-architect.md
View File

0
dx-optimizer.md → agents/dx-optimizer.md
View File

0
elixir-pro.md → agents/elixir-pro.md
View File

0
error-detective.md → agents/error-detective.md
View File

0
fastapi-pro.md → agents/fastapi-pro.md
View File

0
flutter-expert.md → agents/flutter-expert.md
View File

0
frontend-developer.md → agents/frontend-developer.md
View File

0
frontend-security-coder.md → agents/frontend-security-coder.md
View File

0
golang-pro.md → agents/golang-pro.md
View File

0
graphql-architect.md → agents/graphql-architect.md
View File

0
hr-pro.md → agents/hr-pro.md
View File

0
hybrid-cloud-architect.md → agents/hybrid-cloud-architect.md
View File

0
incident-responder.md → agents/incident-responder.md
View File

0
ios-developer.md → agents/ios-developer.md
View File

0
java-pro.md → agents/java-pro.md
View File

0
javascript-pro.md → agents/javascript-pro.md
View File

0
kubernetes-architect.md → agents/kubernetes-architect.md
View File

0
legacy-modernizer.md → agents/legacy-modernizer.md
View File

0
legal-advisor.md → agents/legal-advisor.md
View File

0
mermaid-expert.md → agents/mermaid-expert.md
View File

0
minecraft-bukkit-pro.md → agents/minecraft-bukkit-pro.md
View File

0
ml-engineer.md → agents/ml-engineer.md
View File

0
mlops-engineer.md → agents/mlops-engineer.md
View File

0
mobile-developer.md → agents/mobile-developer.md
View File

0
mobile-security-coder.md → agents/mobile-security-coder.md
View File

0
network-engineer.md → agents/network-engineer.md
View File

0
observability-engineer.md → agents/observability-engineer.md
View File

0
payment-integration.md → agents/payment-integration.md
View File

0
performance-engineer.md → agents/performance-engineer.md
View File

0
php-pro.md → agents/php-pro.md
View File

0
prompt-engineer.md → agents/prompt-engineer.md
View File

0
python-pro.md → agents/python-pro.md
View File

0
quant-analyst.md → agents/quant-analyst.md
View File

0
reference-builder.md → agents/reference-builder.md
View File

0
risk-manager.md → agents/risk-manager.md
View File

0
ruby-pro.md → agents/ruby-pro.md
View File

0
rust-pro.md → agents/rust-pro.md
View File

0
sales-automator.md → agents/sales-automator.md
View File

0
scala-pro.md → agents/scala-pro.md
View File

0
search-specialist.md → agents/search-specialist.md
View File

0
security-auditor.md → agents/security-auditor.md
View File

0
seo-authority-builder.md → agents/seo-authority-builder.md
View File

0
seo-cannibalization-detector.md → agents/seo-cannibalization-detector.md
View File

0
seo-content-auditor.md → agents/seo-content-auditor.md
View File

0
seo-content-planner.md → agents/seo-content-planner.md
View File

0
seo-content-refresher.md → agents/seo-content-refresher.md
View File

0
seo-content-writer.md → agents/seo-content-writer.md
View File

0
seo-keyword-strategist.md → agents/seo-keyword-strategist.md
View File

0
seo-meta-optimizer.md → agents/seo-meta-optimizer.md
View File

0
seo-snippet-hunter.md → agents/seo-snippet-hunter.md
View File

0
seo-structure-architect.md → agents/seo-structure-architect.md
View File

0
sql-pro.md → agents/sql-pro.md
View File

0
tdd-orchestrator.md → agents/tdd-orchestrator.md
View File

0
terraform-specialist.md → agents/terraform-specialist.md
View File

0
test-automator.md → agents/test-automator.md
View File

0
tutorial-engineer.md → agents/tutorial-engineer.md
View File

0
typescript-pro.md → agents/typescript-pro.md
View File

0
ui-ux-designer.md → agents/ui-ux-designer.md
View File

0
ui-visual-validator.md → agents/ui-visual-validator.md
View File

0
unity-developer.md → agents/unity-developer.md
View File

1234
tools/accessibility-audit.md Normal file
View File

File diff suppressed because it is too large Load Diff

1236
tools/ai-assistant.md Normal file
View File

File diff suppressed because it is too large Load Diff

67
tools/ai-review.md Normal file
View File

@@ -0,0 +1,67 @@
---
model: claude-sonnet-4-0
---
# AI/ML Code Review
Perform a specialized AI/ML code review for: $ARGUMENTS
Conduct comprehensive review focusing on:
1. **Model Code Quality**:
- Reproducibility checks
- Random seed management
- Data leakage detection
- Train/test split validation
- Feature engineering clarity
2. **AI Best Practices**:
- Prompt injection prevention
- Token limit handling
- Cost optimization
- Fallback strategies
- Timeout management
3. **Data Handling**:
- Privacy compliance (PII handling)
- Data versioning
- Preprocessing consistency
- Batch processing efficiency
- Memory optimization
4. **Model Management**:
- Version control for models
- A/B testing setup
- Rollback capabilities
- Performance benchmarks
- Drift detection
5. **LLM-Specific Checks**:
- Context window management
- Prompt template security
- Response validation
- Streaming implementation
- Rate limit handling
6. **Vector Database Review**:
- Embedding consistency
- Index optimization
- Query performance
- Metadata management
- Backup strategies
7. **Production Readiness**:
- GPU/CPU optimization
- Batching strategies
- Caching implementation
- Monitoring hooks
- Error recovery
8. **Testing Coverage**:
- Unit tests for preprocessing
- Integration tests for pipelines
- Model performance tests
- Edge case handling
- Mocked LLM responses
Provide specific recommendations with severity levels (Critical/High/Medium/Low). Include code examples for improvements and links to relevant best practices.

1324
tools/api-mock.md Normal file
View File

File diff suppressed because it is too large Load Diff

1776
tools/api-scaffold.md Normal file
View File

File diff suppressed because it is too large Load Diff

812
tools/code-explain.md Normal file
View File

@@ -0,0 +1,812 @@
---
model: claude-sonnet-4-0
---
# Code Explanation and Analysis
You are a code education expert specializing in explaining complex code through clear narratives, visual diagrams, and step-by-step breakdowns. Transform difficult concepts into understandable explanations for developers at all levels.
## Context
The user needs help understanding complex code sections, algorithms, design patterns, or system architectures. Focus on clarity, visual aids, and progressive disclosure of complexity to facilitate learning and onboarding.
## Requirements
$ARGUMENTS
## Instructions
### 1. Code Comprehension Analysis
Analyze the code to determine complexity and structure:
**Code Complexity Assessment**
```python
import ast
import re
from typing import Dict, List, Tuple
class CodeAnalyzer:
def analyze_complexity(self, code: str) -> Dict:
"""
Analyze code complexity and structure
"""
analysis = {
'complexity_score': 0,
'concepts': [],
'patterns': [],
'dependencies': [],
'difficulty_level': 'beginner'
}
# Parse code structure
try:
tree = ast.parse(code)
# Analyze complexity metrics
analysis['metrics'] = {
'lines_of_code': len(code.splitlines()),
'cyclomatic_complexity': self._calculate_cyclomatic_complexity(tree),
'nesting_depth': self._calculate_max_nesting(tree),
'function_count': len([n for n in ast.walk(tree) if isinstance(n, ast.FunctionDef)]),
'class_count': len([n for n in ast.walk(tree) if isinstance(n, ast.ClassDef)])
}
# Identify concepts used
analysis['concepts'] = self._identify_concepts(tree)
# Detect design patterns
analysis['patterns'] = self._detect_patterns(tree)
# Extract dependencies
analysis['dependencies'] = self._extract_dependencies(tree)
# Determine difficulty level
analysis['difficulty_level'] = self._assess_difficulty(analysis)
except SyntaxError as e:
analysis['parse_error'] = str(e)
return analysis
def _identify_concepts(self, tree) -> List[str]:
"""
Identify programming concepts used in the code
"""
concepts = []
for node in ast.walk(tree):
# Async/await
if isinstance(node, (ast.AsyncFunctionDef, ast.AsyncWith, ast.AsyncFor)):
concepts.append('asynchronous programming')
# Decorators
elif isinstance(node, ast.FunctionDef) and node.decorator_list:
concepts.append('decorators')
# Context managers
elif isinstance(node, ast.With):
concepts.append('context managers')
# Generators
elif isinstance(node, ast.Yield):
concepts.append('generators')
# List/Dict/Set comprehensions
elif isinstance(node, (ast.ListComp, ast.DictComp, ast.SetComp)):
concepts.append('comprehensions')
# Lambda functions
elif isinstance(node, ast.Lambda):
concepts.append('lambda functions')
# Exception handling
elif isinstance(node, ast.Try):
concepts.append('exception handling')
return list(set(concepts))
```
### 2. Visual Explanation Generation
Create visual representations of code flow:
**Flow Diagram Generation**
```python
class VisualExplainer:
def generate_flow_diagram(self, code_structure):
"""
Generate Mermaid diagram showing code flow
"""
diagram = "```mermaid\nflowchart TD\n"
# Example: Function call flow
if code_structure['type'] == 'function_flow':
nodes = []
edges = []
for i, func in enumerate(code_structure['functions']):
node_id = f"F{i}"
nodes.append(f" {node_id}[{func['name']}]")
# Add function details
if func.get('parameters'):
nodes.append(f" {node_id}_params[/{', '.join(func['parameters'])}/]")
edges.append(f" {node_id}_params --> {node_id}")
# Add return value
if func.get('returns'):
nodes.append(f" {node_id}_return[{func['returns']}]")
edges.append(f" {node_id} --> {node_id}_return")
# Connect to called functions
for called in func.get('calls', []):
called_id = f"F{code_structure['function_map'][called]}"
edges.append(f" {node_id} --> {called_id}")
diagram += "\n".join(nodes) + "\n"
diagram += "\n".join(edges) + "\n"
diagram += "```"
return diagram
def generate_class_diagram(self, classes):
"""
Generate UML-style class diagram
"""
diagram = "```mermaid\nclassDiagram\n"
for cls in classes:
# Class definition
diagram += f" class {cls['name']} {{\n"
# Attributes
for attr in cls.get('attributes', []):
visibility = '+' if attr['public'] else '-'
diagram += f" {visibility}{attr['name']} : {attr['type']}\n"
# Methods
for method in cls.get('methods', []):
visibility = '+' if method['public'] else '-'
params = ', '.join(method.get('params', []))
diagram += f" {visibility}{method['name']}({params}) : {method['returns']}\n"
diagram += " }\n"
# Relationships
if cls.get('inherits'):
diagram += f" {cls['inherits']} <|-- {cls['name']}\n"
for composition in cls.get('compositions', []):
diagram += f" {cls['name']} *-- {composition}\n"
diagram += "```"
return diagram
```
### 3. Step-by-Step Explanation
Break down complex code into digestible steps:
**Progressive Explanation**
```python
def generate_step_by_step_explanation(self, code, analysis):
"""
Create progressive explanation from simple to complex
"""
explanation = {
'overview': self._generate_overview(code, analysis),
'steps': [],
'deep_dive': [],
'examples': []
}
# Level 1: High-level overview
explanation['overview'] = f"""
## What This Code Does
{self._summarize_purpose(code, analysis)}
**Key Concepts**: {', '.join(analysis['concepts'])}
**Difficulty Level**: {analysis['difficulty_level'].capitalize()}
"""
# Level 2: Step-by-step breakdown
if analysis.get('functions'):
for i, func in enumerate(analysis['functions']):
step = f"""
### Step {i+1}: {func['name']}
**Purpose**: {self._explain_function_purpose(func)}
**How it works**:
"""
# Break down function logic
for j, logic_step in enumerate(self._analyze_function_logic(func)):
step += f"{j+1}. {logic_step}\n"
# Add visual flow if complex
if func['complexity'] > 5:
step += f"\n{self._generate_function_flow(func)}\n"
explanation['steps'].append(step)
# Level 3: Deep dive into complex parts
for concept in analysis['concepts']:
deep_dive = self._explain_concept(concept, code)
explanation['deep_dive'].append(deep_dive)
return explanation
def _explain_concept(self, concept, code):
"""
Explain programming concept with examples
"""
explanations = {
'decorators': '''
## Understanding Decorators
Decorators are a way to modify or enhance functions without changing their code directly.
**Simple Analogy**: Think of a decorator like gift wrapping - it adds something extra around the original item.
**How it works**:
```python
# This decorator:
@timer
def slow_function():
time.sleep(1)
# Is equivalent to:
def slow_function():
time.sleep(1)
slow_function = timer(slow_function)
```
**In this code**: The decorator is used to {specific_use_in_code}
''',
'generators': '''
## Understanding Generators
Generators produce values one at a time, saving memory by not creating all values at once.
**Simple Analogy**: Like a ticket dispenser that gives one ticket at a time, rather than printing all tickets upfront.
**How it works**:
```python
# Generator function
def count_up_to(n):
i = 0
while i < n:
yield i # Produces one value and pauses
i += 1
# Using the generator
for num in count_up_to(5):
print(num) # Prints 0, 1, 2, 3, 4
```
**In this code**: The generator is used to {specific_use_in_code}
'''
}
return explanations.get(concept, f"Explanation for {concept}")
```
### 4. Algorithm Visualization
Visualize algorithm execution:
**Algorithm Step Visualization**
```python
class AlgorithmVisualizer:
def visualize_sorting_algorithm(self, algorithm_name, array):
"""
Create step-by-step visualization of sorting algorithm
"""
steps = []
if algorithm_name == 'bubble_sort':
steps.append("""
## Bubble Sort Visualization
**Initial Array**: [5, 2, 8, 1, 9]
### How Bubble Sort Works:
1. Compare adjacent elements
2. Swap if they're in wrong order
3. Repeat until no swaps needed
### Step-by-Step Execution:
""")
# Simulate bubble sort with visualization
arr = array.copy()
n = len(arr)
for i in range(n):
swapped = False
step_viz = f"\n**Pass {i+1}**:\n"
for j in range(0, n-i-1):
# Show comparison
step_viz += f"Compare [{arr[j]}] and [{arr[j+1]}]: "
if arr[j] > arr[j+1]:
arr[j], arr[j+1] = arr[j+1], arr[j]
step_viz += f"Swap → {arr}\n"
swapped = True
else:
step_viz += "No swap needed\n"
steps.append(step_viz)
if not swapped:
steps.append(f"\n✅ Array is sorted: {arr}")
break
return '\n'.join(steps)
def visualize_recursion(self, func_name, example_input):
"""
Visualize recursive function calls
"""
viz = f"""
## Recursion Visualization: {func_name}
### Call Stack Visualization:
```
{func_name}({example_input})
│
├─> Base case check: {example_input} == 0? No
├─> Recursive call: {func_name}({example_input - 1})
│ │
│ ├─> Base case check: {example_input - 1} == 0? No
│ ├─> Recursive call: {func_name}({example_input - 2})
│ │ │
│ │ ├─> Base case check: 1 == 0? No
│ │ ├─> Recursive call: {func_name}(0)
│ │ │ │
│ │ │ └─> Base case: Return 1
│ │ │
│ │ └─> Return: 1 * 1 = 1
│ │
│ └─> Return: 2 * 1 = 2
│
└─> Return: 3 * 2 = 6
```
**Final Result**: {func_name}({example_input}) = 6
"""
return viz
```
### 5. Interactive Examples
Generate interactive examples for better understanding:
**Code Playground Examples**
```python
def generate_interactive_examples(self, concept):
"""
Create runnable examples for concepts
"""
examples = {
'error_handling': '''
## Try It Yourself: Error Handling
### Example 1: Basic Try-Except
```python
def safe_divide(a, b):
try:
result = a / b
print(f"{a} / {b} = {result}")
return result
except ZeroDivisionError:
print("Error: Cannot divide by zero!")
return None
except TypeError:
print("Error: Please provide numbers only!")
return None
finally:
print("Division attempt completed")
# Test cases - try these:
safe_divide(10, 2) # Success case
safe_divide(10, 0) # Division by zero
safe_divide(10, "2") # Type error
```
### Example 2: Custom Exceptions
```python
class ValidationError(Exception):
"""Custom exception for validation errors"""
pass
def validate_age(age):
try:
age = int(age)
if age < 0:
raise ValidationError("Age cannot be negative")
if age > 150:
raise ValidationError("Age seems unrealistic")
return age
except ValueError:
raise ValidationError("Age must be a number")
# Try these examples:
try:
validate_age(25) # Valid
validate_age(-5) # Negative age
validate_age("abc") # Not a number
except ValidationError as e:
print(f"Validation failed: {e}")
```
### Exercise: Implement Your Own
Try implementing a function that:
1. Takes a list of numbers
2. Returns their average
3. Handles empty lists
4. Handles non-numeric values
5. Uses appropriate exception handling
''',
'async_programming': '''
## Try It Yourself: Async Programming
### Example 1: Basic Async/Await
```python
import asyncio
import time
async def slow_operation(name, duration):
print(f"{name} started...")
await asyncio.sleep(duration)
print(f"{name} completed after {duration}s")
return f"{name} result"
async def main():
# Sequential execution (slow)
start = time.time()
await slow_operation("Task 1", 2)
await slow_operation("Task 2", 2)
print(f"Sequential time: {time.time() - start:.2f}s")
# Concurrent execution (fast)
start = time.time()
results = await asyncio.gather(
slow_operation("Task 3", 2),
slow_operation("Task 4", 2)
)
print(f"Concurrent time: {time.time() - start:.2f}s")
print(f"Results: {results}")
# Run it:
asyncio.run(main())
```
### Example 2: Real-world Async Pattern
```python
async def fetch_data(url):
"""Simulate API call"""
await asyncio.sleep(1) # Simulate network delay
return f"Data from {url}"
async def process_urls(urls):
tasks = [fetch_data(url) for url in urls]
results = await asyncio.gather(*tasks)
return results
# Try with different URLs:
urls = ["api.example.com/1", "api.example.com/2", "api.example.com/3"]
results = asyncio.run(process_urls(urls))
print(results)
```
'''
}
return examples.get(concept, "No example available")
```
### 6. Design Pattern Explanation
Explain design patterns found in code:
**Pattern Recognition and Explanation**
```python
class DesignPatternExplainer:
def explain_pattern(self, pattern_name, code_example):
"""
Explain design pattern with diagrams and examples
"""
patterns = {
'singleton': '''
## Singleton Pattern
### What is it?
The Singleton pattern ensures a class has only one instance and provides global access to it.
### When to use it?
- Database connections
- Configuration managers
- Logging services
- Cache managers
### Visual Representation:
```mermaid
classDiagram
class Singleton {
-instance: Singleton
-__init__()
+getInstance(): Singleton
}
Singleton --> Singleton : returns same instance
```
### Implementation in this code:
{code_analysis}
### Benefits:
✅ Controlled access to single instance
✅ Reduced namespace pollution
✅ Permits refinement of operations
### Drawbacks:
❌ Can make unit testing difficult
❌ Violates Single Responsibility Principle
❌ Can hide dependencies
### Alternative Approaches:
1. Dependency Injection
2. Module-level singleton
3. Borg pattern
''',
'observer': '''
## Observer Pattern
### What is it?
The Observer pattern defines a one-to-many dependency between objects so that when one object changes state, all dependents are notified.
### When to use it?
- Event handling systems
- Model-View architectures
- Distributed event handling
### Visual Representation:
```mermaid
classDiagram
class Subject {
+attach(Observer)
+detach(Observer)
+notify()
}
class Observer {
+update()
}
class ConcreteSubject {
-state
+getState()
+setState()
}
class ConcreteObserver {
-subject
+update()
}
Subject <|-- ConcreteSubject
Observer <|-- ConcreteObserver
ConcreteSubject --> Observer : notifies
ConcreteObserver --> ConcreteSubject : observes
```
### Implementation in this code:
{code_analysis}
### Real-world Example:
```python
# Newsletter subscription system
class Newsletter:
def __init__(self):
self._subscribers = []
self._latest_article = None
def subscribe(self, subscriber):
self._subscribers.append(subscriber)
def unsubscribe(self, subscriber):
self._subscribers.remove(subscriber)
def publish_article(self, article):
self._latest_article = article
self._notify_subscribers()
def _notify_subscribers(self):
for subscriber in self._subscribers:
subscriber.update(self._latest_article)
class EmailSubscriber:
def __init__(self, email):
self.email = email
def update(self, article):
print(f"Sending email to {self.email}: New article - {article}")
```
'''
}
return patterns.get(pattern_name, "Pattern explanation not available")
```
### 7. Common Pitfalls and Best Practices
Highlight potential issues and improvements:
**Code Review Insights**
```python
def analyze_common_pitfalls(self, code):
"""
Identify common mistakes and suggest improvements
"""
issues = []
# Check for common Python pitfalls
pitfall_patterns = [
{
'pattern': r'except:',
'issue': 'Bare except clause',
'severity': 'high',
'explanation': '''
## ⚠️ Bare Except Clause
**Problem**: `except:` catches ALL exceptions, including system exits and keyboard interrupts.
**Why it's bad**:
- Hides programming errors
- Makes debugging difficult
- Can catch exceptions you didn't intend to handle
**Better approach**:
```python
# Bad
try:
risky_operation()
except:
print("Something went wrong")
# Good
try:
risky_operation()
except (ValueError, TypeError) as e:
print(f"Expected error: {e}")
except Exception as e:
logger.error(f"Unexpected error: {e}")
raise
```
'''
},
{
'pattern': r'def.*\(\s*\):.*global',
'issue': 'Global variable usage',
'severity': 'medium',
'explanation': '''
## ⚠️ Global Variable Usage
**Problem**: Using global variables makes code harder to test and reason about.
**Better approaches**:
1. Pass as parameter
2. Use class attributes
3. Use dependency injection
4. Return values instead
**Example refactor**:
```python
# Bad
count = 0
def increment():
global count
count += 1
# Good
class Counter:
def __init__(self):
self.count = 0
def increment(self):
self.count += 1
return self.count
```
'''
}
]
for pitfall in pitfall_patterns:
if re.search(pitfall['pattern'], code):
issues.append(pitfall)
return issues
```
### 8. Learning Path Recommendations
Suggest resources for deeper understanding:
**Personalized Learning Path**
```python
def generate_learning_path(self, analysis):
"""
Create personalized learning recommendations
"""
learning_path = {
'current_level': analysis['difficulty_level'],
'identified_gaps': [],
'recommended_topics': [],
'resources': []
}
# Identify knowledge gaps
if 'async' in analysis['concepts'] and analysis['difficulty_level'] == 'beginner':
learning_path['identified_gaps'].append('Asynchronous programming fundamentals')
learning_path['recommended_topics'].extend([
'Event loops',
'Coroutines vs threads',
'Async/await syntax',
'Concurrent programming patterns'
])
# Add resources
learning_path['resources'] = [
{
'topic': 'Async Programming',
'type': 'tutorial',
'title': 'Async IO in Python: A Complete Walkthrough',
'url': 'https://realpython.com/async-io-python/',
'difficulty': 'intermediate',
'time_estimate': '45 minutes'
},
{
'topic': 'Design Patterns',
'type': 'book',
'title': 'Head First Design Patterns',
'difficulty': 'beginner-friendly',
'format': 'visual learning'
}
]
# Create structured learning plan
learning_path['structured_plan'] = f"""
## Your Personalized Learning Path
### Week 1-2: Fundamentals
- Review basic concepts: {', '.join(learning_path['recommended_topics'][:2])}
- Complete exercises on each topic
- Build a small project using these concepts
### Week 3-4: Applied Learning
- Study the patterns in this codebase
- Refactor a simple version yourself
- Compare your approach with the original
### Week 5-6: Advanced Topics
- Explore edge cases and optimizations
- Learn about alternative approaches
- Contribute to open source projects using these patterns
### Practice Projects:
1. **Beginner**: {self._suggest_beginner_project(analysis)}
2. **Intermediate**: {self._suggest_intermediate_project(analysis)}
3. **Advanced**: {self._suggest_advanced_project(analysis)}
"""
return learning_path
```
## Output Format
1. **Complexity Analysis**: Overview of code complexity and concepts used
2. **Visual Diagrams**: Flow charts, class diagrams, and execution visualizations
3. **Step-by-Step Breakdown**: Progressive explanation from simple to complex
4. **Interactive Examples**: Runnable code samples to experiment with
5. **Common Pitfalls**: Issues to avoid with explanations
6. **Best Practices**: Improved approaches and patterns
7. **Learning Resources**: Curated resources for deeper understanding
8. **Practice Exercises**: Hands-on challenges to reinforce learning
Focus on making complex code accessible through clear explanations, visual aids, and practical examples that build understanding progressively.

1052
tools/code-migrate.md Normal file
View File

File diff suppressed because it is too large Load Diff

946
tools/compliance-check.md Normal file
View File

@@ -0,0 +1,946 @@
---
model: claude-sonnet-4-0
---
# Regulatory Compliance Check
You are a compliance expert specializing in regulatory requirements for software systems including GDPR, HIPAA, SOC2, PCI-DSS, and other industry standards. Perform comprehensive compliance audits and provide implementation guidance for achieving and maintaining compliance.
## Context
The user needs to ensure their application meets regulatory requirements and industry standards. Focus on practical implementation of compliance controls, automated monitoring, and audit trail generation.
## Requirements
$ARGUMENTS
## Instructions
### 1. Compliance Framework Analysis
Identify applicable regulations and standards:
**Regulatory Mapping**
```python
class ComplianceAnalyzer:
def __init__(self):
self.regulations = {
'GDPR': {
'scope': 'EU data protection',
'applies_if': [
'Processing EU residents data',
'Offering goods/services to EU',
'Monitoring EU residents behavior'
],
'key_requirements': [
'Privacy by design',
'Data minimization',
'Right to erasure',
'Data portability',
'Consent management',
'DPO appointment',
'Privacy notices',
'Data breach notification (72hrs)'
]
},
'HIPAA': {
'scope': 'Healthcare data protection (US)',
'applies_if': [
'Healthcare providers',
'Health plan providers',
'Healthcare clearinghouses',
'Business associates'
],
'key_requirements': [
'PHI encryption',
'Access controls',
'Audit logs',
'Business Associate Agreements',
'Risk assessments',
'Employee training',
'Incident response',
'Physical safeguards'
]
},
'SOC2': {
'scope': 'Service organization controls',
'applies_if': [
'SaaS providers',
'Data processors',
'Cloud services'
],
'trust_principles': [
'Security',
'Availability',
'Processing integrity',
'Confidentiality',
'Privacy'
]
},
'PCI-DSS': {
'scope': 'Payment card data security',
'applies_if': [
'Accept credit/debit cards',
'Process card payments',
'Store card data',
'Transmit card data'
],
'compliance_levels': {
'Level 1': '>6M transactions/year',
'Level 2': '1M-6M transactions/year',
'Level 3': '20K-1M transactions/year',
'Level 4': '<20K transactions/year'
}
}
}
def determine_applicable_regulations(self, business_info):
"""
Determine which regulations apply based on business context
"""
applicable = []
# Check each regulation
for reg_name, reg_info in self.regulations.items():
if self._check_applicability(business_info, reg_info):
applicable.append({
'regulation': reg_name,
'reason': self._get_applicability_reason(business_info, reg_info),
'priority': self._calculate_priority(business_info, reg_name)
})
return sorted(applicable, key=lambda x: x['priority'], reverse=True)
```
### 2. Data Privacy Compliance
Implement privacy controls:
**GDPR Implementation**
```python
class GDPRCompliance:
def implement_privacy_controls(self):
"""
Implement GDPR-required privacy controls
"""
controls = {}
# 1. Consent Management
controls['consent_management'] = '''
class ConsentManager:
def __init__(self):
self.consent_types = [
'marketing_emails',
'analytics_tracking',
'third_party_sharing',
'profiling'
]
def record_consent(self, user_id, consent_type, granted):
"""
Record user consent with full audit trail
"""
consent_record = {
'user_id': user_id,
'consent_type': consent_type,
'granted': granted,
'timestamp': datetime.utcnow(),
'ip_address': request.remote_addr,
'user_agent': request.headers.get('User-Agent'),
'version': self.get_current_privacy_policy_version(),
'method': 'explicit_checkbox' # Not pre-ticked
}
# Store in append-only audit log
self.consent_audit_log.append(consent_record)
# Update current consent status
self.update_user_consents(user_id, consent_type, granted)
return consent_record
def verify_consent(self, user_id, consent_type):
"""
Verify if user has given consent for specific processing
"""
consent = self.get_user_consent(user_id, consent_type)
return consent and consent['granted'] and not consent.get('withdrawn')
'''
# 2. Right to Erasure (Right to be Forgotten)
controls['right_to_erasure'] = '''
class DataErasureService:
def process_erasure_request(self, user_id, verification_token):
"""
Process GDPR Article 17 erasure request
"""
# Verify request authenticity
if not self.verify_erasure_token(user_id, verification_token):
raise ValueError("Invalid erasure request")
erasure_log = {
'user_id': user_id,
'requested_at': datetime.utcnow(),
'data_categories': []
}
# 1. Personal data
self.erase_user_profile(user_id)
erasure_log['data_categories'].append('profile')
# 2. User-generated content (anonymize instead of delete)
self.anonymize_user_content(user_id)
erasure_log['data_categories'].append('content_anonymized')
# 3. Analytics data
self.remove_from_analytics(user_id)
erasure_log['data_categories'].append('analytics')
# 4. Backup data (schedule deletion)
self.schedule_backup_deletion(user_id)
erasure_log['data_categories'].append('backups_scheduled')
# 5. Notify third parties
self.notify_processors_of_erasure(user_id)
# Keep minimal record for legal compliance
self.store_erasure_record(erasure_log)
return {
'status': 'completed',
'erasure_id': erasure_log['id'],
'categories_erased': erasure_log['data_categories']
}
'''
# 3. Data Portability
controls['data_portability'] = '''
class DataPortabilityService:
def export_user_data(self, user_id, format='json'):
"""
GDPR Article 20 - Data portability
"""
user_data = {
'export_date': datetime.utcnow().isoformat(),
'user_id': user_id,
'format_version': '2.0',
'data': {}
}
# Collect all user data
user_data['data']['profile'] = self.get_user_profile(user_id)
user_data['data']['preferences'] = self.get_user_preferences(user_id)
user_data['data']['content'] = self.get_user_content(user_id)
user_data['data']['activity'] = self.get_user_activity(user_id)
user_data['data']['consents'] = self.get_consent_history(user_id)
# Format based on request
if format == 'json':
return json.dumps(user_data, indent=2)
elif format == 'csv':
return self.convert_to_csv(user_data)
elif format == 'xml':
return self.convert_to_xml(user_data)
'''
return controls
**Privacy by Design**
```python
# Implement privacy by design principles
class PrivacyByDesign:
def implement_data_minimization(self):
"""
Collect only necessary data
"""
# Before (collecting too much)
bad_user_model = {
'email': str,
'password': str,
'full_name': str,
'date_of_birth': date,
'ssn': str, # Unnecessary
'address': str, # Unnecessary for basic service
'phone': str, # Unnecessary
'gender': str, # Unnecessary
'income': int # Unnecessary
}
# After (data minimization)
good_user_model = {
'email': str, # Required for authentication
'password_hash': str, # Never store plain text
'display_name': str, # Optional, user-provided
'created_at': datetime,
'last_login': datetime
}
return good_user_model
def implement_pseudonymization(self):
"""
Replace identifying fields with pseudonyms
"""
def pseudonymize_record(record):
# Generate consistent pseudonym
user_pseudonym = hashlib.sha256(
f"{record['user_id']}{SECRET_SALT}".encode()
).hexdigest()[:16]
return {
'pseudonym': user_pseudonym,
'data': {
# Remove direct identifiers
'age_group': self._get_age_group(record['age']),
'region': self._get_region(record['ip_address']),
'activity': record['activity_data']
}
}
```
### 3. Security Compliance
Implement security controls for various standards:
**SOC2 Security Controls**
```python
class SOC2SecurityControls:
def implement_access_controls(self):
"""
SOC2 CC6.1 - Logical and physical access controls
"""
controls = {
'authentication': '''
# Multi-factor authentication
class MFAEnforcement:
def enforce_mfa(self, user, resource_sensitivity):
if resource_sensitivity == 'high':
return self.require_mfa(user)
elif resource_sensitivity == 'medium' and user.is_admin:
return self.require_mfa(user)
return self.standard_auth(user)
def require_mfa(self, user):
factors = []
# Factor 1: Password (something you know)
factors.append(self.verify_password(user))
# Factor 2: TOTP/SMS (something you have)
if user.mfa_method == 'totp':
factors.append(self.verify_totp(user))
elif user.mfa_method == 'sms':
factors.append(self.verify_sms_code(user))
# Factor 3: Biometric (something you are) - optional
if user.biometric_enabled:
factors.append(self.verify_biometric(user))
return all(factors)
''',
'authorization': '''
# Role-based access control
class RBACAuthorization:
def __init__(self):
self.roles = {
'admin': ['read', 'write', 'delete', 'admin'],
'user': ['read', 'write:own'],
'viewer': ['read']
}
def check_permission(self, user, resource, action):
user_permissions = self.get_user_permissions(user)
# Check explicit permissions
if action in user_permissions:
return True
# Check ownership-based permissions
if f"{action}:own" in user_permissions:
return self.user_owns_resource(user, resource)
# Log denied access attempt
self.log_access_denied(user, resource, action)
return False
''',
'encryption': '''
# Encryption at rest and in transit
class EncryptionControls:
def __init__(self):
self.kms = KeyManagementService()
def encrypt_at_rest(self, data, classification):
if classification == 'sensitive':
# Use envelope encryption
dek = self.kms.generate_data_encryption_key()
encrypted_data = self.encrypt_with_key(data, dek)
encrypted_dek = self.kms.encrypt_key(dek)
return {
'data': encrypted_data,
'encrypted_key': encrypted_dek,
'algorithm': 'AES-256-GCM',
'key_id': self.kms.get_current_key_id()
}
def configure_tls(self):
return {
'min_version': 'TLS1.2',
'ciphers': [
'ECDHE-RSA-AES256-GCM-SHA384',
'ECDHE-RSA-AES128-GCM-SHA256'
],
'hsts': 'max-age=31536000; includeSubDomains',
'certificate_pinning': True
}
'''
}
return controls
```
### 4. Audit Logging and Monitoring
Implement comprehensive audit trails:
**Audit Log System**
```python
class ComplianceAuditLogger:
def __init__(self):
self.required_events = {
'authentication': [
'login_success',
'login_failure',
'logout',
'password_change',
'mfa_enabled',
'mfa_disabled'
],
'authorization': [
'access_granted',
'access_denied',
'permission_changed',
'role_assigned',
'role_revoked'
],
'data_access': [
'data_viewed',
'data_exported',
'data_modified',
'data_deleted',
'bulk_operation'
],
'compliance': [
'consent_given',
'consent_withdrawn',
'data_request',
'data_erasure',
'privacy_settings_changed'
]
}
def log_event(self, event_type, details):
"""
Create tamper-proof audit log entry
"""
log_entry = {
'id': str(uuid.uuid4()),
'timestamp': datetime.utcnow().isoformat(),
'event_type': event_type,
'user_id': details.get('user_id'),
'ip_address': self._get_ip_address(),
'user_agent': request.headers.get('User-Agent'),
'session_id': session.get('id'),
'details': details,
'compliance_flags': self._get_compliance_flags(event_type)
}
# Add integrity check
log_entry['checksum'] = self._calculate_checksum(log_entry)
# Store in immutable log
self._store_audit_log(log_entry)
# Real-time alerting for critical events
if self._is_critical_event(event_type):
self._send_security_alert(log_entry)
return log_entry
def _calculate_checksum(self, entry):
"""
Create tamper-evident checksum
"""
# Include previous entry hash for blockchain-like integrity
previous_hash = self._get_previous_entry_hash()
content = json.dumps(entry, sort_keys=True)
return hashlib.sha256(
f"{previous_hash}{content}{SECRET_KEY}".encode()
).hexdigest()
```
**Compliance Reporting**
```python
def generate_compliance_report(self, regulation, period):
"""
Generate compliance report for auditors
"""
report = {
'regulation': regulation,
'period': period,
'generated_at': datetime.utcnow(),
'sections': {}
}
if regulation == 'GDPR':
report['sections'] = {
'data_processing_activities': self._get_processing_activities(period),
'consent_metrics': self._get_consent_metrics(period),
'data_requests': {
'access_requests': self._count_access_requests(period),
'erasure_requests': self._count_erasure_requests(period),
'portability_requests': self._count_portability_requests(period),
'response_times': self._calculate_response_times(period)
},
'data_breaches': self._get_breach_reports(period),
'third_party_processors': self._list_processors(),
'privacy_impact_assessments': self._get_dpias(period)
}
elif regulation == 'HIPAA':
report['sections'] = {
'access_controls': self._audit_access_controls(period),
'phi_access_log': self._get_phi_access_log(period),
'risk_assessments': self._get_risk_assessments(period),
'training_records': self._get_training_compliance(period),
'business_associates': self._list_bas_with_agreements(),
'incident_response': self._get_incident_reports(period)
}
return report
```
### 5. Healthcare Compliance (HIPAA)
Implement HIPAA-specific controls:
**PHI Protection**
```python
class HIPAACompliance:
def protect_phi(self):
"""
Implement HIPAA safeguards for Protected Health Information
"""
# Technical Safeguards
technical_controls = {
'access_control': '''
class PHIAccessControl:
def __init__(self):
self.minimum_necessary_rule = True
def grant_phi_access(self, user, patient_id, purpose):
"""
Implement minimum necessary standard
"""
# Verify legitimate purpose
if not self._verify_treatment_relationship(user, patient_id, purpose):
self._log_denied_access(user, patient_id, purpose)
raise PermissionError("No treatment relationship")
# Grant limited access based on role and purpose
access_scope = self._determine_access_scope(user.role, purpose)
# Time-limited access
access_token = {
'user_id': user.id,
'patient_id': patient_id,
'scope': access_scope,
'purpose': purpose,
'expires_at': datetime.utcnow() + timedelta(hours=24),
'audit_id': str(uuid.uuid4())
}
# Log all access
self._log_phi_access(access_token)
return access_token
''',
'encryption': '''
class PHIEncryption:
def encrypt_phi_at_rest(self, phi_data):
"""
HIPAA-compliant encryption for PHI
"""
# Use FIPS 140-2 validated encryption
encryption_config = {
'algorithm': 'AES-256-CBC',
'key_derivation': 'PBKDF2',
'iterations': 100000,
'validation': 'FIPS-140-2-Level-2'
}
# Encrypt PHI fields
encrypted_phi = {}
for field, value in phi_data.items():
if self._is_phi_field(field):
encrypted_phi[field] = self._encrypt_field(value, encryption_config)
else:
encrypted_phi[field] = value
return encrypted_phi
def secure_phi_transmission(self):
"""
Secure PHI during transmission
"""
return {
'protocols': ['TLS 1.2+'],
'vpn_required': True,
'email_encryption': 'S/MIME or PGP required',
'fax_alternative': 'Secure messaging portal'
}
'''
}
# Administrative Safeguards
admin_controls = {
'workforce_training': '''
class HIPAATraining:
def track_training_compliance(self, employee):
"""
Ensure workforce HIPAA training compliance
"""
required_modules = [
'HIPAA Privacy Rule',
'HIPAA Security Rule',
'PHI Handling Procedures',
'Breach Notification',
'Patient Rights',
'Minimum Necessary Standard'
]
training_status = {
'employee_id': employee.id,
'completed_modules': [],
'pending_modules': [],
'last_training_date': None,
'next_due_date': None
}
for module in required_modules:
completion = self._check_module_completion(employee.id, module)
if completion and completion['date'] > datetime.now() - timedelta(days=365):
training_status['completed_modules'].append(module)
else:
training_status['pending_modules'].append(module)
return training_status
'''
}
return {
'technical': technical_controls,
'administrative': admin_controls
}
```
### 6. Payment Card Compliance (PCI-DSS)
Implement PCI-DSS requirements:
**PCI-DSS Controls**
```python
class PCIDSSCompliance:
def implement_pci_controls(self):
"""
Implement PCI-DSS v4.0 requirements
"""
controls = {
'cardholder_data_protection': '''
class CardDataProtection:
def __init__(self):
# Never store these
self.prohibited_data = ['cvv', 'cvv2', 'cvc2', 'cid', 'pin', 'pin_block']
def handle_card_data(self, card_info):
"""
PCI-DSS compliant card data handling
"""
# Immediately tokenize
token = self.tokenize_card(card_info)
# If must store, only store allowed fields
stored_data = {
'token': token,
'last_four': card_info['number'][-4:],
'exp_month': card_info['exp_month'],
'exp_year': card_info['exp_year'],
'cardholder_name': self._encrypt(card_info['name'])
}
# Never log full card number
self._log_transaction(token, 'XXXX-XXXX-XXXX-' + stored_data['last_four'])
return stored_data
def tokenize_card(self, card_info):
"""
Replace PAN with token
"""
# Use payment processor tokenization
response = payment_processor.tokenize({
'number': card_info['number'],
'exp_month': card_info['exp_month'],
'exp_year': card_info['exp_year']
})
return response['token']
''',
'network_segmentation': '''
# Network segmentation for PCI compliance
class PCINetworkSegmentation:
def configure_network_zones(self):
"""
Implement network segmentation
"""
zones = {
'cde': { # Cardholder Data Environment
'description': 'Systems that process, store, or transmit CHD',
'controls': [
'Firewall required',
'IDS/IPS monitoring',
'No direct internet access',
'Quarterly vulnerability scans',
'Annual penetration testing'
]
},
'dmz': {
'description': 'Public-facing systems',
'controls': [
'Web application firewall',
'No CHD storage allowed',
'Regular security scanning'
]
},
'internal': {
'description': 'Internal corporate network',
'controls': [
'Segmented from CDE',
'Limited CDE access',
'Standard security controls'
]
}
}
return zones
''',
'vulnerability_management': '''
class PCIVulnerabilityManagement:
def quarterly_scan_requirements(self):
"""
PCI-DSS quarterly scan requirements
"""
scan_config = {
'internal_scans': {
'frequency': 'quarterly',
'scope': 'all CDE systems',
'tool': 'PCI-approved scanning vendor',
'passing_criteria': 'No high-risk vulnerabilities'
},
'external_scans': {
'frequency': 'quarterly',
'performed_by': 'ASV (Approved Scanning Vendor)',
'scope': 'All external-facing IP addresses',
'passing_criteria': 'Clean scan with no failures'
},
'remediation_timeline': {
'critical': '24 hours',
'high': '7 days',
'medium': '30 days',
'low': '90 days'
}
}
return scan_config
'''
}
return controls
```
### 7. Continuous Compliance Monitoring
Set up automated compliance monitoring:
**Compliance Dashboard**
```python
class ComplianceDashboard:
def generate_realtime_dashboard(self):
"""
Real-time compliance status dashboard
"""
dashboard = {
'timestamp': datetime.utcnow(),
'overall_compliance_score': 0,
'regulations': {}
}
# GDPR Compliance Metrics
dashboard['regulations']['GDPR'] = {
'score': self.calculate_gdpr_score(),
'status': 'COMPLIANT',
'metrics': {
'consent_rate': '87%',
'data_requests_sla': '98% within 30 days',
'privacy_policy_version': '2.1',
'last_dpia': '2025-06-15',
'encryption_coverage': '100%',
'third_party_agreements': '12/12 signed'
},
'issues': [
{
'severity': 'medium',
'issue': 'Cookie consent banner update needed',
'due_date': '2025-08-01'
}
]
}
# HIPAA Compliance Metrics
dashboard['regulations']['HIPAA'] = {
'score': self.calculate_hipaa_score(),
'status': 'NEEDS_ATTENTION',
'metrics': {
'risk_assessment_current': True,
'workforce_training_compliance': '94%',
'baa_agreements': '8/8 current',
'encryption_status': 'All PHI encrypted',
'access_reviews': 'Completed 2025-06-30',
'incident_response_tested': '2025-05-15'
},
'issues': [
{
'severity': 'high',
'issue': '3 employees overdue for training',
'due_date': '2025-07-25'
}
]
}
return dashboard
```
**Automated Compliance Checks**
```yaml
# .github/workflows/compliance-check.yml
name: Compliance Checks
on:
push:
branches: [main, develop]
pull_request:
schedule:
- cron: '0 0 * * *' # Daily compliance check
jobs:
compliance-scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: GDPR Compliance Check
run: |
python scripts/compliance/gdpr_checker.py
- name: Security Headers Check
run: |
python scripts/compliance/security_headers.py
- name: Dependency License Check
run: |
license-checker --onlyAllow 'MIT;Apache-2.0;BSD-3-Clause;ISC'
- name: PII Detection Scan
run: |
# Scan for hardcoded PII
python scripts/compliance/pii_scanner.py
- name: Encryption Verification
run: |
# Verify all sensitive data is encrypted
python scripts/compliance/encryption_checker.py
- name: Generate Compliance Report
if: always()
run: |
python scripts/compliance/generate_report.py > compliance-report.json
- name: Upload Compliance Report
uses: actions/upload-artifact@v3
with:
name: compliance-report
path: compliance-report.json
```
### 8. Compliance Documentation
Generate required documentation:
**Privacy Policy Generator**
```python
def generate_privacy_policy(company_info, data_practices):
"""
Generate GDPR-compliant privacy policy
"""
policy = f"""
# Privacy Policy
**Last Updated**: {datetime.now().strftime('%B %d, %Y')}
## 1. Data Controller
{company_info['name']}
{company_info['address']}
Email: {company_info['privacy_email']}
DPO: {company_info.get('dpo_contact', 'privacy@company.com')}
## 2. Data We Collect
{generate_data_collection_section(data_practices['data_types'])}
## 3. Legal Basis for Processing
{generate_legal_basis_section(data_practices['purposes'])}
## 4. Your Rights
Under GDPR, you have the following rights:
- Right to access your personal data
- Right to rectification
- Right to erasure ('right to be forgotten')
- Right to restrict processing
- Right to data portability
- Right to object
- Rights related to automated decision making
## 5. Data Retention
{generate_retention_policy(data_practices['retention_periods'])}
## 6. International Transfers
{generate_transfer_section(data_practices['international_transfers'])}
## 7. Contact Us
To exercise your rights, contact: {company_info['privacy_email']}
"""
return policy
```
## Output Format
1. **Compliance Assessment**: Current compliance status across all applicable regulations
2. **Gap Analysis**: Specific areas needing attention with severity ratings
3. **Implementation Plan**: Prioritized roadmap for achieving compliance
4. **Technical Controls**: Code implementations for required controls
5. **Policy Templates**: Privacy policies, consent forms, and notices
6. **Audit Procedures**: Scripts for continuous compliance monitoring
7. **Documentation**: Required records and evidence for auditors
8. **Training Materials**: Workforce compliance training resources
Focus on practical implementation that balances compliance requirements with business operations and user experience.

1597
tools/config-validate.md Normal file
View File

File diff suppressed because it is too large Load Diff

70
tools/context-restore.md Normal file
View File

@@ -0,0 +1,70 @@
---
model: claude-sonnet-4-0
---
Restore saved project context for agent coordination:
[Extended thinking: This tool uses the context-manager agent to restore previously saved project context, enabling continuity across sessions and providing agents with comprehensive project knowledge.]
## Context Restoration Process
Use Task tool with subagent_type="context-manager" to restore and apply saved context.
Prompt: "Restore project context for: $ARGUMENTS. Perform the following:
1. **Locate Saved Context**
- Find the most recent or specified context version
- Validate context integrity
- Check compatibility with current codebase
2. **Load Context Components**
- Project overview and goals
- Architectural decisions and rationale
- Technology stack and patterns
- Previous agent work and findings
- Known issues and roadmap
3. **Apply Context**
- Set up working environment based on context
- Restore project-specific configurations
- Load coding conventions and patterns
- Prepare agent coordination history
4. **Validate Restoration**
- Verify context applies to current code state
- Identify any conflicts or outdated information
- Flag areas that may need updates
5. **Prepare Summary**
- Key points from restored context
- Important decisions and patterns
- Recent work and current focus
- Suggested next steps
Return a comprehensive summary of the restored context and any issues encountered."
## Context Integration
The restored context will:
- Inform all subsequent agent invocations
- Maintain consistency with past decisions
- Provide historical knowledge to agents
- Enable seamless work continuation
## Usage Scenarios
Use context restoration when:
- Starting work after a break
- Switching between projects
- Onboarding to an existing project
- Needing historical project knowledge
- Coordinating complex multi-agent workflows
## Additional Options
- Restore specific context version: Include version timestamp
- Partial restoration: Restore only specific components
- Merge contexts: Combine multiple context versions
- Diff contexts: Compare current state with saved context
Context to restore: $ARGUMENTS

70
tools/context-save.md Normal file
View File

@@ -0,0 +1,70 @@
---
model: claude-sonnet-4-0
---
Save current project context for future agent coordination:
[Extended thinking: This tool uses the context-manager agent to capture and preserve project state, decisions, and patterns. This enables better continuity across sessions and improved agent coordination.]
## Context Capture Process
Use Task tool with subagent_type="context-manager" to save comprehensive project context.
Prompt: "Save comprehensive project context for: $ARGUMENTS. Capture:
1. **Project Overview**
- Project goals and objectives
- Key architectural decisions
- Technology stack and dependencies
- Team conventions and patterns
2. **Current State**
- Recently implemented features
- Work in progress
- Known issues and technical debt
- Performance baselines
3. **Design Decisions**
- Architectural choices and rationale
- API design patterns
- Database schema decisions
- Security implementations
4. **Code Patterns**
- Coding conventions used
- Common patterns and abstractions
- Testing strategies
- Error handling approaches
5. **Agent Coordination History**
- Which agents worked on what
- Successful agent combinations
- Agent-specific context and findings
- Cross-agent dependencies
6. **Future Roadmap**
- Planned features
- Identified improvements
- Technical debt to address
- Performance optimization opportunities
Save this context in a structured format that can be easily restored and used by future agent invocations."
## Context Storage
The context will be saved to `.claude/context/` with:
- Timestamp-based versioning
- Structured JSON/Markdown format
- Easy restoration capabilities
- Context diffing between versions
## Usage Scenarios
This saved context enables:
- Resuming work after breaks
- Onboarding new team members
- Maintaining consistency across agent invocations
- Preserving architectural decisions
- Tracking project evolution
Context to save: $ARGUMENTS

1451
tools/cost-optimize.md Normal file
View File

File diff suppressed because it is too large Load Diff

60
tools/data-pipeline.md Normal file
View File

@@ -0,0 +1,60 @@
---
model: claude-sonnet-4-0
---
# Data Pipeline Architecture
Design and implement a scalable data pipeline for: $ARGUMENTS
Create a production-ready data pipeline including:
1. **Data Ingestion**:
- Multiple source connectors (APIs, databases, files, streams)
- Schema evolution handling
- Incremental/batch loading
- Data quality checks at ingestion
- Dead letter queue for failures
2. **Transformation Layer**:
- ETL/ELT architecture decision
- Apache Beam/Spark transformations
- Data cleansing and normalization
- Feature engineering pipeline
- Business logic implementation
3. **Orchestration**:
- Airflow/Prefect DAGs
- Dependency management
- Retry and failure handling
- SLA monitoring
- Dynamic pipeline generation
4. **Storage Strategy**:
- Data lake architecture
- Partitioning strategy
- Compression choices
- Retention policies
- Hot/cold storage tiers
5. **Streaming Pipeline**:
- Kafka/Kinesis integration
- Real-time processing
- Windowing strategies
- Late data handling
- Exactly-once semantics
6. **Data Quality**:
- Automated testing
- Data profiling
- Anomaly detection
- Lineage tracking
- Quality metrics and dashboards
7. **Performance & Scale**:
- Horizontal scaling
- Resource optimization
- Caching strategies
- Query optimization
- Cost management
Include monitoring, alerting, and data governance considerations. Make it cloud-agnostic with specific implementation examples for AWS/GCP/Azure.

Some files were not shown because too many files have changed in this diff Show More