versatile.sh
Una pequeña organización llevada como side project: motores independientes, una forma compartida de trabajar con agentes de IA y los harnesses que mantienen honestas a ambas.
Visión general
versatile-sh es la organización que llevo como side project. Está construida en torno a una idea: motores independientes. Cada motor hace un trabajo (workflows durables, un motor de pruebas, un motor de cómputo, un protocolo de plugins), mantiene un núcleo neutro que no nombra ningún producto y puede usarse sin los demás.
La organización es también una forma de trabajar. Un equipo pequeño trabaja con agentes de IA, y el equipo aprende una sola vez: lo que una persona enseña a un agente se convierte en una regla, un registro o un lint compartidos en lugar de vivir en la memoria de una máquina.
Este caso describe esa forma de trabajar en sentido seguro para lo público: la estructura, los flujos y las compuertas. Los repositorios de los harnesses son privados, así que sus rutas se nombran pero no se enlazan. Los motores aparecen por nombre en clave: nagare (workflow durable), hakoniwa (motor de pruebas), heya (motor de cómputo), tsugite (protocolo de plugins).
| Parte | Qué es |
|---|---|
| Motores | Repositorios independientes con núcleos neutros, cada uno con su hogar de registros |
| Sitio de la empresa | Export estático de Next.js 16, Tailwind CSS 4 y TypeScript, con directorios de conectores y skills y formularios |
| Harness central | Cómo trabaja el equipo: router, docs de workflow, skills, agentes, comandos, hooks, herramientas |
| Harnesses satélite | Conocimiento de ingeniería y registros de proyectos, configuración de infraestructura, motor de investigación, medios |
Primeros pasos
Un colaborador clona el harness central y los satélites que necesita, lado a lado, y luego ejecuta dos herramientas. bin/sync deja todo al día. bin/install enlaza los skills, agentes y comandos en cada checkout.
bin/sync # fast-forward clean checkouts on main; move read copies to each satellite's main
bin/install # link skills, agents, commands into each versatile-sh checkout
bin/install --with-hooks --with-timer # team hooks and a daily sync + harvest timer
bin/conformance # what each repository misses from the baseline- bin/install escribe un symlink por cada skill, agente y comando, listado en el .git/info/exclude de cada proyecto para que no se versione nada en un proyecto.
- Un elemento propio del proyecto con el mismo nombre gana sobre uno enlazado.
- bin/install crea un área local/ que nunca se sube, para todo lo que no es parte de la organización, y construye una lista de exclusión personal a partir de tus otros checkouts.
- bin/sync es idempotente: ejecutarlo dos veces no cambia nada la segunda vez. Nunca hace stash, reset ni cambia de rama.
- --bump registra el main actual de cada satélite como puntero del submódulo, mediante un pull request.
El sitio de la empresa corre con mise, que instala Node.js, pnpm y Bun.
mise run install
mise run dev # pages on http://localhost:3000, without the forms API
mise run build # static export into out/
mise run preview # out/ plus the forms API| Variable | Usada por | Efecto |
|---|---|---|
| DATA_DIR | servidor del sitio | Dónde se guarda la base de datos de formularios |
| CATALOG_DIR | tareas del sitio | Checkout del catálogo que leen mise run catalog y mise run skills |
| VERSATILE_CONFORMANCE=off | bin/sync | Omite la línea de resumen de conformidad |
Arquitectura
El harness central es el único lugar que lo reúne todo. Cada otro harness es un satélite con su propio repositorio, incorporado como submódulo git bajo harness/ en el central. Nada se copia.
versatile-sh/.claude (center: how we work)
router, docs/work, skills, agents, commands, bin, hooks
|
+-------------------+--------------------+--------------------+
| | | |
versatile-harness hosting-harness research-harness <domain>-media
engineering rules infra + deploy method, studies, canonical images,
project records config per app generated home video, logos
|
+-- projects/<repo>/ profile, agents.md, adr/, roadmap, issues
project repositories: the product only (code, tests, README)| Harness | Contiene |
|---|---|
| Central (.claude) | Cómo trabajamos: router, docs/work, skills, agentes, comandos, herramientas bin, hooks, la guía para colegas. Nunca reglas de ingeniería ni hechos de un proyecto |
| versatile-harness | Base de conocimiento de ingeniería (premisas, reglas, patrones, estándares, lints, diseño, decisiones, arquitectura, índice de investigación) y el hogar de registros de cada proyecto |
| hosting-harness | Infraestructura y configuración de despliegue de cada app |
| research-harness | El motor de investigación: método, estudios, estado, un hogar de investigación generado |
| repositorios de medios | La copia canónica de cada imagen, video, logo y fuente de diseño |
| Un repositorio de proyecto | Solo el producto, escrito como si fuera público mañana |
La verdad de un satélite es su main en GitHub. La copia bajo harness/ es de solo lectura y bin/sync la mantiene en ese main. Un cambio se hace en la copia de trabajo hermana, en una rama, mediante un pull request.
Todo lo que no es parte de la organización queda en local/ o en la memoria propia de cada persona. Lo inverso también vale: nada sobre la organización tiene la memoria personal como único hogar.
Bucle de aprendizaje
Cuando un problema se repite o alguien repite una petición, la respuesta es un protocolo fijo. La memoria en una máquina no es aprendizaje, y una regla solo en prosa volverá a romperse.
- 1Reconocer la claseNombrar el problema como una clase, por ejemplo valores de color crudos en componentes. Revisar primero los issues abiertos y el catálogo de lints.
- 2Corregir la causa raízEl cambio más pequeño que elimina la causa, no un parche sobre el síntoma.
- 3CertificarUn test que falla primero o un antes y después, más un barrido de otras instancias de la clase.
- 4Pedir confirmaciónUna línea al dueño. La certificación pertenece al agente, la confirmación al dueño.
- 5Codificar el guardSolo tras un sí explícito: un lint, check, test o ratchet, probado reintroduciendo el error una vez, y registrado en el catálogo de lints en la misma unidad de trabajo.
- 6Registrar y compartirUn pull request en el hogar compartido. Los colegas lo reciben en su próximo pull.
Si el dueño no responde, la corrección y su test de regresión se quedan, el issue se marca como corregido pero no confirmado y no se agrega ningún guard para toda la clase. Por separado, cuando una persona hace algo mejor de lo que describe el harness, se registra como práctica de campo bajo el archivo que es dueño del tema y reemplaza el texto de la regla en su segundo caso confirmado.
Compuerta del pull request
En todo repositorio de versatile-sh el trabajo llega a main solo mediante un pull request desde una rama de feature, integrado con un merge commit tras la validación local. No hay push directo, ni force-push ni reescritura de historial sin la aprobación explícita del dueño.
- 1Ramagit fetch, luego un worktree en una rama de feature desde origin/main. Los commits son granulares, uno por responsabilidad, cada uno compilando.
- 2Validar en localEl único comando de check del repositorio. Los workflows de CI son manuales y no bloquean nada, así que la evidencia en el pull request es la prueba.
- 3Checklist de conocimiento de la sesiónAntes de abrir el pull request, actualizar lo que la sesión cambió o aprendió: el README y los docs del proyecto, los registros en versatile-harness, cualquier regla, patrón o lint que surgió y el harness central si cambió la forma de trabajar. Cada uno va por su propio pull request.
- 4Registrarlobin/pr-ready guarda las respuestas del checklist para la rama. El hook sobre gh pr create retiene el comando hasta que exista ese registro. Caduca al cabo de un día.
- 5Merge y limpiezagh pr merge --merge --delete-branch, borrar la rama local, eliminar el worktree, todo en la misma unidad de trabajo. Se informa al dueño en el chat de lo que se actualizó, con enlaces.
La compuerta es simbólica y falla abierta. Se satisface solo haciendo el checklist, no se aplica a los propios repositorios de harness y deja pasar cualquier otro comando.
Método de investigación
Las decisiones reales pasan por un único motor, el research harness. Un estudio respalda una decisión del dueño, y un estudio que no puede nombrar su decisión no empieza. Su método se reescribió a partir de lo que la investigación anterior hizo bien y mal, y se enmienda después de cada estudio.
- 1IntakeEl dueño responde las preguntas antes de empezar cualquier trabajo, registradas con la fecha.
- 2RecuperarLo que ya está cerrado sobre el tema, con su fecha y commit.
- 3CharterDecisión, unidad de análisis, regla de juicio, niveles de prueba, pisos, alcance, asientos y presupuesto. El dueño lo libera.
- 4Ataque al marcoUn red team objeta la pregunta y las premisas antes de que exista cualquier respuesta.
- 5Inventario y exploraciónUn inventario ciego construido desde el usuario hacia afuera y desde el código hacia adentro, luego una tabla macro de candidatos. El dueño elige qué profundizar.
- 6RondasPropuestas, objeciones, decisiones, auditoría y spikes, liberados por tandas. El dueño decide tras cada tanda.
- 7Síntesis y cierreUn mapa o matriz, decisiones del dueño con recomendaciones, elementos diferidos con un disparador, una auditoría final por un auditor que no es el juez y una retro que enmienda el método.
Una pregunta acotada que una fuente resuelve es investigación puntual y se salta las rondas. Una elección dentro de una tarea recibe una matriz de decisión de diez líneas en el cuerpo del pull request, escrita antes de ejecutar los candidatos.
Premisas
Una premisa es un supuesto permanente del que parte todo diseño y que no se vuelve a discutir en cada tarea. Cada una tiene su propio archivo pequeño en versatile-harness/premises/.
| Premisa | Qué significa para un diseño |
|---|---|
| Público mañana | Todo repositorio de proyecto se escribe como si fuera público mañana |
| Núcleo neutro | Un núcleo no nombra ningún producto, cliente, proveedor ni proyecto hermano |
| Registros privados | Los registros son privados y viven en un solo lugar |
| Un artefacto, cada despliegue | Un artefacto sirve para cada despliegue |
| Los secretos son referencias | Un secreto es una referencia en todas partes salvo en el store y el proceso que lo necesita |
| Sin datos de clientes | Ningún dato de cliente, empleador ni personal en ningún sitio |
| Validación local | Ningún job remoto bloquea un pull request |
| Solo pull requests | El trabajo llega a main solo mediante un pull request |
| Evidencia antes de terminar | Nada se da por hecho sin evidencia |
| Los registros cambian con el código | La misma unidad de trabajo, el mismo flujo de pull request |
| Equipo pequeño con IA | El equipo aprende una sola vez |
| Cada harness su propio repositorio | El central enlaza satélites, nunca los copia |
Un repositorio de proyecto contiene solo el producto. Ningún ADR, runbook, investigación, configuración de despliegue, host ni proceso interno aparece en sus archivos, commits, cuerpos de pull request ni nombres de rama. Eso es lo que hace comprobable la premisa de público mañana.
Compuertas y lints
Todo cambio sube por las mismas compuertas, de la más barata a la más cara, todas en la máquina del desarrollador. Una compuerta comprueba una cosa, tiene un hogar de config y llama al único comando de check del repositorio, mise run check, en lugar de reimplementarlo.
| Compuerta | Comprueba |
|---|---|
| Editor y formato | Formato y lint rápido mientras se escribe |
| Pre-commit | Formato y lint solo de AST de los archivos staged, corregidos y vueltos a stagear |
| Pre-push y check | Linters sobre los paquetes cambiados desde el merge base; el check completo bajo demanda |
| Compuerta de conocimiento | El checklist de la sesión se registra antes de gh pr create |
| Revisión | Ejes de estándares y de spec, mediante /review o /pre-pr |
| Compuerta de merge | El commit integrado es el que selló la validación; solo donde un repositorio la tiene |
| Catálogo de lints | Un error recurrente confirmado se convierte en un lint compartido que todo proyecto activa |
| Bootstrap de repositorio nuevo | Dependabot, Semgrep, lefthook, LICENSE, SECURITY.md, estándar de README, go-lint para Go |
| Conformidad de la organización | bin/conformance lista lo que le falta a cada repositorio |
El catálogo de lints lista cada lint una vez con el problema que previene, dónde está implementado y qué proyectos lo activaron. Los ejemplos incluyen una compuerta de neutralidad para núcleos de motores, una tabla de aristas de dependencias, una comprobación de comentarios, un clock seam, una comprobación de entorno en la raíz de composición y una compuerta Semgrep con ratchet sobre el merge base. Las comprobaciones de Go vienen de un único kit compartido, go-lint.
Los pull requests de Dependabot nunca se dejan ociosos: cada uno se revisa e integra, se corrige e integra, se migra o se planifica en un issue con su versión ignorada.
Niveles de prueba
Una afirmación necesita evidencia que otra persona pueda reproducir, mostrada como antes y después, con la línea base capturada primero. Hay una sola escala, y cada celda de un ADR, estudio o matriz de decisión usa posiciones de ella.
| Nivel | Evidencia | Sirve para |
|---|---|---|
| S | Comportamiento observado en el sistema en ejecución: capturas, salida real de comandos, petición y respuesta reales | UI, comportamiento de extremo a extremo, despliegues |
| A | Un test que falló antes del cambio y pasa después | Bugs, condiciones de carrera, reglas |
| B | Tests dirigidos, comprobación de tipos, lint y build, todo en verde | Refactors, cambios internos |
| C | Leí el código y debería funcionar | Nada: no es evidencia |
| Cambio | Evidencia mínima |
|---|---|
| Feature | A, más S cuando tiene interfaz de usuario |
| Corrección de bug | A: el test que falla primero |
| Refactor | B, tests de comportamiento sin cambios y en verde |
| Configuración o despliegue | S: observado en el sistema en ejecución |
| Cambio visual | S: capturas en ancho de escritorio y de teléfono |
| Afirmación de rendimiento | S o A con números, mismas condiciones antes y después |
En los estudios, las etiquetas leído, especificado y ejecutado se corresponden con esta escala. Una afirmación leída solo es válida como un hecho sobre su fuente, con versión y fecha. Nunca es prueba de que nuestro cambio funcione.
Sitio de la empresa
El sitio es un export estático de Next.js 16 con App Router, Tailwind CSS 4 y TypeScript. Un pequeño servidor Bun reparte el export y guarda los formularios en SQLite, a partir del schema en migrations/.
- Páginas de la empresa, más directorios /connectors y /skills construidos a partir de dos catálogos de archivos simples.
- Formularios: lista de espera, contacto y envíos de conectores y skills. La validación de leads vive en lib/leads.ts.
- POST /api/leads aplica una comprobación de mismo origen, un límite de 8 KB, un honeypot y un límite de tasa por dirección.
- El servidor responde / con un espejo en Markdown cuando la petición pide text/markdown; el sitio también ofrece rutas de descubrimiento llms.txt.
- El sitio no incluye configuración de despliegue. Las reglas de diseño están en DESIGN.md.
Decisiones
| Decisión | Elegido | Descartado | Por qué |
|---|---|---|---|
| Forma de las herramientas | Un harness central más satélites como submódulos | Un monorepo; contenido copiado | Cada responsabilidad tiene su propio historial y verdad; el central enlaza, nunca copia |
| Entrega | Pull request, merge commit, validación local | Push directo; squash; compuerta de CI remoto | Main se mantiene limpio y cada merge se revierte como una unidad; un job remoto que nunca corre no bloquea nada |
| Aprendizaje | Guard tras la confirmación del dueño, registrado una vez | Solo memoria; copias por repositorio | La prosa se vuelve a romper; las copias discrepan |
| Hogar del conocimiento | Registros en un satélite privado | ADRs y runbooks en los repos de producto | Un repositorio de producto debe poder publicarse mañana |
| Investigación | Un estudio con charter, juez y auditor independientes | Una sola pasada de un agente | Una sola pasada es un borrador, nunca un resultado |
| Prueba | Una escala S, A, B, C | Escalas por documento | Todo es comparable |
| Comando de check | Un mise run check por repositorio | Makefiles y scripts ad hoc | Dos definiciones de verde se desvían |
- La compuerta de merge existe solo en algunos repositorios de producto; en los demás la evidencia en el pull request es la compuerta.
- La compuerta de conocimiento es simbólica y falla abierta si su hook da error.
- Los harnesses y varios motores son privados, así que este caso no puede enlazarlos.
- Algunos lints figuran con una implementación aún no verificada; la herramienta de conformidad informa lo que a cada repositorio todavía le falta.
Archivos
Las rutas de los harnesses son privadas y relativas a cada repositorio de harness.
.claude/CLAUDE.mdRouter del harness central: alcance, reglas innegociables, tabla de enrutamiento.claude/docs/work/01-WORKFLOW.mdEl bucle de trabajo, la matriz de decisión, la condición de parada.claude/docs/work/03-EVIDENCE.mdNiveles de prueba y antes y después.claude/docs/work/04-LEARNING-LOOP.mdProblema recurrente a guard a registro compartido.claude/docs/work/06-GIT-AND-PRS.mdReglas de git y el checklist de conocimiento de la sesión.claude/docs/work/10-GATES.mdLa escalera de compuertas.claude/bin/syncActualiza checkouts y copias de lectura de los satélites.claude/bin/installEnlaza skills, agentes, comandos; hooks y timer.claude/bin/conformanceComprobación de la línea base en toda la organizaciónversatile-harness/premises/00-INDEX.mdÍndice de las premisas permanentesversatile-harness/rules/00-INDEX.mdÍndice de reglas de ingenieríaversatile-harness/lints/00-INDEX.mdEl catálogo de lintsresearch-harness/docs/methodology.mdReglas de estudio, etapas y niveles de pruebaversatile.sh/lib/leads.tsValidación de leads del sitioversatile.sh/DESIGN.mdReglas de diseño del sitio