Communitygithub.com

okf-loom

Kit de ferramentas para transformar pacotes de documentos Markdown em grafos de conhecimento OKF validados, com estúdio local, geração de site estático e CLI amigável para agentes.

O que é okf-loom?

Okf-loom é um conjunto de scripts locais (checkout-local) que permite a agentes de IA, como Claude Code ou Codex, trabalhar com pacotes de documentos no formato Open Knowledge Format (OKF). A ferramenta transforma documentos Markdown em um grafo de conhecimento validado, oferecendo validação, busca, descoberta de lacunas, atualização e renderização de um estúdio colaborativo ao vivo. Sua principal vantagem é eliminar a complexidade de pacotes e workflows de publicação — o artefato durável é o layout do repositório git. O okf-loom suporta operações atômicas e seguras via comandos CLI como `validate`, `serve`, `discover`, `wait` e mutadores (`link-add`, `write-concept`). Inclui um estúdio web ao vivo que permite comentários e edição colaborativa, com grafos navegáveis em `/__graph`. O agente deve carregar o `SKILL.md` e executar os scripts do diretório checkout (`scripts/okf-loom`). As regras incluem validação pós-escrita, preferência por mutadores durante sessões ao vivo, e preservação de conteúdo manual. O repositório contém bundles de exemplo (`docs-bundle/demo/`), guias em `resources/`, e testes em `tests/`. A ferramenta é ideal para documentação técnica, bases de conhecimento e workflows de agentes que precisam de um grafo de conhecimento estruturado e colaborativo.

Funciona com✓Claude Code~Codex CLI~Cursor
npx skills add ojamin/okf-loom

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

okf-loom — skill local ao repositório

Este repositório é a skill. Clone-o, carregue este SKILL.md, e então use os pequenos arquivos de recurso e scripts locais ao checkout referenciados abaixo. Não há workflow de publicação de pacotes para aprender; o artefato durável é este layout de repositório git.

Comportamentos padrão (faça-os sem ser solicitado)

Estas são as expectativas permanentes para qualquer agente usando esta skill:

  1. Documentos são pacotes OKF. Quando o usuário solicitar documentação, notas, uma base de conhecimento, ou "escreva isso", crie como conceitos OKF — um arquivo markdown por conceito com frontmatter completa (type, title, description, tags, timestamp, além de aliases/entities/relations/provenance/citations onde carregam informação real). Inicie um novo pacote com scripts/okf-loom bootstrap <dir> ou adicione a um existente. docs-bundle/demo/showcase.md é o exemplo canônico de um conceito completo (abra-o renderizado para ver por que cada chave merece seu lugar).

  2. Valide após escrever. Execute scripts/okf-loom validate <bundle> após qualquer lote de escritas e corrija os achados; execute scripts/okf-loom discover <bundle> periodicamente para capturar links/índices/descrições faltantes. Se arquivos index.md estiverem desatualizados, scripts/okf-loom index <bundle> regenera os blocos gerados (seguro com marcadores — ele só reescreve entre marcadores okf:generated; prosa de índice escrita manualmente sem marcadores será SUBSTITUÍDA, então verifique git diff depois).

  3. Sirva proativamente. O wiki renderizado é o produto, não uma visualização de depuração. Sempre que o usuário quiser ver, ler, revisar, ou comentar documentos — ou você acabou de construir/alterar um pacote que ele provavelmente queira ver — inicie o estúdio sem esperar ser solicitado e entregue a URL:

    scripts/okf-loom serve path/to/bundle --no-open          # local:  http://127.0.0.1:8787/
    scripts/okf-loom serve path/to/bundle --no-open --tunnel # + URL https pública (precisa de cloudflared)
    

    --tunnel exibe um link https://…trycloudflare.com para usuários que não estão nesta máquina e adiciona automaticamente o host do túnel à lista de permissões de origem cruzada do estúdio. Informe ao usuário que ele pode comentar selecionando qualquer texto; o grafo vive em /__graph.

  4. Execute o loop de colaboração. Enquanto um estúdio estiver ativo, comentários de usuários são trabalho para você: scripts/okf-loom wait <bundle> bloqueia até que haja um comentário ou mudança, então reivindique → edite → resolva (comment-claim / mutadores / comment-resolve). Leia resources/studio-agent-loop.md antes do seu primeiro loop.

  5. Prefira mutadores para mudanças de conteúdo enquanto uma sessão de estúdio estiver ativa (write-concept, set-frontmatter, link-add, entity-add, update): eles são atribuídos, reversíveis e transmitidos ao vivo para abas abertas. Edições diretas de arquivo são aceitáveis caso contrário — o watcher as captura.

