Kumihimo

組紐 — muchos hilos entran, un cordón sale.

Kumihimo es el arte japonés de trenzar muchos hilos separados en un único cordón. Esta herramienta funciona de la misma manera: diseñas un plan como un grafo de archivos de texto plano, y Kumihimo trenza ese grafo en un único prompt bien ordenado sobre el que un LLM o un agente de codificación puede actuar.

• Vélo. kumihimo edit abre un lienzo en vivo: nodos coloreados por tipo, aristas de dependencia/membresía/anotación dibujadas de forma distintiva, arrastra para organizar, haz clic para editar. El lienzo sigue a los archivos: cambia un nodo en vim (o deja que Claude lo cambie a través de MCP) y observa cómo se mueve.

• Trénzalo. kumihimo braid compila el grafo en un único prompt determinista: ordenado topológicamente, seccionado por hitos, cada elemento indica sus prerrequisitos reales, con el diagrama Mermaid del propio grafo incrustado.

• Deja que Claude lo dirija. kumihimo mcp sirve el plan a través de MCP: once herramientas para leer, reestructurar, validar y trenzar, de modo que un agente pueda mantener el plan que ejecuta. La hoja de ruta de este propio repositorio es un plan de Kumihimo (plans/roadmap); sus prompts de hitos se trenzaron, no se escribieron a mano, y el lienzo de abajo es esa hoja de ruta la mañana en que terminó v0.1: cada hilo completado, el nodo de lanzamiento bloqueado a la espera de un humano con una etiqueta:

Los archivos son la única fuente de verdad: Markdown con frontmatter YAML, en git, con diffs limpios. El editor, la CLI y el servidor MCP son clientes ligeros sobre una única capa de operaciones; las posiciones de los nodos viven en un sidecar view.yaml, de modo que organizar el grafo nunca ensucia un diff semántico.

Diez minutos

Kumihimo aún no está en un índice de paquetes: instala desde el código fuente (Python 3.11+; Node 18+ solo si quieres el lienzo):

git clone https://github.com/tzavislan/kumihimo
cd kumihimo
cd frontend && npm install && npm run build && cd ..
pip install .

La línea de npm compila el lienzo en vivo y se puede omitir: todo lo de abajo sigue funcionando excepto kumihimo edit, que entonces sirve la API con una página honesta de "frontend no compilado" en lugar del grafo.

kumihimo new myplan
kumihimo edit myplan        # live canvas at 127.0.0.1:8720
kumihimo add myplan build --kind task --title "Build the loader" --body "..."
kumihimo check myplan       # cycles named with paths, dangling edges, field breaches
kumihimo braid myplan       # one prompt on stdout — paste into your agent

Un nodo es un archivo:

---
kind: task
title: Rate-limit middleware
needs: [api-endpoints, pick-algorithm]
in: [ship-guarded-api]
effort: M
acceptance:
  - 429 + Retry-After on breach
---
Middleware on every authenticated route. Fail *open* on Redis errors —
availability beats enforcement.

…y el trenzado compila el grafo en un único prompt: preámbulo, forma Mermaid incrustada, decisiones tomadas expresadas como restricciones, cada tarea con una línea After: honesta y una lista de verificación Done when::

El núcleo es independiente del dominio: entiende identidad, prosa, orden (needs), membresía (in) y anotación (links); todo lo demás proviene de los kinds que defines en el manifiesto, incluidos los campos y las plantillas Jinja2. Un paquete de ingeniería (task, milestone, decision, risk, question) se incluye como predeterminado; examples/fieldnotes es un plan de investigación cuyos kinds viven por completo en su propio manifiesto.

Documentación: https://tzavislan.github.io/kumihimo/ — tutorial, conceptos, kinds personalizados, configuración de MCP, formatos de archivo.

Related MCP server: Executive Cortex MCP

Desarrollo

uv sync
uv run pytest -q
uv run python tools/lint.py            # the conventions linter CI runs
cd frontend && npm install && npm run build   # only if you work on the canvas

Convenciones (aplicadas en CI): CONVENTIONS.md. Contribuciones: CONTRIBUTING.md. Registro de diseño: PLAN.md. Lanzamientos: RELEASING.md.

Licencia

MIT