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.

org · siteversatile.shside project personal (organización, repositorios mayormente privados)Forma una organización, no un repositorioSitio export estático de Next.js 16, servidor de formularios en BunForma de trabajar un harness central más harnesses satéliteVisibilidad sitio y algunos motores públicos; harnesses privadosversatile.sh

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).

ParteQué es
MotoresRepositorios independientes con núcleos neutros, cada uno con su hogar de registros
Sitio de la empresaExport estático de Next.js 16, Tailwind CSS 4 y TypeScript, con directorios de conectores y skills y formularios
Harness centralCómo trabaja el equipo: router, docs de workflow, skills, agentes, comandos, hooks, herramientas
Harnesses satéliteConocimiento 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.

Bootstrap del harnesssh
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.

Sitio de la empresash
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
VariableUsada porEfecto
DATA_DIRservidor del sitioDónde se guarda la base de datos de formularios
CATALOG_DIRtareas del sitioCheckout del catálogo que leen mise run catalog y mise run skills
VERSATILE_CONFORMANCE=offbin/syncOmite la línea de resumen de conformidad

Arquitectura

rulesstudycenterdeploymedia
El harness central es el eje; cada satélite es su propio repositorio, unido a él y nunca copiado dentro.

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.

text
          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)
HarnessContiene
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-harnessBase 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-harnessInfraestructura y configuración de despliegue de cada app
research-harnessEl motor de investigación: método, estudios, estado, un hogar de investigación generado
repositorios de mediosLa copia canónica de cada imagen, video, logo y fuente de diseño
Un repositorio de proyectoSolo 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

recordfixguardproofok?
Un problema recurrente recorre corrección, prueba, confirmación del dueño, guard y registro, y el guard evita que vuelva.

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.

  1. 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.
  2. 2Corregir la causa raízEl cambio más pequeño que elimina la causa, no un parche sobre el síntoma.
  3. 3CertificarUn test que falla primero o un antes y después, más un barrido de otras instancias de la clase.
  4. 4Pedir confirmaciónUna línea al dueño. La certificación pertenece al agente, la confirmación al dueño.
  5. 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.
  6. 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

checklistnotemain
El torniquete solo gira cuando la nota de conocimiento de la sesión está en la caja; entonces la rama llega a main.

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.

  1. 1Ramagit fetch, luego un worktree en una rama de feature desde origin/main. Los commits son granulares, uno por responsabilidad, cada uno compilando.
  2. 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.
  3. 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.
  4. 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.
  5. 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.

  1. 1IntakeEl dueño responde las preguntas antes de empezar cualquier trabajo, registradas con la fecha.
  2. 2RecuperarLo que ya está cerrado sobre el tema, con su fecha y commit.
  3. 3CharterDecisión, unidad de análisis, regla de juicio, niveles de prueba, pisos, alcance, asientos y presupuesto. El dueño lo libera.
  4. 4Ataque al marcoUn red team objeta la pregunta y las premisas antes de que exista cualquier respuesta.
  5. 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.
  6. 6RondasPropuestas, objeciones, decisiones, auditoría y spikes, liberados por tandas. El dueño decide tras cada tanda.
  7. 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/.

PremisaQué significa para un diseño
Público mañanaTodo repositorio de proyecto se escribe como si fuera público mañana
Núcleo neutroUn núcleo no nombra ningún producto, cliente, proveedor ni proyecto hermano
Registros privadosLos registros son privados y viven en un solo lugar
Un artefacto, cada despliegueUn artefacto sirve para cada despliegue
Los secretos son referenciasUn secreto es una referencia en todas partes salvo en el store y el proceso que lo necesita
Sin datos de clientesNingún dato de cliente, empleador ni personal en ningún sitio
Validación localNingún job remoto bloquea un pull request
Solo pull requestsEl trabajo llega a main solo mediante un pull request
Evidencia antes de terminarNada se da por hecho sin evidencia
Los registros cambian con el códigoLa misma unidad de trabajo, el mismo flujo de pull request
Equipo pequeño con IAEl equipo aprende una sola vez
Cada harness su propio repositorioEl 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.

CompuertaComprueba
Editor y formatoFormato y lint rápido mientras se escribe
Pre-commitFormato y lint solo de AST de los archivos staged, corregidos y vueltos a stagear
Pre-push y checkLinters sobre los paquetes cambiados desde el merge base; el check completo bajo demanda
Compuerta de conocimientoEl checklist de la sesión se registra antes de gh pr create
RevisiónEjes de estándares y de spec, mediante /review o /pre-pr
Compuerta de mergeEl commit integrado es el que selló la validación; solo donde un repositorio la tiene
Catálogo de lintsUn error recurrente confirmado se convierte en un lint compartido que todo proyecto activa
Bootstrap de repositorio nuevoDependabot, Semgrep, lefthook, LICENSE, SECURITY.md, estándar de README, go-lint para Go
Conformidad de la organizaciónbin/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.

NivelEvidenciaSirve para
SComportamiento observado en el sistema en ejecución: capturas, salida real de comandos, petición y respuesta realesUI, comportamiento de extremo a extremo, despliegues
AUn test que falló antes del cambio y pasa despuésBugs, condiciones de carrera, reglas
BTests dirigidos, comprobación de tipos, lint y build, todo en verdeRefactors, cambios internos
CLeí el código y debería funcionarNada: no es evidencia
CambioEvidencia mínima
FeatureA, más S cuando tiene interfaz de usuario
Corrección de bugA: el test que falla primero
RefactorB, tests de comportamiento sin cambios y en verde
Configuración o despliegueS: observado en el sistema en ejecución
Cambio visualS: capturas en ancho de escritorio y de teléfono
Afirmación de rendimientoS 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ónElegidoDescartadoPor qué
Forma de las herramientasUn harness central más satélites como submódulosUn monorepo; contenido copiadoCada responsabilidad tiene su propio historial y verdad; el central enlaza, nunca copia
EntregaPull request, merge commit, validación localPush directo; squash; compuerta de CI remotoMain se mantiene limpio y cada merge se revierte como una unidad; un job remoto que nunca corre no bloquea nada
AprendizajeGuard tras la confirmación del dueño, registrado una vezSolo memoria; copias por repositorioLa prosa se vuelve a romper; las copias discrepan
Hogar del conocimientoRegistros en un satélite privadoADRs y runbooks en los repos de productoUn repositorio de producto debe poder publicarse mañana
InvestigaciónUn estudio con charter, juez y auditor independientesUna sola pasada de un agenteUna sola pasada es un borrador, nunca un resultado
PruebaUna escala S, A, B, CEscalas por documentoTodo es comparable
Comando de checkUn mise run check por repositorioMakefiles y scripts ad hocDos 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ón
  • versatile-harness/premises/00-INDEX.mdÍndice de las premisas permanentes
  • versatile-harness/rules/00-INDEX.mdÍndice de reglas de ingeniería
  • versatile-harness/lints/00-INDEX.mdEl catálogo de lints
  • research-harness/docs/methodology.mdReglas de estudio, etapas y niveles de prueba
  • versatile.sh/lib/leads.tsValidación de leads del sitio
  • versatile.sh/DESIGN.mdReglas de diseño del sitio