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:
-
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 dealiases/entities/relations/provenance/citationsonde carregam informação real). Inicie um novo pacote comscripts/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). -
Valide após escrever. Execute
scripts/okf-loom validate <bundle>após qualquer lote de escritas e corrija os achados; executescripts/okf-loom discover <bundle>periodicamente para capturar links/índices/descrições faltantes. Se arquivosindex.mdestiverem desatualizados,scripts/okf-loom index <bundle>regenera os blocos gerados (seguro com marcadores — ele só reescreve entre marcadoresokf:generated; prosa de índice escrita manualmente sem marcadores será SUBSTITUÍDA, então verifiquegit diffdepois). -
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)--tunnelexibe um linkhttps://…trycloudflare.compara 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. -
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). Leiaresources/studio-agent-loop.mdantes do seu primeiro loop. -
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
| Quando | Leia |
|---|---|
| Sempre, primeiro (orientação de 60 segundos + caminhos padrão) | resources/overview.md |
| Antes da sua primeira escrita em qualquer pacote | resources/gotchas.md |
| Executando qualquer verbo CLI / inseguro sobre uma flag | resources/command-reference.md |
| Escrevendo ou editando arquivos de conceito manualmente | resources/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 gating | resources/validation.md |
| Modos de busca, descoberta, planos, builds estáticos | resources/advanced-operations.md |
| Um estúdio está ativo e usuários estão comentando | resources/studio-agent-loop.md |
Alterando o runtime sob scripts/okf_loom/ | resources/architecture-map.md |
| Qualquer coisa ambígua — o contrato vinculante | docs-bundle/reference/spec.md |
| Documentação de usuário final para apontar humanos | docs-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-referenceseja explícito. - Todas as escritas do okf-loom devem permanecer atômicas e seguras com marcadores.
Para regras mais profundas, leia resources/gotchas.md.