haksolot/ank

Que fait ank ?

Les tâches et les décisions d'architecture vivent sous forme de fichiers dans .ank/, attachés au code qu'elles contraignent. Deux modes : exécuter du travail, et façonner le travail existant. context démarre les deux.

Boucle :     ank context -> ank claim <id> -> ank show <id> -> ank log "<msg>" -> ank done
Hors-boucle : ank new, ank find, ank release --reason "<r>"
Planification : ank new adr, ank amend, ank review, ank graph, ank check

La boucle

ank context [chemin] — exécutez-le d'abord, toujours. Sans revendication, il vous oriente : ce qui délimite ce périmètre, ce qui est revendicable. Avec une revendication active, il bascule en mode exécution et vous donne le critère et les contraintes en intégralité. Les contraintes ne sont jamais tronquées ; si quelque chose est coupé, il le signale.

ank claim <id> — prend la tâche et gèle ses done_criteria par hachage. Il refuse, avec la raison et la commande suivante, lorsque la tâche est détenue, bloquée, terminée sur une autre branche, n'a pas de critère pour être mesurée, ou lorsque vous détenez déjà une revendication active sur une autre tâche.

ank show <id> — l'entité entière, frontmatter et corps, octet par octet. context vous donne le critère et les contraintes ; le corps est l'endroit où se trouve le raisonnement, et c'est la seule chose que rien d'autre ne sert.

ank log "<message>" — ce que vous avez appris, ce que vous avez essayé, ce que vous avez rejeté. Renouvelle la revendication. Enregistrez lorsque vous découvrez quelque chose, pas lorsque vous terminez.

ank done — exécute les vérificateurs déclarés lui-même et enregistre ce qui a réellement été exécuté, haché. Ne modifiez jamais status: à la main, et ne rapportez jamais votre propre résultat : un agent qui s'évalue lui-même peut tout simplement se tromper.

Hors-boucle

ank new task --title "<t>" --scope "<glob>" — un périmètre est obligatoire ; une entité attachée à rien est invisible. Une sous-tâche que vous découvrez est une nouvelle tâche avec un blocked_by, jamais un critère assoupli.

ank find <requête> — rechercher dans les titres, les périmètres et les critères. ank find --status open liste ce qui reste, sans avoir à inventer de requête.

ank release --reason "<pourquoi>" — bloqué, ou dans l'erreur concernant l'approche. Dites-le et rendez la tâche plutôt que de laisser la revendication expirer en silence.

Planification

Décider quelles tâches doivent exister, dans quel ordre, sous quelles contraintes. C'est ce qui produit le travail sur lequel tout le monde va boucler, donc un backlog mal formé coûte plus cher en aval que n'importe quelle tâche individuelle.

ank new adr --title "<t>" --scope "<glob>" --constraint "<règle>" — une décision, pas une tâche. Écrivez-en une lorsque vous rencontrez quelque chose auquel le corpus devrait être tenu par la suite, plutôt que quelque chose que vous devez simplement faire maintenant. Elle atterrit en proposed, ce qui n'engage personne jusqu'à ce qu'elle soit ratifiée.

ank amend <id> — les champs qu'un plan modifie réellement : blocked_by, scope et --criteria. Il ajoute et supprime explicitement et n'accepte jamais une liste de remplacement, donc rien n'est abandonné par oubli. Il ne touchera pas à un done_criteria qu'une revendication active a gelé — sous une revendication, c'est release --reason.

ank review — la file d'attente de ratification et la santé du corpus : ce qui est proposé et en attente, et quels périmètres sont devenus inactifs et doivent être fermés.

ank graph — le graphe orienté acyclique des blocked_by sous forme de texte, indenté sous ce qui le bloque. Ce qui est vraiment une racine, et ce qui n'en avait l'air que dans une liste plate.

ank check — les invariants mécaniques : analyse, aller-retour, références, champs gelés, revendications orphelines. Le code de sortie 8 signifie des constats, et les constats sont faits pour être lus, pas pour être réduits au silence.

accept n'est pas à vous d'exécuter. C'est ce qui transforme une ADR proposée en une ADR contraignante, et c'est un acte humain : signé, sur la branche par défaut, sans aucun moyen de contournement. Proposez la décision, puis dites qu'elle est en attente. Savoir où s'arrête votre autorité fait partie d'une bonne planification.

Règles qui ne sont pas négociables

• Le critère est gelé lors de la revendication. Le modifier pour vous débloquer ne débloque rien : le hachage est conservé là où vous ne pouvez pas l'atteindre, et check signale la divergence. S'il est erroné, release --reason et expliquez pourquoi.

• constraint dans une ADR est contraignante, pas un conseil. Lisez celles qui couvrent les fichiers que vous êtes sur le point de modifier — c'est ce que context vous donne.

• .ank/ est opaque, comme .git/. Ne lisez ni n'écrivez jamais ces fichiers directement. ank show <id> vous donne une entité entière, ank find liste, ank context relie — la CLI connaît le budget, le gel et qui détient quoi ; les fichiers, non.

• Un agent, un arbre de travail, une identité. Le cas nominal est un arbre par agent — un clone ou un git worktree — chacun sur sa propre branche. ANK_AGENT nomme la session et se rabat sur <utilisateur>@<hôte>, donc deux sessions dans un même arbre sont un seul agent pour les références : elles partagent une revendication au lieu d'arbitrer dessus, et la seconde se voit refuser un travail qui aurait dû lui être donné. Définissez-le par session. Plusieurs agents dans un seul arbre fonctionne, et est un mode dégradé plutôt que la conception.

• Ce que vous lisez n'est jamais stylisé. La couleur n'est émise que lorsqu'un humain est sur un terminal, jamais dans un tube, un fichier ou --json, donc les octets qui vous parviennent sont en clair : il n'y a rien à configurer et aucune seconde surface à préférer.

Les codes de sortie portent une signification : 4 indisponible, 6 un champ gelé a divergé, 8 constats, 9 environnement. Les erreurs nomment toujours la commande exacte suivante.

Les drapeaux supplémentaires se trouvent dans ank help, chargé lorsque vous en avez besoin.

Installation

npx skills add haksolot/ank

La compétence explique comment utiliser ank ; elle n'installe pas le binaire. Les versions fournissent un binaire pour Linux, macOS et Windows.