Keelokit

Keelokit la página técnica

Para devs: cómo está hecho.

Los comandos, las reglas de la casa, el guard y lo que corre solo en cada commit. El mismo método de la página simple, en detalle.

← Keelokit, en palabras simples ¿Orquestando releases? Cómo funciona Harbor →

Este es el fondo: lo de arriba es lo que se ve, esto es cómo se sostiene.

−20 m

De una idea a un monorepo que funciona

/keelokit:project-new te lleva por cinco etapas y muestra cada una en un tablero. Por etapas, se frena donde importa tu decisión; en modo automático, solo donde hace falta una persona. Va dejando todo por escrito.

  1. 01

    Intake

    Una entrevista que primero lee lo que ya tenés y después pregunta solo lo que falta. Lo que nadie sabe todavía queda escrito como pregunta abierta, con un responsable.

  2. 02

    Producto

    Un PRD corto: el problema, para quién es, qué entra y, explícitamente, qué queda afuera.

  3. 03

    Stack

    El stack de la casa. Lo que se desvía queda registrado como decisión, no improvisado.

  4. 04

    Esqueleto

    Un monorepo generado con CI, hooks de git y tests, en verde antes de escribir una feature.

  5. 05

    Backlog

    Épicas e historias con escenarios de aceptación y las reglas que tienen que respetar, agrupadas en olas de desarrollo que nunca tocan los mismos archivos.

Lo que obtenés
  • mi-app/
  • apps/
  • api/NestJS · Prisma · PostgreSQL
  • web/Vite · React
  • mobile/Expo · iOS y Android
  • site/Astro
  • packages/
  • shared/contratos zod · i18n
  • ui-tokens/una sola fuente para el diseño
  • docs/context/lo que se sabe y lo que falta
  • backlog/historias con ids de escenario
  • .keelokit/reglas, checks, guard, doctor

Elegís qué apps necesita cada producto.

El esqueleto, verificado de punta a punta
pnpm verify --all▶ Up to date with origin/main (GIT-1)▶ Secret scan (gitleaks)▶ Prisma client▶ Format▶ Lint▶ Typecheck▶ Harness doctor  ✔ harness healthy▶ Unit tests▶ Throwaway PostgreSQL (migrated, seeded)▶ Integration tests (real PostgreSQL)▶ Build▶ End-to-end journeys▶ End-to-end on the real stack (./apps/web)▶ Dependency audit✔ verify passed

El stack que genera

  • pnpm
  • TypeScript
  • NestJS
  • Prisma
  • PostgreSQL
  • React
  • Vite
  • Expo
  • Astro
  • Zod
  • Vitest
  • GitHub Actions
  • Fly.io

Por dónde empezar

Qué tenésEmpezá conQué obtenés
Una idea, nada más/keelokit:project-newUn monorepo que funciona, con CI, contexto y un primer backlog
Un repo que ya existe/keelokit:project-adoptLas reglas mapeadas a sus checks, y el resto como deuda con fecha
Una historia para construir/keelokit:build-storyTests escritos primero, código que los pasa y un resultado verificado
Bugs que se siguen escapando/keelokit:check-bugbashArreglos en la causa raíz, y un check que cubre toda la clase de cada bug que se escapó
Un proyecto para seguir/keelokit:project-dashboardNuevoUna página liviana y en vivo: el próximo paso para copiar, lo que te espera, cada ola con sus historias
Alguien a quien mostrárselo/keelokit:project-reportNuevoEl estado completo, de solo lectura, como página para compartir o archivo para exportar
Una app para probar en tu teléfono/keelokit:run-localNuevoTu app y su API corriendo en un teléfono, un emulador o el simulador, con un comando
Un producto listo para usuarios/keelokit:ship-setupStaging y producción configurados y verificados, y después /keelokit:ship-release para cada versión

−22 m

Todos los comandos

Doce comandos y la entrada, agrupados según lo que estés haciendo. Abrí cualquiera para ver qué hace, paso a paso.

Proyecto

Empezar uno, sumar uno existente, seguirlo

/keelokit

Dónde está el proyecto, qué sigue y qué espera tu decisión.

Cómo funciona

