davila7--claude-code-templates/CONTRIBUTING.md

Contributing to Claude Code Templates

We welcome contributions! Help us make Claude Code even better for everyone.

📋 Before contributing, please read our Code of Conduct to ensure a respectful and inclusive environment for all community members.

🧩 Contributing Components

The easiest way to contribute is by adding individual components like agents, commands, MCPs, settings, or hooks.

🤖 Adding Agents

Agents are AI specialists for specific domains (security, performance, frameworks, etc.).

1. Create Agent File

   # Navigate to appropriate category
   cd cli-tool/components/agents/[category]/
   
   # Create your agent file
   touch your-agent-name.md
   

2. Agent File Structure

   # Agent Name
   
   Agent description and purpose.
   
   ## Expertise
   - Specific domain knowledge
   - Key capabilities
   - Use cases
   
   ## Instructions
   Detailed instructions for Claude on how to act as this agent.
   
   ## Examples
   Practical examples of agent usage.
   

3. Available Categories

   • development-team/ - Full-stack developers, architects
   • domain-experts/ - Security, performance, accessibility specialists
   • creative-team/ - Content creators, designers
   • business-team/ - Product managers, analysts
   • development-tools/ - Tool specialists, DevOps experts

4. Creating New Categories If your agent doesn't fit existing categories, create a new one:

   # Create new category folder
   cd cli-tool/components/agents/
   mkdir your-new-category
   
   # Add your agent file to the new category
   cd your-new-category/
   touch your-agent-name.md
   

⚡ Adding Commands

Commands are custom slash commands that extend Claude Code functionality.

1. Create Command File

   cd cli-tool/components/commands/[category]/
   touch your-command-name.md
   

2. Command File Structure

   # /command-name
   
   Brief command description.
   
   ## Purpose
   What this command accomplishes.
   
   ## Usage
   How to use the command with examples.
   
   ## Implementation
   Technical details of what the command does.
   

3. Command Categories

   • code-generation/ - Generate code, tests, documentation
   • analysis/ - Code analysis, optimization, debugging
   • project-management/ - File operations, project structure
   • testing/ - Test generation, validation, coverage
   • deployment/ - Build, deploy, CI/CD operations

4. Creating New Categories If your command doesn't fit existing categories, create a new one:

   # Create new category folder
   cd cli-tool/components/commands/
   mkdir your-new-category
   
   # Add your command file to the new category
   cd your-new-category/
   touch your-command-name.md
   

🔌 Adding MCPs (Model Context Protocol)

MCPs provide external service integrations for Claude Code.

1. Create MCP File

   cd cli-tool/components/mcps/[category]/
   touch your-service-mcp.json
   

2. MCP File Structure

   {
     "mcpServers": {
       "service-name": {
         "command": "npx",
         "args": ["-y", "@your-org/mcp-server"],
         "env": {
           "API_KEY": "<YOUR_API_KEY>",
           "BASE_URL": "https://api.service.com"
         }
       }
     }
   }
   

3. MCP Categories

   • audio/ - Audio processing, text-to-speech, transcription services
   • integration/ - GitHub, GitLab, Jira
   • database/ - PostgreSQL, MySQL, MongoDB
   • cloud/ - AWS, Azure, GCP services
   • devtools/ - Build tools, testing frameworks
   • ai-services/ - OpenAI, Anthropic, other AI APIs

4. Creating New Categories If your MCP doesn't fit existing categories, create a new one:

   # Create new category folder
   cd cli-tool/components/mcps/
   mkdir your-new-category
   
   # Add your MCP file to the new category
   cd your-new-category/
   touch your-service-mcp.json
   

⚙️ Adding Settings

Settings configure Claude Code behavior and performance.

1. Create Settings File

   cd cli-tool/components/settings/[category]/
   touch your-setting-name.json
   

2. Settings File Structure

   {
     "setting-category": {
       "parameter": "value",
       "description": "What this setting controls"
     }
   }
   

