Empezar aquí

La idea en dos minutos

Este repositorio es una máquina de QA que trabaja con un agente de IA. Tú traes el proyecto bajo prueba (el target: un frontend, un backend o ambos) y el boilerplate pone las instrucciones, la capa de conocimiento y las herramientas que el agente usa para planificar pruebas, ejecutarlas, reportar bugs, automatizar y emitir un veredicto de release. Entre cada etapa hay un checkpoint humano: el agente propone y tú apruebas.

Todo lo que puedes invocar pertenece a una de tres categorías:

Las tres comparten el mismo combustible: las variables de .agents/project.yaml (nombre del proyecto, URLs por entorno, clave de Jira) y los catálogos de Jira en .agents/. El agente los lee al empezar la sesión y resuelve los placeholders {{VAR}} antes de actuar.

Instalación

Prerequisitos

El instalador se diagnostica solo y te dice qué falta, pero ahorras una vuelta si instalas antes lo que bloquea.

En Windows funcionan PowerShell y cmd sin WSL. Instala Bun con powershell -c "irm bun.sh/install.ps1 | iex", no con npm i -g bun.

Tres formas de empezar

# Camino recomendado
bunx create-agentic-qa@latest mi-proyecto-qa
cd mi-proyecto-qa

# Camino "Use this template" (después de crear el repo en GitHub)
git clone https://github.com/<tu-org>/<tu-repo>.git
cd <tu-repo>
bun install
bun setup

Si usas la plantilla de GitHub, renombra el proyecto en package.json (name) y en .agents/project.yaml (project.project_name).

Qué hace bun setup

Si tu terminal tiene pantalla, la corrida se ve en una página local que se abre sola (dentro de Orca, como una pestaña de su navegador). Cada pregunta es una tarjeta, y la terminal sigue mostrando el log completo. Con bun setup --headless todo pasa en la terminal, igual que en CI, sin TTY, cuando la lanza un agente o por SSH sin pantalla; --ui abre la página aunque esas reglas digan terminal. Si ninguna página se conecta a los pocos segundos, las preguntas vuelven a la terminal. Los flags y las reglas completas están en bun setup --help.

Es idempotente: cada paso guarda una marca en .template/installer.state.json en cuanto termina, así que una corrida interrumpida sigue donde quedó y una segunda ejecución salta lo que ya terminó. Con --non-interactive (o sin TTY) cada pregunta toma su valor por defecto.

1. Preflight

   Antes de preguntar o escribir nada revisa la máquina: las herramientas, que haya al menos un agente, la carpeta del proyecto, la red y el disco. Cada fila sale como ok, aviso o bloqueo. Un bloqueo frena la corrida sin tocar nada (en la página, con un botón "Volver a comprobar"); que falte acli o engram es solo un aviso. Si faltan las dependencias, corre bun install por su cuenta. Cierra con una única confirmación para empezar.

2. Tu equipo

   Qué agentes soporta el proyecto: Claude Code, OpenCode o Codex. Tu elección queda en harnesses: (.agents/project.yaml) y te ofrece borrar los archivos de los que dejaste fuera (por defecto los conserva). Aquí eliges también los skills de nivel usuario, una casilla por skill: el que desmarcas queda registrado como rechazado y no se vuelve a ofrecer. También pregunta si conectar el plugin de Engram.

3. Instalación en segundo plano

   Arranca en cuanto respondes Tu equipo: dependencias, los navegadores de Playwright, Engram con engram setup en cada agente elegido, los skills de la comunidad y la reparación de compatibilidad. No pregunta nada; las fases siguientes se responden mientras descarga.

4. Tu proyecto

   La identidad y los entornos de .agents/project.yaml (lo que hacía agents:setup). El ejemplo aparece como pista dentro del campo y nunca se escribe como valor.

5. Credenciales

   Dónde viven los secretos: .env (por defecto) o un gestor (1Password, opción avanzada). Luego las variables que usan los MCPs y las credenciales de Atlassian. Un secreto que escribes en la página va enmascarado y solo llega a .env.

6. Jira

   Autentica acli, sincroniza los catálogos (tu workspace, el estándar de UPEX-Galaxy o saltarlo), te deja elegir los estados y transiciones del workflow que no se resuelven solos y valida con jira:check. Si el login falla, una tarjeta dice qué pasó y te deja reintentar.

7. GitHub

   Opcional: crea el repo con gh y hace el push cuando termina la instalación en segundo plano.

8. Verificación

   Una tabla con los CLIs externos, solo informativa: cuáles están y cómo instalar los que faltan. Además retira las copias en texto plano de credenciales MCP que dejó una versión anterior (ver la sección siguiente).

