scchearn/loam

Usando loam

Este é o roteador para o namespace de habilidades loam. Ele não executa trabalho por si só. Ele informa qual habilidade loam invocar para uma determinada intenção e as regras que se aplicam a todas elas.

Esta é uma meta-habilidade de roteamento. Quando você reconhecer a habilidade correspondente, invoque-a através do carregador de habilidades do host. Não execute o trabalho aqui.

Inegociáveis

Três regras mantêm o trabalho loam alinhado com o modelo de memória.

1. Invoque a habilidade relevante antes de qualquer ação loam. Não apenas chamadas de ferramenta. Antes de planejar, pesquisar, iniciar, retomar, fazer checkpoint, debater ou chegar a um consenso, alterar um plano, adicionar à memória, consultar a memória, alterar a memória, fazer lint da memória, normalizar a memória, revisar a memória, capturar aprendizados, auditar orientações, estruturar o wiki ou inicializar um vault: invoque a habilidade correspondente. Este documento é um roteador. O corpo da habilidade tem as regras reais. A responsabilidade é sua em todo o resto. Erre pelo lado de invocar.
2. Memória primeiro, substrato depois. Fale sobre "memória" primeiro. Use "wiki" apenas ao distinguir o substrato markdown do substrato de orientação ou checkpoint. Nunca diga "o wiki" quando quiser dizer "memória" — o wiki é um substrato da memória, não a coisa toda.
3. O agente é dono das gravações de memória. O agente escreve, corrige, roteia e arquiva a memória sem pré-aprovação. O humano pode sinalizar conteúdo desatualizado ou incorreto, o que aciona o mesmo fluxo de correção que uma contradição descoberta pelo agente.

O modelo de memória

Memória é o conceito guarda-chuva para tudo que o loam captura. Existem três substratos:

Substrato	O que é	Quem mantém
wiki	Notas markdown duráveis compatíveis com Obsidian sob wiki/. Páginas de tópico, entidade, conceito, análise.	grupo loam-memory (maioria das habilidades)
guidance	AGENTS.md é o arquivo de orientação canônico. CLAUDE.md é um shim de importação fino (apenas @AGENTS.md). .claude.local.md para substituições pessoais.	grupo loam-memory (auditing-guidance, learning-from-session caminho de orientação)
checkpoints	Estado de trabalho transitório sob wiki/checkpoints/. Notas de reinicialização, não conhecimento durável.	grupo loam-work (checkpointing escreve, resuming lê)

O substrato wiki é o que qmd indexa. O substrato de orientação é o que os hosts carregam como contexto de prompt. Checkpoints são estado de trabalho, não conhecimento — eles se recusam a tocar em index.md ou log.md e não devem se tornar alegações duráveis.

Fale sobre "memória" primeiro. Use "wiki" apenas quando a distinção de substrato for importante. Uma habilidade que opera nas notas markdown trabalha no substrato wiki da memória. Uma habilidade que edita AGENTS.md trabalha no substrato de orientação da memória. Ambos são memória.

Rubrica de admissão à memória durável

Use esta rubrica antes de criar uma página wiki. Habilidades de criação de páginas referenciam esta seção em vez de copiá-la.

Uma alegação ganha uma página wiki apenas se passar em todas as três:

• R1 Reutilizável — uma sessão futura em uma tarefa diferente plausivelmente precisaria dela.
• R2 Sobre o projeto/domínio — base de código, arquitetura, decisões, convenções, dependências externas ou fatos externos duráveis; não a conversa, o agente ou estado de usuário transitório.
• R3 Custoso de reconstruir e verificável novamente — re-derivar a alegação de uma fonte ativa (código, config, calendário, lista de tarefas) custaria mais do que a página custa para manter. Se um comando ou uma leitura de arquivo a recupera, ela não merece uma página. Onde existe uma fonte externa, a página a nomeia para que a atualização possa re-validar. Decisões puras e justificativas são auto-fonte e satisfazem isso ao declarar seu raciocínio.

