Communitygithub.com

JayFarei/opentraces

Implementa todas las correcciones relacionadas con el sitio en main, despliega opentraces.ai en producción de Vercel y verifica que funcione en todas las páginas (escritorio + móvil) y en el flujo de captura de correo electrónico, corrigiendo y redistribuyendo hasta que todo esté en verde. Se ejecuta como un objetivo: implementar -> desplegar -> verificar -> clasificar -> repetir hasta que sea seguro. Úsalo cuando el usuario diga «desplegar sitio», «desplegar en vercel», «subir sitio», «enviar el sitio», «desplegar-sitio» o «implementar y verificar el sitio». Para un lanzamiento coordinado completo que también aumente la versión y publique los paquetes de Python, usa /release-pack en su lugar.

¿Qué es opentraces?

Esta habilidad de agente de IA orquesta un ciclo cerrado de despliegue y verificación para el sitio de marketing Next.js de OpenTraces en Vercel. Está diseñada como un objetivo, no como un comando único: garantiza que todas las correcciones relacionadas con el sitio se fusionen en `main`, se desplieguen en producción de Vercel y se verifiquen exhaustivamente en todas las páginas, dispositivos y el flujo de captura de correo electrónico antes de declarar el éxito. Si alguna ruta falla, el diseño se rompe o la captura de correo no funciona correctamente, el agente vuelve automáticamente a la fase de corrección, reimplementa y vuelve a verificar, registrando cada iteración para su auditoría. La habilidad es compatible con los flujos de trabajo de Vercel, Next.js App Router y herramientas de agente-navegador. Utiliza un archivo de script de flujo de trabajo empaquetado (`verify-site-deploy.workflow.js`) para orquestar la verificación en paralelo en varios puntos de vista y rutas, con manejo inteligente de fallos que reconfirma de forma independiente los errores para evitar falsos positivos. Su principal ventaja es la prevención de regresiones: no solo comprueba que el despliegue se haya completado, sino que verifica activamente el renderizado, errores de consola, desbordamiento de diseño y el correcto funcionamiento del almacenamiento de captura de correo. También incluye reglas estrictas para no contaminar los datos de producción (usa un honeypot para verificaciones sin escritura) y un mecanismo de bloqueo que detiene el ciclo después de 3 reintentos fallidos o problemas de autenticación/credenciales.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/JayFarei/opentraces/tree/HEAD/.claude/skills/deploy-site

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

Implementar Sitio

Desplegar el sitio de marketing Next.js (web/site/) en producción de Vercel, pero tratarlo como un objetivo, no como un comando único: implementar cada corrección relacionada con el sitio en main, desplegarlo, demostrar que funciona en producción en todas las páginas y el flujo de captura de correo electrónico en escritorio y móvil, y seguir corrigiendo + redistribuyendo hasta que todo esté verde.

Contrato del objetivo

Ejecuta esta habilidad como un bucle cerrado. No declares éxito solo con un despliegue limpio de Vercel; un despliegue puede tener éxito mientras una página da error 500, un diseño se rompe en móvil o la escritura de la lista de espera falla en silencio.

  • HECHO cuando: todas las correcciones relacionadas con el sitio están confirmadas y enviadas a main, el despliegue de producción tuvo éxito, cada ruta a continuación devuelve 200 y se renderiza correctamente en escritorio y móvil sin errores de consola/red, y el flujo de captura de correo electrónico acepta un envío y lo persiste (demostrado por lectura de administrador), sin dejar filas de prueba.
  • NO HECHO (repetir bucle) cuando: cualquier ruta no se renderiza, un diseño se rompe en un viewport, la consola muestra errores o la captura de correo no hace un round-trip completp. Corregir en el código fuente, reimplementar, redistribuir, reverificar.
  • BLOQUEADO (detener e informar) cuando: una corrección necesita una credencial/decisión que no tienes (por ejemplo, almacén KV caído, token de administrador faltante, autenticación de Vercel caducada), o el mismo fallo sobrevive a 3 intentos de corrección. Informa el fallo exacto + lo que intentaste; no bucles para siempre.