9. Listo

   Una tarjeta de reporte con lo hecho, lo saltado o con aviso, los errores y el tiempo, y debajo los próximos pasos: abrir tu agente, /agentic-qa-onboard, /project-discovery y lo que quedó pendiente. Al terminar se guarda una copia estática en .session/runs/ (ignorada por git) y la página te muestra la ruta.

Comprueba el resultado en cualquier momento con bun run setup:doctor (añade --json si lo va a leer un agente). Lista las variables pendientes con la URL donde se genera cada token.

Las conexiones con datos reales (Jira y Xray, la base de datos, la API) tienen su propia guía en Setup.

Credenciales y arranque del agente

Copia .env.example a .env (el instalador lo hace por ti) y rellena lo que tu trabajo necesite. .env está en .gitignore y es la fuente por defecto de los secretos (o el gestor de secretos, ver Variables de entorno). Nada de lo que falte bloquea la instalación ni el doctor: cada variable tiene un alcance (framework, tooling o proyecto bajo prueba) y la valida el código que la lee, con un error que la nombra. Qué variable es de quién, qué valida varlock y qué se conecta fuera de .env está en Variables de entorno. Hay dos archivos que se parecen y no hacen lo mismo:

La URL del sitio de Atlassian no va en .env: vive solo en .agents/project.yaml y se lee con bun run --silent jira:url. Una copia vieja en el entorno reconstruía la caché desde un Jira muerto sin avisar, por eso se sacó de ahí.

Cómo llega cada credencial a cada harness

Un harness lee su configuración y arranca los servidores MCP antes de que corra cualquier hook, y una app de escritorio (Claude Desktop, Codex Desktop, OpenCode desktop) o un worker lanzado de forma nativa no trae ninguna variable en su entorno. Por eso ningún MCP depende del entorno del harness: cada servidor que necesita valores de .env arranca a través del mismo loader, igual en los tres hosts (.mcp.json, opencode.jsonc y .codex/config.toml):

bunx -p varlock@<pin> varlock run --no-redact-stdout --inject vars --filter A,B -- <servidor>

El loader lee el esquema de varlock y .env / .env.local (o el gestor de secretos que nombre el esquema) desde la raíz del proyecto en el momento en que arranca el servidor, y le pasa solo las variables de su --filter. No se escribe ninguna copia en texto plano en ningún sitio. Solo hace falta bun install una vez.

Las versiones anteriores de bun run harness:env copiaban las credenciales al bloque env de .claude/settings.local.json y a .auth/opencode/. Ese comando las retira: borra la copia que coincide con .env, mueve a .auth/harness-env-backup/ la que .env no reproduce (pones el valor correcto en .env y borras esa carpeta) y nunca imprime valores. bun run harness:env:check falla mientras quede una copia, y bun run setup:doctor lo reporta también.

1. Rellena .env

   Con los valores que te pidió el instalador o los que faltan según setup:doctor.

2. Reinicia el agente

   El loader lee .env cuando arrancan los servidores MCP. Una sesión abierta no ve los cambios.

claude     # Claude Code
opencode   # OpenCode
codex      # Codex CLI (Codex Desktop usa la misma config del repo)

Abre el harness tal cual en la carpeta del repo, o con su app de escritorio: no hace falta ningún script. Cada servidor MCP lee .env por su cuenta con el loader filtrado de varlock, abras como abras el harness, y nada exporta .env a tu shell. Lo que sí puede tapar el archivo es una variable del proyecto que hayas exportado tú en el perfil de tu shell: gana sobre .env en todo lo que arranques desde esa shell. bun run vars:env:check la nombra (solo el nombre y el largo, nunca el valor); quítala del perfil o abre una terminal limpia.

El ciclo de vida: cinco fases

Cada fase tiene un disparador, un resultado concreto y una frecuencia. Avanzas cuando existe el resultado de la anterior, y vuelves a Mantenimiento cuando la documentación se aleja de la realidad.

  una vez por repo           una vez por target              continuo        cuando hay drift
+-----------------+   +---------------+   +-----------+   +-------------+   +---------------+
| 0 Bootstrap     |-->| 1 Discovery   |-->| 2 Adapt   |-->| 3 QA diario |<--| 4 Mantenim.   |
| bun setup   |   | /project-     |   | /test-    |   | stages IQL  |-->| sync + maps   |
|                 |   |  discovery    |   | framework-|   | con skill   |   |               |
|                 |   |               |   | adaptation|   |             |   |               |
+-----------------+   +---------------+   +-----------+   +-------------+   +---------------+

