Migration Guide

Overview

This guide helps you migrate from the older file-based command system to Orchestre's modern prompt-based architecture. The new system serves prompts dynamically through the MCP protocol, eliminating the need for command files in your projects.

What's Changed

Pure Prompt Architecture

Before (file-based system):

• Commands were files copied to .claude/commands/
• Each project had duplicate command files
• Updates required manual file synchronization
• Projects accumulated command clutter

Now (prompt-based system):

• Commands are MCP prompts served dynamically
• Projects only have .orchestre/prompts.json configuration
• Updates happen instantly server-side
• Projects stay clean and focused

The Benefits

1. Zero Installation: Commands work immediately when Orchestre connects
2. Always Current: Server improvements benefit all projects instantly
3. Smart Loading: Only relevant prompts for your project type
4. No Maintenance: No files to sync, no versions to manage

Migration Steps

1. Update Orchestre

First, ensure you have the latest Orchestre:

# Pull latest changes
cd /path/to/orchestre
git pull

# Rebuild
npm install
npm run build

2. Restart Claude Code

After updating, restart Claude Code to ensure the MCP prompts are loaded:

# Completely quit Claude Code
# Then restart it

3. Clean Up Old Command Files

Remove old command files from your projects:

# Remove old command directory
rm -rf .claude/commands/

# The .orchestre/ directory will be updated automatically

4. Verify Installation

In Claude Code, verify Orchestre is working:

/mcp

You should see Orchestre listed in the MCP connections.

Key Changes

Command Access

Old system: Commands were files in .claude/commands/

.claude/
└── commands/
    ├── create.md
    ├── orchestrate.md
    └── ... (many files)

New system: Commands are MCP prompts, only configuration remains

.orchestre/
└── prompts.json  # Just a list of available commands

Command Usage

The way you use commands hasn't changed:

• Still use /create, /orchestrate, etc.
• Same powerful capabilities
• Better adaptation to your project

Template Commands

Template-specific commands now load automatically:

• MakerKit projects get MakerKit commands
• Cloudflare projects get Cloudflare commands
• No manual installation needed

The 12 Essential Commands

Orchestre focuses on minimal, high-value commands:

Project Setup & Planning (3)

• /create - Initialize new projects
• /initialize - Add to existing projects
• /orchestrate - Analyze and plan

Development & Execution (3)

• /execute-task - Context-aware execution
• /compose-saas-mvp - Rapid SaaS prototyping
• /generate-implementation-tutorial - Comprehensive implementation guides

Enterprise & Production (3)

• /security-audit - Vulnerability detection
• /add-enterprise-feature - Production features
• /migrate-to-teams - Multi-tenancy migration

Knowledge Management (2)

• /document-feature - Contextual documentation
• /discover-context - Codebase analysis

Code Quality (1)

• /review - Multi-LLM consensus code review

Troubleshooting

Commands Not Appearing

If commands don't show after upgrading:

1. Restart Claude Code completely
2. Check MCP connection using the MCP icon
3. Verify Orchestre is running: /mcp command
4. Ensure you're in a project with .orchestre/prompts.json

Old Commands Still Showing

If you see duplicate commands:

1. Remove .claude/commands/ directory
2. Restart Claude Code
3. Only MCP prompts should appear

Performance Issues

The new system should be faster:

• No file I/O for commands
• Instant prompt loading
• Better caching

If slower, check:

• Network connection to MCP server
• Claude Code needs restart
• Clear any corrupted cache

Benefits

For Users

1. Cleaner Projects: No command files cluttering your codebase
2. Always Updated: Get improvements without any action
3. Faster Setup: Commands work instantly on connection
4. Smart Context: Commands adapt to your specific project

For Teams

1. No Sync Issues: Everyone uses the same server version
2. Consistent Experience: No version mismatches
3. Easy Onboarding: New members get all capabilities instantly
4. Central Updates: Improvements deployed to all at once

Future Compatibility

The new architecture ensures:

• Future improvements without breaking changes
• New commands available instantly
• Better integration with Claude Code updates
• Foundation for advanced features

Getting Help

If you encounter issues:

1. Check our FAQ
2. Review Common Issues
3. Join our Discord Community
4. Open an issue on GitHub

Summary

Orchestre's prompt-based architecture represents a reimagining of how AI development tools should work. By moving to pure MCP prompts, we've created a cleaner, faster, and more intelligent system that grows with your needs.