WolfMarkTools/WolfMarkDown

O que WolfMarkDown faz?

Um fluxo de trabalho de publicação para agentes que transforma saídas confusas de IA em Markdown profissional, pronto para revisão e manutenção.

Julgamento do agente para estrutura. Ferramentas determinísticas para prova.

Agentes de IA podem produzir pesquisas, planos e documentação úteis, enquanto deixam para trás comparações achatadas, cabeçalhos inconsistentes, estruturas de chat copiadas, fences quebrados e identificadores técnicos alterados.

O WolfMarkDown oferece ao agente um fluxo de trabalho de publicação disciplinado:

• o agente decide significado, estrutura, sanitização e composição;
• ferramentas determinísticas formatam e validam o Markdown resultante;
• conteúdo protegido, reversão e limites de publicação são verificados antes que o resultado seja mantido.

O resultado não é um mecanismo mágico de reparo de Markdown. É um fluxo de trabalho de agente com prova determinística em torno do artefato.

Por que WolfMarkDown existe

O Prettier é um excelente formatador de Markdown. Ele não consegue decidir se um bloco achatado contém uma tabela de comparação, se uma frase curta é um cabeçalho ou se uma mensagem de agente copiada pertence ao documento.

O WolfMarkDown torna essas decisões explícitas e conservadoras. Ele repara estruturas claras, preserva material genuinamente ambíguo e relata o que foi recuperado. Ele não verifica fatos da fonte nem aprova a publicação.

Capacidade	Apenas Prettier	WolfMarkDown
Formatação determinística de Markdown	Sim	Sim
Reparar estrutura semântica do documento	Não	Sim
Remover estruturas de conversa de IA copiadas	Não	Sim
Reconstruir tabelas de comparação malformadas	Não	Sim
Proteger URLs, código, hashes, versões e identificadores	Não	Sim
Verificar parsing GFM e equilíbrio de fences	Não	Sim
Executar markdownlint antes de publicar	Não	Sim
Verificar idempotência	Não	Sim
Restaurar o original após uma Limpeza falha	Não	Sim
Recusar publicar uma Composição falha	Não	Sim

O WolfMarkDown não reescreve prosa já boa apenas para soar diferente. O objetivo é a limpeza semântica mínima necessária com prova determinística de que o resultado é seguro para manter.

Instalar

npx skills add WolfMarkTools/WolfMarkDown --skill wolfmarkdown

A CLI skills instala a habilidade canônica wolfmarkdown/ para o host compatível com Agent Skills selecionado. Um checkout do repositório também pode executar:

npm ci --prefix wolfmarkdown
node wolfmarkdown/scripts/install.mjs

Para uma instalação não interativa no Claude Code:

npx skills add WolfMarkTools/WolfMarkDown \
  --skill wolfmarkdown \
  -g \
  -a claude-code \
  -y

O instalador repara dependências de tempo de execução apenas quando necessário, configura descoberta compartilhada .agents/skills/wolfmarkdown, configura o caminho de compatibilidade do Claude Code, usa uma junção de diretório no Windows quando apropriado e se recusa a sobrescrever caminhos não relacionados.

Uso rápido

Use WolfMarkDown em docs/architecture.md.

Exporte esta pesquisa como Markdown usando WolfMarkDown.

Verifique docs/architecture.md com WolfMarkDown sem alterá-lo.

Onde um host expõe comandos de barra, o mesmo fluxo de trabalho pode ser invocado como:

/wolfmarkdown docs/architecture.md
/wolfmarkdown verify docs/architecture.md

A invocação em linguagem natural é a interface portátil. A apresentação por comando de barra é específica do host.

Operações

Operação	O que o WolfMarkDown faz
Compose (Composição)	Cria um arquivo .md real a partir de material de origem, remove estruturas apenas de chat, formata, verifica e publica somente após PASS.
Clean (Limpeza)	Repara um arquivo Markdown existente com as menores alterações semânticas necessárias e restaura o original se a verificação falhar.
Verify (Verificar)	Verifica Markdown sem alterá-lo.
Doctor (Diagnóstico)	Inspeciona dependências de tempo de execução e descoberta de habilidades sem modificar a instalação.
Setup (Configuração)	Repara dependências de tempo de execução apenas quando necessário e configura descoberta compartilhada de habilidades.

Alvos típicos de limpeza incluem hierarquia de cabeçalhos, listas malformadas, tabelas GFM quebradas, fences de código não fechados, comentários de agente copiados, redação dependente de conversa e ruído decorativo que não deveria sobreviver na documentação.

Antes e depois

Um rascunho confuso de agente pode achatar uma comparação em um bloco:

Recomendação use relay_v2 para o fluxo de carteira externa.
Comparação Provedor Modo Risco Privy Aprovação externa Médio CDP Carteira incorporada Alto.
Notas de implementação relay_v2 confirma getTransaction após submissão.

