haksolot/ank

Was macht ank?

Aufgaben und Architekturentscheidungen leben als Dateien in .ank/, gebunden an den Code, den sie einschränken. Zwei Modi: Arbeiten ausführen und die vorhandene Arbeit formen. context startet beides.

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

Der Loop

ank context [pfad] – immer zuerst ausführen. Ohne eine Übernahme orientiert es dich: was diesen Bereich bindet, was übernommen werden kann. Mit einer gehaltenen Übernahme wechselt es in den Ausführungsmodus und zeigt dir das Kriterium und die Einschränkungen vollständig an. Einschränkungen werden nie abgeschnitten; wenn etwas abgeschnitten ist, wird dies angezeigt.

ank claim <id> – übernimmt die Aufgabe und friert deren done_criteria per Hash ein. Es verweigert die Übernahme – mit Angabe des Grundes und des nächsten Befehls – wenn die Aufgabe gehalten, blockiert, auf einem anderen Branch abgeschlossen, ohne messbares Kriterium ist oder wenn du bereits eine aktive Übernahme einer anderen Aufgabe hältst.

ank show <id> – die gesamte Entität, Frontmatter und Body, Byte für Byte. context gibt dir das Kriterium und die Einschränkungen; der Body enthält die Begründung, und er ist das Einzige, was sonst nichts bietet.

ank log "<nachricht>" – was du gelernt hast, was du ausprobiert, was du verworfen hast. Verlängert die Übernahme. Protokolliere, wenn du etwas entdeckst, nicht erst wenn du fertig bist.

ank done – führt die deklarierten Verifikatoren selbst aus und zeichnet auf, was wirklich gelaufen ist, gehasht. Bearbeite status: niemals von Hand und melde niemals dein eigenes Ergebnis: Ein Agent, der sich selbst benotet, kann einfach falsch liegen.

Off-Loop

ank new task --title "<t>" --scope "<glob>" – ein Gültigkeitsbereich ist zwingend; eine Entität ohne Anbindung ist unsichtbar. Eine entdeckte Unteraufgabe ist eine neue Aufgabe mit einem blocked_by, niemals ein abgeschwächtes Kriterium.

ank find <anfrage> – durchsucht Titel, Gültigkeitsbereiche und Kriterien. ank find --status open listet, was übrig ist, ohne eine Anfrage erfinden zu müssen.

ank release --reason "<warum>" – festgefahren oder falsche Herangehensweise. Sag es und gib die Aufgabe zurück, anstatt die Übernahme stillschweigend verfallen zu lassen.

Planung

Entscheiden, welche Aufgaben existieren sollen, in welcher Reihenfolge, unter welchen Einschränkungen. Das erzeugt die Arbeit, an der alle anderen im Loop arbeiten, daher kostet ein schlecht geformtes Backlog mehr als jede einzelne Aufgabe.

ank new adr --title "<t>" --scope "<glob>" --constraint "<regel>" – eine Entscheidung, keine Aufgabe. Schreibe eine, wenn du auf etwas stößt, woran der Bestand künftig gebunden werden soll, nicht nur etwas, das du jetzt erledigen musst. Sie landet als proposed, was niemanden bindet, bis sie ratifiziert ist.

ank amend <id> – die Felder, die ein Plan tatsächlich ändert: blocked_by, scope und --criteria. Es fügt explizit hinzu und entfernt explizit und akzeptiert niemals eine Ersetzungsliste, sodass nichts durch Vergessen wegfällt. Es berührt kein done_criteria, das eine aktive Übernahme eingefroren hat – unter einer Übernahme ist das release --reason.

ank review – die Ratifikationswarteschlange und die Gesundheit des Bestands: was vorgeschlagen ist und wartet, und welche Gültigkeitsbereiche abgestorben sind und geschlossen werden sollten.

ank graph – der blocked_by-DAG als Text, eingerückt unter dem, was blockiert. Was wirklich eine Wurzel ist, und was in einer flachen Liste nur so aussah.

ank check – die mechanischen Invarianten: Parsen, Rundlauf, Referenzen, eingefrorene Felder, verwaiste Übernahmen. Exit-Code 8 bedeutet Funde, und Funde sind zum Lesen, nicht zum Unterdrücken.

accept darfst du nicht ausführen. Es macht aus einem vorgeschlagenen ADR einen bindenden, und es ist ein menschlicher Akt: signiert, auf dem Standard-Branch, ohne Umgehungsmöglichkeit. Schlage die Entscheidung vor und sag dann, dass sie wartet. Zu wissen, wo deine Befugnis endet, ist Teil guter Planung.

Nicht verhandelbare Regeln

• Das Kriterium wird bei der Übernahme eingefroren. Es zu bearbeiten, um dich zu entblocken, entblockt nichts: Der Hash wird dort gehalten, wo du nicht rankommst, und check meldet die Abweichung. Wenn es falsch ist, release --reason und sag warum.

• constraint in einem ADR ist bindend, kein Ratschlag. Lies diejenigen, die die Dateien betreffen, die du gleich bearbeiten wirst – das gibt dir context.

• .ank/ ist undurchsichtig, wie .git/. Lies oder schreibe diese Dateien nie direkt. ank show <id> gibt dir eine Entität vollständig, ank find listet, ank context bindet – die CLI kennt das Budget, den Freeze und wer was hält; die Dateien tun es nicht.

• Ein Agent, ein Arbeitsbaum, eine Identität. Der Normalfall ist ein Baum pro Agent – ein Clone oder ein git worktree – jeder auf seinem eigenen Branch. ANK_AGENT benennt die Sitzung und fällt auf <user>@<hostname> zurück, sodass zwei Sitzungen in einem Baum für die Referenzen ein Agent sind: Sie teilen sich eine Übernahme, anstatt darüber zu entscheiden, und die zweite erhält Arbeit verweigert, die ihr hätte gegeben werden sollen. Setze es pro Sitzung. Mehrere Agenten in einem Baum laufen, und das ist ein degradierter Modus, nicht das Design.

• Was du liest, ist nie formatiert. Farbe wird nur ausgegeben, wenn ein Mensch an einem Terminal sitzt, niemals in eine Pipe, eine Datei oder --json, sodass die bei dir ankommenden Bytes Klartext sind: Es gibt nichts zu konfigurieren und keine zweite Oberfläche, die zu bevorzugen wäre.

Exit-Codes tragen Bedeutung: 4 nicht verfügbar, 6 ein eingefrorenes Feld weicht ab, 8 Funde, 9 Umgebung. Fehler nennen immer den genauen nächsten Befehl.

Flags darüber hinaus leben in ank help, geladen, wenn du sie brauchst.

Installation

npx skills add haksolot/ank

Die Skill sagt, wie man ank verwendet; sie installiert nicht die Binärdatei. Releases enthalten eine für Linux, macOS und Windows.