Mantén un registro breve de cada iteración (qué falló, qué cambiaste, resultado de la reverificación) para que el bucle sea auditable. Si el usuario quiere esto como un /goal persistente, apunta el objetivo a esta habilidad y usa las mismas condiciones HECHO/BLOQUEADO.

El bucle

Fase 0  Alcance e implementar     recopilar correcciones del sitio -> verificar localmente -> confirmar -> enviar a main
Fase 1  Desplegar                compilar -> npx vercel@latest --prod (desde la raíz del repositorio)
Fase 2  Verificar (producción)    Flujo de trabajo: rutas x viewports + captura de correo
Fase 3  Clasificar               ¿algún rojo? corregir en el código fuente -> volver a la Fase 0
                                  ¿todo verde? -> HECHO

Contexto

  • Proyecto: opentraces en Vercel (ámbito jayfareis-projects)
  • Framework: Next.js 16 (App Router)
  • Directorio raíz: Vercel está configurado con la raíz en web/site/
  • Dominio: opentraces.ai (producción: https://opentraces.ai)
  • Compilación: next build (se ejecuta desde web/site/)
  • Versión: Lectura automática desde src/opentraces/__init__.py en tiempo de compilación a través de next.config.ts
  • Captura de correo electrónico: EarlyAccessForm envía a /api/waitlist (Upstash/KV en prod). Se renderiza en / (a través de HubTeaser) y /hub. Consulta la sección de Referencia para selectores + lectura de administrador.

Fase 0 — Alcance e implementar las correcciones del sitio

  1. Encuentra lo que está relacionado con el sitio y no implementado. El árbol de trabajo a menudo contiene una mezcla de cambios del sitio y de otros. Implementa solo las correcciones del sitio aquí (el resto es un asunto separado).

    git status --short web/site/
    git status --short -- ':!web/site/'   # cambios que no son del sitio, normalmente déjalos
    git log --oneline origin/main..HEAD -- web/site/   # confirmaciones del sitio aún no enviadas
    
  2. Verificación local antes de implementar (puerta). Ejecuta el sitio contra el servidor de desarrollo ya en ejecución y verifica la superficie modificada con agente-navegador: claro + oscuro, escritorio + móvil, la interacción específica que cambiaste, además de consola/red limpia. Esta es la puerta previa a la implementación; no confirmes una regresión visual. (Si no hay un servidor de desarrollo activo, cd web/site && npm run dev en un puerto libre, verifica, luego detenlo.)

  3. Compilar localmente (detecta errores de tipo/compilación que el servidor de desarrollo oculta):

    cd web/site && npm run build
    

    Corrige cualquier fallo de compilación antes de continuar.

  4. Confirmar en main y enviar. Según la convención del proyecto, confirma directamente en main (no crees automáticamente una rama de funcionalidad a menos que se solicite). Mantén la confirmación limitada a la corrección del sitio; coautoría la confirmación según la regla de pie de página del repositorio.

    git add web/site/   # prepara solo las correcciones del sitio que verificaste
    git commit -m "fix(site): <lo que cambió>"
    git push origin main
    

Fase 1 — Compilar y desplegar

Despliega desde la raíz del repositorio (no web/site/), porque Vercel resuelve el directorio raíz desde su configuración del proyecto (rootDirectory=web/site). Ejecutar desde dentro de web/site/ duplica la ruta. Siempre fija la CLI más reciente (npx vercel@latest).

cd /ruta/a/la/raíz/del/repo
rm -rf web/site/.next kb/app/.next   # salida de compilación obsoleta; infla la subida
npx vercel@latest --prod --yes

NO uses --archive=tgz (medido el 2026-06-26, CLI 54.x). --archive=tgz comprime todo el árbol de trabajo y omite .vercelignore, por lo que arrastra .git-sin-nada-más más kb/, .otbox/, web/site/.next-test/, etc. — una subida de ~3 GB / 1998 archivos que tarda minutos y una vez se colgó durante ~20 min en "Extrayendo archivos de despliegue" en la máquina de compilación (una parada real de producción que tuvimos). La ruta predeterminada archivo por archivo en vercel@latest en cambio:

  • respeta .vercelignore → ~628 archivos / ~40 MB,
  • se sube en ~2 s y alcanza el estado LISTO en ~60 s de extremo a extremo,
  • no alcanza el Error: Subida abortada que --archive=tgz se agregó originalmente para esquivar (eso fue un error de punto final de brew 41.x; vercel@latest lo corrigió, por lo que la solución alternativa ahora es negativa neta).

Si una CLI futura regresa la ruta archivo por archivo y debes recurrir a --archive=tgz, espera el archivo de ~3 GB y una extracción de varios minutos (ocasionalmente estancada); reintenta el despliegue si se cuelga en la extracción.

Captura la URL/ID del despliegue de la salida; lo referenciarás en el informe de verificación.

Consejo: puedes verificar primero un despliegue de previsualización de Vercel (omite --prod) y ejecutar la Fase 2 contra la URL de previsualización antes de promocionar. Esto mantiene las pruebas de captura de correo electrónico completamente fuera de la lista de producción.


Fase 2 — Verificar en producción (arnés JIT a través de Workflow / ultracode)

Demuestra que el sitio en vivo funciona. Esta fase es un arnés justo a tiempo: tú (el planificador) delimitas el alcance de la ejecución para este despliegue, la herramienta Workflow (el tiempo de ejecución determinista) lo ejecuta, y los workers del navegador efímeros devuelven cada uno contra un esquema tipado. El estado intermedio reside en las variables del arnés, no en tu contexto, por lo que la matriz completa se ejecuta sin llenar tu ventana. Esta habilidad opta explícitamente por la orquestación de Workflow (ultracode).

El arnés está empaquetado y congelado junto a esta habilidad: verify-site-deploy.workflow.js. No pegues el script en línea; ejecuta el archivo.

Qué verificar

  • Rutas (cada una debe devolver 200 + renderizar, sin errores de consola/red): /, /explorer, /hub, /schema, /docs, más una verificación puntual de páginas profundas: /schema/0.6.0, /docs/getting-started/installation, /docs/cli/commands, /docs/schema/trace-record.
  • Viewports: escritorio 1440x900 y móvil 390x844 (clase iPhone). Donde una corrección tocó el tema, también verifica claro + oscuro.
  • Por página: HTTP 200, contenido principal visible, sin desbordamiento/recorte de diseño en el viewport, consola limpia, sin solicitudes de red fallidas, navegación funciona.
  • Captura de correo electrónico (su propio agente, ver más abajo).

Verificación de captura de correo electrónico (no contaminar la lista de producción)

/api/waitlist escribe en un almacén en vivo y no tiene un endpoint DELETE, así que sé deliberado:

  • Round-trip real (una vez, escritorio): envía una dirección etiquetada como deploy-verify-<marca de tiempo>@opentraces.ai. Espera HTTP 200 {ok:true} y que el botón cambie al estado de éxito. Confirma que se persistió con la lectura de administrador (GET /api/waitlist + Authorization: Bearer $WAITLIST_ADMIN_TOKEN), anotando el recuento antes/después. Luego límpialo eliminando esa fila del almacén (Upstash ZREM), y vuelve a leer para confirmar que el recuento ha vuelto. Deja la lista prístina.
  • Ruta de deduplicación: envía la misma dirección dos veces, espera "ya estás en la lista" con el recuento sin cambios.
  • Verificaciones de UI móvil + repetidas sin escribir: llena el honeypot oculto (input[name=company]) al enviar. El endpoint devuelve un falso-éxito silencioso y nunca almacena la fila, por lo que puedes confirmar la UI de éxito en móvil sin agregar basura. (Si ves "éxito" pero el recuento no se movió, eso es el honeypot funcionando, no un error.)
  • Si el endpoint devuelve 503 ("la lista de espera no está configurada"), el almacén KV no está conectado en ese despliegue: eso es BLOQUEADO (problema de entorno/almacén), no una corrección de código. Repórtalo.

Ejecutar el arnés

Invoca el artefacto empaquetado con la herramienta Workflow. Delimita su alcance por despliegue con args (este es el paso "planificador" JIT):

Workflow({
  scriptPath: ".claude/skills/deploy-site/verify-site-deploy.workflow.js",
  args: {
    baseUrl: "https://www.opentraces.ai",  // host canónico; o una URL de previsualización para mantener el correo fuera de producción
    changed: ["/hub", "/"],             // rutas que tocó este despliegue -> verificación profunda; el resto se prueba superficialmente
    pagesOnly: false                    // true = omitir la escritura de correo (la validación de solo lectura se ejecuta)
  }
})

Devuelve { base, scoped, failures, allGreen }. allGreen: true significa que la Fase 2 pasó; de lo contrario, failures enumera exactamente qué corregir en la Fase 3.

Cómo aplica el arnés las primitivas JIT (consulta kb/docs/concept-jit-harnesses-generic.md):

  • Clasificar y enrutar: si pasas changed, esas rutas obtienen una verificación completa del navegador (consola, desbordamiento, captura de pantalla); cada otra ruta es solo un curl económico para el estado. Flujo de control JS simple que posee el tiempo de ejecución, ningún modelo en la costura, por lo que un despliegue delimitado sigue siendo económico.
  • Un worker de barrido determinista por viewport (2 workers, no ~18): cada uno ejecuta un solo lote bash fijo (curl + un conjunto limitado de llamadas de agente-navegador por ruta) en un modelo económico (haiku) y devuelve el JSON analizado. Sin un prompt abierto de "verifica todo", por lo que el modelo no puede hacer bucles; cada lote abre una sesión del navegador y la cierra con close --all, por lo que los procesos de Chrome no se acumulan. (Validado el 2026-06-09: ~16s para un barrido completo de viewport profundo, 1 proceso sobrante, frente a las 54 procesos / 15+ min del diseño original por celda.)
  • Confirmación adversaria independiente: cualquier ruta que un barrido marque como fallida es re-verificada por un worker separado con una sesión limpia (modelo predeterminado) que intenta reproducirla; un fallo sobrevive solo si la confirmación también falla, por lo que un error del agente-navegador no se disfraza de un error del sitio.
  • Contratos tipados: cada worker devuelve contra PAGE_VERDICT / EMAIL_VERDICT, por lo que los resultados se fusionan mecánicamente.
  • Captura de correo electrónico tiene su propio worker que demuestra la escritura a través de una lectura de administrador independiente y limpia la fila de prueba (consulta las reglas de no contaminación anteriores).

Para cambiar la matriz, la política de profundidad o el esquema de veredicto, edita el archivo .js, es la fuente única de verdad. Si un cambio es de una página y no deseas orquestación, aún puedes ejecutar la verificación de esa página secuencialmente con la habilidad de agente-navegador en la sesión principal.


Fase 3 — Clasificar e iterar

Lee los failures del flujo de trabajo:

  • Vacío -> el objetivo se ha cumplido. Informa: ID/URL del despliegue, rutas verificadas, viewports, round-trip de correo electrónico demostrado + limpiado. HECHO.
  • No vacío -> para cada fallo, encuentra la causa raíz en el código fuente de web/site/, corrígelo y vuelve a la Fase 0 (verificar localmente -> confirmar -> enviar -> desplegar -> reverificar). Vuelve a ejecutar la verificación limitada primero a las rutas fallidas, luego una pasada completa una vez que estén en verde.
  • Después de 3 intentos fallidos en el mismo fallo, o ante un bloqueo de credenciales/almacén/autenticación, detente e informa como BLOQUEADO con el error exacto y lo que intentaste.

Registra cada iteración en el registro en ejecución para que el bucle sea auditable.

.vercelignore

La ubicación importa: el archivo efectivo es .vercelignore de la raíz del repositorio. Incluso si el Directorio Raíz del proyecto es web/site, se sube todo el repositorio (la compilación lee ../../src/opentraces/__init__.py y ../../skill/SKILL.md), y el único .vercelignore que la subida archivo por archivo respeta es el que está en la raíz del repositorio — los patrones se comparan de forma relativa a la raíz del repositorio. Un web/site/.vercelignore es ignorado; no agregues uno (verificado el 2026-06-26 a través de npx vercel@latest --debug).

Es una lista de ignorados positivos (directorios enumerados explícitamente, no un comodín * con negaciones ! — las negaciones son frágiles y se rompen entre versiones de CLI). Sin ella, la subida incluye los árboles pesados del repositorio. Los grandes que debe excluir (cada uno fue una filtración real que corregimos):

  • kb/ (~2.4 G), .claude/ (~1.5 G), tests/ (~1.4 G), .venv*/ (~0.8 G)
  • .otbox/ (~613 M de tarballs de instantáneas)
  • web/site/.next-test/ (~98 M / más de 1000 archivos — ten en cuenta que **/.next/ no coincide con el sufijo -test, por lo que .next-test/ necesita su propia regla)
  • web/viewer/, web/coming-soon/, web/metrics-worker/

Advertencia: .vercelignore solo filtra la ruta de subida archivo por archivo. La bandera --archive=tgz lo omite (consulta la Fase 1 — otra razón para no usarla).

Para verificar qué se subiría después de editar .vercelignore, ejecuta npx vercel@latest --debug desde la raíz del repositorio y lee la línea Encontrados N archivos … M requeridos para subir, luego Ctrl-C — no es necesario un despliegue completo. Un despliegue saludable del sitio es ~628 archivos, no ~2000.

Archivos que NO deben ser ignorados (la compilación los lee en tiempo de compilación):

ArchivoLeído porPropósito
src/opentraces/__init__.pynext.config.tsDetección de versión para version.json
skill/SKILL.mdlib/docs.ts (getSkillContent())Contenido de vista de máquina en páginas de documentación

Si agregas un nuevo archivo que el sitio lee en tiempo de compilación a través de una ruta relativa como ../../foo, asegúrate de que no esté excluido por .vercelignore.

Referencia

Rutas (matriz de Fase 2): /, /explorer, /hub, /schema, /schema/[version], /docs, /docs/[[...slug]] (~36 slugs de documentación de lib/doc-nav.ts). API: /api/waitlist (POST agregar, GET lectura de administrador), /api/stars.

Selectores del formulario de correo electrónico (EarlyAccessForm.tsx): entrada de correo electrónico input[type=email] / aria-label="dirección de correo electrónico" / .ea-input; enviar button.ea-btn ("obtener acceso temprano" -> cargando -> éxito); honeypot oculto input[name=company] (rellenarlo -> falso-éxito silencioso, nunca almacenado).

Lectura de administrador de la lista de espera: GET /api/waitlist con Authorization: Bearer $WAITLIST_ADMIN_TOKEN. Respuesta: { ok: true, count: N, emails: [...] }. Limpieza: ZREM waitlist deploy-verify-<marca de tiempo>@opentraces.ai.

Ruta de compilación de versión: src/opentraces/__init__.py > __version__ -> next.config.ts -> process.env.NEXT_PUBLIC_APP_VERSION -> version.json servido estáticamente.

Skills relacionados