Cockpit: el pequeño CLI que arregló mi flujo de trabajo con IA

Por Thales (Juste Gnimavo) — CEO y fundador, ZeroSuite, Inc.

En marzo publiqué un artículo extenso explicando el flujo de trabajo que uso para llevar seis productos en producción con Claude como CTO y cero ingenieros humanos. Fue el artículo más leído que he escrito jamás. Describía cinco pilares: la constitución CLAUDE.md, la arquitectura de sesiones, el desarrollo por fases, el bucle de auditoría multi-agente y la estructura de autoridad que le permite a Claude decirme que no.

Mantengo ese artículo. Esos cinco pilares construyeron sh0, FLIN, Déblo, 0fee, 0cron y 0diff. Siguen entregando código que funciona hoy.

Pero el artículo tenía un agujero que yo no veía entonces. Describía cómo llevar bien una sesión individual. No decía nada sobre cómo mantener decenas de sesiones coherentes a lo largo de meses de trabajo.

Ese es un problema aparte. También es el problema que casi rompió una sesión el viernes pasado por la tarde.

El bug que casi desperdició una sesión

El contexto. Estaba metido a fondo en la Fase 4.6 de Conductor, nuestro espacio de trabajo de IA interno. La sesión del día era la Sección C de esa fase, una superficie de API de conversación. La sesión anterior, dos días antes, había entregado la Sección B (el esquema de la base de datos). Abrí una sesión nueva de Claude Code, escribí /next y observé al agente empezar a ejecutar.

Unos 90 segundos después, el agente hizo una pausa. Había leído el cockpit (el archivo de estado que explicaré en un momento) y notado algo que yo no había visto.

state.json.next_prompt apunta al padre PHASE-4.6-WORKSPACE-V1.md, pero el sub-prompt redactado en el commit más reciente es PHASE-4.6C-CONVERSATION-API.md y next_phase nombra la Sección C. Ejecutar el sub-prompt C es la verdadera rebanada siguiente.

El cockpit había derivado. Los metadatos que actualicé al final de la sesión B apuntaban al archivo equivocado. El agente lo detectó cruzando dos campos. Si no lo hubiera hecho, si el agente hubiera ejecutado a ciegas lo que next_prompt nombraba, habría desperdiciado la sesión rehaciendo el alcance de un prompt padre que ni siquiera estaba en cola.

Este es el modo de fallo que mi artículo de los cinco pilares nunca describió. Cada sesión por separado era sólida. La entrega entre sesiones era un copiar-pegar manual y propenso a errores que funcionaba el 95 % de las veces y se rompía silenciosamente el 5 % restante. El coste de ese 5 % no era un error de sintaxis. Eran treinta minutos de confusión, una dirección equivocada tomada y una erosión silenciosa de la confianza en el cockpit mismo.

Me quedé con el problema durante una hora. Después construí la corrección. La libero esta noche como open source bajo licencia MIT. Cualquiera que lea esto puede instalarla en 30 segundos y usarla en cualquier proyecto.

Se llama Cockpit. Abajo está qué es, por qué funciona y por qué creo que cada desarrollador que lleva sesiones impulsadas por IA necesita algo así.

Qué es realmente un cockpit

Llevo usando la palabra «cockpit» informalmente en nuestros repos desde hace unos tres meses. La idea es pequeña: un directorio en la raíz de cada proyecto que responde a la pregunta «dónde estoy, qué estoy haciendo, qué viene después» sin obligar al agente a releer el código.

Un cockpit contiene seis archivos markdown, un archivo JSON y una carpeta de templates:

state.json es la fuente única de verdad legible por máquina. current_phase, next_phase, next_prompt, last_session_id, last_commit, phases_shipped, migrations_applied. Cada campo es un hecho. Los agentes lo leen antes de hacer nada.

now.md es el foco legible por humanos. Un párrafo que describe qué se acaba de entregar, qué hay que hacer a continuación, qué NO hay que hacer. Actualizado al cierre de cada sesión. El yo futuro lee ese párrafo y reconstruye su estado de trabajo sin leer una línea de código.

roadmap.md es la superficie hacia adelante: Next-3, en vuelo, bloqueado, en cola, entregado-esta-semana, marcador de fases. Referencia los prompts bajo docs/plan/sessions/ y los logs bajo session-logs/.

architecture.md numera los segmentos del código (R1, A2, T3 y así sucesivamente) para que una sesión pueda delegar por ID («audita T3», «extiende A2») en lugar de por directorio.

