Substrate v0.7.0 · pre-release
ES EN

Tu proceso de desarrollo, fuera de la cabeza del agente.

Substrate es un gestor de trabajo local-first que vive en tu repo y que tus agentes de código manejan por MCP. El proceso se define una sola vez, como datos: así todos los agentes —esta sesión y la siguiente— leen el mismo estado durable y pasan por los mismos gates en el momento de escribir.

Ver la documentación Ver en GitHub

La v0.7.0 es pre-release: todavía no está en npm, así que hasta que salga se instala desde el código fuente.

¿Por qué no una lista de tareas, un CLAUDE.md o GitHub Issues?

Hay dos cosas que esas opciones no pueden hacer, y son toda la razón por la que Substrate existe.

La lista de tareas de la sesión se evapora

Las listas de tareas propias del runtime del agente son por sesión. Cuando se reinicia el contexto, se pierde todo lo que el agente sabía sobre el estado del trabajo.

Un archivo de convenciones se desdibuja

Un CLAUDE.md es durable pero no tiene estructura, y es solo una recomendación: a medida que se llena el contexto, los agentes se van alejando, y nada les avisa en el momento en que lo incumplen.

Los issues viven fuera del repo

GitHub Issues es durable y estructurado, pero está fuera del árbol de trabajo: es una ida y vuelta que el agente tiene que acordarse de hacer, y no modela tus gates.

El estado de Substrate vive en .substrate/, al lado del código. Una sesión nueva —o un segundo agente— lee exactamente en qué punto está el trabajo y qué gates faltan, sin tener que deducirlo del git log.

Cómo funciona

Un solo binario en tu proyecto. Dos procesos, un directorio, todo local.

Substrate-as-code

