| name | taskherd |
| description | taskherd CLI（エージェントセッション・PR・チケットをタスク単位で束ねるローカル kanban）の操作。使用タイミング (1) 自分のセッションに紐づくボードのタスクの列を進める・note を残す時、(2) 作業中に新しいタスクが確定して起票する時、(3) ボード上のタスク一覧・状態を確認する時、(4) 依頼に taskherd・タスクボード・kanban の語がある時。境界: セッション内の作業ステップ管理（TaskCreate / TodoWrite）は対象外。pane・tab・agent そのものの操作は herdr、実装タスクのスキル連鎖の管理は task。board / picker の TUI 操作はユーザーの領域で、本スキルは CLI だけを扱う。 |
Taskherd
タスク 1 件に、エージェントセッション・PR・Issue・チケット・note を束ねるローカル kanban。状態は ~/.local/state/taskherd/tasks.json（taskherd config path で確認）にあり、CLI からもボード TUI からも同じデータを見る。
前提
command -v taskherd
見つからなければ、その旨を伝えて止まる。パスを推測して直接バイナリを叩かない。
session link / start / jump は herdr サーバに問い合わせるため、herdr が動いていない環境では失敗する。--current はさらに HERDR_PANE_ID を必要とするので、herdr の pane の中からしか使えない。
--json の契約
非対話で使うときは常に --json を付ける。
| |
|---|
| 成功 | stdout に単一の JSON オブジェクト、stderr は空、exit 0 |
| 失敗 | stderr に {"error": ..., "hint": ...}、stdout は空、exit は非 0 |
--json では一切対話しない。入力が要る状況はエラーで落ちる。rm は --yes、note は --set か --append が必須hint を必ず読む。無効な列 id を渡したときは有効な id の一覧が hint に入る- 例外は
start。途中で止まっても結果を stdout に出して exit が非 0 になる。成否は exit code ではなく stage（started → waited → linked → prompted）と linked / prompt_sent で判定する
列
列は config の [[columns]] 次第。id をハードコードせず、その環境の定義を見る:
sed -n '/^\[\[columns\]\]/,/^$/p' "$(taskherd config path --json | jq -r .config)"
taskherd list の 2 カラム目にも列 id が出るが、タスクが 1 件も無い列は行ごと現れないので一覧の代わりにはならない。無効な列 id を渡したときのエラーの hint には常に全 id が入るので、そちらでも確認できる。
add の既定列は config の先頭列。先頭が受け口用の列だと起票したものが意図しない場所に入るので、起票時は常に --status を明示する。
役割で選ぶ。id はその環境の定義に読み替える:
| 状況 | 列の役割 | 標準的な id |
|---|
| 他人の PR・チケットのレビューを頼まれた | 受け口 | review_req |
| やると決まったが未着手 | 待ち | todo |
| 方針・設計を詰めている | 計画 | planning |
| 実装・調査を実際に進めている | 作業中 | working |
| PR を出してレビュー待ち | レビュー | review |
| approve 済みで反映・リリース待ち | 反映待ち | deploying |
| 完了した | 終端 | done |
| やらないと決めた | 終端 | wontfix |
自分のセッションのタスクを進める
自律的に動かしてよいのは、自分のセッションに紐づくタスクだけ。 他のタスクの列は、ユーザーの指示なしに変えない。
1. 自分に紐づくタスクを引く
sid=$(herdr pane current --current | jq -r '.result.pane.agent_session.value')
taskherd list --all --json | jq --arg s "$sid" \
'[.tasks[] | select(any(.sessions[]?; .session_id == $s)) | {id,title,status}]'
空配列なら、このセッションはまだどのタスクにも紐づいていない。
2. 紐づける
taskherd session link <ID> --current --json
3. 列を進める
taskherd move <ID> <STATUS> --json
確認できた事実に対応する遷移だけ行う。 自分が実行した操作（PR を出した・merge した）と taskherd show <ID> --json の live 状態は根拠になる。根拠なく先の列へ進めない。判断がつかないときは動かさず、ユーザーに聞く。
完了基準: move の応答の task.status が意図した列 id と一致している。
起票する
重複を避ける
起票の前に、紐づける URL で既存タスクを引く。 同一性の判断は URL で行う（タイトルは表記が揺れて照合できない）:
taskherd list --all --json | jq --arg u "$URL" \
'[.tasks[] | select(any(.links[]?; .url == $u)) | {id,title,status}]'
ヒットしたら新規に作らず、そのタスクに link / note を足すか列を動かす。
作る
taskherd add "<TITLE>" --status <COL> --link <URL> --note "<WHY>" --json
- 粒度は「1 タスク = 1 つの完了判定」。PR 1 本・チケット 1 件・調査 1 件が単位。複数 PR にまたがる 1 つの作業は、束ねる 1 タスクにリンクを複数付ける（PR ごとに割らない）
- タイトルは、何が終われば完了かが読み取れる形にする。 チケット由来ならチケット側の表題をそのまま使う（後から照合できるため）
--link は複数回指定できる。PR / Issue / チケットの種別は URL から自動判別する--note にはセッションをまたいで必要になる文脈だけを書く（決めた方針・詰まっている点・再開条件）。作業ログはメモリディレクトリ側（@context/memory-file-formats.md）に書く
完了基準: add の応答で task.status が意図した列 id になっていて、task.links に渡した URL が入っている。
後から足す
taskherd link <ID> <URL> --json
taskherd unlink <ID> <URL> --json
taskherd note <ID> --append "<TEXT>" --json
taskherd edit <ID> --title "<NEW>" --due YYYY-MM-DD --json
セッションを起こす・戻る
ユーザーがタスクから作業を始めたい・戻りたいときに使う。
taskherd start <ID> --json
taskherd jump <ID> --json
start は前回同じタスクで起こした agent が idle で残っていればそれを回収する（応答の reused: true）。意図的に 2 つ目を起こすなら --new。cwd の候補が定まらなければ --cwd が必須で、前回と違う cwd を渡した場合は回収も新規起動もせず案内を返す。
Gotchas
--json を省くと note と rm が対話に入る。 エージェントから叩くときは必ず付けるstart は exit code だけで成否を判断しない（stdout の stage を読む）show の live 状態はキャッシュ（config の cache_ttl_minutes）。最新が要るなら taskherd refresh <ID> --json を先に叩く- タスク id は削除しても再利用されない（
next_id は単調増加）。一度得た id は安定した handle として使える
taskherd board をエージェントから起動しない。 TUI はユーザーが開くもので、非対話の実行では無意味に pane を占有する
既存設定との関係
- pane・tab・agent そのものの操作: /herdr（本スキルは taskherd CLI だけを扱う）
- 実装タスクのスキル連鎖の管理: /task（本スキルはボード上の状態管理だけを扱う）
- 作業ログ・調査記録: @context/memory-file-formats.md（note と使い分ける）
