spar

Sigue aprendiendo mientras la IA escribe el código.

Revisar código terminado y convincente no te enseña casi nada. No tienes una posición desde la que juzgarlo, así que lo lees, asientes y sigues adelante.

spar te devuelve esa posición. Antes de que el agente escriba nada, tú dices dónde encaja el cambio, cómo lo harías tú y dónde fallará. Luego él lo implementa, te muestra la diferencia y anota todos los sitios en los que tu modelo se equivocaba.

Esas lagunas se acumulan formando un plan de estudios que nunca tuviste que elegir. El concepto que más a menudo se te escapa sube a la cima por sí solo, y la fricción lo sigue hasta allí, así que nunca tienes que decidir esforzarte.

Cómo se ve

› add an endpoint for cancelling an order

  spar: level 2 (skeleton), 2 open gaps on "transaction boundaries in an ORM"

  Before I write anything:
    1. Where does this belong, and why there?
    2. How would you approach it? (two sentences)
    3. Where will this go wrong?

› 1. Orders controller, calling into the service
  2. load the order, set status, save
  3. no idea

  [writes the controller, the DI wiring and the error handling,
   and leaves the one line that matters]

  // TODO(spar: decide the transaction boundary. Who opens it,
  //             and what happens if the refund call fails halfway?)

Escribes esas cinco líneas tú mismo. Luego spar done las compara con lo que el agente habría escrito y clasifica cada diferencia en una de tres categorías: has entendido mal algo, has tecleado mal algo, o tu versión es mejor. Solo las dos primeras se registran como lagunas.

Tres semanas después, en medio de un trabajo no relacionado:

spar: one gap has come due. Ask them to explain "transaction boundaries in an ORM"
in their own words at the next natural pause. Do not show them the answer first.

Responder "no tengo ni idea" está bien, por cierto. Se registra tal cual, y es una señal lo bastante fuerte como para que la siguiente tarea que toque ese concepto te pida más, no menos.

Related MCP server: Learning Assistant MCP Server

Instalación

npm i -g spar-agent
spar install                                       # finds your agents, backs up, merges
spar setup --project /path/to/repo --stack ".NET"

Esa última línea importa: no ocurre nada en un directorio que no hayas nombrado. Una instalación nueva es completamente inerte. Ni siquiera creará ~/.spar hasta que la apuntes a un proyecto.

spar install es cuidadoso con los archivos que no ha escrito él. Se fusiona con lo que ya existe, hace una copia de seguridad del archivo primero y solo reemplaza las entradas que él mismo puso. Ejecútalo dos veces y la segunda no cambia nada. Usa --dry-run para ver lo que haría.

Dónde estás

spar stats        # in the terminal
spar dashboard    # one self-contained HTML file

CALIBRATION, share of predictions that held, by week
  2026-07-13  ███████▁▁▁   67%     4/6   clean   mean level 2.3
  2026-07-20  ████▁▁▁▁▁▁   44%     4/9   clean   mean level 2.3
  2026-08-03  ████████▁▁   83%    10/12  clean   mean level 0.8
  2026-08-17  ██████████  100%     9/9   clean   mean level 0.3

CURRICULUM, concepts by weakness. The top row is what to learn next.
  * idempotency in webhooks              3 open / 3   box 1.3
    transaction boundaries in an ORM     8 open / 8   box 2.0
    EF change tracking                   0 open / 3   box 5.0

El número que importa es la calibración: la proporción de tus predicciones que no produjeron ninguna idea errónea. Deliberadamente no es un recuento de lagunas, porque un recuento solo sube, y se leería como un declive justo cuando mejoras.

Seis semanas de una incorporación ficticia a .NET. La página sigue el tema de tu sistema.

El panel es un único archivo que nunca toca la red. Sin CDN, sin fuentes web, sin librería de gráficos, y los gráficos son SVG escritos a mano. Cada número está en el marcado, así que la página se lee igual con los scripts desactivados, detrás de una CSP estricta o en una vista previa de adjunto. El script solo añade la selección múltiple a la barra de enfoque. Seguirá abriéndose, sin conexión, con un doble clic, dentro de cinco años.

No hay rachas, puntos ni insignias en ninguna parte. En una herramienta donde "no tengo ni idea" es una respuesta útil, un contador solo te enseñaría a fingir competencia.