carte.md es una vista panorámica en ASCII de cómo encajan rutas, libs y la BD. Visión de un vistazo, sin scroll.

README.md son los protocolos de inicio y cierre de sesión, escritos para el agente que está a punto de actuar sobre este cockpit.

templates/ alberga tres esqueletos canónicos: session-prompt.md, session-log.md, audit-brief.md. Todo borrador de sesión nuevo arranca desde ahí.

Quizá 1000 líneas de markdown a lo largo de la vida del proyecto. Cuesta entre 3 y 5 mil tokens cargarlo (aproximadamente 1k vía la nueva CLI status). Cuesta noventa segundos actualizarlo al cierre de sesión.

Esa fue la forma durante tres meses. Funcionaba.

Lo que faltaba, y lo que el bug del viernes pasado sacó a la luz, era una puerta verificable por máquina. La disciplina del cockpit era 100 % manual. Si olvidaba bumpear un campo, nada me pillaba. El agente al inicio de la sesión confiaba en lo que decía state.json, y state.json decía lo que el yo anterior había tecleado, y el yo anterior había estado distraído.

La corrección también es pequeña en espíritu, aunque no en líneas: un validador TypeScript de un solo archivo (unas 500 líneas hoy) que compara state.json contra el sistema de archivos y contra git, sale con 1 ante cualquier inconsistencia, e imprime una pista → fix por cada hallazgo. Ejecútalo antes de cada push. El día que lo saltes es el día que entregas un archivo de estado que miente.

Qué atrapa el validador

Lo construí un viernes por la tarde. Atrapa nueve modos de fallo que he observado en tres meses de deriva del cockpit en ZeroSuite:

