stripe-switch-account

name	stripe-switch-account
description	Rotates the active Stripe account of a SpecBox project safely. Wraps the switch_stripe_account MCP tool with a UX layer: shows current alias store, asks for from/to, runs dry-run, formats the plan in Markdown, asks for literal confirmation, executes, and surfaces the rollback runbook if something fails. Supports both account_mode='standard' (SaaS, e-commerce) and 'connect' (marketplace). Use when the user says "switch stripe account", "rotar cuenta stripe", "cambiar cuenta stripe", "cambiar de cuenta de stripe", "rotate stripe account", "stripe credentials rotation".
context	direct
allowed-tools	Read, Grep, Glob, Bash(*), Write, Edit, mcp__specbox-stripe__*, mcp__specbox-supabase__*

/stripe-switch-account — Stripe credentials rotation skill

Companion of /stripe-connect and /stripe-standard. Where those scaffold a brand-new integration, this one rotates an already-deployed integration to a different Stripe account. Common cases:

• Test → live (going to production for the first time)
• Live → live (changing legal entity, splitting from a former partner)
• Live → test (rolling back to a sandbox after an incident)

The skill never moves money, customers or subscriptions across accounts — those are immutable once created. What it rotates is the infrastructure: which account the platform's Edge Functions talk to, where the webhooks fire, which sk_* lives in Supabase secrets.

Uso

/stripe-switch-account

Sin argumentos. La skill detecta el alias store, pregunta from/to, propone un plan, pide confirmación literal y ejecuta.

Pre-requisitos

1. Alias store con al menos 2 entradas. Crear con:

   mcp__specbox-stripe__store_stripe_alias_tool({
     alias_name: "prod",
     stripe_api_key: "sk_live_...",
     project_path: "/abs/path/to/project"
   })
   

   La store vive cifrada en .claude/secrets/stripe_aliases.enc.json.
2. specbox-stripe-mcp v0.3+ registrado en .claude/settings.local.json.
3. (Recomendado) specbox-supabase-mcp registrado para auto-rotación de Edge Function secrets. Si falta, la skill genera doc/PENDING_SWITCH_SECRETS.md y guía al usuario para hacerlo manualmente.

---

Paso 0 — Preflight

0.1 Validar proyecto SpecBox

test -f .claude/settings.local.json || test -f .claude/settings.json || {
  echo "ERROR: No es un proyecto SpecBox. Ejecuta onboard_project primero."
  exit 1
}

0.2 Detectar specbox-stripe-mcp

Comprobar que el MCP está registrado: grep -q specbox-stripe .claude/settings.local.json.

Si falta → abortar con instrucciones de instalación:

ERROR: specbox-stripe-mcp no está registrado en este proyecto.
Añádelo a .claude/settings.local.json bajo "mcpServers".
Mínimo requerido: v0.3.0 (incluye switch_stripe_account).

0.3 Detectar el modo del proyecto

Leer package.json / pubspec.yaml / Edge Functions existentes:

• ¿Hay supabase/functions/stripe-webhook con un solo endpoint? → account_mode='standard'.
• ¿Hay 2 webhooks (platform + connect) o referencias a application_fee_percent? → account_mode='connect'.

Si la heurística es ambigua, preguntar al usuario.

0.4 Listar aliases disponibles

mcp__specbox-stripe__list_stripe_aliases_tool_mcp({ project_path: "{abs}" })

Si hay menos de 2 → abortar:

ERROR: Necesitas al menos 2 aliases (origen + destino).
Tienes registrados: [lista]
Crea otro con store_stripe_alias_tool antes de switch.

---

Paso 1 — UX inicial

Mostrar al usuario:

🔄 Stripe Switch Account

Aliases registrados en este proyecto:
  • prod      (live, last used 2026-04-29 14:22)
  • staging   (test, last used 2026-04-15 10:01)
  • legacy    (live, never used)

¿De qué alias migras? (from): prod
¿A qué alias migras?   (to):   staging
¿Modo de cuenta?              standard

¿Qué hacer con la cuenta de origen tras el switch?
  (1) keep_old_active        — no tocar nada (DEFAULT, recomendado para rollback rápido)
  (2) archive_products_only  — archivar los products SpecBox, dejar webhooks
  (3) deactivate_webhooks_only — deshabilitar webhooks, dejar products
  (4) full_archive           — todo lo anterior + cancelar subs SpecBox-managed (irreversible)

Elección: 1

Validar before continuar:

• from != to
• from y to existen en alias_store
• En connect → preguntar también connect_events/connect_url si difieren

---

Paso 2 — Dry-run obligatorio

