Project Configuration

How Orchestre projects are configured and managed.

Overview

Orchestre uses a distributed, lightweight approach to project configuration:

1. Environment Variables - Runtime settings and API keys
2. Template Metadata - Initial project structure from template.json
3. Memory System - Project context in CLAUDE.md files
4. Model Configuration - Optional models.config.json for LLM preferences

Configuration Philosophy

Unlike traditional frameworks with complex configuration files, Orchestre embraces:

• Convention over configuration - Smart defaults that just work
• Distributed knowledge - Configuration lives with the code it affects
• Natural language - Describe what you want, not how to configure it

Project Initialization

When you create a new project:

/create "my-app" using makerkit-nextjs

Orchestre:

1. Copies the template structure
2. Installs template-specific commands
3. Creates initial CLAUDE.md with project context
4. Sets up memory templates for documentation

Environment Configuration

Required Settings

# .env - At least one LLM provider key required
ANTHROPIC_API_KEY=sk-ant-xxx
# or
OPENAI_API_KEY=sk-xxx
# or  
GEMINI_API_KEY=AIzaSyxxx

Optional Settings

# Debug and logging
ORCHESTRE_DEBUG=true
ORCHESTRE_LOG_LEVEL=debug  # error, warn, info, debug, verbose

# Performance tuning
ORCHESTRE_PARALLEL_AGENTS=3  # 1-10, default: 3
ORCHESTRE_TIMEOUT=60000      # milliseconds, default: 30000

# Feature flags
ORCHESTRE_AUTO_REVIEW=true   # Auto-review after changes
ORCHESTRE_DISTRIBUTED_MEMORY=true  # Use CLAUDE.md system

Model Configuration

Optionally configure LLM preferences in models.config.json:

{
  "primary": "claude-3-opus",
  "planning": "gemini-2.0-flash-thinking-exp",
  "review": ["gpt-4o", "claude-3-sonnet"],
  "parameters": {
    "temperature": 0.7,
    "maxTokens": 4096
  }
}

Template Configuration

Each template includes template.json with metadata:

{
  "name": "makerkit-nextjs",
  "description": "Production-ready SaaS starter kit",
  "version": "1.0.0",
  "author": "MakerKit",
  "commands": [
    "add-feature",
    "setup-stripe",
    "add-team-feature",
    // ... more commands
  ],
  "dependencies": {
    "required": ["next", "react", "typescript"],
    "optional": ["stripe", "resend", "posthog"]
  }
}

Memory System Configuration

Project knowledge is stored in CLAUDE.md files throughout your project:

Root CLAUDE.md

# Project: SaaS Platform

## Architecture
- Next.js 14 with App Router
- PostgreSQL with Prisma ORM
- Stripe for subscriptions
- AWS S3 for file storage

## Conventions
- Use server components by default
- Implement auth checks in middleware
- Follow REST API naming conventions

## Key Decisions
- Multi-tenant with team workspaces
- JWT authentication with refresh tokens
- Webhook-driven billing updates

Feature-specific CLAUDE.md

# Authentication System

## Implementation
- NextAuth.js with custom adapter
- JWT tokens with 7-day expiry
- Refresh tokens in httpOnly cookies

## Security Measures
- Rate limiting on auth endpoints
- Email verification required
- 2FA optional per user

Project Metadata

Orchestre automatically tracks:

• Template used for initialization
• Commands available for the project
• Memory structure and documentation
• Creation timestamp and context

This information helps Orchestre provide context-aware assistance.

Configuration by Convention

Many aspects don't require explicit configuration:

File Structure

• Orchestre understands common patterns
• Adapts to your project's structure
• No need to configure paths

Dependencies

• Reads from package.json
• Understands framework conventions
• Suggests compatible packages

Workflows

• Learns from your command usage
• Adapts to your development style
• No workflow configuration needed

Dynamic Adaptation

Orchestre discovers and adapts to your project:

# Discover existing project context
/discover-context

# Document new architectural decisions
/document-feature "Switched to GraphQL API"

# Orchestre learns and adapts
/orchestrate "Add a new API endpoint"
# Now suggests GraphQL resolver instead of REST

Best Practices

1. Document Early and Often

# After major decisions
/document-feature "Chose PostgreSQL for JSONB support"

# After solving complex problems  
/document-feature "Rate limiting: 100 req/min per user"

2. Keep Secrets Secure

# Never commit .env files
echo ".env*" >> .gitignore

# Use platform-specific secret management in production

3. Let Templates Guide You

# Templates include best practices
/create "my-app" using makerkit-nextjs

# Follow template conventions for consistency

4. Leverage Natural Language

# Instead of complex config
/orchestrate "Configure the app for production deployment"

# Orchestre understands context and intent

Troubleshooting

Missing API Keys?

# Check environment
env | grep "_API_KEY"

# Ensure .env is loaded
source .env

Commands Not Working?

# Verify template
cat template.json

# Check available commands
/status

Need Different Models?

# Create models.config.json
echo '{"primary": "gpt-4o"}' > models.config.json

See Also

• Environment Variables
• Model Configuration
• Memory System
• Getting Started