Início rápido

De dentro de okf-loom/:

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

Nenhuma etapa de instalação de runtime principal é necessária para validação normal de documentos. PyYAML é usado quando presente; caso contrário, okf-loom usa seu fallback YAML conservador embutido.

De um workspace pai onde o checkout é nomeado okf-loom/:

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

Os exemplos usam o auxiliar verificado diretamente, em vez de um wrapper de shell local ou script de console instalado.

O que ler, quando

QuandoLeia
Sempre, primeiro (orientação de 60 segundos + caminhos padrão)resources/overview.md
Antes da sua primeira escrita em qualquer pacoteresources/gotchas.md
Executando qualquer verbo CLI / inseguro sobre uma flagresources/command-reference.md
Escrevendo ou editando arquivos de conceito manualmenteresources/format-basics.md então resources/authoring.md
Decidindo como é uma frontmatter "boa"docs-bundle/demo/showcase.md — o exemplo prático
Uma execução de validação falha ou você precisa de CI gatingresources/validation.md
Modos de busca, descoberta, planos, builds estáticosresources/advanced-operations.md
Um estúdio está ativo e usuários estão comentandoresources/studio-agent-loop.md
Alterando o runtime sob scripts/okf_loom/resources/architecture-map.md
Qualquer coisa ambígua — o contrato vinculantedocs-bundle/reference/spec.md
Documentação de usuário final para apontar humanosdocs-bundle/

Layout do repositório

okf-loom/
├── SKILL.md                 # este ponto de entrada de skill carregável
├── resources/               # pequenos arquivos de guia legíveis por agente
├── scripts/
│   ├── okf-loom              # comando auxiliar verificado
│   ├── okf_loom/             # pacote runtime local ao checkout
│   ├── build_skill_archive.py
│   ├── capture_readme_media.py
│   ├── capture_viewer_proof.py
│   ├── capture_signal_controls.py
│   └── lint-js.sh
├── docs-bundle/             # pacote de documentação OKF
├── samples/                 # exemplos de pacotes OKF
├── tests/                   # provas pytest para scripts do checkout
├── docs/                    # mídia do README (docs/media/), screenshots, planos de design
├── README.md                # visão geral humana
├── AGENTS.md                # ponteiro fino para agentes que leem AGENTS primeiro
└── CLAUDE.md                # ponteiro fino para agentes que leem CLAUDE primeiro

Comandos principais

# Validar um pacote.
scripts/okf-loom validate path/to/bundle --strict

# Inspecionar / buscar.
scripts/okf-loom info path/to/bundle
scripts/okf-loom search path/to/bundle "pedido do cliente" --mode hybrid

# Servir o estúdio colaborativo ao vivo (adicione --tunnel para um link público).
scripts/okf-loom serve path/to/bundle --no-open

# Descobrir lacunas e aplicar mutações seguras.
scripts/okf-loom discover path/to/bundle --out /tmp/okf-suggestions.json
scripts/okf-loom link-add --bundle path/to/bundle --source tables/orders --target tables/customers

# Loop de colaboração enquanto um estúdio está ativo (especificação atual §12).
scripts/okf-loom wait path/to/bundle        # bloqueia até que um comentário/mudança chegue
scripts/okf-loom comment-claim path/to/bundle <comment-id> --summary "o que farei"
scripts/okf-loom comment-resolve path/to/bundle <comment-id> --summary "o que fiz"

Inegociáveis

  • Use scripts/okf-loom; não assuma um pacote instalado ou script de console.
  • PyYAML é preferido quando presente, mas o fallback embutido é suficiente para validação normal de runtime/documentos e falha fechada em YAML avançado não suportado.
  • Não adicione fluxo de publicação PyPI/pacote como caminho principal.
  • Preserve chaves de frontmatter desconhecidas e conteúdo de pacote escrito manualmente.
  • type é a única chave de frontmatter de conceito estritamente obrigatória sob OKF v0.1.
  • Links quebrados são avisos por padrão para consumidores; mutadores de autoria falham fechada em alvos faltantes a menos que --allow-forward-reference seja explícito.
  • Todas as escritas do okf-loom devem permanecer atômicas e seguras com marcadores.

Para regras mais profundas, leia resources/gotchas.md.

Habilidades Relacionadas