mcp__specbox-stripe__switch_stripe_account_tool({
  from_alias: "prod",
  to_alias: "staging",
  account_mode: "standard",
  project_path: "{abs}",
  platform_url: "https://{ref}.supabase.co/functions/v1/stripe-webhook",
  platform_events: [...read from project's events.yaml or defaults...],
  scope_action: "keep_old_active",
  dry_run: true
})

Formatear la respuesta como Markdown:

📋 Plan de migración (dry-run)

ORIGEN (prod, sk_live_***)
  Webhook endpoints:    1 SpecBox-managed
  Products:             3
  Subscriptions activas: 27
  Customers:            142

DESTINO (staging, sk_test_***)
  Webhook endpoints:    0
  Products:             0

ACCIONES PROPUESTAS
  1. Crear 1 webhook endpoint en destino (events: ...)
  2. Replicar catálogo (3 products + sus prices)  ← solo si pasaste catalog
  3. Inyectar secrets en Supabase (3 keys)        ← si specbox-supabase MCP detectado
                                  ↳ si no: doc/PENDING_SWITCH_SECRETS.md
  4. scope_action sobre origen: keep_old_active (no toca nada)

Duración estimada: ~12 segundos

⚠️  IMPORTANTE: Las subscripciones, customers, y métodos de pago de la
   cuenta origen NO se mueven. Siguen vivos en prod. Si alguien tenía
   sesión iniciada y va a renovar, el cobro irá a prod, NO a staging.
   Este flow es para infrastructure rotation, no migración de business data.

---

Paso 3 — Confirmación literal

Para ejecutar este switch, escribe EXACTAMENTE:

  Yes, switch from prod to staging

(con esos espacios y mayúsculas; un fallo de typing aborta el switch)

Si el usuario escribe cualquier otra cosa → abortar sin tocar nada.

Si scope_action='full_archive' → segunda confirmación con confirm_token="I understand this archives all SpecBox resources in the source account".

---

Paso 4 — Ejecutar real

mcp__specbox-stripe__switch_stripe_account_tool({
  ...mismo payload que dry-run...
  dry_run: false
})

Streaming progress al usuario:

✓ Pre-flight OK
✓ Webhook endpoint creado en destino: we_1TabcXyz
✓ 3/3 products replicados en destino
✓ Secrets inyectados en Supabase (3 nombres: STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET, STRIPE_PUBLISHABLE_KEY)
✓ scope_action keep_old_active: cuenta origen intacta

✅ Switch completado en 11.2s.

Si algún paso falla:

✗ Webhook endpoint creado en destino
✗ Products replicación: FAILED (E_LIMIT_REACHED)
🔄 Iniciando rollback automático...
✓ Webhook destino eliminado
⚠ Rollback completo. Sistema de vuelta al estado pre-switch.

Revisa los logs y vuelve a intentar.

Si rollback también falla:

🚨 Rollback parcialmente fallido. Estado del sistema mixto.
   Runbook generado en: doc/SWITCH_FAILURE_RUNBOOK.md
   Sigue las instrucciones manualmente.

---

Paso 5 — Smoke-test post-switch

Sugerir al usuario:

Próximos pasos:
  1. Reload de Edge Functions (Supabase los recoge automáticamente).
  2. stripe listen --forward-to {platform_url}  (con la NUEVA cuenta)
  3. Test de un signup nuevo:
       - Card 4242 4242 4242 4242
       - Verifica que aparece en https://dashboard.stripe.com/{test|live}/customers de la cuenta DESTINO.
  4. Si todo OK y scope_action era 'keep_old_active' → considera ejecutar
     /stripe-switch-account de nuevo con scope_action='archive_products_only'
     una vez confirmes que no necesitas rollback.

Si el usuario responde "rollback please":

/stripe-switch-account
  from: staging
  to:   prod

Es exactamente el mismo flow al revés (siempre que prod aún esté keep_old_active).

---

Anexo A — Errores comunes

Error	Causa	Fix
E_ALIAS_NOT_FOUND	El alias no está en la store	Crear con store_stripe_alias_tool
E_DECRYPT_FAILED	macOS Keychain inaccesible o passphrase distinto	Re-ingresar passphrase / re-crear keychain entry
E_INVALID_KEY (en alias)	sk_test_/sk_live_ malformado	Pegar de nuevo desde el dashboard
E_LIVE_MODE_NOT_ALLOWED	sk_live_* sin opt-in	Pasar allow_live_mode=true + live_mode_confirm_token="I acknowledge this affects real money"
E_LIMIT_REACHED	>16 webhook endpoints en la cuenta destino	Borrar los huérfanos: stripe webhooks list --limit=100 y purga manual
E_SUPABASE_WRITE_FAILED	PAT expirado / project_ref incorrecto	Revisar SUPABASE_ACCESS_TOKEN
E_CONFIRMATION_REQUIRED	Token literal incorrecto	Copiar el token exactamente como aparece en el mensaje de error

---

Anexo B — .gitignore enforcement

La store cifrada en .claude/secrets/stripe_aliases.enc.json se añade a .gitignore automáticamente la primera vez que se llama a store_stripe_alias_tool. La skill lo verifica antes de cualquier acción. Si por alguna razón está commiteada al repo, revoca todas las keys de Stripe inmediatamente y rota — el archivo cifrado no debería bastar para recuperarlas, pero asume compromiso.

---

Referencias

• Tool docs: mcp__specbox-stripe__switch_stripe_account_tool
• Alias store: packages/specbox-stripe-mcp/src/specbox_stripe_mcp/lib/alias_store.py
• Skills hermanas: /stripe-connect (marketplace), /stripe-standard (no-Connect)
• Tracking: SpecBox board ff-bc73b5d69f91, US-STRIPE-SWITCH-ACCOUNT