/testability-guide genera dentro de la app una página pública /qa, la Software Testability Guide for QA, y arma aparte un artefacto de credenciales que se publica donde elijas. La página enseña a probar la app en las capas de base de datos, API e interfaz; el artefacto guarda los valores reales. Al volver a correrla, detecta qué cambió en el stack y parcha solo eso.
Lee el repo sin tocarlo, puntúa la testeabilidad y compara contra el snapshot.
Un solo mensaje con las preguntas que la detección no pudo responder.
La página /qa y el artefacto de credenciales, en paralelo.
Reglas de seguridad antes de publicar; tipos, build, lint y navegador después.
Por /git-flow-master. La skill nunca hace push por su cuenta.
Describe una app que ya funciona. Contra un scaffold hueco hay poco que documentar, y la skill te lo avisa antes de seguir.
Nunca se duplican. El botón de la página abre el destino de las credenciales, y el pie del artefacto vuelve a /qa.
| Página /qa (en la app) | Artefacto de credenciales | |
|---|---|---|
| Guarda | Placeholders y el procedimiento | Los valores reales y bloques .env para copiar |
| Quién lo ve | Legible para cualquiera que llegue a la página | Solo el grupo de QA, con el permiso nativo del destino |
| Responde | "Cómo testeo?" | "Qué pego?" |
| Dónde vive | En el repo, en la ruta que elijas (por defecto /qa) | Epic de Jira por defecto, o Confluence, Notion, otra herramienta, o pegado a mano. Nunca en el repo. |
Una vez que las decisiones quedan fijas, la página y el artefacto son independientes y corren en dos subagentes en paralelo. La verificación y el PR van después de los dos.
cada fase deja una entrada en .session/testability-guide/progress.md · la fase 2 la deja como skipped cuando no hay drift, para que el no-op también quede auditado
La skill guarda estado en dos lugares que resuelven problemas distintos. Confundirlos es el error más fácil de cometer.
El mismo generador corre contra proyectos muy distintos: uno con Supabase Auth y Redoc, otro con un login JWT propio y Swagger UI. Una ruta escrita a mano sale mal en la mayoría.
Framework y versión, kit de UI, iconos, tema claro/oscuro, idioma, modelo de auth (todos los que expone), endpoint de login y forma del token, UI de docs y ruta del spec OpenAPI.
Motor de base y rol de QA, archivos de config MCP por agente, cómo se activa el .env, repos mono o poly, rama por defecto y de dónde sale el SHA del deploy.
Leer .env ni archivos de credenciales. Del .env.example enumera nombres de variables, nunca valores.
Instalar nada, levantar el dev server ni correr la suite: eso es la fase 8.
Un párrafo corto que alimenta el snapshot, el objeto qaConfig de la página y el diff de idempotencia.
Lo que no se detectó queda como hueco explícito (<detected: none>), y la página dice "pregúntale a tu lead". Nunca un valor inventado.
Puntúa tres capas. La página se construye igual con cualquier puntaje; lo que cambia es la bandera y la recomendación que te llevas.
| Capa | Testeable cuando… | Si falta |
|---|---|---|
| UI | Los flujos críticos (login como mínimo) tienen selectores estables, data-testid o rol. | Bandera y recomendación de una convención de selectores. |
| API | Hay un camino programático a un token para Authorization: Bearer, con expiración, y un contrato descubrible. | Bandera alta. Recomienda un login normal con contraseña más un endpoint que emita un token con expiración. |
| DB | Existe un rol de QA de solo lectura para inspeccionar sin la app en el medio. | Bandera. Si solo hay un superusuario, la corrida se detiene (ver seguridad). |
Si /qa ya existe, la IA lee el snapshot, repite el discovery y compara campo por campo. Te muestra el diff antes de tocar nada.
/* qa-guide-snapshot skill-version=… stack=… ui-kit=… auth-method=… docs-route=… openapi-spec=… db=… repos-shape=… mcp-config-files=… page-features=… language=… publisher=… credentials-source=… default-branch=… build-sha-source=… testability=… generated=… content-hash=… */
forma del comentario, con los valores omitidos · la lista canónica de campos vive en references/idempotency-snapshot.md
| Resultado del diff | Qué pasa |
|---|---|
| No-op | Solo cambió la fecha o una versión menor. Reporta "está al día" y sale. |
| Parche quirúrgico | Cambió un campo que afecta código (stack, auth, base, idioma…). Se regeneran solo las secciones que ese campo maneja; el resto queda byte a byte igual. |
| Solo re-publicar | Cambió el destino de las credenciales; la página no se toca. |
| Mejora de página | La página es de una versión más plana (sin resaltado, sin tarjetas de request). Te la ofrece; nunca la aplica sola. |
| Re-scaffold completo | Salto mayor en skill-version o tres o más campos de código movidos a la vez. Solo con tu OK, y guarda una copia de la página anterior. |
Las preguntas llegan juntas, cada una con su default y su costo. Puedes contestar "todo por defecto". Lo que ya dijiste en tu pedido inicial queda fijado y no se vuelve a preguntar.
| Pregunta | Default | Lo que hay que saber |
|---|---|---|
| Q1 · destino de credenciales | Epic de Jira | El cuerpo es portable: cambiar de destino después es barato. |
| Q2 · rol de base para testers | Rol qa_* de solo lectura | Las escrituras pasan por la API. Un superusuario se rechaza siempre. |
| Q3 · ruta de la página | /qa | Salvo que choque con la arquitectura de rutas del host. |
| Q4 · redirect de una ruta vieja | Sí, si hay una página hermana | Redirect del lado del servidor; la ruta vieja sigue viva un ciclo de release. Sin hermana, se saltea. |
| Q5 · idioma del texto visible | El del host | Sigue la señal de idioma de la app. Identificadores y data-testid quedan en inglés. |
| Q6 · resaltado de código | Pre-respondidas por la detección | Reusa el del host; si no hay, Shiki del lado del servidor. |
| Q7 · driver de UI para agentes | playwright-cli si su skill está; el MCP de Playwright como alternativa. | |
| Q8 · visor de requests | Tarjetas estilo Postman; bloques curl si el kit no puede. |
Layout propio con índice fijo y hero, no una lista de acordeones. Todo valor que la página muestra sale de qaConfig, el puente entre la detección y el render.
Lo primero que ve un tester: un botón que abre el destino de las credenciales en otra pestaña. Sin destino detectado, un hueco y ningún botón.
Frontend → API → base con el stack detectado, la capa MCP debajo, y los repos oficiales (uno si es monorepo, dos si es polyrepo).
UI + API + DB, y cómo se cargan las variables: el agente abre sin ellas, cada MCP lee su .env al arrancar y un comando que necesita un valor corre con bunx varlock run. Si una no carga, el MCP devuelve 401/403 y hay que salir, corregir y volver a entrar.
El MCP de base o una URI para la extensión SQL del editor, con el mismo rol de solo lectura. El MCP sale del bloque stack: de .agents/project.yaml: DBHub por defecto, y una app Supabase suma además la pestaña del MCP de Supabase, también de solo lectura. Roles, columnas revocadas o la prueba de RLS, solo si el proyecto los tiene.
Las requests de auth reales del proyecto, el MCP de OpenAPI o el de Postman, y el link a la UI de docs detectada. El MCP de OpenAPI solo lista endpoints y lee sus esquemas: las requests con auth corren con curl y el token personal de cada tester. Sin camino a un token, lo dice: nunca inventa un endpoint.
Un fixture que puentea UI y API según la forma del auth detectada, y el recetario de playwright-cli para exploración con agentes.
Usuarios demo, tabla de endpoints sacada del spec y los errores más comunes.
Bajo el subtítulo, la página muestra el SHA corto del commit desplegado, con link al commit cuando hay un repo detectado. Un hallazgo queda atado a un commit, y "ya está mi fix?" se contesta en la misma página.
En runtime, en el servidor, desde la variable de plataforma cuyo nombre anotó la detección en qaConfig.build. En Vercel es VERCEL_GIT_COMMIT_SHA.
Escribir el SHA en el código de /qa: quedaría viejo en el próximo deploy.
Mostrar otras variables de plataforma al lado (mensaje del commit, autor, secretos).
En local, o en un deploy sin metadata de git, el mismo nodo muestra una línea visible: build local, sin SHA de despliegue.
El nodo qa-build-sha siempre está, con el SHA completo en data-sha (vacío en el fallback), para que la automatización lo lea.
El cuerpo markdown de references/credentials-content-template.md es la única fuente de verdad. Cada destino es un adaptador fino que cambia el envoltorio, nunca el contenido.
| Destino (Q1) | Herramienta | Detalle |
|---|---|---|
| Epic de Jira (default) | /acli | Markdown → ADF con el conversor de la skill acli; cada snippet sale con botón de copiar. Las tablas se arman a mano y se verifican leyendo el Epic de vuelta. |
| Página de Confluence | /acli o el MCP de Atlassian | Restricción de página al grupo de QA. |
| Página de Notion | MCP de Notion si está | Compartida solo con personas puntuales. |
| Otra herramienta con MCP o CLI | El MCP o la CLI detectados | Por ejemplo un gestor de secretos o una wiki interna. |
| Pegado a mano | Ninguna | Te entrega el cuerpo y los pasos; tú le devuelves la URL final. Avisa si la URL parece pública. |
Corre antes de cualquier llamada de publicación y aplica a todos los adaptadores: ninguno puede saltearla. Si un punto no se cumple, no se publica.
al final de cada corrida queda un rastro de auditoría: destino, URL del artefacto, ruta, si se rechazó un superusuario, si hace falta rotar y las banderas de testeabilidad
"Terminado" quiere decir que pasó cada chequeo de references/verification-checklist.md. Si uno falla, se arregla y se vuelve a empezar desde el primero.
Con los scripts que declare el package.json del host, nunca uno supuesto. Las reglas de lint no se apagan: se corrige la página.
Con /playwright-cli contra el dev server: carga, título, sello de build, el botón abre el destino en otra pestaña, los bloques de código, el redirect si lo hubo, y una captura para el PR.
Esto lo confirma una persona: snippets con botón de copiar, acceso cerrado y el link de vuelta a /qa.
Ni contraseñas, ni tokens, ni hostnames privados, ni un SHA literal dentro de app/qa/.
El placeholder del hash ya se reemplazó por el real. Y las preguntas de cierre: leyó el código antes de escribir?, las credenciales arriba de todo?, el PR contra la rama por defecto detectada?
Se delegan a /git-flow-master con el nombre de rama, los mensajes de commit y el título del PR. La skill nunca hace push, ni abre el PR, ni toca ramas por su cuenta.
Si algo puede ir directo a una rama protegida no lo decide esta skill: lo resuelve /git-flow-master con git_strategy.policy.direct_push_to_protected de .agents/project.yaml.
La sesión se archiva en .session/.archive/. El snapshot queda en la página: es la señal para la próxima corrida.
El orden de lectura para una IA que arranca en frío. Corta antes cuando la corrida es chica, por ejemplo un no-op del snapshot.
| Archivo | Para qué |
|---|---|
| .agents/project.yaml | Identidad del proyecto, URLs de entornos, repos, clave de Jira. |
| .mcp.json | Qué servidores MCP hay: decide qué destinos de publicación están al alcance. |
| La página /qa existente | Su snapshot, para el chequeo de drift. |
| El contrato del destino | Depende de Q1: el adaptador en references/publishers/. |
| .env.example | Los nombres de las variables que el artefacto referencia. Nunca los valores. |
Los antipatrones completos viven en SKILL.md y viajan en el registro compacto que reciben los subagentes (.agents/skills/REGISTRY.md).
Esta skill no tiene modos con nombre: la misma invocación crea la página la primera vez y la actualiza las siguientes. Nombras la skill y dices qué quieres, en español o en inglés.
La barra carga la skill; el resto de la frase adelanta respuestas.
Sin barra: nombras la skill en la frase.
Mismo patrón que OpenCode, CLI o Desktop.
Deja la app montada; esta skill corre después. También es la dueña de los arreglos de testeabilidad de infraestructura, como un endpoint de token. Deck: Project bootstrap.
Un bug que QA encuentra en la propia página se vuelve una historia normal. También recibe los arreglos de testeabilidad a nivel feature.
Registra /qa como página operativa interna, que no necesita cobertura en el PRD.
Suma la página y la ubicación del artefacto a las rutas clave de .agents/instructions/agent-project.md, para que otras skills sepan que existen.
Uno lleva el commit y el PR; el otro publica el Epic de credenciales cuando ese es el destino.