state.json.next_prompt apunta a un archivo inexistente. La sesión olvidó redactar el siguiente prompt.
state.json.next_prompt apunta a un prompt con status: shipped. El bug exacto que me costó media hora. El cockpit nunca se bumpeó después de la sesión anterior.
state.json.last_session_id no mapea a un archivo de session-log. El log nunca se escribió.
state.json.last_commit no se encuentra en git log. SHA falso, rama borrada, errata.
state.json.phases_shipped[] tiene duplicados. El protocolo de cierre se ejecutó dos veces.
state.json.migrations_applied[] no coincide con drizzle/*.sql. Una migración se entregó sin bumpear el estado, o el estado lista un fantasma.
Un prompt de sesión tiene status: shipped pero session_log: pending. El flip al cierre se hizo con desidia.
El session_log: de un prompt entregado apunta a un archivo inexistente. Errata o renombrado.
Cambios sin commitear en cockpit/, docs/plan/sessions/ o session-logs/. Una sesión anterior olvidó el paso del commit.

Cada hallazgo imprime una línea → fix para que la siguiente sesión pueda resolverlo sin releer la documentación:

cockpit:check · 22 PASS · 1 WARN · 1 FAIL
──────────────────────────────────────────────────────────────────────
  FAIL  next_prompt is already SHIPPED · docs/plan/sessions/PHASE-4.6C-CONVERSATION-API.md has status: shipped — cockpit was not bumped after that session
        → either (a) update state.json.next_prompt to the real next slice, or (b) re-execute the shipped prompt explicitly
  WARN  last_commit is in history but not at HEAD · state=81a5138 HEAD=e8795b1
        → bump state.last_commit to e8795b1 if the new commits are uncockpitted work

✗ 1 drift detected. Fix before push.

Esa es toda la superficie de interacción. Sin dashboard. Sin SaaS. Sin login. Conéctalo a un hook pre-push, a tu CI, a un target en Makefile, lo que encaje con tu proyecto. Código de salida 1 si hay deriva, 0 en caso contrario.

Prueba de campo: dos proyectos en producción, 90 segundos cada uno

Antes de subir la 0.1.0 a npm, ejecuté npx @justethales/cockpit init contra dos proyectos ZeroSuite vivos que llevaba semanas sin abrir. El mismo comando, dos formas muy distintas. Ambos sacaron a la luz bugs concretos en menos de dos minutos.

Prueba 1 — 0seat.dev (SvelteKit + Prisma, un proyecto que llevaba seis semanas en pausa)

El proyecto es una app SvelteKit 2 + Prisma 6 + Stripe + Anthropic SDK, originalmente extraída de un monorepo Solid.js + Bun + InstantDB en marzo. Último commit 2eaf2dd el 31 de marzo. No lo había tocado desde entonces.

Ejecuté:

bashcd ~/ZeroSuite/0seat.dev
npx @justethales/cockpit@latest init
npx @justethales/cockpit@latest status
npx @justethales/cockpit@latest check

Tres hallazgos en 90 segundos, todos los cuales había olvidado:

REFACTORING-PLAN.md llevaba dos meses sin commitear en el árbol de trabajo. El plan pedía migrar desde InstantDB hacia Prisma. El mensaje del commit más reciente decía "going to start added real instantdb client". El plan y el trabajo estaban en desacuerdo. Ningún archivo en el proyecto te decía cuál era el vigente. El campo next_prompt del cockpit me forzó a elegir. (Elegí Prisma — ganó el plan.)
Ocho archivos sin trackear (.auth-keys/, _logs/, 0seat.zip, .nx/, .vscode/, y tres más) llevaban pudriéndose en silencio. cockpit status los sacó a la luz en una sola pantalla.
El CLAUDE.md eran 17 KB de prosa de marketing («The Four-Engine AI-Mesh System»), cero reglas de ingeniería. El desajuste se hizo evidente en cuanto cockpit/now.md me pidió escribir un párrafo de foco y me di cuenta de que no tenía dónde ponerlo.

El check pasó de 8 PASS · 2 FAIL (esqueleto recién generado) a 14 PASS · 0 FAIL · 1 WARN después de cablear el last_commit real, redactar un prompt PHASE-1-PRISMA-AUTH-MAGIC-LINK.md real, y rellenar retroactivamente un session log para el trabajo de marzo. Tiempo total transcurrido: menos de cinco minutos.

Prueba 2 — Poponi (Rust + React Native + SvelteKit + Python, sin git)

Poponi es la app de moto-taxi por voz de Abidjan. Multi-stack: microservicios Rust en el backend, cliente y apps pro en React Native, dashboard SvelteKit, servidor de voz Python (Pipecat + Ultravox), infra. Último mtime de archivo: 15 de abril. Seis semanas de silencio.

Ejecuté los mismos tres comandos. Cockpit imprimió de inmediato branch (no git) · HEAD (no git) — y me di cuenta del peor estado posible. El proyecto local no tenía ninguna carpeta .git, ni en la raíz, ni en ninguno de los seis subdirectorios. El repo privado de GitHub en github.com/zerosuite-inc/poponi-source-code sí existía — lo había creado hace meses con la intención — pero nunca se había inicializado localmente y nada se había subido jamás. La página del remote seguía mostrando las instrucciones por defecto de configuración rápida git init / git add / git commit / git push. Seis semanas de microservicios Rust, cliente y apps pro React Native, dashboard SvelteKit y servidor de voz Python vivían exclusivamente en este portátil. Un café derramado y el proyecto desaparecía.

Cockpit no lo arregló automáticamente. Pero en el momento en que su cabecera de status dijo (no git), noté algo que llevaba semanas perdiéndome. El remote estaba creado, el local nunca ocurrió, nada en ninguno de los dos lados levantaba una bandera.

Lo arreglé en el acto. Misma sesión, diez minutos después del descubrimiento: auditoría de secretos (.env ya estaba en .gitignore, sin claves hardcodeadas en el código, sin JSON de service-account en el árbol), git init -b main, 151 archivos staged, único commit monolítico cf1b77c titulado «initial commit — 6 weeks of multi-stack scaffolding», remote añadido, git push -u origin main. El repo ya no es un punto único de fallo. El coste fueron diez minutos que llevaba semanas evitando porque nada me recordaba gastarlos.

El segundo hallazgo fue que el propio claude.md del proyecto exige una carpeta work-sessions/ con un ciclo de auditoría de cuatro fases para cada feature. La carpeta no existe. La disciplina está documentada en la constitución pero nunca se hace cumplir. La forma session-logs/ del cockpit es la corrección con un 90 % de solape; apuntar a ella forzó la pregunta obvia — ¿estoy escribiendo los reportes o no?

check --no-git descartó correctamente las cuatro aserciones dependientes de git y ejecutó las de metadatos. Los dos fallos reales (sin prompt redactado, sin log escrito) eran ambos legítimos. La CLI degrada con elegancia cuando git no está.

El patrón que ambas pruebas revelaron

El valor de cockpit no está en las líneas de TypeScript. Está en las preguntas que el esqueleto te fuerza a responder:

¿Cuál es la siguiente rebanada concreta? → redacta el archivo o falla.
¿Dónde está el último session log? → lo espera en disco o falla.
¿En qué commit estás anclado? → coincide con git log o falla.
¿El árbol de trabajo está lo bastante limpio para hacer push? → avisa si no.

En ambas pruebas, las preguntas eran el valor. El validador era solo la parte que se negaba a dejarme saltarlas.

Las otras dos piezas

Una vez que el validador existía, me di cuenta de que resolvía un segundo problema que aún no había nombrado: los templates como conocimiento implícito.

Cada sesión produce tres artefactos: el prompt de sesión (redactado al final de la sesión anterior), el session log (escrito al final de esta sesión), y el audit brief (usado para lanzar el agente de auditoría post-implementación). Los tres tenían una forma (formato de frontmatter, orden de secciones, bloques obligatorios como «Observed divergence») que había refinado a lo largo de once sesiones. Las nuevas sesiones descubrían la forma copiando el archivo previo más reciente. Lo que significaba que las rarezas del archivo previo más reciente se propagaban. Lo que significaba que la forma derivaba.

El cockpit ahora entrega esos tres esqueletos bajo cockpit/templates/. Cópialos cuando redactes un artefacto nuevo. La forma se mantiene estable porque ya nadie está copiando del anterior. Todo el mundo copia desde la misma fuente canónica.

La tercera pieza es pnpm cockpit:status: una instantánea en una pantalla del estado del proyecto, imprimible en unos 300 ms, que reemplaza los cuatro o cinco comandos cat que solía ejecutar al inicio de sesión. Imprime el nombre y la versión del paquete, la rama git y HEAD, la fase actual y la siguiente, el estado del próximo prompt y una vista previa, los últimos 10 commits, el foco actual desde now.md, y el Next-3 desde roadmap.md. Consciente del color, consciente del TTY, se porta bien en una sesión de Claude Code o en una terminal normal.

Esa es toda la superficie de CLI hoy: cockpit init (esqueleto), cockpit status (leer), cockpit check (validar), cockpit new prompt|log (template). Cuatro verbos. Cada uno hace una cosa. Ninguno hace nada mágico.

Por qué lo libero como código abierto

Tres razones.

Primero, es lo bastante pequeño para leerlo. Los dos scripts TypeScript suman unas 700 líneas en total, más tres templates y un README. Puedes leerlo todo en treinta minutos y entender exactamente qué hace. Sin algoritmo propietario, sin indexación astuta, sin complejidad oculta. Si dejara de existir mañana, podrías reescribirlo en una tarde.

Segundo, el valor vive en la disciplina, no en la herramienta. La herramienta solo hace que la disciplina sea verificable por máquina. Separar el estado de sesión del estado del proyecto, redactar el siguiente prompt al cierre de cada sesión, validar antes del push: esas reglas funcionan independientemente de qué herramienta las haga cumplir. Toma la disciplina y usa mi herramienta o construye la tuya. Cualquiera de las dos salidas está bien. La mala salida es llevar sesiones impulsadas por IA sin ninguna disciplina, que es lo que veo hacer a la mayoría de los equipos hoy.

Tercero, el patrón está ausente del panorama. Leo artículos sobre flujos de trabajo con IA cada semana. He visto exactamente cero que describan la gestión del estado de sesión. Describen prompts, herramientas, sub-agentes, system messages, selección de modelo: cada capa excepto la que importa cuando estás llevando la sesión 47 de un proyecto que empezó en febrero. El cockpit llena ese hueco.

Dónde encontrarlo:

Código en GitHub (en vivo, licencia MIT): github.com/justethales/cockpit-skill
Paquete npm: @justethales/cockpit en npmjs.com. Instala con npx @justethales/cockpit init en cualquier directorio de proyecto.

Cero llamadas de red, cero telemetría, cero autenticación.

Qué significa esto para los cinco pilares

El artículo original describía cinco pilares: CLAUDE.md, arquitectura de sesiones, desarrollo por fases, bucle de auditoría multi-agente, y estructura de autoridad. Esos pilares siguen siendo correctos. Cockpit no es un sexto pilar. Se sitúa debajo de ellos como el tejido conjuntivo entre sesiones.

El CLAUDE.md le dice a Claude cómo ser un CTO. La arquitectura de sesiones le dice a Claude cómo trabajar en una feature. El desarrollo por fases le dice a Claude cómo descomponer un problema. El bucle de auditoría le dice a Claude cómo verificar su propia salida. La estructura de autoridad le dice a Claude cuándo negarse.

El cockpit le dice a Claude qué día es en la vida del proyecto, qué se hizo ayer, qué toca hoy, y si la entrega desde la sesión de ayer está intacta. Sin el cockpit, los cinco pilares funcionan para una sesión. Con el cockpit, funcionan para meses de sesiones encadenadas.

Si leíste el artículo original y construiste tu propia versión del flujo de trabajo, probablemente ya tienes una versión informal del cockpit: un STATUS.md, un NEXT.md, el hábito de escribir session logs. Lo que libero hoy es esa versión informal formalizada, validada y hecha compartible.

Cómo adoptarlo

Tres caminos, según dónde te encuentres.

Si aún no tienes flujo de trabajo con IA: lee primero el artículo de los cinco pilares. El cockpit es una capa sobre los pilares. Sin los pilares, el cockpit es solo un state.json sin sesiones que gestionar. Construye el flujo de trabajo primero.

Si tienes un flujo de trabajo pero no cockpit: ejecuta npx @justethales/cockpit init en la raíz de tu proyecto. Genera el directorio cockpit/ con los templates prerrellenos, deja los dos scripts de CLI en su sitio, y te dice las cuatro líneas que necesitas añadir a tu package.json. Edita cockpit/now.md y cockpit/state.json para describir dónde estás de verdad. Empieza tu siguiente sesión con npx @justethales/cockpit status en lugar de pegar el mensaje final de la sesión anterior. Notarás la diferencia en la tercera sesión.

Si ya tienes una disciplina tipo cockpit: genera un esqueleto en un directorio temporal con npx @justethales/cockpit init, compara lo que entrega con lo que tienes, toma las piezas que te faltan, ignora las que has mejorado. El validador es la pieza más portable. Atorníllalo a la forma que ya hayas construido.

Qué queda abierto

La revisión honesta de mi propio trabajo, la misma revisión que sacó a la luz el bug del viernes pasado, identificó cuatro debilidades que aún no he abordado:

El cockpit ensucia git log con commits chore(cockpit):. Cada bump de state.json es su propio commit. A lo largo de un año de sesiones, eso es ruido en el changelog. Aún no lo he resuelto. Los dos caminos son: mover el cockpit a una rama huérfana, o aceptar el ruido.

El validador atrapa deriva de metadatos, no deriva de intención. Si now.md miente sobre qué se construyó, el validador no lo pillará. Nada lo hará, excepto los humanos y la auditoría post-implementación. Creo que esto es fundamental.

La CLI es Node-only. Los proyectos en Python, Rust, Go pueden lanzarla vía npx pero pagan una dependencia de Node que de otra forma no querrían. Una distribución binaria es un port de un día si existe la demanda. Por ahora no existe.

Sin camino de rollback. Si una sesión entrega una fase que resulta estar rota en producción, el cockpit no tiene concepto de «Sección C desentregada, revert y reintentar». state.json retrocede a mano. Aún no lo he necesitado. El día que lo necesite, tendré que inventarlo.

Libero estas limitaciones conocidas porque ocultarlas sería deshonesto. El cockpit es bueno. No está terminado.

El punto más grande

Escribo esto un viernes por la noche en lugar de entregar más código porque creo que el patrón importa más que la herramienta.

El desarrollo de software entra en una fase en la que el cuello de botella ya no es la velocidad de tecleo, la intuición arquitectónica, ni la capacidad de leer un stack trace. El nuevo cuello de botella es la capacidad de mantener un estado coherente a través de flujos de trabajo impulsados por IA que duran largo tiempo. Los desarrolladores que averigüen cómo mantener decenas de sesiones alineadas, sin quemar horas a la semana en reconstrucción de contexto, entregarán más y se preocuparán menos que los que sigan tratando cada sesión como un comienzo desde cero.

El cockpit es una respuesta a ese problema. Probablemente hay otras mejores. El problema en sí no está en duda.

Hace cinco meses escribí que la forma en que usas Claude es la razón por la que no obtienes lo que quieres de él. Hoy lo enmendaría: la forma en que gestionas el estado entre sesiones es la razón por la que no estás entregando. Arregla el problema de gestión de estado y el resto se vuelve más fácil.

El cockpit es gratis. La disciplina es el precio.

Recursos

Artículo original del flujo de trabajo: Flujo de trabajo en cinco pilares
Repo en GitHub (licencia MIT): github.com/justethales/cockpit-skill
Paquete npm: @justethales/cockpit — npx @justethales/cockpit init
Issues y feedback: github.com/justethales/cockpit-skill/issues
Yo en X: @JusteThales

Si esto te ahorra media hora a la semana, ya es suficiente. Si te ahorra más, cuéntamelo. Quiero saber qué modos de fallo atrapa que no he anticipado.

— Thales Abidjan, Costa de Marfil 2026-05-30