🎭 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

Code

┌─────────────────────────────────────────────────────┐
│  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!

bash

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

Or add to Claude Code config:

config.json

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

Option 2: One-Command Install ⚡

Terminal

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:

Code

🎭 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

bash

# 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:

server.ts

# 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:

bash

# 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:

bash

# 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

bash

# 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

bash

# 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

Terminal

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

6. Verify Installation

Code

# 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:

bash

# 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:

bash

# 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:

server.ts

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

Verify installation:

bash

# 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

server.ts

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

Code

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

Code

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 status/category/tags
update_task - Modify any field with validation
delete_task - Safe deletion with dependency checks
get_task_context - Full context with dependencies (deprecated, use prepare_task_for_execution)
get_execution_order - Topological sort by dependencies
safe_delete_tasks_by_status - Bulk delete with safety checks

⚙️ Task Execution & Analysis (3 tools)

prepare_task_for_execution - Generate codebase analysis prompt
save_task_analysis - Store analysis results
get_execution_prompt - Enriched implementation context

📖 User Stories (4 tools)

decompose_story - AI-powered story → tasks decomposition with automatic analysis (autoAnalyze=true default)
get_user_stories - List all user stories
get_tasks_by_user_story - Get all child tasks
get_user_story_health - Monitor story completion status

🔗 Dependencies & Conflicts (4 tools)

save_dependencies - Record task resource dependencies
get_task_dependency_graph - Visualize dependency graph
get_resource_usage - Find tasks using a resource
get_task_conflicts - Detect conflicting resource usage

📚 Knowledge & Templates (5 tools)

list_templates - Available prompt/code templates
list_patterns - Coding patterns library
list_learnings - Past experience records
render_template - Generate from template with variables
get_relevant_knowledge - Context-aware suggestions

🧠 Feedback & Learning (7 tools)

add_feedback - Record success/failure/improvement
get_similar_learnings - Find related experiences
get_top_patterns - Most frequently used patterns
get_trending_patterns - Recently popular patterns
get_pattern_stats - Detailed pattern metrics
detect_failure_patterns - Auto-detect risky approaches
check_pattern_risk - Risk assessment before using pattern

⚙️ Project Configuration (14 tools)

Tech Stack:

add_tech_stack - Add framework/library
update_tech_stack - Update version/config
remove_tech_stack - Remove technology

Sub-Agents (Guardians):

add_sub_agent - Register guardian agent
update_sub_agent - Modify agent config
sync_claude_code_agents - Sync from .claude/agents/
read_claude_code_agents - Read agent files
suggest_agents_for_task - AI-powered agent recommendations
update_agent_prompt_templates - Update prompt templates

MCP Tools Management:

add_mcp_tool - Register MCP tool
update_mcp_tool - Update tool config
suggest_tools_for_task - AI-powered tool recommendations

Guidelines & Patterns:

add_guideline - Add coding guideline
add_code_pattern - Add reusable pattern

📊 Task History & Events (13 tools)

get_task_history - Complete event timeline
get_status_history - Status transition log
get_decisions - Decision records
get_guardian_interventions - Guardian activity log
get_code_changes - Code modification history
record_decision - Log a decision with rationale
record_code_change - Log code modifications
record_guardian_intervention - Log guardian action
record_status_transition - Log status change
get_iteration_count - Count task iterations
get_task_snapshot - Task state at timestamp
rollback_task - Restore previous state
get_task_stats - Aggregate statistics

📊 Dashboard Features

Kanban Board - For Everyone

PM View:

Drag & drop user stories
See progress at a glance
Risk indicators in plain English
Export reports for stakeholders

Developer View:

Technical task details
Dependency indicators
Code complexity badges
Direct links to files

Task Detail Page - Deep Insights

Tab: Overview (PM-friendly)

User story description
Technical requirements
Assignee & priority
Dependencies explained

Tab: History (Audit trail)

Complete event timeline
Decision records with rationale
Code changes (with diffs)
Rollback capability

Tab: Dependencies (Developer focus)

Visual dependency graph
Resource impact analysis
Risk assessment
Conflict detection

🏗️ Architecture

Code

┌─────────────────────────────────────────┐
│         PRODUCT MANAGER                 │
│  • Writes user stories                  │
│  • Monitors Kanban board                │
│  • Reviews progress                     │
└─────────────────────────────────────────┘
              ↓ (Dashboard)
┌─────────────────────────────────────────┐
│      ORCHESTRO DASHBOARD (Next.js)      │
│  • Kanban board with real-time updates │
│  • Dependency graphs                    │
│  • Progress visualization               │
└─────────────────────────────────────────┘
              ↓ ↑ (Socket.io)
