es

La herramienta de coordinación tonta

Tareas y decisiones de arquitectura en tu repo, detrás de una sola CLI que cualquier agente de código puede llamar.

npm install -g @haksolot/ank
npx skills add haksolot/ank
Leer el quickstartGitHubDiscord

Open source, Apache-2.0. Linux, macOS y 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

Salida real, sacada del quickstart. Su suite de tests vuelve a ejecutar estos comandos contra el binario en cada cambio.

Funciona con el agente que ya usas

ank es una herramienta de línea de comandos. Cualquier agente que pueda ejecutar un comando de shell puede recorrer el ciclo, y un cliente sin shell llega a los mismos verbos por 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

Un solo comando instala las skills en los agentes de esta lista que encuentre, y en una treintena más.

Tu agente lee el código, no el hilo

Un agente puede leer cada línea de tu código, pero no tu tracker, tu wiki ni el hilo donde decidiste que las sesiones nunca serían JWT autocontenidos. Nada impide que la siguiente sesión escriba uno.

ank guarda esas decisiones y el trabajo en .ank/, unidos por un glob al código que restringen. Antes de empezar, el agente ejecuta ank context src/auth/ y la regla llega junto con la tarea.

Archivos markdown normales en tu repositorio, revisados como cualquier otro cambio. Ningún servidor que mantener: los claims son refs de git.

Seis verbos

Todo el ciclo que necesita un agente. ank help lista todos los demás.

  1. ank context <path>

    Qué restringe este perímetro y qué se puede tomar. La primera llamada, siempre.

  2. ank claim <id>

    Tomar una tarea y congelar su criterio.

  3. ank show <id>

    La entidad completa: frontmatter, cuerpo y log.

  4. ank log "<message>"

    Lo que aprendiste, mientras trabajas. Escribirlo renueva el claim.

  5. ank done

    Ejecutar los verificadores declarados y registrar la prueba.

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

    Devolver la tarea, y decir por qué.

Tres ideas por debajo

Cada una es una propiedad de la herramienta, no una convención que se te pide respetar.

Scope, no jerarquía

Las restricciones y el trabajo son dos planos unidos solo por globs. Una regla escrita el año pasado restringe el trabajo creado hoy, y un glob se comprueba contra el sistema de archivos, cosa que una etiqueta no permite. Sin épicas, sin padres, sin agregados que mantener al día.

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

El criterio se congela al hacer claim

Tomar una tarea congela su done_criteria con un hash, fuera del alcance de quien edita el archivo. Reescribir el criterio para desbloquearte no desbloquea nada: ank check muestra la divergencia. Un claim a la vez por identidad, y un claim es una ref de git: dos agentes que van a por la misma tarea, un solo ganador.

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)

Nadie se declara terminado

Un agente que informa de su propio resultado puede, sencillamente, equivocarse. ank done ejecuta los verificadores por sí mismo y registra lo que realmente se ejecutó, con hash. Una tarea sin nada que ejecutar pide una prueba que le das tú, y cada rechazo nombra el comando que lo resuelve.

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>

Lo que no es

  • No es un tracker. Sin ciclos, estimaciones, velocidad ni roadmap.

  • No es una wiki. Solo entra lo que es accionable o vinculante para un agente.

  • No es una barrera de seguridad. Protege contra la deriva, no contra un atacante.

ank se construye con ank

Su propio repositorio funciona con este ciclo. El .ank/ en su raíz guarda los ADR que su código debe cumplir y las tareas que lo construyeron, y la documentación cita esas decisiones por su id.

La versión es 0.x a propósito: el ciclo y los códigos de salida están especificados, el formato de almacenamiento todavía no.

Ver su .ank/ en GitHub

Instalar ank

Dos comandos. Linux, macOS y Windows, con git 2.34 o posterior.

npm install -g @haksolot/ank
npx skills add haksolot/ank
Leer la guía rápidaOtras formas de instalar