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:
-
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ásaliases/entities/relations/provenance/citationsdonde contengan información real). Inicia un nuevo paquete conscripts/okf-loom bootstrap <dir>o añade a uno existente.docs-bundle/demo/showcase.mdes el ejemplo canónico de un concepto completamente desarrollado (ábrelo renderizado para ver por qué cada clave tiene su lugar). -
Valida después de escribir. Ejecuta
scripts/okf-loom validate <bundle>después de cualquier lote de escrituras y corrige los hallazgos; ejecutascripts/okf-loom discover <bundle>periódicamente para detectar enlaces/índices/descripciones faltantes. Si los archivosindex.mdestán desactualizados,scripts/okf-loom index <bundle>regenera los bloques generados (seguro con marcadores — solo reescribe entre los marcadoresokf:generated; la prosa de índice escrita a mano sin marcadores será REEMPLAZADA, así que verificagit diffdespués). -
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)--tunnelimprime un enlacehttps://…trycloudflare.compara 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. -
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). Leeresources/studio-agent-loop.mdantes de tu primer bucle. -
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ándo | Leer |
|---|---|
| Siempre, primero (orientación de 60 segundos + rutas predeterminadas) | resources/overview.md |
| Antes de tu primera escritura en cualquier paquete | resources/gotchas.md |
| Al ejecutar cualquier verbo CLI / no estar seguro de una bandera | resources/command-reference.md |
| Al escribir o editar archivos de concepto a mano | resources/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 CI | resources/validation.md |
| Modos de búsqueda, descubrimiento, planes, compilaciones estáticas | resources/advanced-operations.md |
| Cuando un estudio está activo y los usuarios comentan | resources/studio-agent-loop.md |
Al cambiar el tiempo de ejecución bajo scripts/okf_loom/ | resources/architecture-map.md |
| Cualquier cosa ambigua — el contrato vinculante | docs-bundle/reference/spec.md |
| Documentación para usuarios finales a la que apuntar humanos | docs-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.
typees 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-referencesea 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.