Keelokit

Keelokit Keelokit Harbor v0.1.0 · publicado

Sesiones que no se ven entre sí. Un convoy. Un solo push a main.

Harbor es el meta-orquestador de releases. Las sesiones de Claude Desktop, de la CLI y de la nube, en varias cuentas, no se ven entre sí. Cada una termina su trabajo en su propia rama y Harbor lo junta como releases coordinados y verificados: un skipper reúne el lote, se verifica una vez y, con el ok del harbormaster, entra a main en un solo push, en orden.

Lo armé con cientos de horas, a esta altura miles, corriendo muchas sesiones a la vez y necesitando que sigan entregando con casi nada de intervención. Es opinado y está hecho a mi manera de trabajar, así que tomá lo que te sirva.

Qué hace

Un logbook que lee cada sesión, cuentas y workers, seals, convoys de new a sail, la guardia del harbormaster, lecturas frescas antes de cada decisión y la importación única de un BOARD.md existente.

Qué necesita

Keelokit 0.12.0 o posterior en el proyecto, Python 3.11+, git y un remoto origin.

Cómo conseguirlo

Desde el marketplace (claude plugin marketplace add leosimini/keelokit-harbor), o el zip de la última versión.

−2 m

Una subida por historia no escala.

Keelokit construye una historia por sesión y la sube a main después de un verify local. Cuando las sesiones no dependen entre sí, es la cantidad justa de proceso. Cuando orquestar se complica, con sesiones en más de una cuenta, máquina o herramienta, aparecen tres costos.

  1. 01

    Un verify completo por subida

    Cada historia repite el chequeo entero antes de subir, sin importar qué más esté esperando.

  2. 02

    Nadie ve la combinación

    Dos ramas pueden estar verdes por separado y romperse entre sí. Te enterás cuando las dos ya están en main.

  3. 03

    Una corrida de CI por push

    Cada push a main dispara el CI. Donde el CI se paga, cada subida es una factura.

Solo KeelokitEl veleroUna historia, un verify, un push a main.
Keelokit + HarborEl convoyMuchos vessels, un verify del conjunto, un push a main.

−4 m

De un vessel sellado a un solo push.

Un convoy es la rama convoy/<n>: main y los vessels, mergeados. Pasa por cinco paradas y el logbook registra cada una.

  1. 1assembling

    Entra un vessel

    convoy add. La rama llega con su commit exacto y un seal verde para ese commit.

  2. 2waiting → ready

    El skipper ensambla

    convoy assemble. main y los vessels se mergean en convoy/<n>, con las migraciones en orden.

  3. 3verifying

    El ok del harbormaster

    convoy sail --ok. Elige cuánto verificar y por qué. La carga crítica espera además tu sí.

  4. 4verifying

    Un verify

    convoy verify. El convoy entero, una vez, sobre su cabeza exacta. Un arreglo es un commit nuevo en convoy/<n>.

  5. 5sailed

    Al puerto

    convoy sail. Un push a main, un fast-forward, nunca --force.

La marea

Si main se mueve mientras esperás

El ok deja de valer, porque se dio para otro contenido. Harbor mergea el main nuevo en el convoy, el harbormaster da un ok nuevo y el convoy se verifica de nuevo.

Harbor nunca hace rebase de un convoy. Cada movimiento de main queda escrito en el logbook con su causa.

−6 m

Lo que Harbor te saca de las manos.

Cinco reglas que importan, escritas como controles en lugar de dejarlas a la memoria. Cada una tiene su imagen, y al lado, lo que pasa de verdad.

logbook

El cuaderno de bitácora

El estado es una rama de git que solo escribe Harbor, harbor/log: archivos TOML con esquema fijo y páginas generadas a partir de ellos. Nunca está en main, así que escribirla no mueve main ni dispara su CI. Cada sesión, cuenta y máquina la lee con git fetch.

seal

El precinto de contenedor

Una rama entra a un convoy solo con su hash exacto y un resultado de verify para ese hash. Un commit posterior no tiene resultado: la entrega no vale hasta que se vuelva a verificar.

hotspot

El canal angosto: un barco por vez

Rutas que declarás compartidas (schema, migraciones, tipos compartidos, textos). Dos ramas que tocan la misma nunca están juntas en convoys abiertos.

watch

El relevo de guardia

Un solo harbormaster a la vez, con un heartbeat que vence. Cuando vence, cualquier sesión puede tomar la guardia, y gana el primer commit.

tope de cuenta

Una tripulación con cupo en cubierta

Cada cuenta de Claude tiene un tope de sesiones activas y una pausa. Al llegar al límite, sus sesiones traspasan lo que empujaron, con hashes, en lugar de dejar trabajo a medias.

−8 m

La tripulación.

Cuatro roles. El logbook lo escribe solo Harbor: nadie a bordo lo edita a mano.

harbormaster

El capitán de puerto, en su guardia

Una sesión a la vez da el ok para zarpar y elige el nivel de verify (changed o all), con su razón. No integra ni escribe código.

skipper

El patrón del convoy

La sesión que lleva un convoy: recibe las entregas, mergea main y los vessels en convoy/<n> y arregla la combinación.

vessel

Una embarcación, chica o grande

La rama de una sesión, hecha con build-story. Entra con su commit exacto y su seal.

convoy approve

El sí del armador

Un convoy con una historia de nivel full o un área crítica espera además tu sí, escrito en tu propia terminal y atado a ese commit.

−10 m

Si no hay nada que orquestar, no lo necesitás.

  • Keelokit solo sube cada historia a main después de su propio verify. Para una persona, o sesiones que no dependen entre sí, es menos para correr.
  • La skill coordinate de Keelokit ya cubre las sesiones en paralelo que no chocan, sin convoyes.
  • Harbor cambia cómo se sube el trabajo. Con Harbor adoptado, build-story se detiene en su propia rama y el convoy hace la subida. No es un modo que se mezcle con la subida directa en el mismo repo.

¿Cuál necesito?

−12 m

−14 m

Probarlo

Necesitás Keelokit 0.12.0 o posterior en el proyecto (.keelokit/), Python 3.11+, git y un remoto origin.

Instalalo desde el marketplace, en Claude Code:

 claude plugin marketplace add leosimini/keelokit-harbor claude plugin install harbor@keelokit-harbor

Después corré /harbor:adopt en un proyecto con Keelokit.

O descargá harbor-plugin.zip, el plugin listo para instalar: en Claude, Customize → Plugins → Upload.

Descargá la última versiónCódigo, documentación y licencia en GitHub

Cómo funciona, en detalle

Licencia MIT.