initialize_project

The initialize_project tool creates new Orchestre projects from templates, setting up the complete development environment including project structure, configuration, and template-specific commands.

Overview

• Purpose: Smart project initialization and setup
• AI Model: None (deterministic)
• Typical Duration: < 1 second
• Source: src/tools/initializeProject.ts

Input Schema

{
  template: string;      // Template name: 'makerkit' | 'cloudflare' | 'react-native'
  projectName: string;   // Name of the project (alphanumeric + hyphens)
  targetPath?: string;   // Optional target directory (defaults to ./{projectName})
}

Output Format

{
  "success": true,
  "projectPath": "./my-saas-app",
  "template": "makerkit",
  "structure": {
    "directories": ["src", "tests", "docs"],
    "files": ["package.json", "README.md", ".env.example"]
  },
  "commandsInstalled": [
    "add-feature",
    "setup-stripe",
    "add-api-endpoint",
    // ... more template commands
  ],
  "knowledgePack": {
    "commands": 15,
    "patterns": 12,
    "memoryTemplates": 5
  },
  "nextSteps": [
    "cd ./my-saas-app",
    "Read requirements.md",
    "/orchestrate requirements.md"
  ]
}

Usage Examples

Basic Usage

// Initialize a SaaS project
@mcp__orchestre__initialize_project({
  template: "makerkit",
  projectName: "my-saas-app"
})

With Custom Path

// Initialize in a specific directory
@mcp__orchestre__initialize_project({
  template: "cloudflare",
  projectName: "edge-api",
  targetPath: "./projects/apis/edge-api"
})

In Commands

The /create command uses this tool:

# /create command internally calls:
@mcp__orchestre__initialize_project({
  template: selectedTemplate,
  projectName: userProvidedName
})

Templates

Available Templates

Template	Description	Use Case
makerkit	Next.js SaaS boilerplate	Full-stack SaaS applications
cloudflare	Edge-first architecture	APIs and edge computing
react-native	Mobile app template	Cross-platform mobile apps

Template Contents

Each template includes:

1. Project Structure

   template/
   ├── src/           # Source code
   ├── tests/         # Test files
   ├── docs/          # Documentation
   └── config/        # Configuration

2. Configuration Files

   • package.json - Dependencies and scripts
   • tsconfig.json - TypeScript configuration
   • .env.example - Environment variables
   • Template-specific configs

3. Knowledge Pack

   .orchestre/
   ├── commands/      # Template commands
   ├── patterns/      # Code patterns
   └── memory/        # Documentation templates

Features

Smart Initialization

The tool performs several intelligent operations:

1. Validation

   • Ensures valid project names
   • Checks template availability
   • Verifies target directory

2. Structure Creation

   • Creates directory hierarchy
   • Copies template files
   • Sets up git repository

3. Command Installation

   • Installs template-specific commands
   • Configures command metadata
   • Sets up command aliases

4. Knowledge Transfer

   • Copies pattern library
   • Installs memory templates
   • Creates initial CLAUDE.md

Error Handling

Common errors and solutions:

Error	Cause	Solution
INVALID_PROJECT_NAME	Invalid characters	Use only letters, numbers, hyphens
TEMPLATE_NOT_FOUND	Unknown template	Check available templates
DIRECTORY_EXISTS	Target exists	Choose different name or path
PERMISSION_DENIED	No write access	Check directory permissions

Advanced Usage

Programmatic Access

import { initializeProjectTool } from '@orchestre/tools';

const result = await initializeProjectTool.handler({
  template: 'makerkit',
  projectName: 'my-app',
  targetPath: './projects/my-app'
});

if (result.success) {
  console.log(`Project created at: ${result.projectPath}`);
  console.log(`Commands available: ${result.commandsInstalled.length}`);
}

Custom Templates

While not directly supported by the tool, you can extend Orchestre with custom templates:

1. Add template to templates/ directory
2. Update template registry
3. Include in tool validation

See Creating Custom Templates for details.

Performance

Optimization

The tool is optimized for speed:

• Parallel file copying
• Minimal I/O operations
• Lazy template loading
• Efficient validation

Benchmarks

Operation	Duration
Validation	~10ms
Directory creation	~50ms
File copying	~200ms
Command installation	~100ms
Total	~400ms

Integration

With Other Tools

initialize_project works seamlessly with other tools:

Workflow Example

# 1. Initialize project
/create makerkit my-app

# 2. Analyze requirements
/orchestrate requirements.md

# 3. Start development
/execute-task "Set up authentication"

Best Practices

1. Choose the Right Template

Consider your project needs:

• SaaS application: Use makerkit
• API/Edge functions: Use cloudflare
• Mobile app: Use react-native

2. Provide Clear Names

Use descriptive project names:

✅ customer-portal
✅ analytics-api
✅ mobile-shopping-app

❌ proj1
❌ test
❌ app

3. Review Generated Structure

After initialization:

1. Check .orchestre/ for commands
2. Read template CLAUDE.md
3. Verify configuration files
4. Understand the structure

Troubleshooting

Project Not Created

Check:

• Valid project name (alphanumeric + hyphens)
• Template exists
• Write permissions
• Sufficient disk space

Commands Not Available

Verify:

• .orchestre/commands/ exists
• Claude Code restarted after creation
• Correct working directory

Template Issues

Solutions:

• Ensure Orchestre is up to date
• Check template files integrity
• Verify template configuration

API Reference

Type Definitions

interface InitializeProjectArgs {
  template: 'makerkit' | 'cloudflare' | 'react-native';
  projectName: string;
  targetPath?: string;
}

interface InitializeProjectResult {
  success: boolean;
  projectPath: string;
  template: string;
  structure: {
    directories: string[];
    files: string[];
  };
  commandsInstalled: string[];
  knowledgePack: {
    commands: number;
    patterns: number;
    memoryTemplates: number;
  };
  nextSteps: string[];
}

Error Codes

enum InitializeErrorCode {
  INVALID_PROJECT_NAME = 'INVALID_PROJECT_NAME',
  TEMPLATE_NOT_FOUND = 'TEMPLATE_NOT_FOUND',
  DIRECTORY_EXISTS = 'DIRECTORY_EXISTS',
  PERMISSION_DENIED = 'PERMISSION_DENIED',
  UNKNOWN_ERROR = 'UNKNOWN_ERROR'
}

Related

• /create command - User-facing initialization command
• Template Guide - Detailed template documentation
• Project Structure - Organization patterns