Qué hace

  1. Lee el repo: etapas aprobadas, preguntas abiertas, historias terminadas y listas, la versión del harness.
  2. Responde en diez líneas: dónde estás, el próximo paso, qué te espera.
  3. Abre el tablero cuando una etapa te espera o se retoma un proceso a medias.

Cuándo

Cada vez que abrís una sesión y no sabés por dónde seguir.

/keelokit:project-new

De una idea a un esqueleto que funciona: intake, PRD, stack, monorepo generado con CI y primer backlog.

Cómo funciona

Qué hace

  1. Pregunta una sola vez cómo trabajar: por etapas o automático, de a una historia o en paralelo.
  2. Te entrevista sobre el producto y escribe el contexto, con preguntas abiertas en lugar de suposiciones.
  3. Escribe un PRD corto y elige solo las aplicaciones que hacen falta; vos aprobás el alcance y las métricas.
  4. Genera el monorepo con CI, hooks y tests, en verde antes de cualquier funcionalidad.
  5. Planifica el backlog en olas de desarrollo; el tablero muestra cada etapa a medida que avanza.

Cuándo

Tenés una idea y una carpeta vacía.

/keelokit:project-adopt

Suma solo el harness a un repo que ya tenés. Lo que todavía no cumple queda como excepción con fecha.

Cómo funciona

Qué hace

  1. Lee el repo sin correr ni cambiar nada, y entiende qué es: un producto con pantallas y base de datos, un servicio, una librería, una CLI, un plugin.
  2. Instala solo .keelokit/ y aplica solo las reglas de la casa que corresponden a ese tipo de proyecto, mapeadas a controles que el repo ya tiene.
  3. Lo que todavía no puede cumplir queda como excepción con fecha que vos aprobás, con una historia para saldarla.
  4. Escribe un diagnóstico del código real y arma el backlog; el tablero muestra lo que encontró.

Cuándo

Ya tenés código y querés las reglas y los controles sin reescribir nada.

/keelokit:project-dashboardNuevo

La página desde la que trabajás: liviana, en vivo y armada desde el repo.

Cómo funciona

Qué hace

  1. Muestra dónde está el proyecto y el único próximo paso, con su comando listo para copiar.
  2. Lista lo que te espera: aprobaciones, las decisiones que dejó un bug bash o una revisión de seguridad con la opción recomendada, entornos a medio configurar.
  3. Muestra cada ola de desarrollo con sus historias, cada una con el link a su archivo: hecha, lista para construir o esperando a otra.
  4. Se mantiene en vivo: se publica una vez y cada actualización cambia la página abierta sin volver a pasarla por el chat, así que gasta muy pocos tokens.

Cuándo

Para ver dónde está todo, aprobar una etapa o retomar después de una pausa.

/keelokit:project-reportNuevo

El estado completo del proyecto, de solo lectura, para compartir o exportar.

Cómo funciona

Qué hace

  1. Muestra cada etapa con sus documentos: el contexto, las preguntas abiertas, el alcance y las métricas del PRD, el stack, el backlog por ola y por épica.
  2. Suma cada bug bash y cada revisión de seguridad con sus hallazgos, los entornos, las decisiones y el historial.
  3. Lo publica como una página propia que podés compartir, o escribe un archivo HTML que se abre en cualquier lado.
  4. Es una foto para leer: sin botones que envían pedidos, y uno nuevo cada vez que quieras compartir un estado posterior.

Cuándo

Para mostrarle el proyecto a un socio, un cliente o un inversor, o guardar registro de cómo estaba.

Planificar

Saber qué construir

/keelokit:plan-intake

Lee briefs, notas o un repo, y pregunta solo lo que falta. Nunca completa un hueco adivinando.

Cómo funciona

Qué hace

  1. Pregunta qué hay escrito y lo lee primero.
  2. Pregunta solo lo que falta, como mucho cuatro preguntas por vez, y solo acepta respuestas medibles.
  3. Escribe el contexto: producto, dominio y sus invariantes, restricciones, entornos, preguntas abiertas.
  4. Todo lo que no se sabe queda como pregunta con un responsable.

Cuándo

