Contributing to Orchestre

Thank you for your interest in contributing to Orchestre! This guide will help you get started with v5's prompt-based architecture.

Ways to Contribute

1. Report Issues

• Use GitHub Issues
• Include clear descriptions and steps to reproduce
• Add relevant error messages and system information

2. Suggest Features

• Open a discussion in GitHub Discussions
• Explain the use case and benefits
• Consider how it fits with Orchestre's philosophy

3. Submit Code

• Fork the repository
• Create a feature branch
• Make your changes
• Submit a pull request

4. Contribute Prompts (New in v5!)

• Design adaptive prompts that discover context
• Create memory templates for better knowledge capture
• Improve existing prompt intelligence
• Add template-specific prompt configurations

5. Enhance Memory Templates

• Create domain-specific memory structures
• Improve knowledge graph patterns
• Add semantic search capabilities
• Design better consolidation strategies

Development Setup

Prerequisites

• Node.js 18 or higher
• npm or yarn
• Claude Code (for testing MCP integration)
• At least one LLM API key (Anthropic, OpenAI, or Google)

Getting Started

# Clone your fork
git clone https://github.com/YOUR-USERNAME/mcp.git
cd orchestre

# Install dependencies
npm install

# Set up environment
cp .env.example .env
# Add your API keys to .env

# Build the project
npm run build

# Run tests
npm test

# Test MCP server locally
npm run dev

# Configure Claude Code to use local MCP server
# Add to Claude Code's MCP settings:
# {
#   "orchestre": {
#     "command": "node",
#     "args": ["/path/to/orchestre/dist/server.js"]
#   }
# }

Code Guidelines

TypeScript

• Use strict mode
• Add types for all parameters and returns
• Follow existing patterns in the codebase
• Use Zod schemas for validation

Testing

• Write tests for new features
• Ensure existing tests pass
• Test with actual Claude Code integration
• Test prompt adaptability across different contexts

Documentation

• Update relevant documentation
• Add examples for new features
• Keep CLAUDE.md files updated
• Document prompt behavior and adaptations

Prompt Contribution Guidelines (v5)

Writing Effective Prompts

1. Discovery First: Prompts should explore and discover context
2. Adaptive Logic: Handle variations in project structure
3. Clear Instructions: Be specific about what Claude should do
4. Error Handling: Include fallback strategies
5. Memory Integration: Update CLAUDE.md files appropriately

Prompt Structure

// Example prompt definition
export const myPrompt: PromptDefinition = {
  name: "my-command",
  description: "Brief description for command list",
  arguments: [
    {
      name: "arg1",
      description: "What this argument does",
      required: true
    }
  ],
  handler: async (args) => {
    // Return the dynamic prompt content
    return `
      # Adaptive prompt that discovers context
      
      First, explore the project structure...
      Then adapt based on findings...
    `;
  }
};

Memory Template Guidelines

1. Colocated Knowledge: Templates should live near relevant code
2. Semantic Structure: Use clear headings and sections
3. Machine Parseable: Maintain consistent formatting
4. Human Readable: Documentation should be natural to read
5. Version Controlled: All memory is tracked in Git

Testing Prompts

• Test with minimal projects
• Test with complex, established codebases
• Verify memory updates are appropriate
• Ensure prompts handle edge cases
• Check for template-specific adaptations

Pull Request Process

1. Before Starting

   • Check existing issues and PRs
   • Discuss major changes first
   • Base your work on the latest main branch

2. Making Changes

   • Follow the existing code style
   • Write meaningful commit messages
   • Add tests for new functionality
   • Update documentation as needed

3. Submitting PR

   • Use a descriptive title
   • Reference related issues
   • Describe what changes were made and why
   • Ensure all tests pass

Commit Messages

Follow conventional commit format:

type(scope): description

[optional body]

[optional footer]

Types:

• feat: New feature
• fix: Bug fix
• docs: Documentation only
• style: Code style changes
• refactor: Code refactoring
• test: Test additions/changes
• chore: Build process or auxiliary tool changes

Project Structure (v5)

orchestre/
├── src/                  # Source code
│   ├── server.ts        # MCP server implementation
│   ├── tools/           # MCP tool implementations (7 tools)
│   ├── prompts/         # Dynamic prompt system
│   │   ├── definitions/ # Prompt definitions (20 prompts)
│   │   ├── handlers/    # Prompt generation logic
│   │   └── templates/   # Template-specific prompts
│   ├── resources/       # MCP resource providers
│   ├── schemas/         # Zod validation schemas
│   └── utils/           # Utility functions
├── templates/           # Project templates
│   ├── makerkit-nextjs/
│   ├── cloudflare-hono/
│   └── react-native-expo/
├── docs/               # Documentation
├── test/               # Test files
└── examples/           # Example usage

Key Changes in v5

• No file-based commands: All commands are MCP prompts
• Dynamic prompt loading: Based on project context
• Template configurations: Each template defines available prompts
• Lighter footprint: Projects only get .orchestre/prompts.json

Philosophy

When contributing, keep in mind Orchestre's core principles:

• Dynamic over static: Prefer adaptive solutions
• Intelligence over automation: Enable thinking, not just execution
• Context over convention: Respect project uniqueness
• Simplicity over complexity: Minimal code, maximum value

Questions?

• Check the documentation
• Ask in GitHub Discussions
• Review existing issues

Thank you for contributing to Orchestre!