Desqualificadores substituem a rubrica:

• D1 efêmero — estado de build, branch atual, "hoje executei X" -> relatório operacional.
• D2 duplicata — uma página existente cobre isso -> alterar a página existente em vez de criar outra.

Critério de desempate: admitir se não for reconstruível de uma fonte ativa; descartar se for reconstruível. wiki/.archive/ é apenas para conteúdo que era durável e agora foi substituído. Material nunca durável não é escrito no wiki e nunca é arquivado.

Matriz de roteamento

Material	Destino	Caminho da habilidade
Fato reutilizável de projeto/domínio, passa na rubrica	página wiki durável	loam::adding-to-memory, auto-correção
Convenção/comando/dica de comportamento de agente	AGENTS.md / CLAUDE.md	loam::learning-from-session caminho de orientação
Estado de sessão para retomada/transferência	wiki/checkpoints/<slug>.md	loam::checkpointing
Contexto por tarefa anexado a uma unidade de trabalho	anotação de tarefa / arquivo de plano	loam::planning, loam::starting
Saída de build, estado de branch, único, não verificável, ou falha na rubrica	descartar, opcionalmente com uma linha de auditoria em log.md	nenhum

Auto-correção e acionadores de sinalização humana

• Auto-correção: quando o agente lê a memória e encontra uma contradição com a evidência atual, move a página durável substituída para wiki/.archive/ com um cabeçalho de arquivamento, escreve a correção no local ativo, anexa uma entrada self-correct a log.md, e continua a tarefa original.
• Sinalização humana: quando o humano diz que uma página de memória está errada ou desatualizada, trate como um acionador de correção, não um pedido de aprovação. Leia a página sinalizada e a evidência atual, arquive a página durável substituída, escreva a correção, registre-a e relate o que mudou.
• Escopo de arquivamento: .archive/ é apenas para páginas que eram duráveis e depois se tornaram incorretas, desatualizadas ou substituídas. Material nunca durável é roteado para outro lugar ou descartado.

Acionadores de validação de atualização

Use updated_at existente mais evidência de lint; não adicione frontmatter de atualização.

• F1 um caminho de arquivo citado mudou desde a updated_at da página.
• F2 uma refatoração, renomeação, exclusão ou migração tocou um caminho referenciado (loam::syncing-code-graph --touched).
• F3 uma versão fixada, API ou documento externo que a página nomeia tem uma menção mais recente.
• F4 updated_at é mais antigo que 90 dias e a página cita superfícies voláteis como APIs, configurações, versões ou caminhos de código. Lint sinaliza isso para re-validação e não arquiva automaticamente.
• F5 contradição na leitura, tratada por auto-correção.

O resultado da validação é um de: confirmado (atualizar updated_at), corrigido (arquivar + reescrever + registrar), ou rebaixado (arquivar com motivo "não se aplica mais").

Bandeiras vermelhas: pensamentos que significam PARE e invoque

Estas racionalizações fazem com que habilidades sejam puladas. Se você se pegar pensando em qualquer uma delas, invoque a habilidade relevante mesmo que você "já a tenha lido" antes na sessão.

