pt

A ferramenta de coordenação burra

Tarefas e decisões de arquitetura no seu repo, atrás de uma única CLI que qualquer agente de código pode chamar.

npm install -g @haksolot/ank
npx skills add haksolot/ank
Ler o quickstartGitHubDiscord

Open source, Apache-2.0. Linux, macOS e Windows.

~/auth-service
ank context src/auth/

CONSTRAINTS (1 active)
  ADR-06d2  Opaque sessions rather than stateless JWT

TASKS (1)
  TASK-820d  [open] Migrate auth to opaque sessions

> ank claim TASK-820d to start

ank claim 820d
claimed TASK-820d259af6a7 migrate-auth-to-opaque-sessions -> HEAD

ank context

TASK-820d  Migrate auth to opaque sessions

DONE_CRITERIA
  The auth tests pass and no reference to jwt.verify remains in src/auth/

CONSTRAINTS (1 active)
  ADR-06d2  Do not introduce self-contained JWTs for user auth. Every session goes through the Redis store.

ank log "jwt.verify removed from session.ts"
logged LOG-6b0f39d7a4c1 on TASK-820d259af6a7

ank done
running: auth-tests ... ok (0.0s)
running: no-jwt ... ok (0.0s)
proof recorded: auth-tests@94a1f671c577 -> local/e3b0c44298fc@9c45c50  (scope/18d14da584ab)
proof recorded: no-jwt@791cc818d0ad -> local/e3b0c44298fc@9c45c50  (scope/18d14da584ab)
TASK-820d259af6a7 -> done

Saída real, tirada do quickstart. A suíte de testes dele roda esses comandos de novo contra o binário a cada mudança.

Funciona com o agente que você já usa

O ank é uma ferramenta de linha de comando. Qualquer agente que consiga rodar um comando de shell consegue percorrer o loop, e um cliente sem shell chega aos mesmos verbos via MCP.

  • Claude Code
  • Codex
  • Cursor
  • OpenCode
  • Gemini CLI
  • GitHub Copilot
  • Cline
  • Amp
  • pi
  • Antigravity
  • Goose
  • Kiro
  • Roo Code
  • Kilo Code
  • Windsurf
  • Qwen Code
  • Mistral Vibe
  • OpenHands
  • Junie
  • Devin

Um único comando instala as skills nos agentes desta lista que ele encontrar, e em uns trinta outros.

Seu agente lê o código, não a thread

Um agente consegue ler cada linha do seu código, mas não o seu tracker, a sua wiki ou a thread em que vocês decidiram que sessões nunca seriam JWTs autocontidos. Nada impede a próxima sessão de escrever um.

ank guarda essas decisões e o trabalho em .ank/, ligados por um glob ao código que eles restringem. Antes de começar, o agente roda ank context src/auth/, e a regra vem junto com a tarefa.

Arquivos markdown comuns no seu repositório, revisados como qualquer outra mudança. Nenhum servidor para manter: claims são refs do git.

Seis verbos

O loop inteiro de que um agente precisa. ank help lista todos os outros.

  1. ank context <path>

    O que restringe este perímetro, e o que está livre para pegar. A primeira chamada, sempre.

  2. ank claim <id>

    Pegar uma tarefa e congelar o critério dela.

  3. ank show <id>

    A entidade inteira: frontmatter, corpo e log.

  4. ank log "<message>"

    O que você aprendeu, enquanto trabalha. Registrar renova o claim.

  5. ank done

    Rodar os verificadores declarados e registrar a prova.

  6. ank release --reason "<why>"

    Devolver a tarefa, e dizer por quê.

Três ideias por baixo

Cada uma é uma propriedade da ferramenta, não uma convenção que pedem para você seguir.

Scope, não hierarquia

Restrições e trabalho são dois planos ligados só por globs. Uma regra escrita no ano passado vale para o trabalho criado hoje, e um glob é conferido contra o sistema de arquivos, coisa que um rótulo não é. Sem épico, sem pai, sem agregado para manter em dia.

ank new adr --title "Opaque sessions rather than stateless JWT" \
    --scope "src/auth/**" \
    --constraint "Do not introduce self-contained JWTs for user auth. Every session goes through the Redis store."
created ADR-06d29e727d24 Opaque sessions rather than stateless JWT

O critério congela no claim

Pegar uma tarefa congela o done_criteria dela por hash, fora do alcance de quem edita o arquivo. Reescrever o critério para se desbloquear não desbloqueia nada: ank check mostra a divergência. Um claim por vez por identidade, e um claim é uma ref do git: dois agentes indo atrás da mesma tarefa, um só vencedor.

ank claim 820d
claimed TASK-820d259af6a7 migrate-auth-to-opaque-sessions -> HEAD
ank claim 51c2
error[7]: human:marie holds a live claim on TASK-820d259af6a7 (expires in 30m)
  -> ank release --reason "<why>"   (a second session on this machine sets its own ANK_AGENT)

Ninguém se declara pronto

Um agente que relata o próprio resultado pode simplesmente estar errado. ank done roda os verificadores ele mesmo e registra o que de fato rodou, com hash. Uma tarefa sem nada para rodar pede uma prova que você entrega, e toda recusa diz o comando que a resolve.

ank claim 51c2
claimed TASK-51c2a0f6d418 say-in-the-readme-what-a-session-is-now -> HEAD
ank done
error[5]: proof required to move TASK-51c2a0f6d418 to done
  -> ank done --proof commit:<sha>

O que ele não é

  • Não é um tracker. Sem ciclos, estimativas, velocity ou roadmap.

  • Não é uma wiki. Só entra o que é acionável ou obrigatório para um agente.

  • Não é uma barreira de segurança. Ele protege contra drift, não contra um atacante.

ank é feito com ank

O próprio repositório dele roda neste loop. O .ank/ na raiz guarda os ADRs que o código dele precisa seguir e as tarefas que o construíram, e a documentação cita essas decisões pelo id.

A versão é 0.x de propósito: o loop e os códigos de saída estão especificados, o formato de armazenamento ainda não.

Ver o .ank/ dele no GitHub

Instalar o ank

Dois comandos. Linux, macOS e Windows, com git 2.34 ou mais recente.

npm install -g @haksolot/ank
npx skills add haksolot/ank
Ler o guia rápidoOutras formas de instalar