Migrate instance data from system-centric (instances/{platform}/{org}/) to client-centric (orgs/{org}/platforms/{platform}/{instance}/) folder structure. Use when asked to migrate work locally, reorganize project folders, or set up org-centric structure.
Activate when the user:
instances/ to orgs/ structureinstances/
salesforce/
gamma-corp/ # Platform first, then org
acme-production/
hubspot/
portal-123/
orgs/
{org_slug}/ # Org first (primary boundary)
_meta/
org.yaml # Org-level metadata
analysis/ # Cross-platform analysis
planning/ # Roadmaps, architecture
delivery/ # Cross-platform deliverables
platforms/
salesforce/
{instance}/ # Platform instances under org
_meta/
instance.yaml # Instance metadata
projects/ # Assessment work
configs/ # RUNBOOK.md, ENV_CONFIG.json
data/ # observations, reflections
hubspot/
{portal}/
node scripts/migrate-to-client-centric.js --dry-run --verbose
node scripts/migrate-to-client-centric.js --only-org <org-name> --write-report
node scripts/migrate-to-client-centric.js --create-symlinks --write-report
| Flag | Description |
|---|---|
--dry-run | Preview without making changes |
--only-org <slug> | Migrate single org for testing |
--write-report | Generate JSON + Markdown report |
--create-backups | Backup before migrating |
--create-symlinks | Create backward-compatibility symlinks |
--verbose | Detailed output |
Both old and new paths are supported via dual-path resolution:
INSTANCE_PATH)orgs/{org}/platforms/{platform}/{instance})instances/{platform}/{instance})instances/{instance})| Variable | Purpose |
|---|---|
ORG_SLUG | Primary org identifier |
CLIENT_ORG | Alias for ORG_SLUG |
INSTANCE_PATH | Direct path override |
PREFER_ORG_CENTRIC | Prefer new structure (default: 1) |
# Resolve path for an org
node .claude-plugins/opspal-salesforce/scripts/lib/org-context-manager.js resolve <org-alias>
# Migrate context to org-centric
node .claude-plugins/opspal-salesforce/scripts/lib/org-context-manager.js migrate <org-alias> --org <org-slug>
# Resolve path for a portal
node .claude-plugins/opspal-hubspot/scripts/lib/portal-context-manager.js resolve <portal-name>
# Migrate context to org-centric
node .claude-plugins/opspal-hubspot/scripts/lib/portal-context-manager.js migrate <portal-name> --org <org-slug>
# Resolve instance path
node .claude-plugins/opspal-core/scripts/lib/path-resolver.js resolve <platform> <instance> [org]
# List discovered orgs
node .claude-plugins/opspal-core/scripts/lib/path-resolver.js list-orgs
# Extract org info from path
node .claude-plugins/opspal-core/scripts/lib/path-resolver.js extract "orgs/acme/platforms/salesforce/prod"
# Load org metadata
node .claude-plugins/opspal-core/scripts/lib/metadata-loader.js load-org <org-slug>
# Load instance metadata
node .claude-plugins/opspal-core/scripts/lib/metadata-loader.js load-instance <org> <platform> <instance>
# List all orgs with metadata
node .claude-plugins/opspal-core/scripts/lib/metadata-loader.js list-orgs
Edit config/instance-mappings.yaml to define org/instance relationships: