claude-symphony

# claude-symphony

<p align="center">
  <img src="https://raw.githubusercontent.com/znehraks/claude-symphony/main/assets/claude_symphony.webp" alt="Claude Symphony Logo" width="400">
</p>

Multi-AI Orchestration Framework for Software Development

[![npm version](https://badge.fury.io/js/claude-symphony.svg)](https://www.npmjs.com/package/claude-symphony)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## Overview

claude-symphony is a 10-stage software development workflow pipeline that orchestrates multiple AI models (Claude, Gemini, Codex) like an orchestra, creating harmonious software through a complete development cycle.

### Key Features

- **10-Stage Pipeline**: Complete development cycle from brainstorming to deployment
- **Multi-AI Orchestration**: Intelligent collaboration between Gemini, Claude, and Codex with parallel, sequential, and debate modes
- **Smart HANDOFF System**: Automatic context extraction, semantic compression, and AI memory integration
- **Auto-Checkpoint & Smart Rollback**: Task-based triggers, file change detection, partial rollback support
- **Pipeline Forking**: Branch exploration for architecture alternatives with merge capabilities
- **Stage Personas**: Optimized AI behavior profiles per stage (Creative Explorer, Precise Builder, etc.)
- **Output Validation**: Automated quality checks with lint, typecheck, and coverage verification
- **Epic Cycles**: User-defined stage range repetition with context preservation between cycles
- **Implementation Order**: Frontend-first or backend-first development approach with reference links
- **Requirements Refinement**: 4-level breakdown system (Epic → Feature → Task → Subtask) with INVEST validation
- **Moodboard UX**: Interactive design reference collection with Claude Vision/Figma MCP analysis

### Pipeline Stages

```
┌─────────────────────────────────────────────────────────────────────┐
│                   claude-symphony Pipeline                          │
├─────────────────────────────────────────────────────────────────────┤
│  01 Brainstorm  →  02 Research  →  03 Planning  →  04 UI/UX        │
│     Gemini          Claude          Gemini          Gemini          │
├─────────────────────────────────────────────────────────────────────┤
│  05 Tasks  →  06 Implement  →  07 Refactor  →  08 QA  →  09 Test   │
│    Claude       Claude           Codex         Claude     Codex     │
├─────────────────────────────────────────────────────────────────────┤
│                          10 Deploy                                  │
│                            Claude                                   │
└─────────────────────────────────────────────────────────────────────┘
```

| Stage | Name | AI Model | Mode |
|-------|------|----------|------|
| 01 | Brainstorming | Gemini + Claude | YOLO (Container) |
| 02 | Research | Claude | Plan Mode |
| 03 | Planning | Gemini | Plan Mode |
| 04 | UI/UX Planning | Gemini | Plan Mode |
| 05 | Task Management | Claude | Plan Mode |
| 06 | Implementation | Claude | Plan + Sandbox |
| 07 | Refactoring | Codex | Deep Dive |
| 08 | QA | Claude | Plan + Sandbox |
| 09 | Testing & E2E | Codex | Sandbox + Playwright |
| 10 | CI/CD & Deployment | Claude | Headless |

## Installation

### Quick Start with npx

```bash
# Create a new project
npx claude-symphony my-project
cd my-project

# Edit project brief
# stages/01-brainstorm/inputs/project_brief.md

# Start development with Claude Code
/run-stage 01-brainstorm
```

### Using Claude Code

In Claude Code, all slash commands are available:

```
/status              # Check pipeline status
/run-stage 01-brainstorm
/handoff             # Create handoff document
/next                # Move to next stage
```

## Quick Start

### Step-by-Step

```bash
# 1. Create project
npx claude-symphony my-saas-app
cd my-saas-app

# 2. Edit your project brief
# Open: stages/01-brainstorm/inputs/project_brief.md

# 3. Start brainstorming stage
# In Claude Code:
/brainstorm

# 4. Check status anytime
/status

# 5. Create handoff and move to next stage
/handoff
/next
```

### Project Brief Template

Edit `stages/01-brainstorm/inputs/project_brief.md`:

```markdown
## Project Name
my-saas-app

## One-line Description
[Describe your project in one line]

## Problem Definition
[What problem are you trying to solve?]

## Target Users
[Who are the main users?]

## Core Features (Draft)
1. [Feature 1]
2. [Feature 2]
3. [Feature 3]
```

## Commands

### Core Commands

| Command | Description |
|---------|-------------|
| `/status` | Check pipeline status |
| `/stages` | List all stages |
| `/run-stage <id>` | Run specific stage |
| `/next` | Move to next stage |
| `/handoff` | Create handoff document |
| `/checkpoint` | Create checkpoint |
| `/restore` | Restore checkpoint |
| `/context` | Check context usage |
| `/init-project` | Initialize project |

### AI Commands

| Command | Description |
|---------|-------------|
| `/gemi

... (truncated)