Agentic QA · Evolución del framework

/framework-development
cambiar el boilerplate con un plan aprobado

Para quien mantiene el framework: un cambio a las bases KATA, a las fixtures, a cli/, a scripts/ o al pipeline de api/schemas/ pasa primero por un plan que vos aprobás, después por código, después por cuatro verificaciones, y cierra con la documentación al día en el mismo PR.

Plan → Code → Verify → Archive Solo la superficie del framework Docs en el mismo PR

Audiencia: maintainers del boilerplate y usuarios avanzados que extienden el framework. La skill existe porque un cambio de superficie (una fixture nueva, un helper de capa, una reescritura del instalador, un extractor del manifest) merece una puerta de planificación antes del código. Es la contraparte arquitectónica del Plan → Code → Review de /test-automation. Pulsá → para avanzar, S para modo presentador, O para overview, F para pantalla completa.

Alcance · 2 de 17

Le toca a esta skill o a otra?

Sí: cambia el framework

Una fixture API nueva o un cambio de firma en ApiFixture / UiFixture / TestFixture

Refactor de las bases KATA: TestContext, ApiBase, UiBase

El instalador y el tooling de cli/, los scripts de scripts/

El pipeline OpenAPI (scripts/sync-openapi.ts), dependencias y scripts de package.json

Doctrina compartida en agentic-qa-core/references/ o una skill nueva del repo

Editar AGENTS.md, una sección de .agents/instructions/, el ROUTER o sus triggers:: modo instructions (references/instructions-doctrine.md)

"Sync AI context": poner los docs al día después de un cambio del boilerplate

No: lo hace otra skill

Pedido	Dueña
Escribir tests de un ticket	`/test-automation`
QA manual de un ticket	`/sprint-testing`
Documentar casos en el TMS	`/test-documentation`
Correr suites de regresión	`/regression-testing`
Context skills de un proyecto consumidor	`project-context`, modo `context-skill`
Docs propios de un proyecto downstream	`test-framework-adaptation`, Fase 9.3

La primera regla de la skill: nada de trabajo por ticket. Gobierna solo la superficie arquitectónica. Si un pedido mezcla las dos cosas (por ejemplo, cambiar UiBase y además migrar los specs que lo usan), se parte en dos: esta skill cambia la base y /test-automation migra los specs en un PR siguiente.

Flujo · 3 de 17

Cada fase habilita la siguiente

Camino principal

Preflight

Toolchain listo

test · types · lint
skills · manifest

→

Fase 0 · inline

Rutas + resume

kata-invariants §10
resume / restart / abort

→

Fase 1 · Single

Plan

plan.md
vos lo aprobás

→

Fase 2 · Sequential

Code por lotes

progress.md
solo el orquestador

→

Fase 3 · Parallel

Verify ×4

+ docs follow-through

→

Fase 4 · inline

Un preflight de toolchain, no de entorno

