claude-symphony

Structured AI development. 8 stages. Quality gates. Checkpoints.

What is claude-symphony?

Describe your app. claude-symphony runs an 8-stage AI pipeline — from brainstorming to deployment — producing a tested, deployable codebase with quality gates at every step.

npx claude-symphony init
# > "What do you want to build?"
# > "A real-time team collaboration tool with chat, file sharing, and video calls"
# > Pipeline starts automatically → 8 stages → tested, deployable codebase

How It Works

claude-symphony orchestrates an 8-stage pipeline where AI agents execute each stage:

| # | Stage | What happens | |---|-------|-------------| | 01 | Brainstorm | Generate features, user stories, requirements | | 02 | Research | Evaluate tech options, analyze feasibility | | 03 | Planning | Design architecture, data models, API, conventions | | 04 | UI/UX | Create wireframes, component tree, design tokens | | 05 | Tasks | Decompose into implementable tasks with priorities | | 06 | Implementation | TDD workflow + integrated refactoring + E2E sheet | | 07 | QA | Security audit, accessibility, full test execution | | 08 | Deployment | CI/CD pipeline, hosting, production deploy |

Multi-agent debate: Stages can run multiple Claude agents with different perspectives (e.g., Visionary vs Skeptic). This is a prompt-based protocol — agents are instructed to critique and refine each other's outputs within the conversation.

Each stage:

• Includes role-specific instructions (creative for brainstorming, precise for implementation)
• Validates outputs before progressing (quality gates)
• Generates a HANDOFF document passing context to the next stage
• Can be retried automatically if validation fails

Quality Gates

Every stage validates its outputs. Stage 06 (Implementation) guides a Write-Test-Verify workflow for each feature:

For EACH feature:
  1. Write tests first (unit + integration)
  2. Write implementation code
  3. Run tests → must pass before moving to next feature
  4. If tests fail → fix implementation, re-run

Quality gate (4 levels, must pass to complete):

| Level | Check | Required | |-------|-------|----------| | 1 | npm run build | Yes | | 2 | npm test — all tests pass | Yes | | 3 | npm run test:e2e — E2E tests | If configured | | 4 | Lint + typecheck | Recommended |

If validation fails, the stage retries with failure details injected into the prompt.

Quick Start

# Install and create a project
npx claude-symphony init

# Enter your Claude Code session
cd my-project
claude

# Start the auto-pilot pipeline
/auto-pilot

That's it. The pipeline runs through all 8 stages automatically.

See Getting Started for more details. You can also drop reference files into references/<stage>/ to give the AI additional context.

Commands

Inside Claude Code, you have 10 commands:

| Command | Description | |---------|-------------| | /auto-pilot | Start automatic pipeline execution | | /pause | Pause the pipeline after current stage | | /resume-stage | Resume a paused pipeline | | /skip | Skip the current stage | | /progress | View current pipeline progress | | /checkpoint | Create a save point | | /restore | Restore from a save point | | /stages | List all stages with status | | /run-stage [id] | Run a specific stage manually | | /debate | Run multi-agent debate for current stage |

CLI Commands

claude-symphony init              # Create new project
claude-symphony init --auto       # Create and auto-start
claude-symphony import ./my-app   # Import existing project
claude-symphony import ./my-app --dry-run  # Analyze without modifying
claude-symphony status            # Show pipeline status
claude-symphony stages            # List all stages
claude-symphony checkpoint        # Create checkpoint
claude-symphony restore [id]      # Restore from checkpoint

Import Existing Projects

Already have a project? Import it and run only the remaining stages:

claude-symphony import ./existing-app
# Analyzes your project → detects tests, CI/CD, components, etc.
# Skips completed stages → runs only what's missing

This is useful for taking an existing prototype and running it through QA, Testing, and Deployment.

Without vs With claude-symphony

| | Without | With claude-symphony | |---|---|---| | Output | Code (quality varies) | Tested codebase with CI/CD config | | Process | Manual or single generation | 10-stage pipeline with checkpoints | | Quality gates | None | 4-level verification (build, test, E2E, lint) | | Tests | Manual setup | Generated per feature | | Context management | Token window only | HANDOFF system between stages |

Documentation

• Getting Started — 5-minute quickstart
• How It Works — Pipeline architecture explained
• CHANGELOG — Release history

Prerequisites

• Claude Code installed and authenticated
• Node.js >= 20.12.0

Contributing

git clone https://github.com/znehraks/claude-symphony.git
cd claude-symphony
pnpm install
pnpm run build
pnpm run test

See CLAUDE.md for development instructions.

License

MIT