Explicar con una imagen

spar card --layout chain --title "Predict before you're told" \
  --subtitle "The gap between your guess and what was true is worth writing down." \
  --step "you:You predict" --step "agent:AI implements" --step "you:You compare"

Una idea por tarjeta, escrita en ~/.spar/cards/. Cuatro diseños cubren la mayoría de las explicaciones: una cadena de pasos, un abanico, una secuencia entre dos partes y una comparación.

Los límites se imponen, no se sugieren. Más de cinco pasos, más de tres viñetas o un cuarto rol de color y el comando se niega a renderizar. Es deliberado, porque todo el valor de una imagen pequeña es que siga siendo pequeña, y una regla que solo vive en un prompt acaba derivando. Si no renderiza, la respuesta son dos tarjetas.

El color marca qué es algo, nunca qué paso es, así que --step "you:..." mantiene you del mismo color en todas las tarjetas que hagas. cards.theme en ~/.spar/config.json elige el aspecto: neon (el predeterminado, oscuro con cajas delineadas) o plain.

Los niveles

En los niveles 2 y 3 el agente siempre deja un test que falla, y spar rechaza la entrega si no lo hace. Un marcador sin test te da una suposición y nada con lo que contrastarla, así que la única forma de saber si tenías razón es preguntar al agente, que es la dependencia que toda la herramienta existe para romper. El test es lo que te permite trabajar solo durante veinte minutos y seguir sabiéndolo.

Configura testCommand en un proyecto y spar también ejecuta la suite en la entrega y espera que esté en rojo, porque un test que ya pasa contra un stub vacío no fija nada:

spar setup --project "$(pwd)" --test-command "npm test"

Esa comprobación está desactivada por defecto. Ejecutar la suite de otra persona automáticamente es invasivo y puede ser lento.

No hay interruptor de apagado, solo el nivel 0. Tu propio registro de lagunas sugiere el nivel y te dice por qué, y siempre puedes anularlo. Las anulaciones se cuentan, porque alguien que corrige constantemente la sugerencia te está diciendo que los umbrales están mal.

Trabajar un ticket por pasos

spar plan --from docs/plan.md          # reads ## Task / ### Task headings
spar plan --step "..." --step "..."    # or name the steps yourself
spar plan                              # where am I
spar step done --session <id>

Mientras un plan está activo, el paso es la tarea. El gate se dispara una vez por paso en lugar de adivinar a partir del silencio, cada paso recibe su propio nivel de tu registro de lagunas, y tu predicción queda vinculada al paso en lugar de a la sesión, así que sigue ahí mañana.

Esa granularidad es el punto. "¿Dónde fallará esto?" es una pregunta real sobre "añade el endpoint de cancelación" y una suposición sobre "implementa la cancelación con reembolsos", y una suposición hace que el número de calibración deje de medir nada.

spar no planifica. Tu agente lee el ticket y tu planificador lo desglosa; spar decide cuánto de cada paso es tuyo. El plan vive en .spar/ del proyecto, y spar lo añade a tu .gitignore en el momento en que lo crea.

Lo que recibe cada agente

MCP está estandarizado donde los hooks no lo están, así que el servidor llega a cualquier cliente MCP sin adaptador. Lo único que no puede hacer es el gate, porque un servidor MCP ofrece herramientas y nunca intercepta las escrituras del propio host. Esa limitación es todo el argumento para mantener adaptadores de hooks por agente, y la razón por la que los niveles voluntarios son una buena prueba pero un mal sustituto.

Instalarlo como plugin

/plugin marketplace add Lander-Parren/spar

Eso ofrece dos plugins. spar es este repo. humanizer es opcional y no es mío: es blader/humanizer, MIT, Copyright (c) 2025 Siqi Chen, fijado a un commit concreto en lugar de seguir su rama principal.

Está listado junto a spar en lugar de copiado dentro, así que se actualiza desde su propio repositorio y conserva su propio autor. La razón de que esté ahí: spar se pasa la vida explicando algo a una persona que todavía está confundida, y una explicación que se lee como escrita por una máquina es la forma más rápida de perderla. La propia skill de spar lleva una versión corta de esa regla para quienes no la instalan.

Lo que no hará