La fase 3 son los stages del IQL

El QA diario sigue los stages del IQL (Integrated Quality Lifecycle). Cada uno tiene un skill que lo ejecuta, salvo Observation, que está declarado sin skill. La metodología completa está en IQL y cómo la implementa este repo, en El IQL en este repo.

Elige tu camino

En la vida de un proyecto pasas por todos, en orden, a medida que una feature madura. En una sesión concreta eliges uno y dejas que el skill conduzca.

Tres piezas que se confunden

Tienen nombres parecidos y verbos que se solapan ("adaptar", "sincronizar", "refrescar").

agentic-qa-core tiene un papel pasivo: guarda la doctrina compartida (plantilla de briefing, patrones de dispatch, test design, gestión de defectos) que los skills de workflow cargan cuando la necesitan. Nunca lo invocas tú.

Cómo se conecta todo: tres circuitos

Circuito 1: variables

bun run agents:setup --escribe--> .agents/project.yaml
                                        |
                                        | el agente lo lee una vez por sesión
                                        v
skills y plantillas con {{PROJECT_KEY}}, {{WEB_URL}}, {{jira.*}}
                                        |
                                        v
        valores reales antes de cada llamada a una herramienta

{{VAR_NAME}}

Variable estática de .agents/project.yaml, global o por entorno.

<<VAR_NAME>>

Variable de sesión que calcula el skill en tiempo de ejecución (por ejemplo <<ISSUE_KEY>> a partir de la rama de git). Nunca se guarda.

{{jira.<slug>}}

Custom field portable de Jira. Se resuelve con .agents/jira-required.yaml y el catálogo .agents/jira-fields.json.

{{jira.work_type.*}}, {{jira.status.*}}, {{jira.transition.*}}

Referencias portables a tipos de issue, estados y transiciones, contra .agents/jira-workflows.json.

bun run vars:check comprueba que todos los placeholders siguen resolviendo. El contrato completo está en .agents/README.md.

Circuito 2: orquestación con subagentes

skill de workflow (/sprint-testing, /regression-testing, ...)
   | escribe un briefing de 7 componentes
   v
subagente (contexto limpio)
   | carga el skill de la herramienta
   v
/acli · /xray-cli · /playwright-cli · MCPs  -->  ejecuta y reporta

La conversación principal coordina y los subagentes hacen la lectura pesada. Cada briefing lleva siete partes: objetivo, docs de contexto, estándares del proyecto, skills a cargar, instrucciones exactas, formato del reporte y reglas. Los estándares salen ya resumidos de .agents/skills/REGISTRY.md (lo genera bun run skills:registry), así el subagente no relee cada SKILL.md. La plantilla está en .agents/skills/agentic-qa-core/references/briefing-template.md.

Antes de trabajar, los skills de testing y /framework-development pasan un chequeo de preparación: herramientas que faltan, MCPs caídos, tokens vencidos o un framework sin adaptar se detectan al principio y no a mitad de la corrida (.agents/skills/agentic-qa-core/references/preflight-gate.md).

Existe un segundo ejecutor opcional, el worker supervisado: una sesión persistente con la que sigues hablando, coordinada por /orca-orchestration. Solo aparece si el binario orca está instalado y su runtime responde.

Circuito 3: auto-carga de skills por CLI

Antes de ejecutar un binario, el agente carga el skill que sabe usarlo (flags, auth, paginación, errores). La tabla binario → skill vive en .agents/instructions/agent-tool-resolution.md (§6.5).

Los MCPs del repo

Los declara .mcp.json y existen igual en opencode.jsonc y .codex/config.toml. Solo viven ahí servers locales: los que leen valores de .env (la base de datos, la API, el bot de Slack) y el de documentación, que no necesita clave. El navegador no es un MCP: es /playwright-cli. La regla general: primero el CLI (gasta menos tokens) y el MCP como respaldo, salvo donde el MCP es la herramienta principal.

Qué hace cada uno y cuándo se usa está en la tabla de MCPs de .agents/instructions/agent-skills-and-mcps.md; las variables que cada server necesita en .env las lista bun run setup:doctor (y .env.example las comenta). Las guías de DBHub y OpenAPI explican los que leen valores del proyecto.

