haksolot/ank

ank は何をしますか？

タスクとアーキテクチャ上の決定は.ank/内にファイルとして保存され、それらが制約するコードに紐付きます。2つのモードがあります。作業を実行することと、既存の作業を整形することです。contextが両方の起点となります。

ループ:      ank context -> ank claim <id> -> ank show <id> -> ank log "<メッセージ>" -> ank done
ループ外:    ank new, ank find, ank release --reason "<理由>"
計画:       ank new adr, ank amend, ank review, ank graph, ank check

ループ

ank context [パス] — 常に最初に実行します。クレームを保持していない場合は現在の状況を把握します。どのような制約がこの範囲を規定しているか、何がクレーム可能かを示します。クレームを保持している場合は実行モードに切り替わり、完了基準と制約を完全な形で提示します。制約が切り詰められることはなく、もし何かが省略されている場合はその旨が明示されます。

ank claim <id> — タスクを取得し、そのdone_criteriaをハッシュで固定します。タスクが他の誰かに保持されている、ブロックされている、別のブランチで完了している、評価基準がない、または別のタスクで有効なクレームをすでに保持している場合、その理由と次に実行すべきコマンドとともに拒否されます。

ank show <id> — エンティティ全体を、フロントマターと本文を含めてバイト単位で表示します。contextが完了基準と制約を提供します。本文は検討の経緯が記述されている場所であり、それ以外の何物も提供しません。

ank log "<メッセージ>" — 学んだこと、試したこと、却下したことを記録します。クレームを更新します。作業が終わったときではなく、何かを発見したときにログを残します。

ank done — 宣言された検証プログラムを自ら実行し、実際に実行されたものをハッシュ化して記録します。status:を手動で編集したり、自分自身で結果を報告したりしないでください。自分自身を評価するエージェントは単に間違っている可能性があります。

ループ外

ank new task --title "<タイトル>" --scope "<グロブ>" — スコープは必須です。何にも紐付かないエンティティは見えません。発見したサブタスクは、blocked_byを持つ新しいタスクとして作成し、完了基準を緩めてはいけません。

ank find <クエリ> — タイトル、スコープ、完了基準を検索します。ank find --status openは残っているタスクを、クエリを考案することなく一覧表示します。

ank release --reason "<理由>" — 行き詰まった場合、またはアプローチが間違っていた場合。その理由を述べてタスクを戻し、クレームが黙って期限切れになるのを防ぎます。

計画

どのようなタスクを、どのような順序で、どのような制約の下で存在させるべきかを決定します。これこそが他の全員がループで作業する成果物を生み出すため、適切に整形されていないバックログは、単一のタスクよりもはるかに大きなコストを後工程に発生させます。

ank new adr --title "<タイトル>" --scope "<グロブ>" --constraint "<ルール>" — タスクではなく、決定事項です。単に今やらなければならないことではなく、今後コードベース全体が従うべきルールに遭遇したときに記述します。proposedステータスで作成され、批准されるまでは誰も拘束しません。

ank amend <id> — 計画で実際に変更するフィールド（blocked_by、scope、--criteria）を扱います。明示的に追加と削除を行い、置き換えリストを受け取ることはないため、忘れられることで何かが削除されることはありません。有効なクレームによって固定されたdone_criteriaには触れません。クレーム下ではrelease --reasonを使用します。

ank review — 批准キューとコードベースの健全性を確認します。提案され待機中のもの、そして活動が停止しクローズが必要なスコープを表示します。

ank graph — blocked_byの有向非巡回グラフ（DAG）をテキストで、ブロックしているものの下にインデントして表示します。真のルートは何か、フラットなリストではルートに見えていただけのものは何かを明らかにします。

ank check — 機械的な不変条件をチェックします。パース、ラウンドトリップ、参照、固定フィールド、孤立したクレームなどを検証します。終了コード8は問題があることを示し、問題は読み取るためのものであり、黙殺するためのものではありません。

acceptはあなたが実行するコマンドではありません。 これは提案されたADRを拘束力のあるものに変換する操作であり、人間の行為です。デフォルトブランチ上で署名付きで行われ、回避方法はありません。決定事項を提案し、それが待機状態であることを伝えてください。自分の権限の限界を認識することは、適切な計画の一部です。

交渉不可のルール

• 完了基準はクレーム時に固定されます。 自分を解放するためにそれを編集しても何も解放されません。ハッシュはあなたの到達できない場所に保持され、checkがその不一致を報告します。もし完了基準が間違っている場合は、release --reasonで理由を述べてください。

• ADR内のconstraintは拘束力を持ち、単なる助言ではありません。 これから触れようとしているファイルをカバーする制約を読んでください。それがcontextが提供するものです。

• ank/は.git/と同様に不透明です。 それらのファイルを直接読み書きしないでください。ank show <id>がエンティティ全体を、ank findが一覧を、ank contextが範囲を提供します。CLIは予算、凍結状態、誰が何を保持しているかを把握しており、ファイルはそれを保持しません。

• 1つのエージェント、1つの作業ツリー、1つのID。 標準的なケースはエージェントごとに1つの作業ツリー（クローンまたはgit worktree）であり、それぞれが独自のブランチを持ちます。ANK_AGENTはセッションを識別し、フォールバックとして<ユーザー>@<ホスト名>が使用されます。そのため、1つのツリー内の2つのセッションは、参照上は1つのエージェントとして扱われます。つまりクレームを共有し、それを調整する代わりに、本来与えられるべき作業を2つ目が拒否されます。セッションごとに設定してください。複数のエージェントが1つのツリーで動作することは可能ですが、それは設計上の意図ではなく、機能が低下したモードです。

• あなたが読むものは決してスタイル設定されません。 カラー出力は人間が端末にいるときにのみ出力され、パイプ、ファイル、--jsonへの出力には使用されません。そのため、あなたに届くバイトはプレーンです。設定すべきものはなく、優先すべき別の表示面もありません。

終了コードは意味を持ちます。4は利用不可、6は固定フィールドの不一致、8は問題発見、9は環境エラーです。エラーは常に正確な次のコマンドを示します。

これらのフラグ以外はank helpにあり、必要なときに参照できます。

インストール

npx skills add haksolot/ank

このスキルはankの使い方を説明します。バイナリをインストールするわけではありません。リリースにはLinux、macOS、Windows用のバイナリが含まれています。