Pensamento	Ação
"Vou apenas escrever isso no wiki"	Invoque loam-adding-to-memory. Aplique a rubrica de admissão, depois escreva ou roteie.
"Vou apenas planejar, é simples"	Invoque loam-writing-spec. Especificações são necessárias antes de loam-planning.
"Vou apenas fazer um debate rápido entre agentes"	Invoque loam-configuring-agents. Debates são controlados por aprovação; sem envios antes da liberação.
"Vou apenas editar este plano diretamente"	Invoque loam-amending-plan. Mudanças no plano em cascata; a habilidade percorre o impacto.
"Vou escrever esta página de memória porque pode ajudar depois"	Aplique a rubrica de admissão primeiro. Se falhar, roteie ou descarte.
"O wiki está desatualizado, vou corrigi-lo inline"	Arquive a página durável substituída, escreva a correção, registre-a e continue.
"Vou apenas capturar este aprendizado como uma nota"	Invoque loam-learning-from-session. Ele roteia para wiki ou orientação, não você.
"Vou apenas verificar o wiki rapidinho"	Invoque loam-querying-memory. Mantenha-se fundamentado na memória, não em contexto desatualizado.
"Vou apenas adicionar este comando ao AGENTS.md"	Invoque loam-learning-from-session (caminho de orientação) ou loam-auditing-guidance para uma auditoria completa.
"Vou apenas pausar e continuar depois"	Invoque loam-checkpointing. Um checkpoint é um artefato retomável, não uma nota mental.
"Vou retomar de onde parei"	Invoque loam-resuming. Verifique o estado ativo antes de agir.
"Vou configurar o wiki"	Invoque loam-scaffolding-wiki primeiro, depois loam-initializing-vault para configuração do Obsidian.

O ciclo de vida loam

Para qualquer tarefa loam:

1. Orientar. Reconheça a habilidade correspondente a partir do gráfico de decisão abaixo. Se duas habilidades parecerem relevantes, aplique as regras de precedência.
2. Escolher habilidade. Invoque-a através do carregador de habilidades do host.
3. Preservar limites de substrato. Não escreva checkpoints em páginas duráveis. Não escreva orientação em páginas wiki. Não escreva conteúdo wiki em AGENTS.md. Cada substrato tem sua habilidade.
4. Aplicar admissão e roteamento antes de gravações na memória. Páginas wiki duráveis devem passar na rubrica; todo o resto vai para orientação, checkpoints, anotações de tarefa ou descarte.
5. Atualizar planos / checkpoints / orientação apenas através da habilidade correspondente. Não edite um plano inline — use loam-amending-plan. Não escreva um checkpoint inline — use loam-checkpointing. Não edite AGENTS.md inline — use loam-learning-from-session ou loam-auditing-guidance.

Regras de conflito (quando duas habilidades parecem relevantes)

• Habilidades de processo / trabalho atual vencem antes de habilidades de manutenção de memória. Se você estiver no meio da execução e descobrir um problema de memória, termine a etapa de trabalho atual primeiro (ou faça checkpoint), depois invoque a habilidade de memória.
• Gravações de memória são de propriedade do agente. Se o trabalho atual produzir um aprendizado, roteie-o através da matriz; se expuser memória desatualizada, corrija inline com arquivamento + registro.
• Checkpoints são transitórios. Eles vivem sob wiki/checkpoints/ mas não são alegações duráveis. Eles se recusam a atualizar index.md ou log.md. Não promova um checkpoint a uma nota durável sem passar por loam-adding-to-memory.
• Alterar vs lint. loam-amending-memory corrige alegações incorretas específicas. loam-linting-memory verifica a saúde de todo o gráfico. Se você encontrou um erro específico, altere. Se você quer uma verificação geral, faça lint.
• Consultar vs revisar. loam-querying-memory responde a uma pergunta. loam-reviewing-memory revela lacunas. Se você quer uma resposta, consulte. Se você quer saber o que não está resolvido, revise.
• Adicionar vs aprender. loam-adding-to-memory ingere uma fonte (arquivo, artigo, conversa como nota). loam-learning-from-session captura insights derivados da sessão e os roteia para wiki ou orientação. Se você tem uma fonte, adicione. Se a sessão produziu insight, aprenda.

Gráfico de decisão

