Primeros pasos para la puesta en marcha de `NEO`

Existen dos formas de trabajar con NEO. La primera es usar un editor de código (por ejemplo, VSCode) y, desde ahí, trabajar junto con tu asistente de IA (por ejemplo, Claude). La segunda es trabajar directamente con la aplicación de escritorio del asistente de IA (por ejemplo, Claude Code Desktop), compartiéndole la carpeta local del proyecto.

¿Qué opción elegir?

Opción	Cómo se trabaja	Elegila si...
A — Editor + asistente de IA	Instalás un editor de código (VSCode u otro) y, adentro, una extensión del asistente de IA	Preferís ver en una misma pantalla los archivos del proyecto, el código generado y el chat con el asistente
B — Asistente de IA de escritorio	Instalás solo la app de escritorio del asistente (por ejemplo, Claude Code Desktop) y le indicás la carpeta del proyecto	Preferís algo más simple, sin instalar ni aprender a usar un editor de código

A lo largo de esta guía, cada paso indica si aplica (Solo opción A), (Solo opción B), o a ambas por igual (cuando no dice nada). Seguí siempre los pasos que correspondan a la opción que elegiste.

Paso 1. Instalar VSCode (solo si elegiste la Opción A)

Los pasos detallados son para VSCode, pero podés usar cualquier editor, por ejemplo IntelliJ.

Descargalo desde code.visualstudio.com y seguí el instalador (siguiente, siguiente, finalizar).
Abrilo una vez instalado para confirmar que arranca bien.

Paso 2. Instalar tu asistente de IA

Los pasos para instalarlo dependen de la opción que elegiste:

(Solo opción A)

En VSCode, abrí el panel de extensiones (ícono de cuadraditos en el margen izquierdo, o Ctrl+Shift+X).

Los pasos de abajo son para Claude Code. Si usás Codex o Copilot, instalá la extensión equivalente y seguí el flujo de login propio de esa herramienta.

Buscá "Claude Code for VS Code" e instalala.
Al abrirla por primera vez te va a pedir iniciar sesión con tu cuenta de Claude/Anthropic — seguí el flujo de login que te propone (se abre el navegador, confirmás y volvés a VSCode).

(Solo opción B)

Los pasos de abajo son para Claude Code. Si usás Codex o Copilot, instalá la versión de escritorio propia de ese agente.

Descargalo desde code.claude.com y seguí el instalador (siguiente, siguiente, finalizar).
Abrilo una vez instalado — la primera vez te va a pedir iniciar sesión con tu cuenta de Claude/Anthropic, seguí el flujo de login que te propone.

Paso 3. Instalar Git

Git es lo que te permite descargar ("clonar") los repositorios del proyecto.

Windows: descargalo de git-scm.com e instalalo con las opciones por defecto (esto también instala Git Bash, una terminal que vas a necesitar más adelante).
Mac: suele venir preinstalado; si no, corré xcode-select --install desde la Terminal, o descargalo de git-scm.com.

Verificar que quedó instalado: abrí una terminal (en Windows, buscá "Git Bash") y escribí:

git --version

Si te devuelve un número de versión, está listo.

Paso 4. Clonar los repositorios

Vas a trabajar con al menos dos carpetas, según el proyecto:

NEO-releases — donde viven las skills y los playbooks.
El repo del proyecto bajo test (por ejemplo, TechStore) — donde vas a generar y correr los tests.

Para obtener el link a un repositorio, seguí estos pasos:

Entrá a GitLab — antes vas a necesitar que te den permisos de acceso al proyecto. Hacé clic sobre el repositorio que querés clonar (por ejemplo, "NEO-releases"), presioná el botón Code y copiá la URL de "Clone with HTTPS" (o "Clone with SSH", si preferís esa opción).

Importante: se recomienda que ambos repositorios queden descargados al mismo nivel, es decir, como subdirectorios del mismo directorio padre.

Cómo clonarlos depende de la opción que elegiste:

(Solo opción A)

Para clonar el repositorio en VSCode: Ctrl+Shift+P → escribí "Git: Clone" (se abre un campo de texto arriba de todo) → pegá la URL del repositorio que copiaste → elegí una carpeta en tu computadora → Open cuando termine. (El mismo procedimiento se explica con más detalle en last_version.md, sección 6.)

(Solo opción B)

