Superself

Superself é uma CLI (npm install -g superself@0.6.1, Node 22.12+) com licença Apache-2.0 que controla a versão do estado de um projeto — objetivos, decisões, unidades de trabalho, relatórios — como um log de eventos somente de adição em um repositório git separado do código. O estado é derivado sob demanda, então nada nele é mantido manualmente. Essa habilidade ensina um agente a 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 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 store para os quais este diretório se resolve.
• Pule a habilidade quando self --version falhar: o projeto não usa Superself, e nada abaixo deve ser inventado manualmente. Esta habilidade é escrita contra superself@0.6.1; uma versão principal ou secundária diferente pode ter movido um verbo ou flag, então verifique self <command> --help antes de confiar em uma.

Início da sessão

1. Execute self context e trate sua saída como a verdade atual: o objetivo, decisões e convenções ativas, trabalho em andamento, relatórios recentes. Ele é dobrado do log, nunca escrito manualmente.
2. Algo faltando no contexto foi colocado fora do conjunto renderizado de propósito; self search <query> encontra registros ativos de contexto deixados de fora, e self work show <id> imprime o resumo completo e o histórico de relatórios de uma unidade.

Durante o trabalho

• Trabalho substantivo se anexa a uma unidade de trabalho. Crie uma com self work add "<required outcome>" — o resultado é o que deve se tornar verdade, não a tarefa — então 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 diz quem e desde quando e não recusa. Julgue e prossiga.
• Após o commit, relate o progresso: self report <id> "<what happened>". O commit HEAD atual é anexado como evidência automaticamente; --evidence <commit|note> attaches something else, --file <path> anexa um resumo mais longo.
• Registre uma decisão que o usuário confirmou: self decide "<text>" --why "<reason>". Use --proposed quando o usuário não a confirmou. Uma decisão por evento.
• Bloqueado? self work block <id> --on decision|dependency|external --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 é perdido quando a conversa termina.

Fechamento

• 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 aconteceu verificavelmente: self work done <id> --report "<what verifiably happened>". Uma alegação vazia é recusada, e os critérios declarados a impedem até que cada um seja coberto.
• O texto de um registro é imutável após confirmado. Corrija-o reestilizando: --supersedes <id> em qualquer verbo de adição registra a nova redação e mantém a linhagem. retract retira um registro sem nada o substituindo.

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 chega à main através de um pull request: a revisão de PR e o CI controlam a mesclagem. Superself controla o contexto e o grafo de trabalho, não o portão de mesclagem.
• 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 ele 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.

Indo mais fundo

self --help lista todos os verbos; self <command> --help imprime os flags de um comando sem tocar no estado. Guias de tópicos vêm com 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á faltando nele

…