La búsqueda web y Postman no están en .mcp.json a propósito: son servers remotos cuyo único contenido del lado del proyecto era una API key, así que se conectan una vez por máquina a nivel del harness (un conector de claude.ai o un server de usuario en Claude Code, la config global de OpenCode, codex mcp add en Codex) y los skills los resuelven por capacidad, sea cual sea el prefijo. Cómo conectarlos por harness: Variables de entorno. El MCP de Atlassian tampoco está: es opt-in y se documenta en .agents/skills/agentic-qa-core/references/mcp-atlassian-optin.md. Jira y Xray se manejan con acli y bun xray (guía).

Engram: memoria entre sesiones

Engram es un servidor MCP que guarda memoria estructurada y sobrevive a sesiones y compactaciones. bun setup lo conecta a cada harness con engram setup, a nivel de usuario, fuera del repo. Ese comando registra el servidor de memoria y nada más. En Claude Code, además, ofrece instalar el plugin de Engram (claude plugin install engram@engram), que trae los hooks de sesión. El boilerplate no usa la capa de workflow de gentle-ai: los skills de workflow ya cubren Plan, Code y Verify.

Dos cosas conviene saber. El agente guarda solo cuando él llama a mem_save; nada se guarda solo. Y la búsqueda compara palabras, no significado: dos o tres palabras clave del título de la memoria encuentran más que la pregunta entera.

Si saltas Engram, todo sigue funcionando, pero cada sesión empieza sin memoria.

Chuleta: quiero X, ejecuto Y

Todo lo de esta tabla existe como skill (con su modo, si tiene varios) o script de package.json. Los skills se muestran en la forma de Claude Code (/<skill> <modo>); en OpenCode y Codex se piden en prosa ("cargá la skill <skill>, modo <modo>"), como explica Skill y modo.

Catálogo de skills

El catálogo es .agents/skills/REGISTRY.md (generado por bun run skills:registry). .agents/instructions/agent-skills-and-mcps.md es otra cosa: el router de frases disparadoras que usa el agente para elegir skill, no el inventario. Hay tres tipos: propios del repo, vendorizados (como judgment-day, de gentle-ai) y de la comunidad, que instala bun setup a nivel de proyecto. Además hay skills de usuario (la lista USER_LEVEL_SKILLS de cli/install.ts): el agente carga sin preguntar las que una regla del repo o tus propias instrucciones nombran para un momento concreto (por ejemplo mkd cuando hay una decisión pesada, con tradeoffs reales) y te pide permiso para cualquier otra.

Workflow: los stages del pipeline

Setup, contexto, herramientas y soporte

El resto (onboarding, discovery, adaptación del framework, mapas de contexto, git, administración de Jira, orquestación, revisión y los wrappers de CLI) son skills de soporte: su fila en .agents/skills/REGISTRY.md dice cuándo se cargan y qué hacen. Las de la comunidad las instala bun setup (listas PROJECT_LEVEL_SKILLS y USER_LEVEL_SKILLS en cli/install.ts).

Comandos y scripts

Skill y modo

No hay archivos de comando. Un skill se invoca por su nombre más un modo: en Claude Code, /project-context data; en OpenCode y Codex, en prosa ("carga project-context, modo data"). El primer token de tus argumentos que coincide con un modo es el modo; el resto se le pasa al skill. Si ninguno coincide, el skill pregunta.

Una fila de ejemplo; los modos de cada skill están en su SKILL.md y el catálogo en .agents/skills/REGISTRY.md.

Scripts de package.json

Se ejecutan con bun run <nombre>. La lista vive en package.json (regla 11 de AGENTS.md: se lee ahí, nunca de una copia). Se reconocen por prefijo: instalación, entorno y agentes (setup, agents:*, harness:env (retira copias viejas), env:set), instrucciones del agente (instructions:*), worktrees (worktree:*), documentación (docs*), Jira, Xray y caché local (jira:*, xray, context:*, tests:map), tests y reportes (test*, allure:*), API y KATA (api:*, kata:*), navegador (browser:profiles) y calidad del repo (lint:*, format:*, types:check, vars:*, skills:*, repo:*, git:policy). La lista por prefijo no es exhaustiva: hay scripts sueltos, como sync y pw:install.

Además está prepare, que instala los hooks de Husky al hacer bun install. No hay un script env porque nada necesita .env exportado en tu shell: cada proceso lo carga por su cuenta (los MCP con el loader de .env, los scripts de Bun con su propio autoload).

Decks visuales

Presentaciones en español (términos técnicos en inglés) que recorren cada skill paso a paso. Están publicadas en GitHub Pages porque los proyectos creados con el scaffolder no traen los archivos. /agentic-qa-onboard puede abrirte el que corresponda.

El catálogo completo, con los decks de oficio de cada skill y la KATA Academy, está en la portada del sitio.

Siguientes pasos