Project Rename

Systematic checklist for renaming a project across every layer. Run each phase in order.

Phase 0: Preparation

1. Identify the old name and all its variants (lowercase, UPPERCASE, CamelCase, kebab-case, snake_case, with/without prefix)
2. Identify the new name and generate all equivalent variants
3. Create a branch for the rename work
4. Run a global grep for every variant to build the full scope:

   grep -rn "old_name\|old-name\|OldName\|OLD_NAME\|oldname" \
     --include='*.{ts,tsx,js,py,md,json,yaml,yml,tf,sql,toml,cfg,conf,env,sh}' \
     --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=contracts/lib .

Phase 1: Infrastructure (Terraform / IaC)

See references/terraform-patterns.md for detailed Terraform rename patterns and code examples.

Gotcha — ACM + Route53 zone mismatch: If the Terraform zone lookup references zone A but the ACM cert needs validation in zone B, cert validation fails silently. Ensure the zone lookup matches var.domain.

Destroy & recreate workflow:

1. Disable ALB deletion protection
2. terraform destroy -auto-approve
3. Force-delete non-empty ECR repos via aws ecr delete-repository --force, then terraform state rm
4. Update all .tf files with new names
5. terraform apply
6. Import pre-existing DNS records: terraform import

Phase 2: AWS Secrets Manager

Copy each secret from old path to new path:

for secret in supabase admin-key commission contracts api-keys x402; do
  VALUE=$(aws secretsmanager get-secret-value --secret-id "old/$secret" --query SecretString --output text)
  aws secretsmanager create-secret --name "new/$secret" --secret-string "$VALUE"
done

Phase 3: Docker & Build

Phase 4: CI/CD (GitHub Actions)

Phase 5: Application Code

Phase 6: Documentation

Update: README.md, CLAUDE.md, SPEC.md, PLAN.md, agent-card.json, IDEA.yaml — project name, URLs, infrastructure details, deploy commands, secret paths, ECR repos.

Phase 7: Final Sweep

grep -rn "old_name\|old-name\|OldName\|OLD_NAME" \
  --include='*.{ts,tsx,js,py,md,json,yaml,yml,tf,toml,cfg,conf,sh}' \
  --exclude-dir=node_modules --exclude-dir=.git --exclude-dir=contracts/lib .

Do NOT rename: immutable on-chain contracts, historical SQL migrations, git history, third-party libraries.

Phase 8: Build, Deploy & Verify

1. Build and push Docker images to new ECR repos
2. Force ECS redeployment
3. Verify health endpoints + dashboard loads
4. Check DNS points to new ALB
5. Commit with a clear message

Key Lessons

• Grep for ALL name variants including UPPERCASE env vars, kebab-case, camelCase
• ECR repos cannot be destroyed if not empty — force-delete via CLI first
• Route53 zone lookups cause silent cert validation failures when mismatched
• Stale DNS records pointing to destroyed ALBs need manual UPSERT
• Remove backward-compat aliases completely — they accumulate tech debt
• Check Terraform state for imported resources that may conflict on apply