# AI Coding Assistants Setup
[](https://github.com/CodySwannGT/ai-coding-assistants-setup/actions/workflows/ci.yml)
[](https://github.com/CodySwannGT/ai-coding-assistants-setup/actions/workflows/quality.yml)
**Enterprise-grade development workflow automation powered by AI coding assistants**
[Setup](#-setup) • [Features](#-features) • [Prerequisites](#-prerequisites) • [Documentation](#-documentation) • [Contributing](./CONTRIBUTING.md) • [License](#license)
---
## 🚀 Quick Start
Get started in seconds with a single command:
```bash
npx ai-coding-assistants-setup
```
This command will:
- ✅ Analyze your project and detect existing tools
- ✅ Install and configure essential development tools (Husky, ESLint, Prettier, CommitLint)
- ✅ Set up GitHub Actions workflows for CI/CD
- ✅ Add required npm scripts for quality checks
- ✅ Create AI assistant configuration files
- ✅ Set up environment templates
### Options
```bash
npx ai-coding-assistants-setup --help # Show help
npx ai-coding-assistants-setup --dry-run # Preview changes without modifying files
npx ai-coding-assistants-setup --non-interactive # Skip prompts, use defaults
npx ai-coding-assistants-setup --verbose # Show detailed output
```
## 🚀 Overview
AI Coding Assistants Setup is a comprehensive toolkit that transforms your development workflow with enterprise-grade automation, quality assurance, and AI-powered assistance. This project provides production-ready configurations for Claude Code, Roo Code, and other AI assistants, along with automated workflows for code quality, security scanning, performance testing, and release management.
### 🤖 AI Coding Assistants
#### Claude Code
[Claude Code](https://docs.anthropic.com/en/docs/claude-code) is Anthropic's official AI coding assistant that provides:
- **Intelligent Code Generation**: Write, debug, and refactor code with context-aware suggestions
- **Multi-file Editing**: Work across multiple files with understanding of your entire codebase
- **Integrated Terminal**: Execute commands and see results directly within your workflow
- **GitHub Integration**: Automated PR reviews and issue management
- **MCP Support**: Extensible through Model Context Protocol servers
[📚 Claude Code Documentation](https://docs.anthropic.com/en/docs/claude-code) | [🛠️ CLI Usage](https://docs.anthropic.com/en/docs/claude-code/cli-usage) | [🔧 Settings](https://docs.anthropic.com/en/docs/claude-code/settings)
#### Roo Code
[Roo Code](https://docs.roo.ai) is an AI-powered development environment that offers:
- **Mode-based Development**: Specialized modes for different tasks (architect, debugger, tester, etc.)
- **SPARC Methodology**: Structured approach to complex development workflows
- **Persistent Memory**: Maintains context across sessions through knowledge graphs
- **Custom Workflows**: Define project-specific modes and behaviors
- **Team Collaboration**: Share configurations and knowledge across your team
[📚 Roo Code Documentation](https://docs.roo.ai) | [🎯 SPARC Methodology](https://docs.roo.ai/sparc) | [⚙️ Custom Modes](https://docs.roo.ai/modes)
### Why Use This?
- **🏢 Enterprise Ready**: Battle-tested configurations used in production environments
- **🔒 Security First**: Automated security scanning, secret detection, and compliance checks
- **🚄 Performance Optimized**: Built-in load testing and performance monitoring
- **🤖 AI-Powered**: Leverage Claude and Roo's capabilities for code reviews, documentation, and more
- **📊 Quality Assured**: Comprehensive testing frameworks and code quality tools
- **🔄 Fully Automated**: From commit to deployment with intelligent workflows
## ✨ Features
### 🤖 AI Assistant Integration
- **Claude Code Integration**: Automated code reviews, security analysis, and documentation generation
- **GitHub App Support**: Seamless integration with Claude's GitHub app for PR reviews
- **MCP Server Configuration**: Model Context Protocol support for enhanced AI capabilities
- **Custom Commands**: Pre-configured Claude commands for common development tasks
### 🛡️ Security & Compliance
- **Multi-layered Security Scanning**: GitGuardian, Snyk, and custom security checks
- **Secret Detection**: Automated scanning for exposed credentials and API keys
- **License Compliance**: FOSSA integration for license validation
- **Vulnerability Management**: Dependabot configuration for dependency updates
### 📈 Quality Assurance
- **Automated Code Reviews**: AI-powered reviews with customizable guidelines
- **Code Quality Analysis**: SonarCloud integration for maintainability metrics
- **Test Automation**: Support for unit, integration, and E2E testing
- **Performance Testing**: K6 load testing with cloud integration
### 🚀 CI/CD Workflows
- **GitHub Actions Workflows**: Production-ready pipelines for quality, release, and testing
- **Semantic Release**: Automated versioning and changelog generation
- **Multi-environment Support**: Configurations for dev, staging, and production
- **Rollback Capabilities**: Safe deployment with automated rollback options
### 🪝 Git Hooks & Automation
- **Pre-commit Hooks**: Automated linting, formatting, and security checks
- **Commit Message Standards**: Conventional commits with Jira integration
- **Branch Protection**: Automated checks before allowing merges
- **Change Detection**: Smart workflows that only run when needed
## 📋 Prerequisites
- **Node.js**: Version 18.0.0 or higher
- **npm**: Version 7.0.0 or higher
- **Git**: Version 2.30.0 or higher
- **GitHub Account**: For workflow automation
- **Claude API Key**: For AI-powered features
## 🏁 Setup
> **Note**: The Quick Start command above (`npx ai-coding-assistants-setup`) is the recommended way to set up your project. The sections below provide additional details and manual setup options.
### What Gets Modified
When you run the setup command, the following changes will be made to your project:
#### Files Created
- `.github/workflows/` - CI/CD pipelines for quality checks and releases
- `.husky/` - Git hooks for pre-commit and commit message validation
- `.claude/` - Claude AI assistant configuration
- `.eslintrc.json` - ESLint configuration
- `.prettierrc.json` - Prettier formatting rules
- `commitlint.config.js` - Commit message standards
- `.env.example` - Environment variable template
- `CLAUDE.md` - Project context for AI assistants
- Various other configuration files
#### package.json Updates
The following scripts will be added (existing scripts are preserved):
```json
{
"scripts": {
"lint": "echo \"lint not configured yet\"",
"typecheck": "echo \"typecheck not configured yet\"",
"format:check": "echo \"format:check not configured yet\"",
"build": "echo \"build not configured yet\"",
"test": "echo \"test not configured yet\"",
"test:unit": "echo \"test:unit not configured yet\"",
"test:integration": "echo \"test:integration not configured yet\"",
"test:e2e": "echo \"test:e2e not configured yet\""
}
}
```
These are placeholder scripts that ensure your CI/CD workflows can run immediately. Replace them with your actual commands as you implement each tool.
### Customizing Lint and Format Rules
The setup creates **default configuration files** for ESLint and Prettier, but **projects are free to customize or replace these entirely** with their own rules:
#### ESLint Configuration
The default `.eslintrc.json` provides basic rules, but you can:
```bash
# Replace with your existing ESLint config
cp your-existing/.eslintrc.json .eslintrc.json
# Or extend/modify the generated config
# Edit .eslintrc.json to add your custom rules, plugins, and extends
```
**Example custom configuration:**
```json
{
"extends": [
"eslint:recommended",
"@typescript-eslint/recommended",
"your-company/eslint-config"
],
"plugins": ["your-custom-plugin"],
"rules": {
"your-custom-rule": "error",
"indent": ["error", 2],
"quotes": ["error", "single"]
}
}
```
#### Prettier Configuration
The default `.prettierrc.json` uses standard formatting, but you can:
```bash
# Replace with your existing Prettier config
cp your-existing/.prettierrc.json .prettierrc.json
# Or customize the generated config
# Edit .prettierrc.json with your team's preferences
```
**Example custom configuration:**
```json
{
"semi": false,
"singleQuote": true,
"tabWidth": 4,
"trailingComma": "all",
"printWidth": 100,
"useTabs": false
}
```
#### Using Existing Configuration
If your project already has lint/format configurations:
1. **Keep your existing files** - The setup won't overwrite existing `.eslintrc.*` or `.prettierrc.*` files
2. **Update package.json scripts** - Ensure your `lint` and `format:check` scripts work with your configurations
3. **Verify CI compatibility** - Test that your custom rules work with the CI/CD workflows
#### Framework-Specific Configurations
The setup supports any ESLint/Prettier configuration, including:
- **React**: `eslint-plugin-react`, `@typescript-eslint/parser`
- **Vue**: `eslint-plugin-vue`, `@vue/eslint-config-prettier`
- **Angular**: `@angular-eslint/eslint-plugin`
- **Node.js**: `eslint-plugin-node`
- **Custom company standards**: Your internal ESLint configs
#### Validation
After customizing your rules, verify they work with the CI system:
```bash
# Test your custom lint configuration
npm run lint
# Test your custom format configuration
npm run format:check
# Run a complete quality check
npm run test && npm run lint && npm run format:check
```
The AI Coding Assistants Setup provides the **infrastructure and automation**, while giving you **complete freedom** to define your code style and quality standards.
### Optional Dependencies
After running the setup, you may want to install these development tools that the configuration files support:
```bash
# Code Quality Tools
npm install --save-dev eslint prettier eslint-config-prettier eslint-plugin-prettier
# Git Hooks
npm install --save-dev husky
npx husky install
# Commit Standards
npm install --save-dev @commitlint/cli @commitlint/config-conventional
# TypeScript (if using)
npm install --save-dev typescript @types/node
# Testing (choose based on your needs)
npm install --save-dev jest @types/jest # For Jest
npm install --save-dev vitest # For Vitest
npm install --save-dev mocha chai # For Mocha/Chai
```
**Note:** The setup tool only copies configuration files. Installing these packages is optional and depends on which tools you want to use in your project.
### Manual Setup
If you prefer to set up manually or need to customize specific parts:
#### 1. Environment Configuration
Create a `.env` file in your project root:
```bash
# Only the Anthropic API key goes here
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxxxxxxxxxxxx
```
Configure additional API keys in `.claude/settings.local.json` (copy from `.claude/settings.local.json.example`):
- GitHub Personal Access Token
- Optional: Context7, Brave, Firecrawl API keys
See the [Environment Variables Documentation](./docs/ENVIRONMENT_VARS.md) for the complete reference of all available environment variables.
#### 2. Copy Required Files
Copy these files and directories to your project:
#### GitHub Workflows and Configuration
- `.github/workflows/quality.yml` - Automated quality checks for PRs (testing, linting, security scanning)
- `.github/workflows/release.yml` - Semantic release automation with changelog generation
- `.github/workflows/load-test.yml` - K6 performance testing pipeline
- `.github/workflows/ci.yml.example` - Example CI workflow caller for pull requests
- `.github/workflows/deploy.yml.example` - Example deployment workflow showing the complete pattern: release → deploy → load test
- `.github/workflows/k6/` - K6 test scripts and configurations
- `.github/workflows/scripts/` - Helper scripts for CI/CD operations
- `.github/code_review_guidelines.md` - Guidelines for AI-powered code reviews
- `.github/security_scan_guidelines.md` - Security scanning configuration
- `.github/dependabot.yml` - Automated dependency updates
**Note:** The workflow files (`quality.yml`, `release.yml`, `load-test.yml`) are reusable workflows. You need to create caller workflows in your project to use them. Example callers are provided in `ci.yml.example` and `deploy.yml.example`. See [Step 6: Create Workflow Callers](#6-create-workflow-callers) below for detailed instructions.
#### Git Hooks
- `.husky/pre-commit` - Pre-commit checks (linting, formatting, tests)
- `.husky/commit-msg` - Commit message validation and Jira key detection
#### Claude Configuration
- `.claude/commands/project.md` - Custom Claude commands for your project
- `.claude/settings.json` - Claude project settings
- `.claude/settings.local.json.example` → `.claude/settings.local.json` - Local API keys and MCP configuration
#### Other Configuration Files
- `.mcp.json` - Model Context Protocol server configuration
- `sonar-project.properties.example` → `sonar-project.properties` - SonarCloud configuration
- `commitlint.config.js` - Commit message standards enforcement
- `.env.example` → `.env` - Environment variables template
#### 3. Install Claude GitHub App
```bash
# Open Claude CLI
claude
# Install the GitHub app
/install-github-app
```
See [Claude GitHub Actions Documentation](https://docs.anthropic.com/en/docs/claude-code/github-actions) for more details.
#### 4. Configure GitHub Secrets
Use the GitHub CLI to set up secrets from your `.env` file:
```bash
# Copy .github/workflows/.env.example to .github/workflows/.env
cp .github/workflows/.env.example .github/workflows/.env
# Edit the file with your values
# Then run:
gh secret set --env-file .github/workflows/.env
```
Required secrets:
- `PAT`: Your GitHub Personal Access Token
Optional secrets for enhanced features:
- Security scanning: `SONAR_TOKEN`, `SNYK_TOKEN`, `GITGUARDIAN_API_KEY`
- Release management: `SENTRY_AUTH_TOKEN`, `SENTRY_ORG`, `SENTRY_PROJECT`
- Load testing: `K6_CLOUD_TOKEN`
- AI Security scanning and code reviews: `ANTHROPIC_API_KEY`
See the [Environment Variables Documentation](./docs/ENVIRONMENT_VARS.md) for details on all available secrets.
#### 5. Update package.json Scripts
Ensure your `package.json` includes these scripts:
```json
{
"scripts": {
"test:unit": "jest --testPathPattern=unit",
"test:integration": "jest --testPathPattern=integration",
"test:e2e": "jest --testPathPattern=e2e",
"lint": "eslint .",
"format:check": "prettier --check .",
"typecheck": "tsc --noEmit",
"build": "your-build-command"
}
}
```
#### 6. Create Workflow Callers
The workflow files you copied are reusable workflows. Create these caller workflows in your project's `.github/workflows/` directory. Example files are provided as `ci.yml.example` and `deploy.yml.example`.
#### Quality Workflow Caller (`ci.yml`)
```yaml
name: CI
on:
pull_request:
types: [opened, synchronize, reopened]
push:
branches:
- main
- develop
jobs:
quality:
uses: ./.github/workflows/quality.yml
secrets: inherit
```
#### Release and Deploy Workflow Caller (`deploy.yml`)
See `deploy.yml.example` for the complete pattern. The recommended approach:
```yaml
name: Deploy
on:
push:
branches:
- main # Production
- staging # Staging (includes automatic load testing)
- develop # Development
jobs:
# Step 1: Create release
release:
uses: ./.github/workflows/release.yml
with:
environment: ${{ github.ref_name }}
release_strategy: 'semantic'
require_approval: ${{ github.ref_name == 'main' }}
node_version: '20'
secrets: inherit
# Step 2: Deploy application
deploy:
needs: release
runs-on: ubuntu-latest
steps:
# Your custom deployment logic here
# Step 3: Load test (staging only)
load_test:
needs: [release, deploy]
if: github.ref_name == 'staging'
uses: ./.github/workflows/load-test.yml
with:
environment: staging
test_scenario: smoke
secrets: inherit
```
**Note:** The workflows are separated for flexibility. See `deploy.yml.example` for the complete implementation with all features.
#### Load Test Workflow Caller (`load-test-caller.yml`)
```yaml
name: Load Test
on:
workflow_dispatch:
inputs:
test_file:
description: 'K6 test file to run'
required: true
default: 'basic-load-test.js'
duration:
description: 'Test duration (e.g., 30s, 5m)'
required: false
default: '1m'
vus:
description: 'Number of virtual users'
required: false
default: '10'
jobs:
load-test:
uses: ./.github/workflows/load-test.yml
with:
test_file: ${{ github.event.inputs.test_file }}
duration: ${{ github.event.inputs.duration }}
vus: ${{ github.event.inputs.vus }}
secrets: inherit
```
## 📁 Project Structure
```
your-project/
├── .github/
│ ├── workflows/ # CI/CD pipelines
│ │ ├── quality.yml # Code quality checks
│ │ ├── release.yml # Automated releases with deployment
│ │ ├── load-test.yml # Performance testing
│ │ ├── ci.yml.example # Example CI caller workflow
│ │ └── deploy.yml.example # Example deployment workflow
│ ├── code_review_guidelines.md
│ └── security_scan_guidelines.md
├── .claude/ # Claude configuration
│ ├── commands/
│ └── settings.json
├── .husky/ # Git hooks
├── docs/ # Documentation
├── src/ # Your source code
└── tests/ # Test suites
```
## 🔄 Workflows
### Quality Workflow
Runs on every pull request:
- 🧪 Automated testing (unit, integration, E2E)
- 🔍 Code quality analysis
- 🛡️ Security scanning
- 📏 Code coverage reporting
- 🤖 AI-powered code review
### Release Workflow
Automated semantic releases:
- 📦 Version bumping
- 📝 Changelog generation
- 🏷️ Git tagging
- 📢 Release notifications
- 🔐 Signed releases (optional)
- 📋 SBOM generation (optional)
- ✅ Compliance validation
### Deployment Workflow
The recommended pattern (see `deploy.yml.example`):
1. 📦 **Release Creation**: Calls release.yml for versioning
2. 🚀 **Custom Deployment**: Your deployment logic (AWS, K8s, etc.)
3. 🔍 **Load Testing**: Automatic for staging environments
4. 📊 **Monitoring**: Post-deployment health checks
#### Post-Deployment Load Testing
The deployment workflow pattern includes automatic load tests for staging. This follows best practices:
- **Why staging?** Load testing on production can impact real users and should be done sparingly
- **Why post-deployment?** Ensures the deployed application is tested in its actual environment
- **Automatic execution**: No manual intervention needed for staging deployments
- **Non-blocking**: Load test failures won't rollback the deployment but are reported for review
### Load Testing Workflow
Performance validation:
- 📊 K6 load tests
- 📈 Performance metrics
- 🎯 Threshold validation
- ☁️ Cloud test execution
## 📚 Documentation
- [Environment Variables Reference](./docs/ENVIRONMENT_VARS.md) - Complete list of all environment variables and secrets
- [GitHub Repository Setup Guide](./docs/GITHUB_SETUP.md) - Comprehensive GitHub CLI commands for branch protection, status checks, and Copilot configuration
- [Third-Party Services Setup Guide](./docs/THIRD_PARTY_SETUP.md) - CLI-based setup instructions for Jira, Sentry, SonarCloud, Snyk, K6, and other integrations
### 🚀 Deployment and Load Testing Pattern
The recommended pattern separates concerns for maximum flexibility:
1. **Release Workflow** (`release.yml`): Creates semantic version, changelog, and GitHub release
2. **Deploy Workflow** (`deploy.yml.example`): Implements your custom deployment logic
3. **Load Test Workflow** (`load-test.yml`): Runs performance tests after deployment
#### Why This Pattern?
- **Flexibility**: Each project can implement its own deployment strategy (AWS, K8s, Vercel, etc.)
- **Reusability**: Release workflow remains unchanged across different deployment targets
- **Staging Load Tests**: Automatic load testing for staging, manual for production
- **Post-Deployment Testing**: Tests the actual deployed application, not just the build
- **Non-Blocking**: Load test failures are reported but don't rollback deployments
#### Implementing Your Deployment
1. Copy `deploy.yml.example` to `.github/workflows/deploy.yml`
2. Customize the `deploy` job with your deployment commands
3. The example includes:
- AWS CDK deployment example
- Environment URL output for load testing
- Automatic load testing for staging
- Post-deployment monitoring
#### Load Test Configuration
For staging deployments, the example workflow:
- Runs a smoke test (5 minutes, 50 virtual users)
- Uses the deployment URL from your deploy job
- Reports results without blocking the release
- Can be customized in the `load_testing` job
To run load tests manually or with different parameters, use the `load-test-caller.yml` example.
## 🔧 Development
### Local Testing
To test the npx command locally during development:
```bash
# Link the package globally
npm link
# Test the command
ai-coding-assistants-setup --help
# Or test with npx from the project directory
npx . --help
```
### Unlink After Testing
```bash
npm unlink -g ai-coding-assistants-setup
```
## 🤝 Contributing
We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.
## 📄 License
This project is licensed under the MIT License - see the [LICENSE](./LICENSE.md) file for details.
## 🙏 Acknowledgments
- [Claude](https://www.anthropic.com/claude) - AI assistant by Anthropic
- [GitHub Actions](https://github.com/features/actions) - CI/CD platform
- [K6](https://k6.io/) - Load testing framework
- [SonarCloud](https://sonarcloud.io/) - Code quality platform
- [Husky](https://typicode.github.io/husky/) - Git hooks management
---
**Built with ❤️ by [Cody Swann](https://github.com/CodySwannGT)**
[Report Bug](https://github.com/CodySwannGT/ai-coding-assistants-setup/issues) • [Request Feature](https://github.com/CodySwannGT/ai-coding-assistants-setup/issues) • [Documentation](./docs/)