Para clonar el repositorio, abrí una terminal:

Windows: buscá "Git Bash" en el menú de inicio y abrilo.
Mac: abrí la aplicación Terminal.

Posicionate en la carpeta donde querés que vivan tus proyectos (por ejemplo, cd Documents) y ejecutá:

git clone <URL-del-repositorio>

Reemplazá <URL-del-repositorio> por el link que copiaste en el paso anterior (por ejemplo, la URL de "Clone with HTTPS" de NEO-releases). Repetí el comando para cada repositorio que necesites clonar (NEO-releases y el repo del proyecto bajo test).

Como se indicó más arriba, ambos repositorios deben quedar como subdirectorios del mismo directorio padre.

Paso 5. Instalar Node.js y npm

Node.js es el motor que necesita Playwright para correr. npm (Node Package Manager) viene incluido con Node.js — no se instala aparte.

Descargá la versión LTS (la recomendada, no la "Current") desde nodejs.org.
Abrí el instalador que se descargó y seguilo con las opciones por defecto (siguiente, siguiente, finalizar).

Verificar que quedó instalado: para esto necesitás abrir una terminal y escribir un par de comandos. Dónde abrirla depende de qué opción elegiste al principio:

(Solo opción A)

En VSCode, abrí la terminal integrada desde el menú Terminal → New Terminal (o el atajo Ctrl+ñ / Ctrl+`).
Escribí, uno por uno:
```
node --version
npm --version
```

(Solo opción B)

Abrí una terminal:
- Windows: buscá "Git Bash" en el menú de inicio y abrilo.
- Mac: abrí la aplicación Terminal.
Escribí, uno por uno:
```
node --version
npm --version
```

Ambos comandos tienen que devolver un número de versión. Si en cambio te aparece un mensaje como "no se reconoce como un comando" (command not found), cerrá la terminal, volvé a abrirla (o reiniciá la computadora) e intentá de nuevo — a veces hace falta reiniciar para que el sistema reconozca la instalación nueva.

Paso 6. Disponibilizar las skills para tu asistente de IA

Con todo lo anterior instalado, falta un último paso: indicarle al asistente dónde están las skills de NEO-releases. El asistente no las "adivina" solo — necesita encontrarlas en una carpeta específica de tu computadora.

6.1 Cómo funciona

Cada skill es una carpeta con un archivo SKILL.md adentro: instrucciones escritas para que el asistente sepa hacer una tarea puntual (leer una historia, armar un plan de pruebas, generar tests, etc.). El repositorio NEO-releases ya trae todas las skills armadas — lo único que falta es "conectarlas" con el proyecto bajo test.

Al arrancar una sesión, tu asistente busca las skills en esta carpeta, dentro del proyecto bajo test:

<proyecto-bajo-test>/.claude/skills/

Si usás Codex o Copilot en vez de Claude Code, es la misma lógica reemplazando .claude por .codex o .copilot.

No hace falta copiar los archivos a mano: vas a crear un enlace (symlink) que apunta a la carpeta real dentro de NEO-releases. Así, cuando el equipo técnico actualice una skill y vos actualizás tu copia de NEO-releases (git pull, ver last_version.md), el cambio se refleja solo, sin repetir ningún paso.

6.2 Vincular las skills al proyecto bajo test

1. Abrí una terminal:

Opción A: en VSCode, abrí la terminal integrada desde el menú Terminal → New Terminal (o el atajo Ctrl+ñ / Ctrl+`).

Opción B: buscá "Git Bash" en el menú de inicio si estás en Windows, o abrí la aplicación Terminal si estás en Mac.

2. Parate en la carpeta del proyecto bajo test (no en NEO-releases) y creá la carpeta donde van a vivir las skills:

cd /ruta/al/proyecto-bajo-test
mkdir -p .claude/skills

Reemplazá /ruta/al/proyecto-bajo-test por la ruta real donde clonaste el proyecto en tu computadora.

3. Si clonaste NEO-releases al lado de ese proyecto (mismo directorio padre, como se indicó en el Paso 4), corré:

for skill in ../NEO-releases/skills/*/; do
  name=$(basename "$skill")
  ln -sfn "$(cd "$skill" && pwd)" .claude/skills/"$name"
done

El repo NEO-releases trae este mismo bloque guardado en el archivo link-claude-skills.sh, así que también podés simplemente correr:

bash ../NEO-releases/link-claude-skills.sh

Si usás Codex o Copilot, reemplazá .claude por .codex/.copilot en el bloque anterior (no hay un script equivalente todavía para esas dos herramientas).

IMPORTANTE: si estás en la Opción A (VSCode con la extensión de Claude Code), después de crear las skills es necesario recargar VSCode para que se puedan ver.

6.3 Verificar que tu asistente ya las ve

Abrí una sesión con tu asistente de IA sobre el proyecto bajo test y escribile, en lenguaje natural:

Listá las skills de QA disponibles

Si la instalación salió bien, tu asistente va a responder con la lista de skills (qa-read-user-story, qa-create-test-plan, qa-workflow-e2e, etc.).

Paso 7. Cómo configurar Playwright mcp

Playwright es la herramienta que efectivamente abre un navegador (Chrome, Firefox, etc.), navega por la app bajo test, hace clics, completa formularios y verifica resultados. Es el "brazo ejecutor" que usan las skills detrás de escena cuando el proyecto está configurado con este framework.

Para los siguientes pasos necesitás abrir una terminal, igual que hiciste antes:

(Solo opción A)

En VSCode, abrí la terminal integrada desde el menú Terminal → New Terminal (o el atajo Ctrl+ñ / Ctrl+`).

(Solo opción B)

Windows: buscá "Git Bash" en el menú de inicio y abrilo.
Mac: abrí la aplicación Terminal.

Luego, en esa terminal, parate en la carpeta raíz del proyecto bajo test (donde está su archivo package.json — no en NEO-releases):

cd /ruta/al/proyecto-bajo-test

7.1 Instalar las dependencias del proyecto

npm install

Esto descarga las librerías que el proyecto ya tiene declaradas.

7.2 Instalar el navegador para la etapa de exploración

Este paso descarga los navegadores Chromium, Firefox y WebKit. Solo hace falta correrlo una vez por computadora (o cuando cambia la versión de Playwright del proyecto).

Además de correr los tests, tu asistente usa un navegador propio para explorar la app manualmente antes de generar los tests:

npx @playwright/mcp install-browser chrome-for-testing

Paso 8. Datos del ambiente bajo test (URL y credenciales)

Las skills necesitan saber contra qué URL probar y con qué usuario. Estos datos tenés que completarlos en un archivo .env (que nunca se sube al repositorio — está en .gitignore), en la raíz del proyecto bajo test:

# .env
APP_BASE_URL=https://tu-app-bajo-test.com
APP_USERNAME=usuario-de-prueba
APP_PASSWORD=contraseña-de-prueba

Si no tenés este archivo todavía, no es un problema: lo vamos a generar en el paso siguiente, cuando ejecutes la skill de configuración del proyecto.

Paso 9. Configurar el proyecto con NEO

En este paso ya estamos en condiciones de empezar a usar las skills de NEO. Para eso vamos a abrir el asistente de IA que configuramos en el Paso 2, parados sobre el proyecto bajo test.

9.1 Abrir el asistente sobre el proyecto bajo test

(Solo opción A)

En VSCode, abrí el asistente de IA con el ícono de Claude ubicado en la barra superior.
Verificá que VSCode esté posicionado sobre el repositorio del proyecto bajo test.
Iniciá un chat nuevo.

(Solo opción B)

Abrí la aplicación Claude Code Desktop.
En el extremo superior izquierdo, hacé clic en el botón </> Code.
Seleccioná la carpeta local del repositorio bajo test que clonaste en el Paso 4 — así le indicás al asistente sobre qué proyecto (y qué rama) vas a trabajar.

9.2 Ejecutar `qa-bootstrap-stack`

Aplica a las dos opciones (A y B).

En el chat, ejecutá el primer comando:

/qa-bootstrap-stack

Qué pasa: el asistente analiza el repositorio para determinar con qué tecnologías está armado el proyecto. Todo lo que no puede inferir solo, te lo va a preguntar.

Algunos datos los infiere y solo te los propone como sugerencia:

Sistema operativo del ambiente de test y URL base de la aplicación bajo test — con esto arma una primera propuesta de configuración, que después vas a poder ajustar.
Versión del build de la app a testear — toma el dato de package.json y te lo sugiere.

Otros son preguntas puntuales, con opciones para elegir:

Te pregunta	Opciones	Qué significa
Método de autenticación	`[1] Basic Auth` (usuario y contraseña, los que definiste en el Paso 8) · `[2] Google SSO` · `[3] API Token` · `[4] Ninguno` · `[5] Otro`	Elegí el que use tu app bajo test
De dónde tomar las historias de usuario	`[1] Local` · `[2] Cloud` (Jira, etc.) · `[3] Otro`	Según lo que elijas, te va a preguntar el detalle en el paso siguiente — por ejemplo, el nombre de una carpeta o la URL de acceso a un repositorio
Directorio de las historias de usuario (si elegiste "Local")	Sugiere la carpeta `specs/` (la crea si no existe)	Podés aceptar la sugerencia o indicar otra carpeta
¿En qué directorio se guardan los planes de test (`test_plans_dir`)?	`[1] test-plans/` (default) · `[2] docs/test-plans/` · `[3] Otro`	Ahí queda el desglose paso a paso del razonamiento que siguió el agente
¿En qué directorio se genera la suite de tests ejecutable (`tests_dir`)?	`[1] tests/<test_framework>/` (default — ej. `tests/playwright/`, `tests/lippia/`) · `[2] docs/tests/` · `[3] Otro` (ruta relativa a la raíz del repo)	Ahí se crean los tests automatizados (`.js`) que después podés volver a ejecutar
¿En qué directorio se escriben los reportes finales (`reports_dir`)?	`[1] test-results/reports/` (default) · `[2] docs/test-results/reports/` · `[3] Otro` (ruta relativa a la raíz del repo)	Ahí se guarda el reporte con el resultado de las pruebas manuales y automatizadas, el análisis de riesgos, etc.
¿En qué directorio van el reporte de ejecución manual + screenshots (`scripted_dir`)?	`[1] execution/` (default) · `[2] docs/execution/` · `[3] Otro` (ruta relativa a la raíz del repo)	Ahí se guardan los resultados de las ejecuciones

Qué te queda al final de este paso: el archivo qa-stack.yaml, con toda la información recopilada del proyecto necesaria para poder ejecutar los planes de aquí en adelante.

Paso 10. Ejecutar `qa-workflow-e2e` para iniciar el flujo QA completo

Trigger: qa-workflow-e2e

Qué pasa: a partir de una historia de usuario, este paso genera las pruebas automatizadas y las ejecuta.

En el chat con tu asistente, escribí un prompt como este:

Te brindo la información, quiero que solo la guardes como contexto:
Quiero correr el flujo end-to-end completo para la historia user-stories/PA-US-03.md.

Reemplazá user-stories/PA-US-03.md por la ruta y el nombre real del archivo que contiene tu historia de usuario.

Qué te queda al final de este paso: las pruebas automatizadas generadas y sus resultados, guardados en los archivos dentro de las carpetas que configuraste en el Paso 9 (tests_dir, reports_dir, etc.).

Primeros pasos para la puesta en marcha de NEO

¿Qué opción elegir?

Paso 1. Instalar VSCode (solo si elegiste la Opción A)

Paso 2. Instalar tu asistente de IA

(Solo opción A)

(Solo opción B)

Paso 3. Instalar Git

Paso 4. Clonar los repositorios

(Solo opción A)

(Solo opción B)

Paso 5. Instalar Node.js y npm

(Solo opción A)

(Solo opción B)

Paso 6. Disponibilizar las skills para tu asistente de IA

6.1 Cómo funciona

6.2 Vincular las skills al proyecto bajo test

6.3 Verificar que tu asistente ya las ve

Paso 7. Cómo configurar Playwright mcp

(Solo opción A)

(Solo opción B)

7.1 Instalar las dependencias del proyecto

7.2 Instalar el navegador para la etapa de exploración

Paso 8. Datos del ambiente bajo test (URL y credenciales)

Paso 9. Configurar el proyecto con NEO

9.1 Abrir el asistente sobre el proyecto bajo test

(Solo opción A)

(Solo opción B)

9.2 Ejecutar qa-bootstrap-stack

Paso 10. Ejecutar qa-workflow-e2e para iniciar el flujo QA completo

Primeros pasos para la puesta en marcha de `NEO`

9.2 Ejecutar `qa-bootstrap-stack`

Paso 10. Ejecutar `qa-workflow-e2e` para iniciar el flujo QA completo