3. Settings Categories

   • performance/ - Memory, timeout, cache settings
   • ui/ - Interface customization, themes
   • mcp/ - MCP server configurations
   • security/ - Access control, permissions

4. Creating New Categories If your setting doesn't fit existing categories, create a new one:

   # Create new category folder
   cd cli-tool/components/settings/
   mkdir your-new-category
   
   # Add your setting file to the new category
   cd your-new-category/
   touch your-setting-name.json
   

🪝 Adding Hooks

Hooks provide automation triggers for different development events.

1. Create Hook File

   cd cli-tool/components/hooks/[category]/
   touch your-hook-name.json
   

2. Hook File Structure

   {
     "hooks": {
       "hook-name": {
         "event": "trigger-event",
         "command": "action-to-perform",
         "description": "What this hook does"
       }
     }
   }
   

3. Hook Categories

   • git/ - Pre-commit, post-commit, pre-push
   • development/ - File changes, build events
   • testing/ - Test execution, coverage checks

4. Creating New Categories If your hook doesn't fit existing categories, create a new one:

   # Create new category folder
   cd cli-tool/components/hooks/
   mkdir your-new-category
   
   # Add your hook file to the new category
   cd your-new-category/
   touch your-hook-name.json
   

📦 Contributing Templates

Templates are complete project configurations that include CLAUDE.md, .claude/* files, and .mcp.json.

Creating New Templates

1. Create Template Directory

   cd cli-tool/templates/
   mkdir your-template-name
   cd your-template-name
   

2. Template Structure

   your-template-name/
   ├── CLAUDE.md                    # Main configuration
   ├── .claude/
   │   ├── settings.json           # Automation hooks
   │   └── commands/               # Template-specific commands
   ├── .mcp.json                   # MCP server configuration
   └── README.md                   # Template documentation
   

3. CLAUDE.md Guidelines

   • Include project-specific configuration
   • Add development commands and workflows
   • Document best practices and conventions
   • Include security guidelines
   • Provide testing standards

4. Template Categories

   • Framework-specific (React, Vue, Angular, etc.)
   • Language-specific (Python, TypeScript, Go, etc.)
   • Domain-specific (API development, machine learning, etc.)
   • Industry-specific (e-commerce, fintech, etc.)

Template Quality Standards

• Comprehensive Configuration - Include all necessary Claude Code setup
• Clear Documentation - Well-documented CLAUDE.md with examples
• Practical Commands - Useful slash commands for the domain
• Proper MCPs - Relevant external integrations
• Testing - Test template with real projects

🛠️ Contributing to Additional Tools

For advanced contributors who want to improve the CLI tools like analytics, health check, and chat monitoring.

🚀 Development Setup

Prerequisites

• Node.js 14+ (for the installer)
• npm or yarn
• Git

Project Setup

# Clone the repository
git clone https://github.com/davila7/claude-code-templates.git
cd claude-code-templates

# Navigate to the CLI tool directory
cd cli-tool

# Install dependencies
npm install

# Link for local testing
npm link

# Run test suite
npm test

📊 Analytics Dashboard Development

The analytics dashboard provides real-time monitoring of Claude Code sessions.

Development Workflow

# Start analytics dashboard
npm run analytics:start

# Clear cache during development
curl -X POST http://localhost:3333/api/cache/clear -H "Content-Type: application/json" -d '{"type":"all"}'

# Refresh data
curl http://localhost:3333/api/refresh

# Restart server completely
pkill -f analytics && sleep 3 && npm run analytics:start

Architecture

src/analytics/
├── core/                     # Business logic
│   ├── StateCalculator.js   # Conversation state detection
│   ├── ProcessDetector.js   # Running process detection
│   ├── ConversationAnalyzer.js # Message parsing
│   └── FileWatcher.js       # Real-time file monitoring
├── data/                    # Data management
│   └── DataCache.js        # Multi-level caching
├── notifications/           # Real-time communication
│   ├── WebSocketServer.js  # Server-side WebSocket
│   └── NotificationManager.js # Event-driven notifications
└── utils/                   # Utilities
    └── PerformanceMonitor.js # System health monitoring

Common Development Issues

Problem: Changes don't appear in dashboard

# Solution: Clear cache and refresh
curl -X POST http://localhost:3333/api/cache/clear -H "Content-Type: application/json" -d '{"type":"conversations"}'
curl http://localhost:3333/api/refresh

Problem: WebSocket not updating

# Solution: Hard refresh browser (Ctrl+F5 or Cmd+Shift+R)

💬 Chat Monitor Development

Mobile-optimized interface for viewing Claude conversations in real-time.

Architecture

src/chats/
├── components/              # UI components
├── services/               # API communication
├── websocket/              # Real-time updates
└── styles/                 # Mobile-first CSS

Development Commands

# Start chat monitor
npm run chats:start

# Start with tunnel (requires cloudflared)
npm run chats:start -- --tunnel

# Test mobile interface
npm run chats:test

🔍 Health Check Development

Comprehensive diagnostics tool for Claude Code installations.

Health Check Categories

• Installation Validation - Claude Code setup verification
• Configuration Check - Settings and file validation
• Performance Analysis - Memory, disk, network diagnostics
• Security Audit - Permission and access checks

Development

# Run health check
npm run health-check

# Add new health check
# 1. Create check in src/health-checks/
# 2. Add to health check registry
# 3. Test with various scenarios

🧪 Testing

Component Testing

# Test component installation
npx claude-code-templates@latest --agent your-agent --dry-run
npx claude-code-templates@latest --command your-command --dry-run
npx claude-code-templates@latest --mcp your-mcp --dry-run

Template Testing

# Test template installation
npx claude-code-templates@latest --template your-template --dry-run

# Test with specific scenarios
npm start -- --language python --framework django --dry-run
npm start -- --language javascript --framework react --dry-run

Tool Testing

# Test analytics
npm run analytics:test

# Test chat monitor
npm run chats:test

# Test health check
npm run health-check:test

🤝 Contribution Process

1. Fork and Clone

git clone https://github.com/your-username/claude-code-templates.git
cd claude-code-templates

2. Create Feature Branch

git checkout -b feature/your-contribution

3. Make Changes

• Follow the guidelines above for your contribution type
• Test thoroughly with real scenarios
• Include comprehensive documentation

4. Test Changes

cd cli-tool
npm test
npm start -- --dry-run

5. Submit Pull Request

• Clear description of changes
• Screenshots for UI changes
• Testing instructions
• Reference related issues

🎯 What We're Looking For

High Priority Components

• Security Agents - Security auditing, vulnerability scanning
• Performance Commands - Optimization, profiling, monitoring
• Cloud MCPs - AWS, Azure, GCP integrations
• Framework Agents - React, Vue, Angular, Next.js specialists

High Priority Templates

• Modern Frameworks - Svelte, SvelteKit, Astro, Qwik
• Backend Frameworks - NestJS, Fastify, Hono, tRPC
• Full-Stack - T3 Stack, create-remix-app, SvelteKit
• Mobile - React Native, Expo, Flutter

Medium Priority Tools

• Analytics Enhancements - Better visualizations, export options
• Chat Monitor Features - Search, filtering, conversation history
• Health Check Improvements - More diagnostic categories, fix suggestions

📞 Getting Help

Community Support

• GitHub Issues - Report bugs or request features
• GitHub Discussions - Join community discussions
• Documentation - Complete guides at docs.aitmpl.com

Quick Start Guides

• Browse Components - aitmpl.com to see existing components
• Component Examples - Check existing components for structure reference
• Template Examples - Review successful templates for best practices

📄 License

By contributing to this project, you agree that your contributions will be licensed under the MIT License.

🙏 Recognition

All contributors are recognized in our:

• GitHub Contributors page
• Release Notes for significant contributions
• Community Discussions for helpful contributions

Thank you for helping make Claude Code Templates better for everyone! 🚀