Após o agente tornar a estrutura explícita, o WolfMarkDown pode publicar um documento como:

# Decisão do fluxo de carteira

## Recomendação

Use `relay_v2` para o fluxo de carteira externa.

## Comparação

| Provedor | Modo | Risco |
| --- | --- | --- |
| Privy | Aprovação externa | Médio |
| CDP | Carteira incorporada | Alto |

## Notas de implementação

`relay_v2` confirma `getTransaction` após submissão.

A saída recupera uma tabela e cabeçalhos, preserva os identificadores técnicos e não adiciona nenhuma informação ausente na fonte. Este é um exemplo estrutural ilustrativo; o julgamento semântico permanece de propriedade do agente.

Exemplos

Os exemplos públicos mostram o WolfMarkDown recuperando estrutura de Markdown real gerado por agente sem inventar significado ausente.

• Exemplo de Migração de App Móvel — um fixture completo de antes e depois cobrindo sanitização de wrapper de chat, tabelas separadas por tabulações, marcadores Unicode, variáveis de ambiente protegidas e uma nota de banco de dados intencionalmente ambígua.
• Entrada bruta — a saída da IA fonte antes do reparo.
• Saída estruturada — o Markdown resultante com cabeçalhos, tabelas GFM, listas e um bloco de código env.

O README do exemplo registra o harness OpenCode, o modelo GLM-5.2 e o prompt exato usados para reprodução.

Status de integração com hosts suportados

O WolfMarkDown tem uma implementação canônica. A tabela distingue caminhos de descoberta testados no repositório de aceitação do host que ainda precisa de um teste de fumaça dedicado.

Host	Status de integração	Caminho de descoberta
Codex	Caminho de descoberta do repositório e instalador testados	.agents/skills compartilhado
Cursor	Caminho de descoberta do repositório e instalador testados	.agents/skills compartilhado
Claude Code	Caminho de link de compatibilidade testado	.claude/skills
OpenCode	Aceitação do host pendente	.agents/skills compartilhado quando habilitado pelo host
Gemini CLI	Aceitação do host pendente	.agents/skills compartilhado quando habilitado pelo host
GitHub Copilot	Aceitação do host pendente; intake de plugin é evidência histórica	Suporte a Agent Skills ou plugin habilitado pelo host

A aceitação do host não é inferida da presença de um binário ou diretório. O modelo do host determina a qualidade semântica; WolfMarkDown fornece o fluxo de trabalho e verificações determinísticas.

Como funciona

Intenção do usuário
    ↓
Julgamento semântico do agente
    ↓
Mapa de origem e reparo semântico
    ↓
Verificações de parsing GFM + cabeçalho/tabela
    ↓
Verificações de fence, frontmatter + espaço em branco
    ↓
Verificação de formatação Prettier
    ↓
markdownlint
    ↓
Integridade de token protegido (com snapshot da fonte) + idempotência
    ↓
PASS → manter ou publicar     FAIL → restaurar ou não publicar

Antes da formatação, o agente verifica se há estrutura semântica achatada. Um documento pode ser Markdown válido e ainda assim ser uma transformação falha se perdeu tabelas, cabeçalhos, listas ou relacionamentos.

Limite de reparo semântico

O agente reconstrói cabeçalhos, listas, tabelas, parágrafos e seções irmãs apenas quando a fonte torna a estrutura clara. Uma sequência de guias sem cabeçalho não é automaticamente uma tabela, uma frase curta não é automaticamente um cabeçalho e uma frase isolada Rótulo: valor não é automaticamente um item de lista. Para documentos longos, o agente mantém um mapa de origem e reconcilia o contorno completo, relacionamentos entre seções, limites de tabela e valores protegidos antes de publicar. Se a fonte não puder ser revisada completamente, ele preserva a incerteza e relata o limite em vez de adivinhar.

Verificação e limite de qualidade

PASS do WolfMarkDown significa que o artefato passou nas verificações determinísticas aplicáveis:

• o artefato Markdown passou nas verificações de formatação, parsing, lint, fence e idempotência;
• o agente fez e relatou decisões estruturais baseadas na fonte;
• o conteúdo técnico protegido foi preservado somente quando a integridade foi verificada contra um snapshot da fonte intocado, como em Clean e Compose ou com --integrity-from;
• operações Clean e Compose falhas não deixaram um resultado publicado não verificado.

Verify independente sem uma fonte de integridade relata integridade como ignorada. Seu PASS não prova que tokens protegidos foram preservados.

Detalhes protegidos

Quando um snapshot de fonte intocado está disponível, as verificações de integridade protegem conteúdo técnico, incluindo:

