wshobson/superself

O que superself faz?

Superself é uma CLI Apache-2.0 (npm install -g [email protected], Node 22.12+) que versiona o estado de um projeto — metas, decisões, unidades de trabalho, relatórios — como um log de eventos imutável em um repositório git separado do código. O estado é derivado sob demanda, então nada nele é mantido manualmente. Esta habilidade instrui um agente sobre como ler e escrever esse estado através da CLI self. Ela é mantida pelos autores do Superself: https://github.com/fxylabs/superself

Quando esta habilidade se aplica

• O arquivo AGENTS.md ou CLAUDE.md do projeto contém um bloco entre <!-- superself:begin e <!-- superself:end -->, ou self setup imprime o workspace, projeto e repositório para os quais este diretório resolve.
• Ignore a habilidade quando self --version falhar: o projeto não usa Superself, e nada abaixo deve ser inventado manualmente. Esta habilidade é escrita para [email protected]; uma versão major ou minor diferente pode ter movido um verbo ou flag, então verifique self <comando> --help antes de confiar em um.

Início da sessão

1. Execute self context e trate sua saída como verdade atual: a meta, decisões e convenções ativas, trabalho em aberto, relatórios recentes. Ele é derivado do log, nunca escrito manualmente.
2. Algo ausente do contexto foi propositalmente deixado de fora do conjunto renderizado; self search <consulta> encontra registros vivos que o contexto omitiu, e self work show <id> imprime o resumo completo e histórico de relatórios de uma unidade.

Durante o trabalho

• Trabalho substancial é anexado a uma unidade de trabalho. Crie uma com self work add "<resultado esperado>" — o resultado é o que deve se tornar verdadeiro, não a tarefa — depois self work start <id>. start lê o resumo e registra que esta sessão pegou a unidade; se outra sessão a detém, a CLI informa quem e desde quando e não recusa. Julgue e prossiga.
• Após commitar, reporte o progresso: self report <id> "<o que aconteceu>". O commit HEAD atual é anexado automaticamente como evidência; --evidence <commit|note> anexa outra coisa, --file <caminho> anexa um resumo mais longo.
• Registre uma decisão confirmada pelo usuário: self decide "<texto>" --why "<motivo>". Use --proposed quando o usuário ainda não a confirmou. Uma decisão por evento.
• Bloqueado? self work block <id> --on decisão|dependência|externo --why "...". Substituído ou movido? self work retire <id> --why "..." [--successor <id>]. Nunca marque tal unidade como concluída e nunca a deixe falsamente bloqueada.
• Encontrou uma lacuna entre um objetivo e o estado atual? Proponha o trabalho com self work propose e seu resumo; o usuário aceita ou recusa.
• O usuário aprovou um próximo passo ou uma continuação? Registre-o imediatamente com self work add e o contexto por trás dele. Um plano que vive apenas na conversa se perde quando a conversa termina.

Encerramento

• self work done <id> fecha uma unidade apenas quando um relatório carrega um commit ou um artefato, ou o próprio "done" declara o que verificavelmente aconteceu: self work done <id> --report "<o que verificavelmente aconteceu>". Uma mera alegação é recusada, e os critérios declarados a bloqueiam até que cada um seja coberto.
• O texto de um registro é imutável uma vez confirmado. Corrija-o reafirmando: --supersedes <id> em qualquer verbo de adição registra a nova redação e mantém o histórico. retract retira um registro sem substituí-lo.

Regras que mantêm o estado confiável

• Registros — eventos, decisões, relatórios, convenções — são escritos em inglês para que quem os abrir em seguida possa lê-los; responda à pessoa em seu próprio idioma.
• Um branch atinge a main através de um pull request: revisão de PR e CI controlam o merge. Superself gerencia o contexto e o grafo de trabalho, não a porta de merge.
• Nunca edite manualmente arquivos de estado gerados ou qualquer coisa sob .superself/.
• Em um projeto sem um bloco superself, execute self setup primeiro. Se ele resolver o diretório para um projeto registrado, pergunte ao usuário uma vez se deseja executar self connect, que escreve o bloco gerenciado em AGENTS.md ou CLAUDE.md. Se não resolver nenhum projeto, pergunte uma vez se deseja registrá-lo com self project init. Nunca registre ou conecte um projeto por conta própria.

Aprofundando

self --help lista todos os verbos; self <comando> --help imprime as flags de um comando sem tocar no estado. Guias de tópico acompanham a CLI:

• self help agents — como uma sessão conduz esta CLI, do início ao fim
• self help context — o que self context renderiza, e por que algo está ausente
• self help records — uma entidade por trás de cada tipo de registro, e como corrigir um registro
• self help placement — escopo, prioridade e exposição — como um registro ganha seu lugar no contexto
• self help work — o grafo de trabalho: resultados, evidências, critérios e propostas
• self help goals — metas de longo prazo, objetivos, marcos e o que é necessário para alcançar um
• self help workspace — o repositório, os projetos nele e como movê-lo entre máquinas