haksolot/ank

¿Qué hace ank?

Las tareas y las decisiones de arquitectura viven como archivos en .ank/, adjuntos al código que restringen. Dos modos: ejecutar trabajo, y dar forma al trabajo existente. context inicia ambos.

Bucle:       ank context -> ank claim <id> -> ank show <id> -> ank log "<msg>" -> ank done
Fuera del bucle:  ank new, ank find, ank release --reason "<r>"
Planificación:    ank new adr, ank amend, ank review, ank graph, ank check

El bucle

ank context [ruta] — ejecútalo primero, siempre. Sin una reclamación activa te orienta: qué delimita este perímetro, qué es reclamable. Con una reclamación activa cambia a modo ejecución y te da el criterio y las restricciones completas. Las restricciones nunca se truncan; si algo se corta, lo indica.

ank claim <id> — toma la tarea y congela sus done_criteria mediante un hash. Se niega, con la razón y el siguiente comando, cuando la tarea está retenida, bloqueada, finalizada en otra rama, no tiene criterio con el que medirse, o cuando ya posees una reclamación viva en otra tarea.

ank show <id> — la entidad completa, frontmatter y cuerpo, byte por byte. context te da el criterio y las restricciones; el cuerpo es donde vive el razonamiento, y es lo único que nada más sirve.

ank log "<mensaje>" — lo que aprendiste, lo que intentaste, lo que rechazaste. Renueva la reclamación. Registra cuando descubres algo, no cuando terminas.

ank done — ejecuta los verificadores declarados y registra lo que realmente se ejecutó, con hash. Nunca edites status: a mano, y nunca informes tu propio resultado: un agente que se califica a sí mismo simplemente puede estar equivocado.

Fuera del bucle

ank new task --title "<t>" --scope "<glob>" — un ámbito es obligatorio; una entidad no adjunta a nada es invisible. Una subtarea que descubres es una tarea nueva con un blocked_by, nunca un criterio suavizado.

ank find <consulta> — busca títulos, ámbitos y criterios. ank find --status open lista lo que queda, sin necesidad de inventar una consulta.

ank release --reason "<por qué>" — estancado, o equivocado sobre el enfoque. Dilo y devuelve la tarea en lugar de dejar que la reclamación expire en silencio.

Planificación

Decidir qué tareas deben existir, en qué orden, bajo qué restricciones. Esto es lo que produce el trabajo sobre el que todos los demás iteran, por lo que un backlog mal diseñado cuesta más aguas abajo que cualquier tarea individual.

ank new adr --title "<t>" --scope "<glob>" --constraint "<regla>" — una decisión, no una tarea. Escribe una cuando encuentres algo a lo que el corpus deba atenerse después, en lugar de algo que solo tienes que hacer ahora. Se crea como proposed, lo que no vincula a nadie hasta que se ratifica.

ank amend <id> — los campos que un plan realmente cambia: blocked_by, scope y --criteria. Añade y elimina explícitamente y nunca toma una lista de reemplazo, por lo que nada se pierde por olvido. No tocará un done_criteria que una reclamación viva haya congelado — bajo una reclamación, eso es release --reason.

ank review — la cola de ratificación y la salud del corpus: qué está propuesto y en espera, y qué ámbitos han quedado inactivos y necesitan cerrarse.

ank graph — el DAG de blocked_by como texto, indentado bajo lo que lo bloquea. Qué es realmente una raíz, y qué solo parecía una en una lista plana.

ank check — los invariantes mecánicos: análisis sintáctico, ida y vuelta, referencias, campos congelados, reclamaciones huérfanas. El código de salida 8 significa hallazgos, y los hallazgos son para leerlos, no para silenciarlos.

accept no es tuyo para ejecutarlo. Es lo que convierte un ADR propuesto en uno vinculante, y es un acto humano: firmado, en la rama por defecto, sin forma de evitarlo. Propón la decisión, luego di que está en espera. Saber dónde termina tu autoridad es parte de una buena planificación.

Reglas que no son negociables

• El criterio se congela al reclamar. Editarlo para desbloquearte no desbloquea nada: el hash se mantiene donde no puedes alcanzarlo, y check informa la divergencia. Si es incorrecto, release --reason y explica por qué.

• constraint en un ADR es vinculante, no un consejo. Lee los que cubren los archivos que estás a punto de tocar — eso es lo que context te entrega.

• .ank/ es opaco, como .git/. Nunca leas ni escribas esos archivos directamente. ank show <id> te da una entidad completa, ank find lista, ank context vincula — la CLI conoce el presupuesto, la congelación y quién tiene qué; los archivos no.

• Un agente, un árbol de trabajo, una identidad. El caso nominal es un árbol por agente — un clon o un git worktree — cada uno en su propia rama. ANK_AGENT nombra la sesión y se reduce a <usuario>@<hostname>, así que dos sesiones en un mismo árbol son un solo agente para las referencias: comparten una reclamación en lugar de arbitrar sobre ella, y la segunda recibe un rechazo del trabajo que debería habérsele asignado. Establécelo por sesión. Varios agentes en un mismo árbol funciona, y es un modo degradado en lugar del diseño.

• Lo que lees nunca tiene estilo. El color se emite solo cuando un humano está en una terminal, nunca hacia un pipe, un archivo o --json, por lo que los bytes que te llegan son planos: no hay nada que configurar ni una segunda superficie que preferir.

Los códigos de salida tienen significado: 4 no disponible, 6 un campo congelado divergió, 8 hallazgos, 9 entorno. Los errores siempre nombran el siguiente comando exacto.

Las banderas más allá de estas viven en ank help, cargadas cuando las necesites.

Instalación

npx skills add haksolot/ank

El skill explica cómo usar ank; no instala el binario. Los lanzamientos incluyen uno para Linux, macOS y Windows.