• URLs, código inline e código em fence;
• chaves públicas, assinaturas, hashes, versões e identificadores;
• caminhos de sistema de arquivos e variáveis de ambiente contextuais;
• datas, percentuais e valores monetários.

Esta é evidência de qualidade do Markdown, não aprovação de conteúdo. PASS não estabelece correção factual, completude, atualidade, conformidade com políticas ou autorização para publicar. Não verifica fatos de afirmações.

Verificações determinísticas são prova de propriedades do artefato. Elas não são um oráculo semântico e não substituem a responsabilidade do agente de considerar cada sinal claro da fonte.

Evidência do lançamento v0.2.1

• 82/82 testes Node passam.
• Verificações executáveis de propriedades semânticas cobrem cabeçalhos, tabelas GFM, tokens protegidos e preservação de tabelas ambíguas.
• skills-ref validate ./wolfmarkdown passa.
• Instalador, Doctor, reversão, colisão de alvo, integridade e idempotência permanecem cobertos.

Intake histórico de plugin externo

O pacote v0.1.1 de Agent Plugins passou na intake automatizada de plugin externo do GitHub Awesome Copilot. Esta é evidência histórica de empacotamento, não evidência de aceitação do host para v0.2.1.

Detalhes da arquitetura

WolfMarkDown/
├── plugin.json
├── .agents/
│   └── skills/
│       └── wolfmarkdown → ../../wolfmarkdown
├── skills/
│   └── wolfmarkdown → ../wolfmarkdown
└── wolfmarkdown/
    ├── SKILL.md
    ├── config/
    ├── lib/
    ├── references/
    ├── scripts/
    └── tests/

Decisões de propriedade do agente

O agente é dono do roteamento de intenção, mapeamento de origem, classificação semântica, sanitização de conversa, recuperação de cabeçalho/lista/tabela, tratamento de ambiguidade e composição.

Prova determinística

Os scripts são donos da formatação, lint de Markdown, parsing GFM, equilíbrio de fence, verificações de frontmatter, integridade de token protegido, idempotência, instalação, verificações de Doctor, reversão e avaliação semântica baseada em propriedades. Eles não reescrevem o significado da fonte.

Prettier é o único formatador final.

O ID da habilidade da máquina e o diretório do sistema de arquivos são intencionalmente em minúsculas wolfmarkdown; o nome do produto é WolfMarkDown.

Avaliações semânticas

O corpus de avaliação usa documentos sintéticos e propriedades estruturais em vez de snapshots frágeis de documento completo. Execute um caso contra um candidato produzido por agente após o verificador normal:

node wolfmarkdown/scripts/evaluate-semantic.mjs \
  --case ambiguous-structure-preservation \
  source.md candidate.md

O avaliador verifica contagens esperadas de cabeçalhos e tabelas, preservação de token protegido e propriedades de segurança, como recusar transformar uma sequência ambígua sem cabeçalho em uma tabela. Ele não infere ou repara o candidato.

Comandos do desenvolvedor

npm ci --prefix wolfmarkdown
npm test
npx --yes skills-ref validate ./wolfmarkdown

Comandos diretos úteis:

node wolfmarkdown/scripts/doctor.mjs
node wolfmarkdown/scripts/format-markdown.mjs path/to/file.md
node wolfmarkdown/scripts/verify-markdown.mjs path/to/file.md
node wolfmarkdown/scripts/evaluate-semantic.mjs --help

Casos semânticos residem em wolfmarkdown/tests/evals/. Entradas de aceitação entre hosts residem em wolfmarkdown/tests/acceptance/.

Limites atuais

• /wolfmarkdown setup só funciona após a habilidade ser detectável pelo host.
• --mode não é suportado.
• Forks de habilidades específicas de fornecedor não são criados.
• Windows requer permissão para criar a junção de descoberta apropriada.
• Sanitização semântica permanece julgada pelo agente por design.
• O verificador prova propriedades do artefato Markdown; não certifica prosa arbitrária ou prontidão para publicação.
• O reparo de documentos longos depende do agente reter e reconciliar seu registro do documento; revisão incompleta da fonte deve ser relatada em vez de adivinhada.

Metadados do repositório

Tópicos recomendados do repositório GitHub:

ai-agents agent-skills markdown documentation claude-code codex cursor github-copilot

Os tópicos devem ser configurados nas configurações do repositório GitHub. São metadados de detectabilidade, não evidência de compatibilidade.

Contribuindo

Encontrou um caso extremo de Markdown que o WolfMarkDown deveria tratar melhor? Abra uma issue.

Pull requests são especialmente úteis para falhas reprodutíveis de Markdown, casos extremos de integridade, problemas de instalação entre plataformas, evidências adicionais de aceitação de host e melhorias focadas que preservam a arquitetura de implementação única.

Licença

WolfMarkDown está disponível sob a Licença MIT. Veja o arquivo LICENSE para obter o texto completo.