┌─────────────────────────────────────────┐
│         SUPABASE (Data Layer)           │
│  • Tasks, dependencies, resources       │
│  • Event queue & real-time sync         │
│  • Knowledge base & pattern tracking    │
└─────────────────────────────────────────┘
              ↓ ↑ (PostgreSQL)
┌─────────────────────────────────────────┐
│    ORCHESTRO MCP SERVER (Conductor)     │
│  • 27 tools for task orchestration      │
│  • Pattern learning & risk detection    │
│  • AI story decomposition               │
└─────────────────────────────────────────┘
              ↓ ↑ (MCP Protocol)
┌─────────────────────────────────────────┐
│      CLAUDE CODE (Developer + AI)       │
│  • Analyzes codebase                    │
│  • Implements features                  │
│  • Records decisions                    │
└─────────────────────────────────────────┘

💡 Real-World Example

Story: E-commerce Checkout Flow

PM writes in dashboard:

Code

"Customer should complete purchase with
credit card payment and email confirmation"

Orchestro decomposes (AI-powered):

✅ Design checkout database schema (2h) - No dependencies
✅ Implement payment service integration (4h) - Depends on: #1
✅ Create checkout API endpoints (3h) - Depends on: #2
✅ Build checkout UI components (4h) - Depends on: #3
✅ Add email notification service (2h) - Depends on: #3
✅ Implement order confirmation flow (3h) - Depends on: #4, #5

Total: 18 hours, 6 tasks, dependencies mapped automatically

Developer flow (with autoAnalyze=true):

typescript

// 1. Decompose story (auto-analyzes tasks)
decompose_story("Customer checkout with payment")
// → Creates 6 tasks
// → Auto-generates analysis prompts for tasks without dependencies
// → Returns analysisPrompts[] ready to use

// 2. Claude reviews analysis prompts
// Prompts include: files to check, patterns to find, risks to identify

// 3. Claude analyzes codebase using the prompts
// Finds: existing payment tables, similar schemas
// Risks: None (new table)

// 4. Save analysis results
save_task_analysis({
  taskId: "task-1-id",
  filesToCreate: ["migrations/002_checkout.sql"],
  dependencies: [{type: "file", name: "001_orders.sql", action: "uses"}],
  risks: []
})

// 5. Get enriched context
get_execution_prompt("task-1-id")
// → Returns: related code, patterns, guidelines

// 6. Implement!
// Claude writes migration, runs tests

// 7. Record learning
add_feedback({
  pattern: "e-commerce checkout schema",
  type: "success",
  feedback: "Stripe integration smooth"
})

Key improvement: Step 1 now auto-prepares analysis, reducing manual workflow steps!

PM sees:

✅ Task 1 → Done (real-time update)
🟡 Task 2 → In Progress (Claude working)
⏳ Tasks 3-6 → Blocked (waiting for dependencies)
📊 Progress: 17% (1/6 tasks done)

🧪 Pattern Learning in Action

Automatic Failure Detection (Saves Time!)

typescript

// Scenario: Regex parsing keeps failing

// Attempt 1
add_feedback({
  pattern: "regex pattern matching",
  type: "failure",
  feedback: "Unescaped metacharacters broke parser"
})

// Attempt 2
add_feedback({
  pattern: "regex pattern matching",
  type: "failure",
  feedback: "Special chars not sanitized"
})

// Attempt 3
add_feedback({
  pattern: "regex pattern matching",
  type: "success",
  feedback: "Finally worked after sanitizing"
})

// Now Orchestro knows...
detect_failure_patterns()
// 🚨 Returns:
// {
//   pattern: "regex pattern matching",
//   failure_rate: 66.67%,
//   risk_level: "medium",
//   recommendation: "⚡ Review sanitization first!"
// }

// Next time, before using regex:
check_pattern_risk("regex pattern matching")
// ⚠️ Warning: "67% failure rate (2/3).
//    Common issue: Unescaped metacharacters.
//    Mitigation: Use sanitization helper first."

Result: Future regex tasks complete faster with fewer errors!

🎨 Tech Stack

Backend (MCP Server)

TypeScript 5.0
@modelcontextprotocol/sdk
Supabase (PostgreSQL)
Socket.io for real-time

Frontend (Dashboard)

Next.js 14 (App Router)
React 18 + TypeScript
TailwindCSS + shadcn/ui
React Flow (graphs)
react-markdown (rendering)

Database (Supabase/PostgreSQL)

Core: projects, tasks, task_dependencies
Knowledge: learnings, patterns, templates, pattern_frequency
Resources: resource_nodes, resource_edges, code_entities, code_dependencies
System: event_queue, file_history, codebase_analysis
Tech: JSONB metadata, GIN indexes, Row-level security (RLS)

AI Integration

Claude Code (MCP protocol)
AI task decomposition
Pattern recognition
Risk assessment

📈 Performance & Scale

