Agentic QA · Skill de workflow
Saca del boilerplate el proyecto de ejemplo y lo conecta a tu app: login real, la primera entidad, variables, CI y MCPs. Al terminar, el repo está listo para escribir tests automatizados con KATA contra el sistema que vas a testear.
Decidir · 2 de 17
Usala para
No es para esto: va a
| Regenerar los mapas de dominio e infraestructura | /project-discovery |
| Escribir los tests de un sprint | /test-automation |
| Correr suites de regresión | /regression-testing |
| Documentar casos en el TMS | /test-documentation |
| Elegir la estrategia de branching | /git-flow-master |
| Editar docs/core/** o docs/assets/** | nunca: los entrega el updater |
Toca solo este repo. El repo objetivo, desde acá, es de solo lectura.
Mapa · 3 de 17
Sin escrituras
Fase 0
Prerrequisitos y genericidad
tabla GENERIC / ADAPTED
bloquea si falta contexto
Fase 1
Análisis y cuestionario
auth · OpenAPI · entidad
una sola tanda de preguntas
Fase 2
El plan
.context/reports/
Status: PENDING APPROVAL
Tu aprobación explícita del plan abre la segunda mitad
Fase 3
Identidad y variables
project.yaml · .env
variables.ts
Fase 4
OpenAPI y facades
api:sync
{entity}.types.ts
Fase 5
Auth
AuthApi · LoginPage
setups · api:login
Fase 6
Primera entidad
fixtures · smoke
borra los Example*
Fase 7
CI, manifest y MCP
workflows · kata-manifest
los tres hosts
Fase 8
Gate de validación
en orden, frena
en la primera falla
Fase 9
Escaneo y cierre
GENERIC / ADAPTED
plan en COMPLETED
Idempotencia · 4 de 17
Lo que trae el boilerplate como ejemplo
| Dominio | hotel / booking en tests/data/ |
| ATC keys | PROJ- y UPEX- en los @atc |
| URLs | localhost:3000, dojo.upexgalaxy.com |
| Componentes | ExampleApi, ExamplePage, ExampleSteps |
| Specs | module-example/ en e2e e integration |
| Reporte | Agentic QA Boilerplate en allurerc.mjs |
Cada corrida empieza igual
Corre las señales de detección de la Fase 9 antes que nada y te muestra la tabla GENERIC / ADAPTED. Lo GENERIC es el trabajo de esta corrida; lo ADAPTED se saltea.
Todo adaptado
Te dice que el framework ya está adaptado al proyecto y termina. No rehace trabajo hecho.
Plan anterior
Se retoma, no se reescribe. Si solo existe adapt-framework-plan.md (el nombre viejo de la skill), lo renombra antes de tocarlo.
Fase 0 · 5 de 17
Obligatorios: si falta uno, bloquea
| Qué tiene que existir | Quién lo genera |
|---|---|
| Mapa de business-domain-context | /project-discovery |
| Mapa de infra-context con backend y frontend | /project-discovery |
| .context/project-config.md | /project-discovery |
| Mapa de business-data-context | project-context modo data |
| Fuente del contrato de API: tipos generados, una spec alcanzable o, si no hay OpenAPI, el mapa de business-api-context | api:sync o project-context |
| .env.example | el proyecto |
Un placeholder cuenta como faltante. Un mapa se verifica por su lector: bun run context:map <slug> --list tiene que mostrar secciones.
Recomendados: pausa y propone
Los mapas de business-e2e-context y business-api-context, y el Master Test Plan. Si faltan, te propone abrir una sesión limpia, correr project-context modo refresh-all y volver.
Vos decidís
Seguir o pausar. Si seguís, cada hueco queda en la sección Discovery Gaps del plan: no arma KATA sobre suposiciones.
Fase 1 · 6 de 17
Lee
Los mapas de contexto con bun run context:map, la spec o los tipos de OpenAPI, el Master Test Plan si está, .env.example, .agents/project.yaml, config/variables.ts y las referencias KATA de test-automation. Inspecciona la superficie de ejemplo sin tocarla.
Una entidad, no todas
Elige la entidad de más tráfico según el Master Test Plan, la construye de punta a punta y deja las demás como follow-ups. No arma todo de una vez.
El cuestionario: una sola tanda, preguntas cortas
| Auth | Esquema, endpoint de login, campos del body, campo del token, TTL, header, ruta de login, roles y usuarios de prueba. |
| Identidad y entornos | Nombre, project key, dominio, stacks y la lista real de entornos con sus URLs. |
| OpenAPI y entidad | De dónde sale la spec y qué entidad va primero. |
| Base y MCP | Si hay base para validar, qué servidores usa cada entorno, qué hosts va a usar el equipo. |
| CI, reportes y docs | Modalidad de TMS, nombre del reporte Allure, GitHub Pages, y si se limpian los docs en esta corrida. |
Obstáculos en staging (verificación por email, 2FA, captcha, rate limits) sin un bypass para CI: frena y pide el bypass en vez de adivinar.
Fase 1 · 7 de 17
Sin auto-refresh
bun run api:login genera un token nuevo en cada corrida. Nada lo renueva al vencer. La skill no te va a decir lo contrario.
Lo elegís vos, en el plan
(a) Token por corrida, por defecto: se re-corre el setup cuando vence. (b) Un chequeo de vencimiento con createdAt + expiresIn, si el TTL del proyecto es corto.
Fase 2 · 8 de 17
El gate
Termina con "esperá la aprobación explícita antes de la Fase 3". Vos marcás el Approval Checklist y das el OK. Sin eso, no se escribe código.
Dónde vive
En .context/reports/, un reporte propio de la skill. Nunca en .context/PBI/: esa es la caché de solo lectura que sincroniza Jira.
Lo que vas a revisar
| Auth Strategy | La rama elegida, endpoints, forma del token, regla de refresh e indicador de login exitoso. |
| OpenAPI Strategy | Fuente, comando de sync, facades a crear y si el MCP openapi queda activo. |
| Components | Qué se crea, qué se modifica, qué se borra y la reescritura de las ATC keys. |
| Env Vars + Secrets | Claves de .env y los Secrets de GitHub que vas a cargar vos. |
| Discovery Gaps | Lo que no se pudo verificar: refresh, multi-tenant, sin OpenAPI, sin base. |
| Genericness Baseline | La foto de la tabla GENERIC / ADAPTED que esta corrida va a cerrar. |
Fase 3 · 9 de 17
.agents/project.yaml
Completa cada null: identidad, stacks, tracker y cada hoja de environments.<env>. Te ofrece bun run agents:setup para hacerlo guiado.
.env
Credenciales por entorno (<ENV>_USER_EMAIL, <ENV>_USER_PASSWORD), API_BASE_URL, OPENAPI_SPEC_PATH, TMS y base. No existe BASE_URL: las URLs viven en envDataMap. Los valores secretos los escribe la persona, en su terminal o en el gestor de secretos que nombre secrets.provider; la IA solo escribe URLs, claves de proyecto y flags, y verifica por nombre con varlock load --agent.
config/variables.ts
La mitad del proyecto: Environment, los mapas de credenciales, envDataMap (base y api) y los endpoints de auth. variables.core.ts no se toca.
La lista de entornos, una sola
Vive en varios archivos que tienen que coincidir: config/variables.ts, .agents/project.yaml, config/validateTestEnv.ts, scripts/api-login.project.ts y las opciones de los workflows. Se fija la lista real y se borran los entornos que el proyecto no corre.
Schema de entorno
.env.schema es del proyecto: declara cada variable que agregó o renombró, con @required=forEnv(<env>). .env.core.schema es del framework y no se edita. Si la app no tiene login, el par de usuario de prueba se borra.
Valida con vars:check, vars:env:check, test:env:check y vars:schema:check. Después, reiniciá la sesión: un MCP no ve un valor escrito en .env a mitad de sesión.
Fase 4 · 10 de 17
Spec
URL, GitHub o archivo local
bun run api:sync -t
Generado
api/openapi-types.ts
+ openapi.json
+ .openapi-config.json
Facade
api/schemas/{entity}.types.ts
el único que importa @openapi
Componentes
{Entity}Api, {Entity}Page
importan @schemas/…
Regla de oro
Un componente importa de @schemas/{domain}.types, nunca de @openapi. El escaneo final lo verifica con un grep sobre tests/components/.
Qué adapta
auth.types.ts al login real, un facade nuevo por entidad (copiando el patrón de example.types.ts) y el re-export en api/schemas/index.ts.
Sin spec
Primero curl a los endpoints reales, después interfaces escritas a mano. Se anota en Discovery Gaps y el MCP openapi se desactiva en los tres hosts.
Fase 5 · 11 de 17
Dos caminos que tienen que andar
| Camino | Qué se adapta |
|---|---|
| Playwright | AuthApi y LoginPage (se quedan, con locators reales y sus ATC keys pasadas a {{PROJECT_KEY}}), y los setups api-auth y ui-auth. ApiBase.buildHeaders() solo si el header no es estándar. |
| curl del agente | scripts/api-login.project.ts, el único archivo a adaptar: buildAuthPayload() y extractTokenFromResponse(). |
authenticate es el último recurso, para un login que un solo POST no expresa (OAuth, MFA, varias requests). Reemplaza la fase de request del core, así que el proyecto deja de recibir sus mejoras.
Verificación
Un 2xx, o un 4xx de la app que no sea 401, prueba el token.
La falla silenciosa
Si el token tiene otra forma y el adaptador no se tocó, .auth/tokens.env queda vacío y todo curl da 401, mientras los setups de Playwright siguen en verde.
Fase 6 · 12 de 17
Crea
tests/components/api/{Entity}Api.ts y/o tests/components/ui/{Entity}Page.ts, con sus @atc('{{PROJECT_KEY}}-NNN'), y los registra en ApiFixture, UiFixture y TestFixture con imports por alias.
Borra
ExampleApi, ExamplePage, ExampleSteps, example.types.ts, las carpetas module-example/, example.json y la línea testIgnore que ya no sirve.
Limpia
DataFactory.ts y types.ts pierden hotel y booking y ganan el dominio real. createUser, createCredentials y los tipos genéricos se quedan.
El smoke va con @critical
Es el tag que filtran los proyectos smoke de playwright.config.ts y los workflows. Con @smoke, test:smoke no seleccionaría ningún test.
Un smoke real
Usa la entidad nueva por el fixture y prueba al menos una operación de dominio completa. Sin mocks contra la auth real. Los specs de referencia con UPEX- se pasan a {{PROJECT_KEY}} si sus endpoints existen; si no, se borran.
Fase 7 · 13 de 17
kata-manifest.json
Borrar los ejemplos lo deja viejo, y el pre-commit bloquea un manifest viejo. bun run kata:manifest y después kata:manifest:check.
Workflows de suites
Opciones de entorno iguales a la lista real, nombres de secretos con el esquema por entorno, smoke en @critical. Reportes en GitHub Pages o en el portal privado: te pregunta cuál.
Secrets de GitHub
Te deja un bloque para copiar. Si gh está autenticado y aprobás, los carga desde .env con gh secret set, sin mostrar nunca un valor. TMS_PROVIDER va como Variable, no como secreto.
MCP en los tres hosts
Todo cambio entra igual en .mcp.json, opencode.jsonc y .codex/config.toml, cada uno con su sintaxis. bun run agents:compat:check lo prueba. Si falta uno, ese host pierde el servidor.
Solo servidores locales
Búsqueda web, Postman y Atlassian se conectan a nivel harness, una vez por máquina, nunca en los archivos del proyecto. Te recomienda Exa, Tavily y Context7.
dbhub.toml y allurerc.mjs
La base que corresponda (o dbhub desactivado si no hay base) y el nombre real del reporte Allure.
Fase 8 · 14 de 17
Sin auto-arreglos
Ante una falla te reporta el diagnóstico y no corrige nada sin tu aprobación.
| Síntoma | Causa |
|---|---|
| El smoke corre 0 tests | El tag no es @critical |
| La 2ª corrida vuelve a loguear | Se rompió el reuso de sesión: dependencias de proyectos en playwright.config.ts o .auth/* |
| .auth/tokens.env sin token | api-login.project.ts sin adaptar al login real |
Fase 9 · 15 de 17
Algunas señales (la tabla completa está en la referencia)
| ATC keys | Ningún @atc('PROJ- ni @atc('UPEX- en tests/components/ |
| Facades | Ningún componente importa @openapi |
| URLs | envDataMap igual a los entornos de project.yaml |
| Auth | .auth/*.json no vacíos y API_TOKEN_<ROLE>_<ENV> en tokens.env |
| MCP | Paridad en los tres hosts y harness:env:check en verde |
| Gate | bun run repo:check sale en 0 |
agent-project.md
Registra en .agents/instructions/agent-project.md la estrategia de auth, la primera entidad, la fuente de OpenAPI y los gaps abiertos. AGENTS.md no se toca: es del boilerplate y tiene presupuesto de tamaño. CLAUDE.md sigue siendo solo @AGENTS.md.
Docs del proyecto
Si lo aprobaste, limpia la identidad de ejemplo de README.md, CONTEXT.md, INSTALLER.md y las carpetas propias de docs/. Nunca docs/core/** ni docs/assets/**. Cierra con bun run docs:check.
Plan en COMPLETED
Con lo creado, lo que pasa, los gaps y los Secrets que todavía tenés que cargar.
Salvaguardas · 16 de 17
| # | Regla |
|---|---|
| A1 | Escribir antes de que apruebes el plan, o saltear el escaneo de genericidad. |
| A2 | Escribir en el repo objetivo: desde acá es de solo lectura. |
| A3 | Hardcodear credenciales. Viven en .env o en el gestor de secretos, y las tipea la persona; una variable de MCP vacía es un STOP de sesión. |
| A4 | Editar las mitades sincronizadas: config/variables.core.ts, .env.core.schema, scripts/lib/api-login-core.ts, docs/core/**. El próximo bun sync borraría el cambio. |
| A5 | Prometer un refresh de token que no existe, o probar la auth contra mocks. |
| A6 | Cambiar un MCP en un solo host, o meter un servidor remoto en los archivos del proyecto. |
| A7 | Arreglar por su cuenta una falla del gate, o cargar Secrets sin tu OK. |
Sin sobre-ingeniería: una entidad primero, auth solo lo que la app pide.
Sin adivinar: un obstáculo sin bypass frena y se pide.
Sin secretos a la vista: nombra la clave, nunca el valor.
Cierre · 17 de 17
Cómo se invoca
Claude Code: /test-framework-adaptation, o con una entidad para acotar el primer componente: /test-framework-adaptation <entidad>.
OpenCode y Codex: cargá la skill test-framework-adaptation, modo adapt.
Tiene un solo modo, adapt. También se activa con "adapt framework" o "wire fixtures".
Antes
/project-discovery: dominio, infraestructura y project-config.md.
project-context, modo refresh-all: data → e2e → api → test-plan, en una sesión limpia.
Después
/test-automation: los tests de cada ticket sobre la entidad ya cableada.
/git-flow-master: Strategy Setup si la estrategia sigue heredada.
/regression-testing: las suites en CI.
Lo que deja la skill
Un repo sin restos del ejemplo · login real en Playwright y en el curl del agente · la primera entidad con su smoke en @critical · variables, CI y MCPs alineados en los tres hosts · .context/reports/test-framework-adaptation-plan.md en COMPLETED.
Canon: .agents/skills/test-framework-adaptation/SKILL.md y references/adaptation-workflow.md, que es dueño del flujo completo de Fase 0 a 9.