Contribuir

Las contribuciones son bienvenidas. El repositorio es GustavoGutierrez/alisio; las instrucciones para contribuir también están en AGENTS.md y CONTRIBUTING.md.

Herramientas

• pnpm (11.25.0) para las dependencias. Mantén solo pnpm-lock.yaml; no añadas otros lockfiles.
• Bun para el desarrollo (pnpm dev) y el binario independiente; los paquetes compilados se ejecutan en Node.js >= 22.16 o Bun >= 1.4.2.
• Biome para lint y formato, Vitest para las pruebas y TypeScript (tsc) para los tipos y la compilación.

pnpm install --frozen-lockfile
pnpm dev --help

Comprobaciones

Ejecuta estas comprobaciones antes de abrir un pull request:

Comando	Qué comprueba
pnpm typecheck	TypeScript en paquetes, pruebas, fixtures, scripts y la configuración de la documentación
pnpm lint	Lint y formato con Biome
pnpm test	Suite de Vitest (algunos fixtures también se ejecutan en Bun)
pnpm build	Compilación con tsc de cada paquete
pnpm test:cli	La CLI compilada bajo Node contra un proveedor simulado local
pnpm test:compiled	Compila el binario independiente y ejecuta contra él el fixture de extremo a extremo
pnpm pack:check	Contenido de los paquetes npm
pnpm website:check	Enlaces internos, #anclas y paridad inglés/español
pnpm website:build	Este sitio de documentación, incluidos website:check y la comprobación de enlaces rotos

pnpm check las ejecuta todas en orden.

Reglas de desarrollo

• TDD estricto: escribe primero la prueba que falla y después la implementación.
• Prueba el comportamiento en los límites de los módulos. No añadas pruebas de snapshot que simplemente repitan la implementación. Una excepción: las especificaciones golden pequeñas y revisadas a mano en tests/golden/dashboard/*.json (el DashboardSpec que devuelve el planificador para unos pocos datasets de como máximo 40 filas, o los CSV de ejemplo). Son comportamiento del planificador en su límite; un cambio de regla que mueva uno exige revisión humana. Nunca hagas una instantánea del HTML generado: comprueba su estructura.
• Mantén los SDKs de proveedores y los imports específicos de un runtime fuera de @alisio/sdk y de los contratos del núcleo del agente.
• Preserva los IDs de llamadas a herramientas, los datos de continuación del proveedor y la consistencia de las sesiones persistidas.
• Nunca trates un manifiesto de complemento ni un subproceso como un sandbox.
• El código, los comentarios y las pruebas se escriben en inglés; este sitio se escribe en inglés y en español. apps/website/implementation-status.md se escribe en español y registra las limitaciones y el alcance de la verificación; actualízalo cuando cambien.

Decision Intelligence

Antes de añadir un Decision Pack o cualquier uso de ctx.decisions, el cambio debe pasar la regla de admisión: cuatro preguntas sobre si la decisión es cerrada, frecuente, vale la pena resolverla así y admite una alternativa segura, y ocho respuestas escritas en la pull request (la decisión, el trabajo del LLM que se elimina, la métrica, la alternativa, el comportamiento sin proveedor, cómo se valida la salida, por qué el código determinista no basta y qué va en state). Las funciones que no pueden responderlas no usan el motor de decisiones.

Versionado

Las versiones y los changelogs se gestionan con changesets. Añade un changeset a cada pull request que modifique un paquete publicado:

pnpm changeset

En main, el workflow de release abre un pull request de versión y, una vez fusionado, publica en npm con provenance y adjunta los binarios independientes a una GitHub Release.

Documentación

El sitio está en apps/website/ y se construye con VitePress:

pnpm website:dev     # local preview
pnpm website:check   # internal links, anchors and EN/ES parity
pnpm website:build   # production build with dead-link check
pnpm website:deploy  # build and deploy to Cloudflare (maintainers)

El sitio se publica en Cloudflare Workers, en https://alisioair.com, desde el equipo de una persona mantenedora con pnpm website:deploy; el workflow Website de GitHub solo lo construye y lo comprueba. Las credenciales nunca van en el repositorio: inicia sesión con wrangler login e indica la cuenta en apps/website/.env (copiado de apps/website/.env.example, nunca se sube).

Las páginas en inglés están en apps/website/<page>.md y las páginas en español en apps/website/es/<page>.md. Los enlaces internos usan rutas del sitio (/configuration en inglés, /es/configuration en español). specification.md, herdr.md, implementation-status.md, validation.txt, benchmark.json y README.md de apps/website/ están excluidos del sitio; enlácelos con URLs absolutas de GitHub.

Lista de paridad de la documentación

• [ ] Cada página existe en ambos idiomas (apps/website/<page>.md y apps/website/es/<page>.md), y ambas figuran en la barra lateral de apps/website/.vitepress/config.ts.
• [ ] Ambas versiones tienen los mismos títulos en el mismo orden y los mismos bloques de código; los comandos, flags y claves de configuración son idénticos.
• [ ] La prosa se traduce fielmente; ninguna versión es un resumen de la otra.
• [ ] El inglés y el español se actualizan en el mismo pull request.
• [ ] apps/website/es/limitations.md sigue incluyendo apps/website/implementation-status.md, y apps/website/limitations.md en inglés refleja su contenido actual.
• [ ] pnpm website:build termina sin enlaces rotos (pnpm website:check valida #anclas y paridad, algo que la propia comprobación de enlaces de VitePress no cubre).