Kumihimo

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

Kumihimo es el arte japonés de trenzar muchos hilos separados en un solo cordón. Esta herramienta funciona de la misma manera: organizas 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.

• Míralo. kumihimo edit abre un lienzo en vivo: nodos coloreados por tipo, aristas de dependencia/pertenencia/anotación dibujadas de forma distinta, 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 propia hoja de ruta de este 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 para que reorganizar el grafo nunca ensucie un diff semántico.

Diez minutos

pip install kumihimo

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), pertenencia (in) y anotación (links); todo lo demás proviene de los kinds que defines en el manifiesto, incluidos campos y 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.

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

Desarrollo

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

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

Licencia

MIT