/migrate-to-teams

Migrate single-tenant application to multi-tenant architecture with team/organization support.

Overview

• Purpose: Multi-tenancy migration orchestration
• Category: Specialized Commands
• Type: Dynamic prompt
• MCP Tools: Multiple (migration workflow)

Syntax

/migrate-to-teams [strategy] [options]

Usage Examples

# Basic migration
/migrate-to-teams

# With specific strategy
/migrate-to-teams --strategy gradual

# Preserve existing data
/migrate-to-teams --preserve-data

# Custom schema
/migrate-to-teams --schema "organization-based"

Migration Strategies

Gradual Migration

• Add team support alongside existing
• Migrate users incrementally
• Maintain backward compatibility
• Zero downtime

Big Bang Migration

• Complete migration at once
• Scheduled downtime
• Clean architecture
• Faster completion

Hybrid Approach

• Core changes immediate
• Feature migration gradual
• Balanced risk/reward

Output Example

🏢 Multi-Tenant Migration Plan

## Current State Analysis
- Single-tenant application
- 1,250 active users
- 450GB data
- PostgreSQL database

## Migration Strategy: Gradual

### Phase 1: Schema Evolution (Week 1)
```sql
-- Add organizations table
CREATE TABLE organizations (
  id UUID PRIMARY KEY,
  name VARCHAR(255) NOT NULL,
  slug VARCHAR(255) UNIQUE NOT NULL,
  created_at TIMESTAMP DEFAULT NOW()
);

-- Add team relationships
ALTER TABLE users ADD COLUMN organization_id UUID;
ALTER TABLE users ADD CONSTRAINT fk_organization 
  FOREIGN KEY (organization_id) REFERENCES organizations(id);

-- Add to all resource tables
ALTER TABLE projects ADD COLUMN organization_id UUID NOT NULL;
CREATE INDEX idx_projects_org ON projects(organization_id);

Phase 2: Data Migration (Week 2)

// Create default organization for existing users
const migration = async () => {
  const defaultOrg = await createOrganization({
    name: 'Default Organization',
    slug: 'default'
  });
  
  await db.users.update(
    { organization_id: null },
    { organization_id: defaultOrg.id }
  );
}

Phase 3: Application Updates (Week 3-4)

Authentication Layer

// Add organization context
const authMiddleware = async (req, res, next) => {
  const user = await getUser(req);
  const org = await getOrganization(user.organization_id);
  
  req.user = user;
  req.organization = org;
  next();
}

Data Access Layer

// Add organization scoping
class ProjectRepository {
  async findAll(organizationId: string) {
    return db.projects.findAll({
      where: { organization_id: organizationId }
    });
  }
}

Permission System

const permissions = {
  'org:owner': ['*'],
  'org:admin': ['users:*', 'projects:*', 'settings:*'],
  'org:member': ['projects:read', 'projects:write']
};

Phase 4: Features (Week 5)

• Team invitation system
• Organization switching
• Team management UI
• Billing per organization

Phase 5: Migration Tools

# Bulk organization creation
/execute-task "Create organization import tool"

# User migration script
/execute-task "Build user-to-org assignment tool"

Security Considerations

✅ Row-level security policies ✅ Organization isolation ✅ Cross-tenant protection ✅ Audit logging per org

Testing Strategy

1. Unit tests for org context
2. Integration tests for isolation
3. Load tests for multi-tenant
4. Security penetration testing

Rollback Plan

• Feature flags for gradual enable
• Database backup before migration
• Rollback scripts prepared
• Monitoring during migration

## Key Components

### Database Changes
- Organization tables
- Foreign key relationships
- Isolation indexes
- RLS policies

### Application Changes
- Authentication updates
- Authorization layer
- Data scoping
- API modifications

### UI Updates
- Organization switcher
- Team management
- Invitation flows
- Admin interfaces

## Best Practices

## Prompt Adaptation

This prompt dynamically adapts based on:

### Context Discovery
- Analyzes current project state and structure
- Discovers existing patterns and conventions
- Understands team workflows and preferences
- Adapts to technology stack and architecture

### Intelligence Patterns
- Learns from previous executions in the project
- Adapts complexity based on team expertise
- Prioritizes based on project phase
- Suggests optimizations from accumulated knowledge

## Memory Integration

This prompt actively uses and updates distributed memory:

### Reads From
- `CLAUDE.md` - Project context and conventions
- `.orchestre/` - Orchestration state and patterns
- Feature-specific CLAUDE.md files
- Previous execution results

### Updates
- Relevant CLAUDE.md files with new insights
- `.orchestre/` with execution patterns
- Documentation as part of the workflow
- Pattern library with successful approaches


### 1. Test Isolation
```bash
/migrate-to-teams --dry-run
/execute-task "Create isolation tests"

2. Gradual Rollout

Use feature flags for controlled migration

3. Monitor Everything

• Performance impact
• Error rates
• User experience
• Data integrity

Common Patterns

Organization Model

interface Organization {
  id: string
  name: string
  slug: string
  subscription?: Subscription
  settings: OrgSettings
}

Membership Model

interface Membership {
  userId: string
  organizationId: string
  role: 'owner' | 'admin' | 'member'
  joinedAt: Date
}

Context Passing

interface RequestContext {
  user: User
  organization: Organization
  membership: Membership
}

Integration

With Database

/migrate-to-teams
/execute-task "Run migration scripts"
/validate-implementation "data isolation"

With Testing

/migrate-to-teams
/setup-testing "multi-tenant scenarios"

Direct Invocation

This is a dynamic prompt that Claude executes directly - no file installation needed:

# Simply type the command
/migrate-to-teams [parameters]

# Claude will:
# 1. Analyze current context
# 2. Discover relevant patterns
# 3. Execute intelligently
# 4. Update distributed memory
# 5. Provide detailed results

Related

• /add-team-feature - Team features
• /add-enterprise-feature - Enterprise features
• Multi-tenancy Guide - Best practices