Todo se queda en tu máquina, en ~/.spar/. Sin cuenta, sin telemetría, sin llamadas de red, sin clave API propia. El registro contiene conceptos y malentendidos en lugar de tu lógica de negocio, que es lo que hace que sea seguro hacer una captura para un colega.

Y falla en abierto, siempre. Un binario que falta, una config corrupta, un bug en su propio código: el gate se abre y tú sigues. Una herramienta de aprendizaje nunca debería ser la razón por la que no puedes publicar.

Una vez por tarea, no una vez por archivo. Quince ediciones detrás de una predicción son un solo gate.

Vigila los comandos de shell además de las herramientas de escritura, porque un agente recurre a cat > file <<EOF o perl -0pi mucho más a menudo que a una herramienta de escritura dedicada, y algunas configuraciones le dicen que prefiera exactamente eso. Un comando de shell solo se detiene cuando realmente escribe en algún lugar dentro de un proyecto rastreado: redirecciones, tee, sed y perl in situ, destinos de cp y mv, y one-liners de intérpretes que abren un archivo para escribir. Las lecturas y las ejecuciones de tests pasan sin tocarse. El shell no se puede parsear con regex, así que esto es deliberadamente conservador y se pierde formas exóticas en lugar de detener el trabajo ordinario.

Una tarea sigue viva mientras haya movimiento en ella, y caduca tras 30 minutos de silencio (idleMinutes en ~/.spar/config.json). Eso mide la inactividad en lugar de la antigüedad, así que una tarea larga y cuidadosa nunca se interrumpe a mitad. Si vas a empezar algo nuevo antes de que se acabe el temporizador, spar next --session <id> lo rearma de inmediato.

El sesgo es deliberado. Rearmar en un seguimiento te cuesta treinta segundos y te empuja hacia spar rush, que es como mueren estas herramientas. Perderte una tarea cuesta una sola laguna, y ese concepto volverá a aparecer.

Una laguna vuelve al inicio de la sesión, formulada como una pregunta para la siguiente pausa natural. Nunca una cola, nunca una interrupción. Si la respondes bien, sube una casilla (1, 3, 7, 16 y 35 días). Si la respondes mal, empieza de nuevo mañana.

No hay una app aparte ni una bandeja de entrada que ignorar, porque llega en la sesión en la que ya estabas trabajando.

Probarlo sin arriesgar nada

example/ es un pequeño proyecto TypeScript sin dependencias, creado para que apuntes a él.

cd example
spar setup --project "$(pwd)" --stack "TypeScript"

Luego pide a tu agente que añada la cancelación de pedidos y observa cómo el gate lo detiene. example/README.md explica qué hay que buscar.

Dónde viven las instrucciones

Un comando emite hechos. La skill dice qué hacer con ellos. spar done imprime un diff; qué cuenta como idea errónea en lugar de errata está en la skill. El gate informa de que una tarea no ha sido gateada y nombra los comandos; por qué predices primero está en la skill.

Esa separación existe para que el procedimiento pueda ser leído por cualquier cliente compatible con skills y cambiado sin necesidad de un release. Para agentes que no pueden cargar skills, spar guide <topic> imprime las mismas secciones desde el mismo archivo:

spar guide                       # list the topics
spar guide the-closing-review

Una sola fuente, dos formas de entregarla, para que las dos no puedan divergir. Un test verifica que cada sección a la que apunta un hook existe de verdad, lo que significa que renombrar un encabezado rompe la compilación en lugar de enviar a alguien a una página que no está.

npm install
npm test              # spar's own suite
npm run build
npm run emit          # regenerate the checked-in hook configs
npm run validate:example   # drive every hook end to end against example/

validate:example es el que detecta problemas de cableado. Los tests unitarios prueban las piezas; ese script prueba que un payload de hook real produce la decisión que debería, en un home desechable, contra el binario compilado.

La misma definición de hook se comprueba tres veces: el layout de plugin de Claude Code, el namespace de Agent Plugins y el de Cursor. Los dos estándares discrepan sobre dónde pertenecen los archivos específicos del cliente, así que no hay una única ubicación que satisfaga a ambos. Los tres se generan desde src/core/hookconfig.ts con npm run emit, y un test falla en el momento en que divergen.

Licencia

MIT