haksolot/ank

O que ank faz?

Tarefas e decisões de arquitetura vivem como arquivos em .ank/, ligadas ao código que restringem. Dois modos: executar trabalho e modelar o trabalho existente. context inicia ambos.

Loop:      ank context -> ank claim <id> -> ank show <id> -> ank log "<msg>" -> ank done
Off-loop:  ank new, ank find, ank release --reason "<r>"
Planejamento:  ank new adr, ank amend, ank review, ank graph, ank check

O Loop

ank context [caminho] — execute-o primeiro, sempre. Sem um claim ativo, ele orienta: quais vínculos delimitam este perímetro, o que é reivindicável. Com um claim ativo, ele alterna para execução e fornece o critério e as restrições por completo. As restrições nunca são truncadas; se algo for cortado, ele avisa.

ank claim <id> — pega a tarefa e congela seus done_criteria por hash. Ele recusa, com o motivo e o próximo comando, quando a tarefa está em andamento, bloqueada, finalizada em outro branch, não possui critério para ser medida, ou quando você já possui um claim ativo em outra tarefa.

ank show <id> — a entidade completa, frontmatter e corpo, byte por byte. context fornece o critério e as restrições; o corpo é onde reside o raciocínio, e é a única coisa que nada mais serve.

ank log "<mensagem>" — o que você aprendeu, o que tentou, o que rejeitou. Renova o claim. Registre quando descobrir algo, não quando terminar.

ank done — executa os verificadores declarados e registra o que realmente foi executado, com hash. Nunca edite status: manualmente e nunca relate seu próprio resultado: um agente que se autoavalia pode simplesmente estar errado.

Off-loop

ank new task --title "<t>" --scope "<glob>" — um escopo é obrigatório; uma entidade não vinculada a nada é invisível. Uma subtarefa descoberta é uma nova tarefa com um blocked_by, nunca um critério suavizado.

ank find <consulta> — pesquisa títulos, escopos e critérios. ank find --status open lista o que resta, sem precisar inventar uma consulta.

ank release --reason "<porquê>" — travou ou errou a abordagem. Diga isso e devolva a tarefa em vez de deixar o claim expirar em silêncio.

Planejamento

Decidir quais tarefas devem existir, em que ordem, sob quais restrições. Isso é o que produz o trabalho que todos os outros executam no loop, então um backlog mal formatado custa mais a jusante do que qualquer tarefa individual.

ank new adr --title "<t>" --scope "<glob>" --constraint "<regra>" — uma decisão, não uma tarefa. Escreva uma quando encontrar algo ao qual o corpus deve ser mantido posteriormente, em vez de algo que você apenas precisa fazer agora. Ela cai como proposed, que não vincula ninguém até ser ratificada.

ank amend <id> — os campos que um plano realmente altera: blocked_by, scope e --criteria. Ele adiciona e remove explicitamente e nunca aceita uma lista de substituição, para que nada seja descartado por esquecimento. Não tocará em um done_criteria que um claim ativo congelou — sob um claim, isso é release --reason.

ank review — a fila de ratificação e a saúde do corpus: o que está proposto e aguardando, e quais escopos ficaram inativos e precisam ser encerrados.

ank graph — o DAG de blocked_by como texto, indentado sob o que o bloqueia. O que é realmente uma raiz, e o que apenas parecia ser em uma lista plana.

ank check — os invariantes mecânicos: análise, ida e volta, referências, campos congelados, claims órfãos. Código de saída 8 significa descobertas, e descobertas são para leitura, não para silenciamento.

accept não é seu para executar. É o que transforma um ADR proposto em um vinculativo, e é um ato humano: assinado, no branch padrão, sem alternativa. Proponha a decisão, depois diga que está aguardando. Saber onde sua autoridade termina é parte de um bom planejamento.

Regras que não são negociáveis

• O critério é congelado no claim. Editá-lo para se desbloquear não desbloqueia nada: o hash está retido onde você não pode alcançá-lo, e check relata a divergência. Se estiver errado, release --reason e explique o porquê.

• constraint em um ADR é vinculativo, não um conselho. Leia os que cobrem os arquivos que você está prestes a tocar — é isso que context lhe entrega.

• .ank/ é opaco, como .git/. Nunca leia ou escreva esses arquivos diretamente. ank show <id> fornece uma entidade completa, ank find lista, ank context vincula — a CLI conhece o orçamento, o congelamento e quem detém o quê; os arquivos não.

• Um agente, uma árvore de trabalho, uma identidade. O caso nominal é uma árvore por agente — um clone ou um git worktree — cada um em seu próprio branch. ANK_AGENT nomeia a sessão e recai para <usuário>@<hostname>, então duas sessões em uma árvore são um único agente para as referências: elas compartilham um claim em vez de arbitrar sobre ele, e a segunda recebe trabalho recusado que deveria ter recebido. Defina-o por sessão. Vários agentes em uma árvore funciona, e é um modo degradado em vez do design.

• O que você lê nunca é estilizado. Cor é emitida apenas quando um humano está em um terminal, nunca em um pipe, arquivo ou --json, então os bytes que chegam a você são simples: não há nada para configurar e nenhuma segunda superfície para preferir.

Códigos de saída carregam significado: 4 indisponível, 6 um campo congelado divergiu, 8 descobertas, 9 ambiente. Erros sempre nomeiam o próximo comando exato.

Flags além destas vivem em ank help, carregadas quando você precisar delas.

Instalação

npx skills add haksolot/ank

A skill diz como usar ank; ela não instala o binário. Os releases carregam um para Linux, macOS e Windows.