🎭 Orchestro

Your AI Development Conductor - From Product Vision to Production Code

Transform product ideas into reality with an intelligent orchestration system that bridges Product Managers, Developers, and AI. Orchestro conducts the entire development symphony: task decomposition, dependency tracking, pattern learning, and real-time progress visualization.

🎯 Why Orchestro?

The Problem:

Product Managers lose track of development progress
Developers struggle with context switching and dependencies
Knowledge is lost between Claude Code sessions
No single source of truth for what's being built

The Solution: Orchestro orchestrates the entire development lifecycle:

👔 For PMs: Visual Kanban board, user story decomposition, progress tracking
👨‍💻 For Developers: AI-powered task analysis, dependency graphs, pattern learning
🤖 For Claude Code: Structured workflows, enriched context, knowledge retention
📊 For Everyone: Real-time dashboard, transparent progress, complete audit trail

Think Trello × Jira × AI - but designed specifically for AI-assisted development.

✨ Key Features

👔 For Product Managers & Owners

User Story Decomposition - Write a story, AI creates technical tasks automatically
Visual Progress Board - Kanban view with real-time updates
No Technical Knowledge Required - Manage development without coding
Complete Transparency - See exactly what's being built, when, and why
Risk Awareness - Auto-flagged risks with plain English explanations

👨‍💻 For Developers

Intelligent Task Analysis - AI analyzes codebase and suggests implementation
Dependency Tracking - Visual graphs show what depends on what
Pattern Learning - System learns from successes and failures
Conflict Prevention - Detects when tasks touch the same files
Context Retention - Never lose context between sessions

🤖 For Claude Code

60 MCP Tools - Complete toolkit for orchestrated development
Structured Workflows - prepare → analyze → implement → learn
Enriched Prompts - Context-aware implementation guidance
Knowledge Base - Templates, patterns, learnings persist forever

📊 For Everyone

Real-Time Dashboard - Live updates via Socket.io
Complete History - Timeline of all decisions and changes
Rollback Capability - Undo mistakes safely
Export Everything - Markdown reports for stakeholders

🎼 The Development Symphony

How Orchestro Conducts Your Development

┌─────────────────────────────────────────────────────┐
│  PRODUCT MANAGER                                     │
│  "User should login with email/password"           │
└─────────────────────────────────────────────────────┘
                        ↓
            ┌──────────────────────┐
            │  ORCHESTRO AI        │
            │  Decomposes Story    │
            └──────────────────────┘
                        ↓
    ┌──────────────────────────────────────────┐
    │  7 Technical Tasks Created               │
    │  • Database schema                       │
    │  • Authentication service                │
    │  • API endpoints                         │
    │  • Frontend components                   │
    │  • State management                      │
    │  (with dependencies automatically)       │
    └──────────────────────────────────────────┘
                        ↓
            ┌──────────────────────┐
            │  DEVELOPER/CLAUDE    │
            │  Implements Tasks    │
            └──────────────────────┘
                        ↓
    ┌──────────────────────────────────────────┐
    │  PM SEES PROGRESS                        │
    │  • Kanban updates in real-time          │
    │  • Risks flagged automatically          │
    │  • Dependencies visualized              │
    └──────────────────────────────────────────┘

🚀 Quick Start

Option 1: From MCP Registry ⭐ (Recommended)

Orchestro is now in the Official MCP Registry!

# Install via NPX (no global install needed)
npx @khaoss85/orchestro@latest

Or add to Claude Code config:

{
  "mcpServers": {
    "orchestro": {
      "command": "npx",
      "args": ["-y", "@khaoss85/orchestro@latest"],
      "env": {
        "DATABASE_URL": "your-supabase-connection-string"
      }
    }
  }
}

Option 2: One-Command Install ⚡

npx @orchestro/init

That's it! The installer will:

✅ Download and setup Orchestro
✅ Apply database migrations to Supabase
✅ Configure Claude Code automatically
✅ Setup Supabase connection
✅ Start the dashboard
✅ Verify everything works

Interactive prompts:

🎭 Orchestro Setup Wizard

? Supabase connection string: ████████
? Project name: My Project
? Install location: ~/orchestro

⚙️  Setting up...
✓ Orchestro installed
✓ Claude Code configured
✓ Database ready

🎉 Done! Restart Claude Code and ask:
   "Show me orchestro tools"

Option 2: Manual Install (5 Minutes)

1. Prerequisites

# Node.js 18+
node --version

# Supabase account (free tier works great)
# Sign up at https://supabase.com

2. Database Setup on Supabase

Create your Supabase project:

Go to https://supabase.com and create a new project
Wait for the database to be provisioned (~2 minutes)
Go to Settings → Database and copy the Connection String (Transaction mode)

Apply database schema:

# Clone this repo first
git clone https://github.com/khaoss85/mcp-orchestro.git
cd mcp-orchestro

# Install dependencies
npm install

# Set your Supabase connection string
export DATABASE_URL="your-supabase-connection-string"

# Apply all migrations to create the schema
npm run migrate

Verify database setup:

# The migrate script will show you all tables created:
# You should see:
# ✅ Running migration: code_entities
# ✅ Running migration: add_tasks_metadata
# ✅ Running migration: fix_status_transition_trigger
# ✅ Running migration: event_queue
# ✅ Running migration: auto_update_user_story_status
# ✅ Running migration: add_task_metadata_fields
# ✅ Running migration: add_pattern_frequency_tracking

# Or verify manually via Supabase dashboard:
# Go to Database → Tables and check all tables are created

Get your credentials:

# From Supabase Dashboard:

# 1. DATABASE_URL (for migrations & MCP server)
#    Settings → Database → Connection String → Transaction mode
#    Example: postgresql://postgres:[password]@db.[project].supabase.co:5432/postgres

# 2. SUPABASE_URL (for API calls)
#    Settings → API → Project URL
#    Example: https://[project].supabase.co

# 3. SUPABASE_SERVICE_KEY (for admin operations - keep secret!)
#    Settings → API → service_role key
#    Example: eyJhbG...

3. Quick Setup Script

# Run interactive setup
npm run setup

# Or manual configuration:
cat > .env << EOF
DATABASE_URL=your-supabase-connection-string
SUPABASE_URL=your-supabase-url
SUPABASE_SERVICE_KEY=your-service-key
EOF

4. Configure Claude Code

# Auto-configure (recommended)
npm run configure-claude

# Or manually edit:
open ~/Library/Application\ Support/Claude/claude_desktop_config.json

# Add:
{
  "mcpServers": {
    "orchestro": {
      "command": "node",
      "args": ["/absolute/path/to/orchestro/dist/server.js"],
      "env": {
        "DATABASE_URL": "your-connection-string"
      }
    }
  }
}

5. Start Dashboard

npm run dashboard
# 🌐 Opens http://localhost:3000

6. Verify Installation

# Restart Claude Code, then ask:
"Show me all orchestro tools"

# You should see 60 tools! 🎭

Option 3: Add to Existing Project

Already have a Claude Code project? Add Orchestro:

# In your project directory
npx @orchestro/add

# Or via Claude Code config:
claude mcp add orchestro

See Integration Guide for existing project setup.

Option 4: Claude Code Plugin 🎁 (Easiest!)

New! Install Orchestro as a Claude Code plugin with one command:

# In Claude Code terminal
/plugin marketplace add khaoss85/mcp-orchestro

# Install the Orchestro Suite
/plugin install orchestro-suite@orchestro-marketplace

# Restart Claude Code when prompted

What you get:

✅ Orchestro MCP Server - 60 tools via npx @khaoss85/orchestro@latest (no global install needed)
✅ 5 Guardian Agents - database, API, architecture, test-maintainer, production-ready
✅ Auto-configured - MCP server and agents ready to use
✅ Complete Documentation - Setup guide included

Prerequisites:

Supabase account (see Option 2 for setup)

Environment variables set:

export SUPABASE_URL="https://your-project.supabase.co"
export SUPABASE_SERVICE_KEY="your-service-key"
export ANTHROPIC_API_KEY="your-key"

Verify installation:

# Check agents
/agents
# Should show: database-guardian, api-guardian, architecture-guardian,
#              test-maintainer, production-ready-code-reviewer

# Test MCP tools
mcp__orchestro__get_project_info
mcp__orchestro__list_tasks

Plugin includes:

MCP server configuration (.mcp.json)
5 specialized guardian agents
Complete README with usage examples
Troubleshooting guide

See plugins/orchestro-suite/README.md for detailed plugin documentation.

🎭 Use Cases

📱 For Product Managers

Scenario: New feature request from stakeholder

1. Write user story in dashboard:
   "User should be able to export report as PDF"

2. Click "Decompose with AI"
   → Orchestro creates 5 technical tasks with dependencies

3. Monitor Kanban board:
   → See real-time progress as Claude implements
   → Risks flagged automatically (e.g., "PDF library size impact")
   → Hover over task for technical details

4. Review & Accept:
   → See code diffs in plain English
   → Rollback if needed
   → Export timeline for stakeholder report

💻 For Developers

Scenario: Implementing complex feature

1. Pick task from Kanban board

2. Ask Claude:
   "Prepare task [task-id] for execution"
   → Orchestro analyzes codebase
   → Shows: files to modify, dependencies, risks

3. Get enriched context:
   → Past similar implementations
   → Relevant patterns (with success rates!)
   → Risk mitigation strategies

4. Implement with confidence:
   → Conflict detection warns if other tasks touch same files
   → Pattern learning suggests best approaches
   → Complete history for rollback safety

🤝 For Teams

Scenario: Cross-functional collaboration

PM writes story → AI decomposes → Dev implements → All see progress

• PM: Non-technical Kanban view
• Dev: Technical dependency graph
• Claude: Enriched implementation context
• Everyone: Real-time updates, complete transparency

🛠️ All 60 MCP Tools ✅ Production Tested

📋 Project Management (3 tools)

get_project_info - Project metadata and status
get_project_configuration - Complete project configuration
initialize_project_configuration - Setup default tools and guardians

📝 Task Management (7 tools)

create_task - Create with assignee, priority, tags, category
list_tasks - Filter by st

…

Orchestro

Installation

Configuration

How to use

README