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

1. Go to https://supabase.com and create a new project
2. Wait for the database to be provisioned (~2 minutes)
3. 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 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

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

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

Orchestro decomposes (AI-powered):

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

Total: 18 hours, 6 tasks, dependencies mapped automatically

Developer flow (with autoAnalyze=true):

// 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!)

// 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)

• 60 MCP tools fully functional and tested
• Real-time dashboard with Kanban
• AI story decomposition with dependencies
• Pattern learning & failure detection
• Dependency tracking & conflict detection
• Task metadata (assignee, priority, tags, category)
• Complete audit trail with task history
• Project configuration management
• Claude Code agent synchronization
• AI-powered agent and tool suggestions

🚧 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

• Multi-team workspaces
• Cross-project pattern sharing
• Velocity tracking & estimation
• Auto-assignment based on expertise
• Slack/Teams integration

🚀 Phase 4: Advanced AI

• LangGraph auto-orchestration
• Predictive risk detection
• Auto-conflict resolution
• Code review automation
• Documentation generation

---

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

1. Fork the repo
2. Create feature branch (git checkout -b feature/amazing-feature)
3. Commit changes (git commit -m 'Add amazing feature')
4. Push to branch (git push origin feature/amazing-feature)
5. 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

---