.substrate/boards/*.json define los boards, los grupos, tu propio field_schema y las políticas. Se commitean junto con el código y se leen de nuevo en cada llamada: al editar el JSON, el cambio aplica al instante. Sin migraciones ni cascadas.

El estado de ejecución, en SQLite

Las tareas, los comentarios y un log de eventos append-only viven en una base SQLite local (libsql, modo WAL, seguro para agentes concurrentes). Está en el .gitignore: el estado de ejecución se queda en tu máquina.

Una web UI de solo lectura

substrate serve levanta un inspector solo en localhost: un kanban en vivo que se refresca solo, así que cuando un agente mueve una tarea se ve a los pocos segundos. Solo observa: nunca escribe, y no hay drag-and-drop.

Todo lo que Substrate agrega a tu proyecto: 
.substrate/
  config.json          # project id + name
  boards/*.json        # boards, groups, field_schema, policies, team  (committed)
  members/*.json       # optional team registry                        (committed)
  data.sqlite          # tasks, comments, event log                    (gitignored)
  attachments/         #                                               (gitignored)
  logs/substrate.log   # warnings + errors from mcp/serve              (gitignored)

El JSON se commitea. La base de datos y los adjuntos quedan en el .gitignore por defecto.

Gates que se disparan al escribir

Dos clases de políticas. Ese es todo el modelo.

transition_guard — bloquea

Bloquea el pase de un grupo a otro cuando falta un campo requerido y le devuelve transition_blocked al agente en el mismo instante de la escritura, nombrando el campo que falta.

agent_responsibility — sugiere

Adjunta sugerencias no bloqueantes a las escrituras que coinciden. Cada escritura devuelve un envelope con la lista de políticas que se dispararon.

human_only — la compuerta que un agente no puede abrir

Marca un campo como human_only y las herramientas de escritura del agente se niegan a asignarlo: solo una persona puede, desde la CLI. Un guard que lo exige es una firma que un agente sin supervisión no puede darse a sí mismo.

Lo que recibe el agente cuando intenta saltarse una etapa: 
{
  "ok": false,
  "error": {
    "code": "transition_blocked",
    "message": "Policy 'tests-before-review' blocks moving from 'Build & Test' to 'Review'.",
    "details": {
      "policy_id": "pol_01HX…",
      "from_group": "Build & Test",
      "to_group": "Review"
    }
  }
}

Lo que un gate no hace

El campo que revisa un gate es autodeclarado: el agente pone tests_passing: true por su cuenta, nadie corre tus tests. Un gate es un paso de confesión, no un control: registra la afirmación y bloquea hasta que se haga, pero no verifica que sea cierta. Una barrera dura en el momento justo sigue ganándole a una recomendación escrita de la que el agente ya se alejó, pero conviene decirlo con precisión.

La barrera real: los campos human_only

Si un campo se marca human_only, las herramientas de escritura del agente se niegan a setearlo, y update_board se niega a desprotegerlo. Solo una persona puede hacerlo, desde la CLI: substrate approve <task_id> <field>. Un guard que exige un campo human_only es una aprobación que un agente sin supervisión no puede darse a sí mismo. substrate pending-approval lista todo lo que está esperando una firma humana.

Empezar

Node 20 o superior, y unos minutos.

Hoy: instalar desde el código fuente

Substrate todavía no está en npm. Hay que clonar el repo, compilarlo y linkear el binario una sola vez: después, substrate funciona igual en todos lados.

shell 
git clone https://github.com/42pe/substrate.git
cd substrate && pnpm install && pnpm build && pnpm link --global
substrate install-skill        # installs the agent skill into ~/.claude/skills/
cd /path/to/your-project && substrate init
substrate serve                # inspect at http://localhost:7475

Conectar tu agente

Agregar el servidor MCP por stdio a la config de tu runtime de agentes. A partir de ahí, el agente llama a whoami y sigue solo: 32 herramientas y un set documentado de convenciones.

.mcp.json 
{
  "mcpServers": {
    "substrate": {
      "command": "substrate",
      "args": ["mcp"]
    }
  }
}

La CLI

Cinco comandos. Todos fallan con un error claro si el directorio no tiene un .substrate/.

substrate init
Crea un .substrate/ en el directorio actual, opcionalmente con un flujo de arranque. Los tableros se commitean a git; el estado de ejecución queda fuera, en el .gitignore.
substrate serve
Levanta la interfaz web local, de solo lectura, en 127.0.0.1:7475 — y busca hasta el 7499 si ese puerto está ocupado. Un solo serve por directorio.
substrate explain
Dibuja el flujo entero como una página HTML autocontenida, con las compuertas marcadas. Lee solo los archivos del tablero: nunca abre la base, así que funciona en un clon recién hecho.
substrate pending-approval
Lista cada tarea que está esperando a una persona, con el comando substrate approve exacto para destrabar cada una. --json devuelve el agregado estructurado.
substrate approve <task_id> <field>
Asigna un campo human_only: la única escritura que las herramientas de un agente rechazan por diseño. Queda firmada en el log como persona, y no mueve la tarea — eso lo hace el agente en su próximo intento. substrate unapprove la revierte.

La referencia completa, con todos los flags y los casos borde, va en la documentación. Documentación

Estado y alcance

En qué consiste esto, antes de dedicarle una tarde.

  • Versión 0.7.0, pre-release. El paquete todavía no está publicado en npm.
  • Lo mantiene una sola persona, y es open source (MIT). El triage es más o menos semanal y no hay SLAs. Los reportes de bug con una reproducción se miran primero.
  • Node.js 20 o superior. macOS y Linux son las plataformas principales y están cubiertas por CI. Windows es best-effort —WSL es el camino recomendado— y Windows en ARM no está soportado, porque el driver de SQLite no publica un binding nativo para esa plataforma.
  • Por ahora, un solo checkout por proyecto. El estado de ejecución está en el .gitignore, así que un git worktree o un clon nuevo trae los boards pero arranca con una base de tareas vacía. Substrate avisa al iniciar cuando eso pasa, para que no te sorprenda en silencio.

Lo que Substrate no es

  • No es hosteado ni es un servicio. Solo localhost: sin cuentas, sin nube, sin telemetría, y la CLI nunca hace una llamada de red.
  • No es multiusuario. Un proyecto, una máquina. El estado de ejecución es por máquina, así que dos personas en el mismo repo no ven las tareas de la otra: el JSON del flujo se sincroniza por git, las tareas no.
  • No es un verificador. Los gates registran afirmaciones, no las comprueban.
  • No es un sistema de permisos. El team de un board es metadata descriptiva para orientarse, nunca un permiso.

Roadmap

Lo que todavía no está listo, y qué cambia cuando lo esté. Cada punto desaparece de esta lista el día que sale.

  • Publicado en npm

    Hoy Substrate se instala desde el código fuente. Cuando el paquete esté publicado, la instalación pasa a ser un solo comando npx y la configuración de MCP deja de apuntar a una ruta local.

  • Slides de la charla

    La presentación de la charla f13, publicada tal como se dio.

Novedades cuando salga

Nada de marketing, solo noticias sobre el desarrollo de Substrate.

Tu dirección va a Mailchimp, nuestro proveedor de correo, y a ningún otro lado. Sin píxeles de seguimiento, sin compartirla, sin venderla. Todos los correos llevan un link para darte de baja. Más sobre privacidad.

Otra opción, sin dar el correo: seguir los releases en GitHub.

Privacidad

Este sitio. Las analíticas vienen de PostHog: qué páginas se visitan, en qué se hace clic, más o menos desde dónde. Mailchimp carga un script propio para que el dominio cuente como conectado a la lista de correo. Entre los dos dejan cookies con identificadores al azar, para que una segunda visita no se cuente como una persona nueva. Sin trackers publicitarios, no se comparte ni se vende nada, y no se intenta averiguar quién eres. Lo único más que queda en tu navegador es la preferencia de idioma — y nada de esto alcanza a Substrate en sí, que es el punto de abajo.

La herramienta en sí. Substrate no recolecta ni envía nada. No tiene telemetría y la CLI nunca hace una llamada de red: tus boards, tus tareas y tus logs se quedan en tu máquina.

Enlaces

Usarlo

Código

Sitio del desarrollador