Un producto nuevo, o una funcionalidad nueva que necesita contexto.

/keelokit:plan-backlog

Épicas e historias con escenarios de aceptación y los invariantes que respetan, en olas de desarrollo para que el trabajo en paralelo no choque.

Cómo funciona

Qué hace

  1. Divide el PRD en épicas e historias que se pueden ver funcionando de punta a punta.
  2. Escribe los escenarios de aceptación de cada historia y los invariantes que tiene que respetar.
  3. Agrupa las historias en olas de desarrollo que nunca tocan los mismos archivos, para construirlas en paralelo.
  4. Te muestra el orden; las historias que vienen de un bug bash o de una revisión de seguridad lo indican.

Cuándo

Después del PRD, después de sumar una funcionalidad, o para replanificar.

Construir

Convertir historias en producto que funciona

/keelokit:build-story

Una historia por vez, o una ola entera en paralelo: primero los tests, después el código, y después quienes no lo escribieron intentan romperlo.

Cómo funciona

Qué hace

  1. Escribe el contrato de la historia: cada escenario, invariante y dimensión que puede romper.
  2. Un verificador escribe los tests de aceptación antes del código; fallan por el motivo correcto.
  3. Un builder los hace pasar sin tocar los tests.
  4. Un revisor lee el diff en frío y un breaker lo ataca: envíos dobles, pedidos simultáneos, datos de otro cliente.
  5. El verificador la recorre en la app corriendo; recién ahí entra.

Cuándo

Una historia está lista. De a una, o varias de la misma ola a la vez.

Revisar

Encontrar lo que se escapó, y que no vuelva

/keelokit:check-bugbashNuevo

Una cacería de bugs en datos, API, integridad, UX, i18n, accesibilidad y seguridad. Cada bug que se escapó suma un check para toda su clase.

Cómo funciona

Qué hace

  1. Mira qué es el proyecto y caza en consecuencia: modelo de datos, contratos y pantallas en un producto; experiencia de desarrollo, documentación y empaquetado en una librería o un plugin.
  2. Otro agente intenta refutar cada hallazgo; solo quedan los que se reproducen.
  3. Corrige cada uno en la causa, con un test que falla primero.
  4. Suma un control para toda la clase, registra el escape y convierte lo que queda en historias.

Cuándo

Después de cada ola, y antes de un release.

/keelokit:check-security

Seguridad y privacidad a fondo: datos personales, la ley de cada mercado, abusos de los recorridos críticos, escaneos.

Cómo funciona

Qué hace

  1. Mapea cada dato personal: qué es, para qué, quién lo ve, cuánto tiempo, a dónde va.
  2. Nombra la ley de privacidad de cada mercado y qué le pide a este producto.
  3. Modela las amenazas de los recorridos críticos; escanea dependencias, imágenes y staging (OWASP ZAP).
  4. Revisa datos personales en los logs, exportación y borrado, retención y cifrado.
  5. Corrige con un test y un control por clase; las decisiones de privacidad y las preguntas legales te llegan a vos.

Cuándo

Antes del primer lanzamiento a producción, y cuando un release toca datos personales, autenticación o pagos.

/keelokit:check-health

¿Cada regla sigue respaldada por un check que funciona? Suma reglas y registra excepciones.

Cómo funciona

Qué hace

  1. Verifica que cada regla de la casa tenga un control vivo: un test, una regla de lint, un job de CI, un hook de git.
  2. Revisa excepciones, contexto, invariantes, áreas críticas y el backlog.
  3. Suma una regla nueva con su control, o registra una excepción con fecha y tu aprobación.

Cuándo

Cuando el CI o el tablero muestran errores del harness, o para sumar una regla.

Entornos

De tu teléfono a tus usuarios: local, staging y producción, versiones

/keelokit:run-localNuevo

Tu app y su API en tu teléfono, un emulador de Android o el simulador de iOS, con un comando. Lo que le falte a tu Mac, lo instala después de un solo sí.

Cómo funciona