Capacidad	Necesidad	Por qué
Toolchain de desarrollo	REQUIRED	La Fase 3 corre `bun run test`, `bun run types:check`, `bun run lint:check` y `bun run skills:check`: los cuatro tienen que resolver desde el arranque.
`kata-manifest.json` limpio	REQUIRED	Fuente de verdad de componentes y ATCs (Critical Rule #12). `bun run kata:manifest:check` para verificar, `bun run kata:manifest` para regenerar.
Navegadores de Playwright	SCOPE	Solo si el cambio toca fixtures, bases KATA o tests: la verificación corre la suite (`bun run pw:install`).
`/github-actions-docs` · `/playwright-best-practices`	OPTIONAL	Se inyectan en el briefing cuando el cambio toca YAML de CI o fixtures y tests.

N/A en esta skill

Entorno, credenciales, API, DB, tracker, TMS: es meta-trabajo sobre este repo, sin sistemas vivos.

Cómo te lo muestra

Huecos y rojos llegan juntos, en un solo checklist. Se arregla con tu aprobación; un rojo bloqueante para todo.

Las dos leyes del preflight (preflight-gate.md): los argumentos son respuestas (el nombre del cambio y las rutas ya dadas no se vuelven a preguntar) y se prueba, no se supone. La mitad de entorno y credenciales de la base genérica no aplica a esta skill.

Fase 0 · 5 de 17

Primero, qué rutas toca?

Path self-check contra kata-invariants.md §10

Resultado	Qué pasa
ALLOWED	Sigue: `cli/`, `scripts/`, `tests/utils/`, bases y fixtures.
FORBIDDEN	Aborta y deriva a la skill de la fila: `tests/e2e/` a `/test-automation`, `.context/PBI/` a `/sprint-testing`.
Ninguna tabla	La IA te pregunta. Nunca supone.
Las dos	Se parte: acá el framework, después la dueña de la fila prohibida.

Tablas completas: kata-invariants.md §10.

Resume check

Busca .session/framework-development/<change-name>/progress.md. Si existe, te muestra el objetivo del plan, la última fase completa, la siguiente y las notas bloqueantes, y te da tres opciones: resume, restart (archiva lo anterior con sufijo -aborted) o abort.

Desde un worktree

La sesión se busca en el checkout principal: mirar solo el .session/ del worktree no encuentra nada y reinicia en silencio trabajo ya hecho.

Tablas completas en .agents/skills/framework-development/references/kata-invariants.md §10; ahí también están la estructura de .agents/, tests/integration/ y los artefactos generados, que se regeneran y no se editan. La Fase 0 no escribe archivos: es una decisión corta e inline y su resultado queda en la sección Investigation del plan.md. Saltarse la Fase 0 es la forma más común de que un cambio de framework se filtre a superficie de tickets, o de perder estado a mitad de camino. El scope de sesión es el change-name en kebab-case que das al arrancar.

Fase 1 · 6 de 17

Un solo `plan.md`, y lo aprobás vos

Qué hace la IA

Un subagente de Plan escribe un único artefacto en .session/framework-development/<change-name>/plan.md. Reúne lo que antes eran exploración, propuesta, spec, diseño y tareas.

Qué decidís vos

La IA te presenta el plan y espera tu aprobación antes de la Fase 2. Sin ese OK no se escribe código.

Dónde vive

.session/ está en el gitignore: el plan es local, no se commitea. Si la sesión se corta, el archivo persiste y la Fase 0 lo levanta.

Secciones propias de esta skill

Invariants touched: qué reglas INVARIANT de KATA roza el cambio.

Public API delta: qué cambia en la superficie que usan los tests.

Strict TDD flag: apagado por defecto. Se prende solo si lo pediste; entonces cada tarea de código va precedida por un test que falla, en el mismo lote.

Se suman a las secciones base del schema de agentic-qa-core/references/session-management.md §6 (Goal, Investigation, Task breakdown, Risks, Verification checklist y el resto).

Si el cambio ES una skill

El Task breakdown sigue skill-scaffold.md §2 para su tipo y el checklist incluye su Definition of Done (slide 12).

Un archivo, no cinco documentos separados. "Invariants touched" y "Public API delta" son las mejores candidatas a ADR (slide siguiente). El briefing de cada subagente de Plan y de Code lleva siempre la línea que apunta a kata-invariants.md §10, sin copiar las tablas: la referencia es la autoridad.

Tras aprobar el plan · 7 de 17

Las decisiones que atan, por escrito

Cuándo hay ADR: las dos puertas

1 · Arquitectura de test. El enfoque rehace capas KATA, una fixture API, el runner, el modelo de aislamiento y paralelismo, o el pipeline OpenAPI y de tipos.

2 · Difícil de revertir. Si se puede deshacer barato, no hace falta ADR.

Test de las dos puertas: agentic-qa-core/references/adr-doctrine.md §1.

Por qué

Una decisión de framework ata a cada sesión de test que viene después. Si queda solo en un plan.md archivado, se vuelve a discutir o se viola sin que nadie lo note.

Cuándo y cómo

Se escribe en .context/ADR/ADR-NNNN-<slug>.md después de aprobar el plan y antes de codificar.

Estado

Tu aprobación del plan ya es la decisión, así que el ADR nace Accepted y su línea Deciders la cita. La IA no te pide que lo "aceptes" otra vez. Proposed queda solo para una parte que sigue abierta, y el ADR dice cuál.

Append-only

Un ADR no se reescribe ni se borra: un ADR nuevo lo reemplaza. Plantilla y ciclo de vida: .context/ADR/README.md.

Fuentes: framework-development/SKILL.md (Compact Rules, Phase 1 ADR seeding, F8) y adr-doctrine.md (paso 4 y A4). No es ADR un fix de un test flaky, un ajuste local de un spec ni un nombre.

Fase 2 · 8 de 17

Código en lotes, uno detrás del otro

Lotes

Salen de la lista de tareas del plan: 3 a 5 tareas acopladas por lote, o una sola cuando toca un archivo de carga (ApiBase.ts, UiBase.ts, TestContext.ts).

Cada subagente de Code

Aplica sus tareas en orden, corre la verificación de cada una y devuelve una línea por tarea. Si algo falla: para y reporta. Nunca se auto-arregla.

progress.md

Solo el orquestador, una entrada por lote. No lee los diffs de los subagentes: si querés verlos, corre git diff.

Ola de workers (opcional)

Cuándo: los lotes del plan son de verdad independientes (archivos distintos, ninguna API pública compartida en vuelo). Se te ofrece; nunca se entra en silencio.

Propiedad de archivos: cada worker tiene su lista exacta y commitea con rutas explícitas. Dos lotes sobre un mismo módulo no comparten ola.

launch.txt: una línea autosuficiente por worker, siempre. Lanzarlas y supervisarlas es orca-orchestration; sin él, una persona las pega a mano.

Fase 0 y Fase 3 siguen con el conductor: el path self-check corre una vez sobre la unión de rutas; los cuatro verificadores, una vez sobre el árbol integrado. Un verde por worker no es verde de la ola.

Dos lotes sobre el mismo módulo se serializan, o cada uno va a su propio worktree. Leer antes de cada edición: un vecino puede haber cambiado un archivo compartido desde que se escribió el brief. La Critical Rule #15 (nada de descartes globales) pesa el doble cuando varias sesiones comparten árbol.

Fase 3 · 9 de 17

Cuatro verificadores, en paralelo

#	Comando	Qué protege
V1	bun run test	La suite: que el cambio no rompa ningún test.
V2	bun run types:check	Los tipos de todo el repo.
V3	bun run lint:check	ESLint, con los bloques de imports (slide 14).
V4	bun run skills:check	Lint de skills: cubre `.agents/skills/`, `AGENTS.md` y `cli/install.ts`, que los otros tres no miran.

Los cuatro salen con código 0. Sigue el docs follow-through y después la Fase 4.

REJECT

Uno distinto de 0: elegís retry del lote, skip-and-document o abort. Sin auto-fix y sin archivar.

Si la que se rompió es una skill, se reporta upstream (upstream-feedback.md): borrador local redactado, se abre solo con tu OK y se verifica con gh issue view.

Una skill rota es un paso equivocado, un verificador que falta o una regla vieja. En el propio boilerplate no hay issue: se arregla directamente con esta skill. El cuarto verificador cuesta un slot paralelo y evita una clase entera de fallas. El orquestador agrega los cuatro reportes inline y decide. Para el PR, bun run repo:check agrupa además docs:check, agents:compat:check y kata:manifest:check (la lista exacta está en package.json).

Cierre de la Fase 3 · 10 de 17

"Sync AI context": la doc viaja en el mismo PR

Cuándo

El cambio agrega, renombra o retira una skill, un script de package.json o una ruta de doc, o cambia un comportamiento que alguna página describe.

Qué se toca

.agents/instructions/agent-context-map.md y agent-skills-and-mcps.md, README.md, INSTALLER.md, CONTEXT.md, docs/core/, los decks y la home de Pages, en el mismo PR.

Sin listas copiadas

Las páginas humanas apuntan a .agents/skills/REGISTRY.md y nunca enumeran las skills (Rule #17).

Qué prueba bun run docs:check

Cada skill del repo tiene su fila en el router de .agents/instructions/agent-skills-and-mcps.md.

Cada bun run <script> citado en AGENTS.md, en sus secciones de .agents/instructions/ o en los docs existe en package.json.

Cada link relativo y cada ruta citada existe, también los links markdown de .agents/, .context/ y .claude/.

Sin citas archivo:línea ni afirmaciones sobre el presente (Rule #17).

La prosa sigue siendo juicio, con dos ayudas. Una región de código marcada con LINT.IfChange nombra sus páginas: tocarla sin tocarlas bloquea el push y el CI, salvo un commit con Docs-Checked: <label> <motivo> (ADR-0016). Y si el cambio toca cli/, scripts/, .husky/ o las instrucciones, un quinto verificador (V5, solo reporta) busca en los docs la prosa que describe el comportamiento viejo.

Docs de un proyecto downstream: test-framework-adaptation, Fase 9.3.

.agents/instructions/agent-context-map.md rutea "sync AI context" / "sync AI memory" a /framework-development cuando el cambio es del boilerplate. docs:check corre dentro de bun run repo:check, en cada push y en CI.

Fase 4 · 11 de 17

Cerrar el ciclo, no publicar

Lo que hace el orquestador, inline

1. Confirma que el Verification checklist del plan pasa: los cuatro verificadores en 0.

2. Mueve el directorio entero a .session/.archive/<YYYY-MM-DD>-framework-development-<change-name>/, con plan.md y progress.md lado a lado.

3. Guarda el resumen de sesión en Engram con la ruta del archivo, para que una búsqueda posterior llegue a los artefactos.

4. Te da esa ruta para que /git-flow-master la cite en el cuerpo del commit.

Con REJECT no hay Archive

El directorio queda donde está para depurar, retomar o abortar.

Cierre de sesión

En el chat, nunca en Jira: la lista de capturas con rutas verificadas y el footer con skills, MCPs y CLIs usados y los niveles de testing tocados, con "none" explícito donde no hubo (session-footer-contract.md).

Lecciones

Lo aprendido se propone en refinements.md dentro del scope; nunca se aplica a una skill viva sin tu OK (skill-refinement-protocol.md).

El código lo publica /git-flow-master a partir del diff de la Fase 2 verificado en la Fase 3. Archive cierra el ciclo; no es el paso de entrega. Se conservan los dos archivos como directorio (no concatenados) para poder rebobinar a una fase completa en el futuro.

Caso especial · 12 de 17

Cuando el cambio es una skill

El constructor: skill-creator

Siempre. Es una skill de comunidad (T3) que cli/install.ts instala a nivel proyecto. Se carga para el borrador, los prompts de prueba, los evals y la pasada de descripción.

El contrato: este repo

Frontmatter con metadata.kind, archivos y secciones por tipo, Definition of Done: agentic-qa-core/references/skill-scaffold.md. skill-creator no es dueño de ese contrato.

Si falta en la máquina

Se arma desde la plantilla de la referencia y la IA te lo dice.

Definition of Done (skill-scaffold.md §5)

bun run skills:check en verde: tipo declarado, sufijo coherente, sin rutas viejas.

bun run skills:registry regenerado y bun run skills:registry:check en verde.

Fila en .agents/instructions/agent-skills-and-mcps.md (solo T1) y un cargador: qué flujo la carga y cuándo.

evals/evals.json para una skill de tipo workflow.

Las context skills de un proyecto consumidor no pasan por acá: las crea project-context, modo context-skill, con el mismo constructor.

El docs follow-through de la slide 10 aplica también: una skill nueva necesita su fila en el router de .agents/instructions/agent-skills-and-mcps.md, y docs:check falla si falta.

La referencia de la skill · 13 de 17

Qué se puede extender y qué no se toca

KATA organiza la automatización en cuatro capas con una sola dirección de dependencia: TestContext, Base, domain Components y Fixtures. Steps es una capa intermedia opcional entre Components y Fixtures. Los archivos de test consumen las Fixtures: no son una capa.

INVARIANT: romperlo pide versión mayor

Agregar una capa nueva entre las existentes: prohibido.

Colapsar capas "por simplicidad": prohibido. Son arquitectura, no abstracción especulativa.

La regla de fixtures ({ api } · { ui } · { test }), la identidad del ATC, el alcance DRY, los alias de import, la forma de las tuplas HTTP.

EXTENSIBLE: lista explícita

Utilidades agnósticas en tests/utils/, helpers reutilizables en ApiBase / UiBase.

Una fixture API nueva: el archivo de fixture, kata-manifest.json y al menos un test que la use.

Scripts con su entrada en package.json, facades OpenAPI, alias nuevos en tsconfig.base.json.

Matriz "si cambiás X, verificá Y", tablas completas y lo que esta skill no puede tocar: .agents/skills/framework-development/references/kata-invariants.md.

Fuente: kata-invariants.md, fórmula canónica y secciones 1 a 8. Nunca se publica un número de capas suelto: la forma corta es "cuatro capas con nombre, más Steps opcional". Desde esta skill nunca se editan los componentes de módulo en tests/components/ (Page, Api, Steps por ticket): son de /test-automation. Una fixture huérfana se pudre, y el manifest es la puerta anti-duplicación.

.agents/instructions/agent-harnesses.md · 14 de 17

`cli/` no importa nada de afuera

La regla

Nada bajo cli/ importa de un directorio hermano de la raíz: ni scripts/, ni config/, ni tests/, ni api/, ni packages/, tampoco a través de un alias.

Por qué

cli/ es el componente que se auto-actualiza: bun sync refresca esos archivos y re-ejecuta el proceso antes de sincronizar el resto. El cli/ nuevo corre contra la copia vieja de todo lo demás. Un import que escapa rompe bun sync al cargar el módulo, y con él el rollback, bun setup y bun run setup:doctor.

Dónde va lo compartido

En cli/lib/. Si un script de scripts/ lo necesita, importa desde cli/: esa dirección es segura porque scripts/ se sincroniza después y nunca se re-ejecuta a mitad de corrida.

Quién lo hace cumplir

El bloque CLI_IMPORT_CLOSURE de eslint.config.base.js, así que bun run lint:check lo atrapa en CI, en pre-push y en bun run repo:check. Al lado vive KATA_IMPORT_ALIASES, que prohíbe ./ y ../ bajo tests/.

Fuentes: .agents/instructions/agent-harnesses.md (cli/ IS IMPORT-CLOSED; root configs ship in halves) y la regla F7 de la skill: refactorizar cli/install.ts exige probar la instalación completa en un clon limpio, porque verificar en un repo ya instalado no prueba nada. Como eslint.config.js es del proyecto y no se sobrescribe, validateEslintBlockWiring hace fallar agents:compat:check cuando un bloque exportado por la base no está cableado en el consumidor.

Lo que nunca hace · 15 de 17

Los rieles que te protegen

Regla	Nunca	Por qué te importa
F1 · F3	Trabajo por ticket ni componentes de módulo en `tests/components/`	esa superficie es de `/test-automation`
F2	Colapsar las capas KATA	rompe la cadena que asume cada componente
F4	Saltear el pipeline en un "refactor rápido"	es la vía más segura a una regresión sin detectar
F5	Subir de versión mayor Playwright, Bun o TypeScript sin una corrida de regresión E2E	los upgrades juntos esconden roturas de fixtures, locators y tipos
F6	Una fixture API sin su archivo de fixture, `kata-manifest.json` y un test que la use	una fixture huérfana se pudre
F7	Tocar `cli/install.ts` sin probar en un clon limpio	un bug ahí llega en silencio a cada usuario nuevo
F8	Una decisión de arquitectura difícil de revertir sin ADR	se re-discute o se viola sin aviso

Critical Rules en las que se apoya: #2, #7, #12, #15 y #17. Tampoco edita artefactos generados (api/openapi-types.ts, kata-manifest.json, reports/) ni credenciales.

Critical Rules: #2 plan antes de código, #7 tests → types → lint, #12 manifest como fuente de verdad, #15 sin descartes globales, #17 la prosa nombra al dueño y no copia su valor. Fuente: sección "Anti-patterns" de la SKILL.md (F1 a F8), Compact Rules y kata-invariants.md §9. Ante un fallo de subagente: STOP, reportar, sin re-ejecutar solo; vos decidís retry, skip o abort.

Qué lee y qué escribe · 16 de 17

Entradas, salidas y sus dueños

Lee, en este orden

kata-manifest.json: qué existe antes de proponer algo nuevo

kata-architecture.md y typescript-patterns.md (de test-automation)

tests/components/: forma de Api, Page y Steps

cli/install.ts: si toca el instalador

scripts/sync-openapi.ts y api/schemas/: pipeline de tipos

package.json y el lockfile: antes de tocar versiones o scripts

Escribe

Qué	Dónde
Plan, progreso y archivo	`.session/` (local)
ADR, cuando aplica	`.context/ADR/`
El cambio	solo rutas ALLOWED de `kata-invariants.md` §10
La doc	`.agents/instructions/` (`agent-context-map.md`, `agent-skills-and-mcps.md`), `README.md`, `INSTALLER.md`, `CONTEXT.md`, `docs/core/`

Lo generado se regenera con su comando (bun run kata:manifest, bun run api:sync).

El orden de lectura corta antes cuando el cambio es chico. Fuente: sección Inputs de la SKILL.md y kata-invariants.md §9 y §10. El estado de sesión vive en el checkout principal aunque la sesión corra en un worktree.

Cierre · 17 de 17

Invocación y handoffs

Cómo se invoca

Claude Code: /framework-development.
OpenCode y Codex: cargá la skill framework-development.

Modo por defecto: le das un <change-name> en kebab-case al arrancar. Modo instructions: cualquier edición de AGENTS.md, una sección, el ROUTER o los triggers. También la activan "evolve framework", "refactor cli", "sync AI context".

Antes y después

Después del Archive: /git-flow-master commitea y abre el PR.
Si hubo split: /test-automation migra los specs consumidores.
Ola opcional: orca-orchestration.
Doctrina compartida: agentic-qa-core (sus references/).

Dónde leer más

En .agents/skills/framework-development/: SKILL.md y kata-invariants.md.
En agentic-qa-core/references/: session-management.md, skill-scaffold.md, adr-doctrine.md.

La idea que ordena todo

El framework es el piso de cada test: un cambio ahí pasa por tu aprobación del plan, cuatro verificaciones y la doc en el mismo PR. Si algo falla, la IA para y te pregunta.

Inventario de skills: .agents/skills/REGISTRY.md. El canon de esta skill es su propia SKILL.md.

Fin del recorrido. Para el flujo de tests por ticket, seguí al deck de /test-automation.

/framework-developmentcambiar el boilerplate con un plan aprobado