⚡ Query Speed: <10ms with GIN indexes
🔄 Real-time: 1s polling interval
🗄️ Storage: Auto-cleanup processed events (24h)
📊 Scalability: Tested with 100+ tasks
🚀 Analysis: Non-blocking (delegated to Claude)
👥 Users: Multi-PM, multi-developer ready

🔐 Security & Compliance

✅ Environment Variables - No hardcoded secrets
✅ Supabase RLS - Row-level security policies
✅ Complete Audit Trail - Every decision recorded
✅ Event Processing - Prevents duplicate actions
✅ Local First - All data in your Supabase instance
✅ GDPR Ready - Export & delete capabilities

📚 Documentation

Getting Started

QUICK_START.md - 5-minute setup guide
PM_GUIDE.md - For Product Managers (Coming Soon)
DEV_GUIDE.md - For Developers (Coming Soon)
EXAMPLES.md - Real-world usage examples

Deep Dive

WORKFLOW.md - Complete workflow explanation
ARCHITECTURE.md - Technical architecture
API.md - MCP Tools reference

🗺️ Roadmap

✅ Phase 1: Core Orchestration (DONE)

🚧 Phase 2: PM Empowerment (Current)

Non-technical PM dashboard view
Story templates for common features
Progress reporting & exports
Stakeholder notifications
Risk explanations in plain English

🔮 Phase 3: Team Intelligence

🚀 Phase 4: Advanced AI

🤝 Contributing

We welcome contributions from PMs, Developers, and AI enthusiasts!

For Product Managers:

📝 Share user story templates
💡 Suggest PM-friendly features
📊 Report UX issues

For Developers:

🔧 Submit bug fixes
✨ Add new MCP tools
📈 Improve pattern detection

How to contribute:

Fork the repo
Create feature branch (git checkout -b feature/amazing-feature)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open Pull Request

📝 Changelog

v2.1.0 (2025-10-10) - Current 🎉

✅ Published to MCP Registry - Now in Official MCP Registry
✅ NPM Package - Published as @khaoss85/orchestro on npm
✅ 60 MCP Tools - Expanded from 27 to 60 production-ready tools
✅ Automatic Task Analysis - decompose_story now auto-prepares analysis prompts (autoAnalyze=true default)
✅ Project Configuration System - Complete tech stack, agents, tools management
✅ Claude Code Agent Sync - Automatic sync with .claude/agents/ directory
✅ AI Agent/Tool Suggestions - Smart recommendations for tasks
✅ Task History & Events - Complete audit trail with 13 history tools
✅ User Story Health - Monitor completion and status alignment
✅ Bug Fix - Resolved SQL error in get_project_configuration
✅ Full Test Coverage - All 60 tools tested and verified (96.7% success)

v2.0.0 (2025-10-03)

✅ Rebranded to Orchestro - "Your AI Development Conductor"
✅ Pattern Analysis Tools - 5 new MCP tools for failure detection
✅ Pattern Frequency - Automatic tracking with database triggers
✅ Risk Assessment - detect_failure_patterns & check_pattern_risk
✅ Task Metadata - assignee, priority, tags fields
✅ PM-focused Documentation - Updated for product owners

v1.5.0 (2025-10-02)

✅ New workflow: MCP orchestrates, Claude Code analyzes
✅ 3 execution tools: prepare, save_analysis, get_execution_prompt
✅ tasks.metadata JSONB column
✅ Event queue updated (8 event types)
✅ Guardian verification passed

v1.0.0

Initial MCP implementation
Basic task management
AI story decomposition
Knowledge base integration

🌟 Success Stories

"As a PM, I finally understand what developers are building in real-time. Orchestro bridges the gap between product vision and technical implementation." — Your testimonial here

"Pattern learning saved us hours. The system warned about a risky approach before we wasted time on it." — Your testimonial here

📞 Support & Community

📧 Issues: GitHub Issues
💬 Discussions: GitHub Discussions
📖 Docs: Comprehensive guides in the repo
🌐 Dashboard: http://localhost:3000
🐦 Twitter: @orchestro_ai (Coming Soon)

📜 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

Claude Code - MCP platform & AI development
Supabase - Database & real-time infrastructure
Next.js - React framework for dashboard
React Flow - Beautiful dependency graphs
shadcn/ui - Gorgeous UI components

🎭 Ready to Conduct Your Development Symphony?

Transform product ideas into production code with AI orchestration

Get Started · PM Guide · Dev Guide · See Examples

Status: ✅ Production Ready (96.7% Test Coverage) Version: 2.1.0 NPM: @khaoss85/orchestro Registry: MCP Registry MCP Tools: 60 Made for: PMs · Developers · Claude Code

🎼 Conducting development, one task at a time

Made with ❤️ by developers who care about product

⭐ Star us on GitHub to support the project!