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

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

Por ahora el repo es privado: dejando tu correo te avisamos cuando se abra.

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"] } } }

Estado y alcance

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

Versión 0.7.0, pre-release. El repo es privado y el paquete todavía no está publicado.
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.
Sitio de documentación

La instalación, los conceptos, los gates, el flujo con agentes y la referencia de la CLI ya están escritos y esperan un deploy.
Slides de la charla

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

Novedades cuando salga

Poco volumen, nada de marketing: un correo cuando Substrate llegue a npm, otro cuando se abra el repo, y alguna nota de release de vez en cuando. Nada más.

Privacidad

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

Ejemplo: board de delivery webgithub.com/42pe/substrate/tree/main/examples/web-delivery

Código

Charlas y escritos

Diego Ferreyradiegoferreyra.com