Communitygithub.com

okf-loom

Kit de herramientas para convertir paquetes de documentos Markdown en grafos de conocimiento OKF validados, con un estudio local, salida de sitio estático y CLI amigable para agentes.

¿Qué es okf-loom?

okf-loom es un skill para agentes de IA (como Claude Code, Cursor o Codex) que permite trabajar con el Open Knowledge Format (OKF). Su propósito es transformar paquetes de documentos Markdown en grafos de conocimiento estructurados y validados. El skill se distribuye como un repositorio de git: se clona, se carga el archivo SKILL.md y se usan los scripts locales (scripts/okf-loom) sin necesidad de instalar paquetes. Entre sus funciones principales se incluyen: validar paquetes de conceptos OKF (cada concepto es un archivo Markdown con metadatos en frontmatter), iniciar un estudio colaborativo local (servido en http://127.0.0.1:8787) con capacidad de comentarios en vivo y túnel público opcional, buscar y descubrir relaciones faltantes, y ejecutar mutaciones atómicas seguras (como añadir enlaces o entidades). El skill está diseñado para ser autocontenido: el repositorio incluye scripts, recursos de guía, un paquete de documentación de ejemplo (docs-bundle/) y pruebas. Su flujo de trabajo espera que el agente valide después de cada escritura, sirva el estudio proactivamente y gestione comentarios de usuarios mediante un bucle de colaboración.

Compatible con✓Claude Code~Codex CLI~Cursor
npx skills add ojamin/okf-loom

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

okf-loom — skill local del repositorio

Este repositorio es el skill. Clónalo, carga este SKILL.md y luego usa los pequeños archivos de recursos y los scripts locales referenciados abajo. No hay un flujo de publicación de paquetes que aprender; el artefacto duradero es esta estructura de repositorio git.

Comportamientos predeterminados (hazlos sin que te lo pidan)

Estas son las expectativas permanentes para cualquier agente que use este skill:

  1. Los documentos son paquetes OKF. Cuando el usuario solicite documentación, notas, una base de conocimiento o "escribe esto", redáctalo como conceptos OKF — un archivo markdown por concepto con frontmatter completo (type, title, description, tags, timestamp, más aliases/entities/relations/provenance/citations donde contengan información real). Inicia un nuevo paquete con scripts/okf-loom bootstrap <dir> o añade a uno existente. docs-bundle/demo/showcase.md es el ejemplo canónico de un concepto completamente desarrollado (ábrelo renderizado para ver por qué cada clave tiene su lugar).

  2. Valida después de escribir. Ejecuta scripts/okf-loom validate <bundle> después de cualquier lote de escrituras y corrige los hallazgos; ejecuta scripts/okf-loom discover <bundle> periódicamente para detectar enlaces/índices/descripciones faltantes. Si los archivos index.md están desactualizados, scripts/okf-loom index <bundle> regenera los bloques generados (seguro con marcadores — solo reescribe entre los marcadores okf:generated; la prosa de índice escrita a mano sin marcadores será REEMPLAZADA, así que verifica git diff después).

  3. Sirve de forma proactiva. La wiki renderizada es el producto, no una vista de depuración. Cada vez que el usuario quiera ver, leer, revisar o comentar documentos — o acabes de construir/cambiar un paquete que probablemente querría ver — inicia el estudio sin esperar a que te lo pidan y dale la URL:

    scripts/okf-loom serve ruta/al/paquete --no-open          # local:  http://127.0.0.1:8787/
    scripts/okf-loom serve ruta/al/paquete --no-open --tunnel # + URL https pública (necesita cloudflared)
    

    --tunnel imprime un enlace https://…trycloudflare.com para usuarios que no están en esta máquina y agrega el host del túnel a la lista blanca de orígenes cruzados del estudio automáticamente. Dile al usuario que puede comentar seleccionando cualquier texto; el grafo vive en /__graph.

  4. Ejecuta el bucle de colaboración. Mientras un estudio esté activo, los comentarios del usuario son trabajo para ti: scripts/okf-loom wait <bundle> se bloquea hasta que llega un comentario o cambio, luego reclama → edita → resuelve (comment-claim / mutadores / comment-resolve). Lee resources/studio-agent-loop.md antes de tu primer bucle.

  5. Prefiere mutadores para cambios de contenido mientras una sesión del estudio esté activa (write-concept, set-frontmatter, link-add, entity-add, update): están atribuidos, se pueden deshacer y se transmiten en vivo a las pestañas abiertas. Las ediciones directas de archivos están bien en otros casos — el observador las detecta.

Inicio rápido

Desde dentro de okf-loom/:

scripts/okf-loom --help
scripts/okf-loom validate docs-bundle --strict

No se requiere un paso de instalación de tiempo de ejecución principal para la validación normal de documentos. PyYAML se usa cuando está presente; de lo contrario, okf-loom usa su fallback YAML incorporado conservador.

Desde un espacio de trabajo padre donde el checkout se llame okf-loom/:

okf-loom/scripts/okf-loom validate okf-loom/docs-bundle --strict

Los ejemplos usan el helper directamente verificado en el repositorio, no un wrapper de shell local o un script de consola instalado.

Qué leer, cuándo

CuándoLeer
Siempre, primero (orientación de 60 segundos + rutas predeterminadas)resources/overview.md
Antes de tu primera escritura en cualquier paqueteresources/gotchas.md
Al ejecutar cualquier verbo CLI / no estar seguro de una banderaresources/command-reference.md
Al escribir o editar archivos de concepto a manoresources/format-basics.md luego resources/authoring.md
Al decidir cómo se ve un frontmatter "bueno"docs-bundle/demo/showcase.md — el ejemplo trabajado
Cuando una ejecución de validación falla o necesitas compuertas de CIresources/validation.md
Modos de búsqueda, descubrimiento, planes, compilaciones estáticasresources/advanced-operations.md
Cuando un estudio está activo y los usuarios comentanresources/studio-agent-loop.md
Al cambiar el tiempo de ejecución bajo scripts/okf_loom/resources/architecture-map.md
Cualquier cosa ambigua — el contrato vinculantedocs-bundle/reference/spec.md
Documentación para usuarios finales a la que apuntar humanosdocs-bundle/

Estructura del repositorio

okf-loom/
├── SKILL.md                 # este punto de entrada del skill cargable
├── resources/               # archivos de guía pequeños legibles por agente
├── scripts/
│   ├── okf-loom              # comando helper verificado en el repositorio
│   ├── okf_loom/             # paquete de tiempo de ejecución local del checkout
│   ├── build_skill_archive.py
│   ├── capture_readme_media.py
│   ├── capture_viewer_proof.py
│   ├── capture_signal_controls.py
│   └── lint-js.sh
├── docs-bundle/             # paquete de documentación OKF
├── samples/                 # paquetes OKF de ejemplo
├── tests/                   # pruebas pytest para scripts del checkout
├── docs/                    # medios del README (docs/media/), capturas de pantalla, planos de diseño
├── README.md                # visión general humana
├── AGENTS.md                # puntero delgado para agentes que leen AGENTS primero
└── CLAUDE.md                # puntero delgado para agentes que leen CLAUDE primero

Comandos principales

# Validar un paquete.
scripts/okf-loom validate ruta/al/paquete --strict

# Inspeccionar / buscar.
scripts/okf-loom info ruta/al/paquete
scripts/okf-loom search ruta/al/paquete "pedido cliente" --mode hybrid

# Servir el estudio colaborativo en vivo (añade --tunnel para un enlace público).
scripts/okf-loom serve ruta/al/paquete --no-open

# Descubrir brechas y aplicar mutaciones seguras.
scripts/okf-loom discover ruta/al/paquete --out /tmp/okf-suggestions.json
scripts/okf-loom link-add --bundle ruta/al/paquete --source tables/orders --target tables/customers

# Bucle de colaboración mientras un estudio está activo (especificación actual §12).
scripts/okf-loom wait ruta/al/paquete        # se bloquea hasta que llega un comentario/cambio
scripts/okf-loom comment-claim ruta/al/paquete <id-comentario> --summary "lo que haré"
scripts/okf-loom comment-resolve ruta/al/paquete <id-comentario> --summary "lo que hice"

No negociables

  • Usa scripts/okf-loom; no asumas un paquete instalado o script de consola.
  • PyYAML es preferido cuando está presente, pero el fallback incluido es suficiente para la validación normal de documentos/tiempo de ejecución y falla de forma cerrada en YAML avanzado no soportado.
  • No agregues un flujo de publicación a PyPI/paquete como ruta principal.
  • Preserva claves de frontmatter desconocidas y contenido de paquete escrito a mano.
  • type es la única clave de frontmatter de concepto estrictamente requerida bajo OKF v0.1.
  • Los enlaces rotos son advertencias por defecto para los consumidores; los mutadores de autoría fallan de forma cerrada en objetivos faltantes a menos que --allow-forward-reference sea explícito.
  • Todas las escrituras de okf-loom deben mantenerse atómicas y seguras con marcadores.

Para reglas más profundas, lee resources/gotchas.md.

Skills relacionados