EXECUTE AGORA
Alvo: $ARGUMENTS
Todos os documentos da base de conhecimento (KB) residem em uma coleção: um diretório sob kb/ com um COLLECTION.md local, como kb/notes/, kb/reference/, kb/instructions/ ou uma coleção de biblioteca instalada como kb/commonplace/notes/. Cada coleção que aceita escritas possui um COLLECTION.md com seu registro, meta de qualidade, ofertas de tipos e convenções de vinculação.
Documentos com frontmatter carregam um type: com valor de caminho que aponta para um documento de especificação de tipo, por exemplo type: kb/types/note.md ou type: kb/reference/types/adr.md. Arquivos sem frontmatter são text implícito.
Passo 1 - Analisar Argumentos
Modo edição: o primeiro argumento é um caminho para um arquivo .md existente. Leia-o, infira a coleção a partir do caminho e leia seu caminho type: do frontmatter. Se tiver frontmatter mas nenhum type:, pare e corrija esse problema estrutural antes de editar. Se não tiver frontmatter, trate-o como text implícito. Abra o documento de especificação de tipo nomeado por type: antes de fazer edições estruturais.
Modo nova escrita: tudo o mais. Extraia coleção, tipo e tópico dos argumentos. Padrões: coleção notes, tipo kb/types/note.md. Se o tipo solicitado for uma instrução e nenhuma coleção explícita for fornecida, use a coleção instructions.
Para novas escritas, resolva a coleção de destino para um diretório sob kb/ com um COLLECTION.md local; nomes abreviados como notes significam kb/notes/. Leia a seção ## Types dessa coleção e escolha um caminho de tipo listado. Se o tipo solicitado não estiver listado e o usuário não forneceu um caminho explícito, pare e liste os tipos disponíveis. Se o usuário fornecer um caminho de tipo explícito kb/.../*.md, abra esse arquivo e verifique se é um documento de especificação de tipo antes de usá-lo.
Passo 2 - Carregar Convenções da Coleção
Leia o COLLECTION.md da coleção de destino para obter as convenções de escrita da coleção, incluindo regras de vinculação de saída. Encontre a seção de vinculação de saída (o cabeçalho varia — procure aquele que nomeia destinos e rótulos) e trate-a como autoritativa. Ela informa para quais coleções de destino esta origem pode vincular, quais destinos estão excluídos, quais rótulos são autorizados para quais pares origem->destino e a necessidade do leitor que cada rótulo atende. O formato interno varia (blocos por destino, uma única tabela de rótulos com uma coluna de destinos, prosa) — leia para o conteúdo, não para a forma. Não há um documento de vinculação separado para consultar.
Falha grave se a coleção de destino não tiver nenhum COLLECTION.md. Toda coleção que aceita escritas deve ter um COLLECTION.md; seu registro, meta de qualidade e regras de vinculação são o que distingue coleções. Não prossiga com convenções padrão.
Passo 3 - Carregar a Especificação do Tipo
Leia o documento de especificação de tipo selecionado. Seu frontmatter deve incluir type: kb/types/type-spec.md, name, description e schema. Seu corpo fornece a forma do artefato e pode incluir um bloco de modelo. Siga esse corpo como o contrato estrutural de autoria.
Não recue de um caminho de tipo ausente para note.
Para text, escreva markdown bruto sem frontmatter apenas quando o usuário explicitamente quiser captura não estruturada. Caso contrário, use kb/types/note.md.
Passo 4 - Pesquisar Antes de Escrever
O Write não executa descoberta ativa — essa é a função do cp-skill-connect. Write redige uma nota e confirma apenas links que o autor já possui em mãos, além de uma verificação de duplicatas barata:
- Verificação de quase duplicata. Pesquise na coleção de destino pelos termos distintivos do título da nova nota com
rg(por exemplo,rg -i "termo chave" kb/notes/ --glob "*.md"). Esta é uma pesquisa de termos direcionada — não enumere toda a coleção; uma listagem completa custa contexto linear e é a ferramenta errada para a verificação de duplicatas de uma única nota. Se uma quase duplicata já existir, prefira editá-la a criar uma segunda nota. - Contexto já carregado. Notas, fontes e ingestões trazidas para a sessão para esta escrita são candidatas de primeira classe a links. Se valeu a pena ler, vale a pena considerar como link.
- Alvos nomeados pelo usuário. Alvos de link que o usuário menciona no prompt.
No modo edição, também execute uma consulta de backlinks na nota alvo — uma consulta, sem pesquisa no corpo — para que edições não órfãos dependentes.
Toda descoberta além disso — varreduras de descrição em toda a coleção, prospecção entre destinos, pesquisa no corpo, travessia de tags, seguimento de links, raciocínio de arestas reversas — pertence ao cp-skill-connect, não aqui. Write permanece focado na autoria de uma única nota.
Passo 5 - Rascunhar e Salvar
Siga o documento de especificação de tipo e as convenções da coleção. Derive um nome de arquivo em letras minúsculas hifenizado a partir de # Title, a menos que editando um arquivo existente. Para artefatos tipados, defina type: para o caminho exato da especificação de tipo relativo ao repositório, não o nome do tipo.
Defina traits (características) apenas quando claramente justificado. As traits disponíveis e seus significados estão definidos na especificação do tipo alvo (por exemplo, a tabela de traits em kb/types/note.md) — extraia o vocabulário de lá, não de uma lista memorizada.
Preserve o frontmatter e os links existentes durante edições, a menos que a alteração solicitada exija modificá-los.
Passo 6 - Validar
Valide a nota que você escreveu ou editou:
commonplace-validate path/to/file.md
Corrija falhas estruturais antes de parar.
Em seguida, sugira cp-skill-connect como o próximo passo. O Passo 4 confirma apenas links que o autor já tinha em mãos (contexto carregado, nomeados pelo usuário) mais uma verificação de duplicatas; o restante da participação do gráfico da nota — varreduras de descrição em toda a coleção, candidatos entre destinos, resultados de pesquisa no corpo, travessia de tags, seguimento de links, candidatos de arestas reversas — só aparece sob a skill connect. A sugestão não é um polimento opcional.
Mecânicas Universais
Estas se aplicam a todos os artefatos tipados, independentemente da coleção.
Frontmatter torna as notas pesquisáveis. Ausência de frontmatter significa text implícito; qualquer arquivo com frontmatter deve incluir um type: com valor de caminho. A maioria das notas de biblioteca também precisa de description (entre aspas duplas, 50-200 caracteres), além de traits, tags e status opcionais.
Descrições são filtros de recuperação, não resumos. O teste: se um agente pesquisasse pelo conceito desta nota e obtivesse 5 resultados, esta descrição ajudaria a escolher esta? Parafrasear o título adiciona zero valor de recuperação.
Vocabulário. Use o vocabulário ativo declarado no AGENTS.md raiz. Ao escrever ou editar prosa substancialmente, glose e vincule o vocabulário ativo na primeira menção significativa quando o leitor pode não conhecer o termo. Não altere passagens intocadas apenas para adicionar links de vocabulário.
Links. Use caminhos markdown relativos a partir do arquivo de origem. Cada link deve apontar para um arquivo real.
A posição codifica o compromisso. Inline conectores de prosa (desde [X](./x.md), porque [X](./x.md), mas [X](./x.md)) são os mais fortes — o alvo é uma premissa do argumento atual. Rodapé links carregam um rótulo explícito e uma frase de contexto: - [título](./caminho.md) — rótulo: frase de contexto.
O COLLECTION.md da coleção autoriza rótulos por destino e nomeia a necessidade do leitor que cada rótulo atende. Escolha um rótulo cuja necessidade do leitor corresponda ao propósito do link; escreva a frase de contexto para responder "[origem] conecta-se a [destino] porque [razão específica]." Se nenhum rótulo autorizado se encaixar, o candidato está fora do escopo para esta coleção — descarte o link ou levante-o ao autor da coleção para estender a autorização.
Nomes de arquivo são em letras minúsculas, hifenizados, .md, derivados de # Title, máximo de 70 caracteres.
Rastreamento de destilação: ao destilar de notas em um artefato focado, adicione Distilled into: no rodapé de cada nota de origem. O artefato destilado não vincula de volta.
Renomeações: nunca renomeie manualmente. Use commonplace-relocate-note para atualizar backlinks.