Qué hace

  1. Revisa qué le falta a la Mac (Node, Docker, el JDK, el SDK de Android, Xcode…), lo muestra todo junto y lo instala después de un solo sí.
  2. Levanta la base de datos y la API, pregunta si cargar los datos de ejemplo y muestra los usuarios de prueba para entrar.
  3. Abre la app en el teléfono, emulador o simulador que elijas, sin recompilar lo que ya está instalado.
  4. Si un paso falla, guarda el error para que Claude lo lea, lo arregle y vuelva a intentar. Nunca frena un proceso, un contenedor o un emulador sin preguntar.

Cuándo

Querés ver y tocar lo que estás construyendo. En macOS, para proyectos con app móvil.

/keelokit:ship-setup

Staging y producción para quien nunca desplegó nada: una guía, la automatización y la prueba de cada paso.

Cómo funciona

Qué hace

  1. Escribe una guía de despliegue con un checklist por entorno, en palabras simples.
  2. Hace lo que no necesita tus credenciales: apps en Fly.io, configuración, entornos de GitHub con aprobación para producción, tokens de despliegue.
  3. Te guía con las cuentas, los inicios de sesión, el pago y tus propias claves; nunca escribe una credencial.
  4. Verifica cada paso de verdad y lo muestra en el tablero.

Cuándo

Después del esqueleto, antes del primer release, o cuando un entorno no está listo.

/keelokit:ship-release

Una versión de tu producto que se puede nombrar, leer y a la que se puede volver.

Cómo funciona

Qué hace

  1. Elige la próxima versión según lo que entró: cosas nuevas, arreglos, cambios que rompen.
  2. Escribe notas de versión que un usuario entiende, cada línea atada a su historia o hallazgo.
  3. Crea el tag vX.Y.Z en main, solo después de tu sí.
  4. Producción se despliega solo cuando una persona lo aprueba en GitHub; sigue el despliegue hasta el final.

Cuándo

Terminó una ola y el último bug bash está limpio.

Harness

Mantener el harness al día

/keelokit:harness-upgrade

Mantenimiento del harness, no de tu app: trae a tu proyecto las reglas y controles nuevos de Keelokit.

Cómo funciona

Qué hace

  1. Compara la versión del harness de tu proyecto con la nueva.
  2. Aplica los cambios de la plantilla en una rama: reglas, doctor y guard, CI, hooks, configuraciones base.
  3. Nunca reescribe el código del producto: las apps, las migraciones, los tests de punta a punta y las traducciones quedan como están.
  4. Resuelve conflictos, corre todos los controles y te consulta por cualquier regla nueva que falle.

Cuándo

Después de actualizar el plugin, o cuando el tablero dice que el harness quedó atrás.

−24 m

Nuevo en 0.8

Una página para trabajar, un reporte para compartir

/keelokit:project-dashboard arma una página corta desde tu repo, en tu idioma: dónde está el proyecto, el próximo paso, lo que te espera. Se mantiene en vivo y es liviana: se publica una vez y cada actualización cambia la página abierta sin volver a pasarla por el chat, así que seguir un proyecto gasta muy pocos tokens. Para otra persona, /keelokit:project-report genera el estado completo, de solo lectura, para compartir o exportar.

Fleetly, una app móvil de ejemplo para flotas de reparto, a mitad de la construcciónVer en tamaño completo
Una página para trabajar, un reporte para compartir: Fleetly, una app móvil de ejemplo para flotas de reparto, a mitad de la construcción
Dónde estás y qué sigue
01

Dónde estás y qué sigue

Las etapas como una línea de avance, las decisiones de ejecución que tomaste una sola vez y el único próximo paso con su comando listo para copiar.

Lo que te espera
02

Lo que te espera

Aprobaciones, las decisiones que dejó un bug bash o una revisión de seguridad con la opción que recomienda, entornos a medio configurar, actualizaciones del harness. Cada una con el link a su origen y su pedido listo.

Cada ola, cada historia
03

Cada ola, cada historia

Las historias bajo su ola de desarrollo, cada una con el link a su archivo en el repo: hecha, lista para construir (copiás su comando) o esperando a otra. Las olas terminadas se pliegan.

Salud y entornos de un vistazo
04

Salud y entornos de un vistazo

