# ccsetup

[![npm version](https://img.shields.io/npm/v/ccsetup.svg)](https://www.npmjs.com/package/ccsetup)
[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/marcia-ong/ccsetup/pulls)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![npm downloads](https://img.shields.io/npm/dm/ccsetup.svg)](https://www.npmjs.com/package/ccsetup)

Quick setup for Claude Code projects with built-in 50+ agents, ticket system, planning tools and agent orchestration workflow.

## Installation

```bash
# Create a new project
npx ccsetup my-project

# Setup in current directory
npx ccsetup .

# Install globally (optional)
npm install -g ccsetup
ccsetup my-project
```

## Command Line Options

```bash
ccsetup [project-name] [options]

Options:
  --force, -f     Skip all prompts and overwrite existing files
  --dry-run, -d   Show what would be done without making changes
  --agents        Interactive agent selection mode
  --all-agents    Include all agents without prompting
  --no-agents     Skip agent selection entirely
  --browse-agents Copy all agents to /agents folder for browsing
  --help, -h      Show help message

Examples:
  ccsetup                      # Create in current directory
  ccsetup my-project           # Create in new directory
  ccsetup . --force            # Overwrite files in current directory
  ccsetup my-app --dry-run     # Preview changes without creating files
  ccsetup --agents             # Interactive agent selection only
  ccsetup my-app --all-agents  # Include all agents automatically
  ccsetup --browse-agents      # Copy all agents for manual selection
```

## What's Included

The boilerplate template creates:

- **CLAUDE.md** - Project instructions for Claude
- **GEMINI.md** - (Optional) Waterfall Architect prompt for comprehensive task planning - optimized for Gemini's larger context window
- **agents/** - Specialized AI agents (planner, coder, checker, etc.)
- **tickets/** - Task tracking system
- **plans/** - Project planning documents
- **docs/** - Documentation with ROADMAP.md and agent-orchestration.md
- **.claude/** - Claude Code specific directory structure (created automatically)

## Key Features

- 🎯 **Interactive Agent Selection** - Choose which agents to include during setup
- 📚 **Browse Mode** - Copy all 50+ agents to explore and manually select later
- 🔄 **Agent Orchestration Workflows** - Pre-defined workflows that automatically coordinate multiple agents for complex tasks
- 🔒 **Smart Conflict Resolution** - Handle existing files with skip/rename/overwrite options
- 📁 **.claude Directory Support** - Automatic creation of Claude Code directory structure
- 🏃 **Dry Run Mode** - Preview changes before applying them
- ⚡ **Force Mode** - Skip all prompts for automated workflows
- 🎨 **Standalone Agent Preview** - Explore available agents without setup
- 🎭 **Systematic Task Execution** - Agents work in sequence, building on each other's outputs

## Project Structure

- **templates/** - The boilerplate templates that will be copied to user's project
- **bin/** - CLI executable for ccsetup
- **agents/**, **docs/**, **plans/**, **tickets/** - Working files for ccsetup development (not part of the template)

## Usage

1. Create a new project:

   ```bash
   npx ccsetup my-awesome-project
   cd my-awesome-project
   ```

2. Edit `CLAUDE.md` with your project-specific instructions

3. Update `docs/ROADMAP.md` with your project goals

4. Start creating tickets in `tickets/` directory

## Claude Code Integration

ccsetup seamlessly integrates with Claude Code:

- **Automatic Detection** - Checks if Claude Code is initialized in your project
- **.claude Directory** - Creates Claude Code directory structure automatically
- **Agent Installation** - Copies agents to `.claude/agents/` for native Claude Code support
- **Smart Initialization** - Offers to create `.claude` directory if Claude Code isn't detected

When running in the current directory (`npx ccsetup .`), it will check for Claude Code and provide instructions if not found. For new projects, ccsetup will remind you to initialize Claude Code after setup.

## Using Agents

The boilerplate includes 50+ specialized agents covering all aspects of development:

### Core Development Agents

- **planner.md** - Strategic planning and task breakdown
- **coder.md** - Implementation and development
- **checker.md** - Testing and quality assurance
- **researcher.md** - Research and information gathering

### Language Specialists

- **python-pro.md**, **golang-pro.md**, **rust-pro.md**, **javascript-pro.md**, **c-pro.md**, **cpp-pro.md**, **sql-pro.md**

### Infrastructure & Operations

- **devops-troubleshooter.md**, **cloud-architect.md**, **terraform-specialist.md**, **database-admin.md**, **network-engineer.md**

### Quality & Security

- **code-reviewer.md**, **security-auditor.md**, **test-automator.md**, **performance-engineer.md**

### And Many More!

Over 50 specialized agents for frontend, backend, blockchain, ML/AI, business analysis, and more!

📖 **[View all agents with detailed descriptions →](https://github.com/MrMarciaOng/ccsetup/blob/main/template/agents/README.md)**

### Interactive Agent Selection

During setup, ccsetup will prompt you to either:

1. **Browse Mode** - Get all 50+ agents to explore later
2. **Select Specific Agents** - Choose from curated list

```bash
🤖 How would you like to set up agents for your Claude Code project?

Use arrow keys to navigate, Enter to select

> Browse Mode - Copy all 50+ agents to /agents folder (explore later)
  Select Agents - Choose specific agents to include now
  Skip - Don't include any agents

# If you choose "Select Agents":
🤖 Select agents to include in your Claude Code project

Use arrow keys to navigate, space to select/deselect, 'a' to toggle all

Choose your agents:
◯ backend - Backend development specialist for API design and server optimization
◯ blockchain - Web3 and smart contract development expert
◯ checker - Quality assurance and code review specialist
◯ coder - Expert software developer for implementation
◯ frontend - Frontend development specialist for UI/UX
◯ planner - Strategic planning specialist for complex problems
◯ researcher - Research specialist for documentation and code analysis
◯ shadcn - shadcn/ui component library expert
```

You can also use flags to control agent selection:

- `--all-agents` - Include all available agents
- `--no-agents` - Skip agent selection entirely
- `--agents` - Preview available agents without creating a project

Example:

```bash
# Include all agents without prompting
npx ccsetup my-project --all-agents

# Create project without any agents
npx ccsetup my-project --no-agents

# Preview available agents only
npx ccsetup --agents
```

### Browse Mode - New Feature! 📚

With 50+ specialized agents available, browse mode lets you explore all agents at your leisure:

```bash
# Copy all agents to /agents folder for browsing
npx ccsetup my-project --browse-agents
```

In browse mode:

- All 50+ agents are copied to your project's `/agents` folder
- You can read through each agent to understand their capabilities
- Manually copy the ones you want to `~/.claude/agents` when ready
- No overwhelming selection process during setup!

Example workflow:

```bash
# 1. Create project with browse mode
npx ccsetup my-project --browse-agents

# 2. Explore agents
cd my-project/agents
ls  # See all available agents

# 3. Read agent descriptions
cat code-reviewer.md

# 4. Copy desired agents to activate them
cp code-reviewer.md ~/.claude/agents/
cp python-pro.md ~/.claude/agents/
```

This approach is perfect when you:

- Want to explore all available agents
- Prefer to choose agents based on your project needs as they arise
- Don't want to be overwhelmed with 50+ choices during setup

### Conflict Resolution

When existing files are detected, ccsetup offers smart conflict resolution:

```bash
⚠️  File conflicts detected. You will be asked how to handle each category.

📄 CLAUDE.md conflicts:
  - CLAUDE.md

Conflict resolution options:
  1) skip      (s) - Keep your existing files
  2) rename    (r) - Save template files with -ccsetup suffix
  3) overwrite (o) - Replace with template versions

Your choice for CLAUDE.md [s/r/o]:
```

Categories are handled separately:

- **CLAUDE.md** - Project instructions (warns before overwriting)
- **Agents** - AI agent files
- **Documentation** - docs/ folder files
- **Plans** - plans/ folder files
- **Tickets** - tickets/ folder files

## Agent Orchestration Showcase

The template includes powerful agent orchestration workflows that guide Claude through complex tasks systematically. Here are real-world examples:

### 🚀 Feature Development Example

**Scenario**: Building a user authentication system

```bash
# In Claude Code, you would say:
"I need to add user authentication to my app. Use the feature development workflow to guide me through this."

# Claude will automatically orchestrate:
1. Researcher Agent → Analyzes existing codebase, identifies auth patterns
2. Planner Agent → Creates detailed implementation plan with JWT, sessions, etc.
3. Coder Agent → Implements auth endpoints, middleware, and UI components
4. Checker Agent → Tests security, validates implementation, checks edge cases
```

### 🐛 Bug Fix Example

**Scenario**: Users report login failures after 5 minutes

```bash
# You tell Claude:
"Users are getting logged out after 5 minutes. Use the bug fix workflow to investigate and fix this."

# Claude orchestrates:
1. Researcher Agent → Investigates session handling, token expiry, logs
2. Coder Agent → Fixes token refresh logic, updates session timeout
3. Checker Agent → Verifies fix, tests edge cases, ensures no regressions
```

### 🏗️ API Development Example

**Scenario**: Building a REST API for a blog platform

```bash
# You request:
"Help me build a complete REST API for blog posts with CRUD operations. Follow the API development workflow."

# Claude coordinates:
1. Planner Agent → Designs RESTful endpoints, database schema, auth strategy
2. Backend Agent → Implements controllers, models, middleware, validation
3. Frontend Agent → Creates API client, integration examples (if needed)
4. Checker Agent → Tests all endpoints, validates OpenAPI spec, security audit
```

### 🎨 UI Component Example

**Scenario**: Creating a responsive dashboard with shadcn/ui

```bash
# You ask:
"Create a dashboard with charts and stats cards using shadcn. Use the UI component workflow."

# Claude executes:
1. Frontend Agent → Designs component structure, responsive layout
2. Shadcn Agent → Implements with shadcn/ui components, themes, animations
3. Checker Agent → Tests responsiveness, accessibility, performance
```

### 🔍 Quality Assurance Example

**Scenario**: Comprehensive review before deployment

```bash
# You request:
"Run full QA on the authentication feature we just built."

# Claude performs:
1. Researcher Agent → Analyzes all changes, identifies test requirements
2. Checker Agent → Runs security scans, performance tests, accessibility checks
3. Coder Agent → Fixes any issues found
4. Checker Agent → Final validation, generates QA report
```

### 💡 How to Use Agent Orchestration

1. **Read the orchestration guide**:

   ```
   "Read docs/agent-orchestration.md to understand available workflows"
   ```

2. **Choose your workflow**:

   - Feature Development: Complex new features
   - Bug Fix: Investigating and fixing issues
   - Refactoring: Improving code quality
   - API Development: Building APIs
   - UI Components: Frontend development
   - Blockchain: Web3 features
   - QA: Quality assurance

3. **Let Claude guide you**:

   ```
   "I need to [your task]. Which workflow should we use?"
   ```

4. **Follow the flow**:
   - Claude will automatically use agents in the correct sequence
   - Each agent builds on the previous one's work
   - You get systematic, thorough results

The orchestration ensures nothing is missed and follows best practices automatically!

## Getting Started with Claude Code

After setting up your project with `ccsetup`:

1. **Open Claude Code** in your project directory:

   ```bash
   cd my-awesome-project
   claude
   ```

2. **Let Claude understand your project** by asking:

   - "Read the CLAUDE.md file to understand this project"
   - "Check the roadmap in docs/ROADMAP.md"
   - "What agents are available in the agents directory?"
   - "Read the README files in docs, tickets, and plans folders to understand the workflow"

3. **Start working** with Claude:

   - Use the planner agent: "Use the planner agent to help me design a user authentication system"
   - Create tickets: "Create a ticket for implementing user login"
   - Implement features: "Use the coder agent to implement the login functionality"
   - Review code: "Use the checker agent to review the code we just wrote"

4. **Important setup steps**:

   - **Update ROADMAP.md**: Define your project's goals, features, and development phases
   - **Read folder documentation**: Each folder (docs/, tickets/, plans/) has a README explaining its purpose and format
   - **Customize CLAUDE.md**: Add project-specific instructions, commands, and context

5. **Workflow tips**:
   - Always start with planning for complex features
   - Create tickets to track progress
   - Use the appropriate agent for each task
   - Keep CLAUDE.md updated with project-specific instructions
   - Follow the workflow defined in docs/ROADMAP.md

## Features

### Core Features

- ✅ Pre-configured project structure for Claude Code
- 🤖 50+ specialized agents from the [wshobson/agents](https://github.com/wshobson/agents) collection - [view all →](https://github.com/MrMarciaOng/ccsetup/blob/main/template/agents/README.md)
- 🎫 Built-in ticket and planning system
- 📋 Ready-to-use boilerplate with best practices
- 📁 Automatic .claude directory integration

### CLI Features

- 🎯 Interactive agent selection with descriptions
- 🔄 Smart conflict resolution (skip/rename/overwrite)
- 👀 Dry-run mode to preview changes
- ⚡ Force mode for CI/CD pipelines
- 🎨 Standalone agent preview mode
- 🛡️ Security validations for file operations

### Agent Orchestration

The template includes `docs/agent-orchestration.md` which defines workflows for:

- **Feature Development** - Researcher → Planner → Coder → Checker
- **Bug Fixes** - Researcher → Coder → Checker
- **Refactoring** - Researcher → Planner → Coder → Checker
- **API Development** - Planner → Backend → Frontend → Checker
- **UI Components** - Frontend → Shadcn → Checker
- **Blockchain** - Planner → Blockchain → Checker
- **Quality Assurance** - Researcher → Checker → Coder → Checker

## Credits

Born from our discussions in TechOverflow with [vichannnnn](https://github.com/vichannnnn) and [nasdin](https://github.com/nasdin)

The 44 specialized agents collection is from [wshobson/agents](https://github.com/wshobson/agents) - an amazing collection of Claude Code subagents for every development need!

## License

MIT