"Eu quero..."
├─ iniciar algo novo
│  ├─ pesquisar uma pergunta ──────────── /loam::writing-spec
│  ├─ planejar trabalho aprovado ──────── /loam::planning
│  └─ debater / chegar a um consenso ──── /loam::configuring-agents
├─ executar trabalho
│  ├─ começar um plano ──────────────────── /loam::starting
│  ├─ pausar / transferir ───────────────── /loam::checkpointing
│  ├─ retomar após pausa ────────────────── /loam::resuming
│  └─ alterar um plano em andamento ─────── /loam::amending-plan
├─ trabalhar com memória
│  ├─ adicionar uma fonte ──────────────── /loam::adding-to-memory
│  ├─ ingerir uma base de código ────────── /loam::ingesting-codebase
│  ├─ sincronizar desvio de gráfico de código ─ /loam::syncing-code-graph
│  ├─ fazer uma pergunta ─────────────────── /loam::querying-memory
│  ├─ corrigir o que está errado ────────── /loam::amending-memory
│  ├─ verificação de saúde ───────────────── /loam::linting-memory
│  ├─ normalizar corpus bagunçado ────────── /loam::normalizing-memory
│  ├─ ver o que não está resolvido ───────── /loam::reviewing-memory
│  ├─ capturar aprendizados da sessão ────── /loam::learning-from-session
│  └─ auditar orientação do agente ───────── /loam::auditing-guidance
└─ configurar o substrato
   ├─ estruturar o wiki ────────────────── /loam::scaffolding-wiki
   └─ iniciar vault Obsidian ───────────── /loam::initializing-vault

Nota de precedência para casos ambíguos

Se uma intenção mapear para duas habilidades, a árvore acima é o roteador primário. Quando a árvore não desambiguar, aplique as regras de conflito na seção de ciclo de vida. Quando ainda estiver incerto: pergunte ao usuário qual intenção é mais próxima.

Referência compacta de habilidades

Uma linha por habilidade. O gráfico de decisão é o roteador primário; isto é para consulta rápida.

• loam-writing-spec — pesquisar uma pergunta, produzir specs/<slug>.md
• loam-planning — compilar especificação aprovada em plano pronto para execução
• loam-starting — iniciar ou retomar a execução de um plano
• loam-resuming — retomar a partir de notas de checkpoint
• loam-checkpointing — escrever um checkpoint retomável antes de pausar
• loam-configuring-agents — executar um debate ou conferência estruturada entre agentes com posições distintas e um entregável de convergência, controlado por aprovação
• loam-amending-plan — atualizar um plano em andamento após mudança de escopo
• loam-adding-to-memory — ingerir uma fonte na memória (substrato wiki)
• loam-ingesting-codebase — ingerir base de código como páginas de entidade com arestas wikilink
• loam-syncing-code-graph — reconciliar gráfico de código com o repositório em portão de plano ou sob demanda
• loam-querying-memory — responder a uma pergunta a partir da memória
• loam-amending-memory — corrigir alegações de memória específicas, incorretas ou desatualizadas
• loam-linting-memory — verificar a saúde do gráfico de memória
• loam-normalizing-memory — adaptar estrutura a um corpus de memória bagunçado
• loam-reviewing-memory — revelar lacunas não resolvidas na memória
• loam-learning-from-session — capturar aprendizados da sessão, rotear para wiki ou orientação
• loam-auditing-guidance — auditar e melhorar AGENTS.md / CLAUDE.md / .claude.local.md
• loam-scaffolding-wiki — instanciar um novo scaffold de substrato wiki
• loam-initializing-vault — configurar um vault Obsidian com configuração

Instalando comandos de barra

Se o usuário quiser /checkpoint e /resume como comandos de atalho (em vez de digitar /loam::checkpointing e /loam::resuming), você pode instalá-los. Os arquivos de comando estão no repositório loam sob commands/.

Leia references/commands-install.md para o protocolo completo. Ele cobre:

• Em qual host você está executando (sinais de detecção)
• Qual formato de comando seu host espera (markdown vs TOML)
• Onde instalar (global vs local ao projeto)
• O protocolo de pedir permissão antes de copiar

Os arquivos de comando estão agrupados como ativos sob assets/commands/