El doctor, el último bug bash y la última revisión de seguridad con lo que corrigieron, staging y producción paso a paso, y los documentos del proyecto a un clic.

Copialo o mandáselo a Claude
05

Copialo o mandáselo a Claude

Cada botón copia su pedido y llena esta caja: lo completás y lo enviás a la sesión de Claude que mira el tablero, o lo pegás en cualquier chat.

El reporte completo, para compartir o exportar
06

El reporte completo, para compartir o exportar

/keelokit:project-report muestra cada etapa con sus documentos, cada hallazgo, las decisiones y el historial. De solo lectura, como página para compartir o archivo HTML que se abre en cualquier lado.

Claro u oscuro, con un clic, y el contraste probado con WCAG AA en los dos
Claro u oscuro, con un clic, y el contraste probado con WCAG AA en los dos

−26 m

Nuevo en 0.9

Tu app en tu teléfono, con un comando

/keelokit:run-local levanta la base de datos y la API y abre tu app en un teléfono Android, un emulador o el simulador de iOS. Es el primer paso de los entornos: local, después staging y producción con /keelokit:ship-setup, y las versiones con /keelokit:ship-release.

  1. Prepara la Mac por vos

    Revisa qué falta, lo muestra todo junto y lo instala después de un solo sí. Nada se instala a tus espaldas.

  2. La segunda vez es instantánea

    Si la app ya está instalada y no cambió nada nativo, no recompila: la abre y listo.

  3. Lista para probar

    Pregunta si cargar los datos de ejemplo y muestra los usuarios de prueba para entrar.

  4. Si algo se rompe, Claude lo arregla

    Cada paso deja su log y el último error; Claude lo lee, lo repara y vuelve a correrlo. Nunca frena un proceso, un contenedor o un emulador sin preguntar.

Tu app en un teléfono AndroidSalida de ejemplo
pnpm run:local android▶ Diagnosis  ✓ Node v22.12.0  ✓ pnpm 10.33.0  ✓ Docker running  ! JDK 17▶ I am going to install/configure:    JDK 17 (brew install --cask zulu@17)   [y/N] y▶ Database and API  ✓ database on port 5432  ✓ API on port 3000 (log: .local-dev/logs/api.log)▶ Android: Galaxy S20 (USB)  ✓ already installed, nothing native changed: no rebuild  ✓ Metro running, app opened

Por ahora en macOS. Probado en un Galaxy S20 por USB y en el simulador de iOS.

−28 m

Lo que no se ve

En mi experiencia, los agentes tienden a cerrar historias y dejan un tendal de bugs en el camino, que no documentan ni explicitan. De ahí salieron estas cuatro ideas.

I

Una regla necesita un check

Cada regla apunta a algo que la verifica: un test, una regla de lint, un hook de git, un job de CI. El doctor avisa cuando una regla se quedó sin su check.

II

Lo que no se sabe queda como pregunta

Lo que nadie sabe todavía se escribe con un responsable y la pregunta exacta. No se inventan valores que suenan bien.

III

El que construye no se evalúa

Un verificador escribe los tests de aceptación antes del código, un revisor lee el diff en frío, un breaker ataca la rama, y solo el verificador puede dar una historia por terminada.

IV

Los bugs vienen en clases

Lo que siempre tiene que cumplirse (los totales cierran, un aviso sale una sola vez, un límite aguanta dos requests a la vez) se escribe como invariante y se prueba con tests de propiedades, de concurrencia y de repetición. El código crítico pasa por mutation testing, para que sus tests puedan fallar de verdad.

Pruebas, no promesas

  • Construido con sí mismo. Keelokit usa su propio harness. Un bug bash sobre su propio repo encontró 50 causas raíz, y cada arreglo dejó un control para su tipo de bug.
  • Hallazgos reproducidos, arreglos revisados. En un bug bash, cada hallazgo lo tiene que reproducir un agente que no lo reportó (dos, en los graves), y cada arreglo lo revisa uno que no lo escribió. Un arreglo rechazado se deshace; una corrida cortada sigue donde quedó.
  • El texto del repo es dato, no orden. Los agentes del bug bash reciben lo que dice el repositorio marcado como dato, así una instrucción plantada en un archivo no los puede manejar.
  • No solo apps. Mira qué es el proyecto: un producto web o móvil, o una librería, una CLI o un plugin, y revisa lo que importa en cada caso: pantallas y datos, o experiencia del desarrollador, documentación y empaquetado.
El doctor, en un proyectoSalida de ejemplo
pnpm doctorKeelokit doctor  Gates: intake ✓ → product ✓ → stack ✓ → skeleton ✓ → backlog ✓  Rules: 34 · Context gaps: 2 (0 blocking)  Invariants: 6 · Critical areas: 1 · Escapes logged: 2  Backlog: 4/11 done · next: AUTH-005, PAY-001  warn  exception for UI-1 until 2026-12-01: map SDK needs a literal colour  ERROR rule QA-1: CI job 'unit' has continue-on-error
Algunas reglas de la casa, y qué las hace cumplir
  • SEC-1Sin secretos en el repoescaneo en CI · guard · pre-commit
  • CFG-1Cada variable de config documentadaun test que compara schema, archivos .env y README
  • AUTHZ-1Cada ruta con su decisión de accesoun test que lee el router real
  • I18N-1Texto solo a través de traduccionesregla de lint · test de paridad de idiomas
  • QA-4Ningún test silenciadoguard · pre-commit
  • TRACE-1Cada escenario con su testdoctor, en CI
  • INV-1Cada invariante probado por un testdoctor, en CI
  • MUT-1Tests del código crítico que pueden fallarmutation score en CI

−30 m

Lo que corre solo

  1. Antes de cada acción de un agente

    Un guard frena secretos (claves de AWS, GitHub, Stripe, Anthropic, npm, GitLab, JWT y más, aunque vengan partidas en dos ediciones), cambios a archivos .env y a migraciones ya aplicadas, hooks salteados, tests silenciados y deploys a producción.

  2. Al empezar una sesión

    Un estado corto: dónde está el proyecto y qué historias están listas.

  3. En cada commit y push

    El mismo guard como hook de git, y después el chequeo local completo antes de que algo llegue al remoto.

  4. En CI

    Escaneo de secretos, lint y tipos, tests unitarios y de integración contra un PostgreSQL real, recorridos de punta a punta con análisis de accesibilidad y contra la API real, mutation testing del código crítico, análisis estático y deploy a staging.

El guard, frenando a un agente
git commit -m "wip" --no-verifyBlocked by Keelokit — QA-2: never bypass git hooks echo "API_KEY=…" > apps/api/.envBlocked by Keelokit — SEC-2: don't write .env files from the shell;edit .env.example, real values go in the secret store

−32 m

Dónde pasa cada cosa.

Keelokit no tiene servidor propio ni junta datos. Todo queda en tu computadora y en tus cuentas.

Tu computadora

Donde se trabaja

Ahí corre Claude Code con Keelokit. Ahí se escribe el código y se prueba la app mientras se construye.

GitHub

Guarda y controla

  • Guarda el código en un repositorio privado a tu nombre, con el historial de cada cambio.
  • Con cada cambio, un robot corre todas las pruebas y los controles. Si algo falla, no entra.
  • Pide la aprobación de una persona antes de pasar a producción.

Fly.io

Donde vive la app

El servidor en internet para la parte de atrás de la app, la que procesa pedidos, y su base de datos.

StagingUna copia de prueba. Se actualiza sola con cada cambio aprobado.
tu OK
ProducciónLa que usan tus clientes. Solo cambia cuando vos aprobás.
Hosting webEl que elijas. Ahí se publica la web y la página de presentación.
DockerUna base de datos de prueba en tu computadora, para no tocar datos reales.
Sentry (opcional)Te avisa si la app tira errores a tus usuarios.
claude.aiDonde se publica el tablero del proyecto, privado en tu cuenta.

−34 m

Ideas de las que aprendí, y una nota sobre las imágenes

Ideas de las que aprendí. El desarrollo guiado por especificaciones (OpenSpec, Spec Kit), Superpowers por separar quién construye de quién revisa, Copier por los templates que se pueden actualizar, y mucha prueba y error en mis propios proyectos.