byteratio/kanban-plans

ローカルかんばんによる計画追跡

かんばんは、Claudeセッションが異なるプロジェクトや異なる日を超えて計画の状態を維持できるように存在します。計画の獲得、ステータス間の移動、メモの残置が可能です。複数のClaudeインスタンスが1つのボードを共有することがあります。プロジェクトスラッグの下に作業を常に分類し、異なるリポジトリからの計画が衝突しないようにしてください。

かんばんが動作しているマシン上のプロジェクトで非自明な計画に取り組む場合、作業中はかんばんと対話する必要があります。

ボード

ソース: https://github.com/hechtch/kanban — Angular SPAとSQLite上のGo APIで構成されています。ローカルで動作し、ホスト型インスタンスはありません。

git clone https://github.com/hechtch/kanban.git
cd kanban
make container-build && make container-run   # CONTAINER_RUNTIME=podman if you use podman

make container-runは-p 8000:8000を公開し、~/.kanban/dataを永続化のためにマウントするため、単一のコンテナがUIとAPIの両方をポート8000で提供します。

モード	人間向けUI	エージェントAPIベース
コンテナ (make container-run)	http://localhost:8000/board	http://localhost:8000/api/agent
開発 (make run)	http://localhost:4200/board	http://localhost:8000/api/agent

エージェントAPIはどちらのモードでもポート8000 — 人間のUIリンクのみが異なります。make runはAngular開発サーバーを別途4200で提供するためです。ユーザーがmake runを実行していることがわからない限り、コンテナの8000 UIリンクを使用してください。

ユーザーがかんばんを別の場所にデプロイしている場合（リバースプロキシの背後、別の公開ポートなど）、そのベースURLを教えてくれます。デフォルトよりもそちらを優先し、/api/agentサフィックスは維持してください。

起動していますか？

KB=http://localhost:8000/api/agent
curl -sS http://localhost:8000/api/health
# {"status":"ok"}

これが失敗した場合、かんばんは実行されていません。自分で起動しないでください — ~/.kanban/data/kanban.dbに書き込みを行い、そのDBを競合させる2番目のプロセスは、追跡しないよりも悪い結果をもたらします。ユーザーにダウンしていることを伝え、上記のmake container-run行を提供し、実際の作業を追跡せずに続行してください。

正準仕様 — エンドポイントの詳細はこちらを参照

APIは型付きGoハンドラから生成された完全なOpenAPI 3.1仕様を同梱しています。パス、リクエスト/レスポンスの形状、ステータスコード、検証ルールの信頼できる情報源です。疑問がある場合は、推測したり古いドキュメントに依存したりせず、代わりにそれを取得してください。

• 仕様 (JSON): http://localhost:8000/api/openapi.json
• 仕様 (YAML): http://localhost:8000/api/openapi.yaml
• Swagger UI (人間向け): http://localhost:8000/api/docs

このファイルの残りの部分は、エージェントワークフロー（スラッグ、規約、レシピ）を提供するため、APIをゼロから学ぶ必要はありません。ここでカバーされていないエンドポイント固有の詳細については、仕様を読んでください。

レスポンスには、レスポンスのJSONスキーマを指す$schema URLフィールドが含まれます（humaの慣例）。スキーマに対してレスポンスを検証する場合を除き、無視してください。

このスキルが想定する計画ファイル規約

ボードは計画を追跡し、計画はリポジトリ内のマークダウンファイルです。

• plans/<topic>.md — 進行中の各計画に対して1ファイル。理由と内容を記述します。実行可能タスクにはチェックボックス（- [ ] / - [x]）を使用し、作業の進行に合わせてその場で洗練させます。
• plans/done/<topic>.md — 作業が出荷または中止されたときにファイルが移動する場所。先頭に短い「Delivered in <バージョン> — <日付>」ヘッダーを付けます。
• CHANGELOG.md — 公開用の「変更内容」。plans/done/が理由を保持します。

リポジトリがまだこのレイアウトを使用していない場合は、plans/を作成し、ボード上で計画を主張する前にファイルをシードしてください。以下のスラッグルールはファイル名に依存します。

スラッグルール

すべてはスラッグでキー付けされ、数値IDでは決してキー付けされません。プロンプトやコードにtask.idを保存しないでください。

• 計画スラッグ = 計画ファイル名から.mdを除き、小文字にしたもの。plans/photo-import.md → photo-import。
• プロジェクトスラッグ = リポジトリまたはイニシアチブ名をケバブケースにしたもの。~/projects/photo-organizer → photo-organizer。（「Photo Organizer」という名前のプロジェクトの場合、サーバーは名前から自動的にphoto-organizerを導出します。明示的なスラッグを渡すこともできます。）
• 形状（サーバー側で強制）: ^[a-z0-9]([a-z0-9-]*[a-z0-9])?$。不正なスラッグは400を返します。小文字、単語間はハイフン、アンダースコアや大文字は使用禁止。

タスク本文が計画そのもの

計画を最初に主張するときは、計画マークダウンをbodyフィールドとして送信してください。その瞬間からかんばんDBが正規の情報源となります。途中でファイルに編集を同期しないでください。ディスク上のplans/<slug>.mdファイルはシード（一度だけ使用）、plans/done/<slug>.mdは作業が出荷されたときに書き込むアーカイブスナップショットです。

後で新しいbodyで再PUTすると、あなたのバージョンが優先されます。人間はUIの/task/<task_id>でタイプミスを修正することもできます。どちらの編集も同じ列に反映されます。

計画を主張することが「Claudeのもの」にする方法

設定可能な担当者フィールドはありません。ボードがそれを導出します。plan_slugを持つタスク — これはまさにPUT /plans/<slug>が作成するものです — は、サイドバーの担当者フィルターでClaudeの下に表示され、カードにClaudeチップが表示されます。人間が手動で作成したタスクにはplan_slugがなく、youの下に残ります。

したがって、このAPIを通じて計画を主張することは、目に見える行為です。人間自身が行っている作業についてメモを残すためだけに計画を主張しないでください。

ステータス

5つのボード列、固定:

todo  →  doing  →  blocked  →  awaiting_merge  →  done

さらにbacklog（ボード外、オプションの6番目）。

• blocked — 作業を進められない。メモで理由を説明してください。
• awaiting_merge — コードは作成されプッシュ済みで、PRのマージまたは手動マージを待機中。作業が出荷されていないためdoneとは異なります。
• ブランチが実際にメインラインにマージされた場合にのみdoneに切り替えてください。自動遷移はしないでください。

'waiting'は有効なステータスではありませｎ。マイグレーションで'blocked'に名前変更されました。

gitブランチ

計画（および任意のタスク）にはgit_branchフィールドを設定できます — 作業が行われているブランチです。フィーチャーブランチを作成したら設定し、人間がカード上で確認できるようにします。

curl -sS -X PUT $KB/plans/photo-import \
  -H 'Content-Type: application/json' \
  -d '{"git_branch":"feat/photo-import"}'

{"git_branch": null}でクリアします。ブランチはカード上で等幅フォントのチップとして表示されます。

推奨モデルと努力量

すべてのタスクにはmodelとeffortを設定できます — 次に作業を引き継ぐエージェントへのヒントです。人間がチケットから設定します（または計画の重みを知っている場合はあなたが設定できます）。これらはカード上でfable / xhighのようなチップとして表示されます。これらを尊重してください：sonnet / highと書かれた計画を再開する場合、それが所有者が費やしたいと考えるティアです。fable / xhighの監査計画は、大きなモデルを高努力で使用することを意味します。

curl -sS -X PUT $KB/plans/security-audit \
  -H 'Content-Type: application/json' \
  -d '{"model":"fable","effort":"xhigh"}'

• modelは自由形式の略記 — fable、opus、sonnet、haikuが標準セットです。サーバーは小文字化してトリムし、40文字を超えるものは拒否します。
• effortはlow、medium、high、xhigh、max（Claude Codeの推論努力ティア）のいずれかでなければなりません。それ以外は422になります。
• 両方ともオプションで独立しています。nullでクリアします。省略は「優先なし — セッションのデフォルトを使用」を意味します。

プロジェクト: アーカイブとデフォルトタグ

プロジェクトは名前/色以外に2つのフィールドを持ち、どちらも同じPUT $KB/projects/<slug> upsertで設定可能です。

• archived — プロジェクトは完了しました。その計画はサイドバーとボードから外れます（人間が展開できる「アーカイブ」セクションに折りたたまれます）が、何も削除されず、すべてのエンドポイントは引き続きそれらを返します。プロジェクトの作業が出荷されたときに設定します。

  curl -sS -X PUT $KB/projects/photo-organizer \
    -H 'Content-Type: application/json' -d '{"archived":true}'
  

• tags — プロジェクト内のすべてのタスクが持つタグです。サーバーは読み取り時にそれらを各タスクのtagsにマージするため、["infra"]とタグ付けされたプロジェクト下の計画は、個別にタグ付けされることなくinfraタグが付いて返されます。タスクタグと同様にセット全体を置き換えます。

  curl -sS -X PUT $KB/projects/photo-organizer \
    -H 'Content-Type: application/json' -d '{"tags":["media","infra"]}'
  

  マージは読み取り時に行われるため、プロジェクトからタグを削除すると、すべてのタスクから一度に削除されます。プロジェクトのタグを個々のタスクに設定しないでください。サーバーは継承されたタグをタスク自身のセットから除去するため、何も起こらない書き込みになります。

セッションごとのワークフロー

KB=http://localhost:8000/api/agent

# 1. プロジェクトが存在することを確認（冪等 — 初回は201、以降は200）。
curl -sS -X PUT $KB/projects/photo-organizer \
  -H 'Content-Type: application/json' \
  -d '{"name":"Photo Organizer","color":"#d4654a"}'

# 2. 計画を主張 + 現在の本文を送信 + プロジェクト下に配置。
#    最初のPUTはstatus=todoで作成。以降のPUTはパッチ。
BODY=$(jq -Rs . < plans/photo-import.md)
curl -sS -X PUT $KB/plans/photo-import \
  -H 'Content-Type: application/json' \
  -d "{\"title\":\"Photo Import\",\"project_slug\":\"photo-organizer\",\"body\":$BODY}"

# 3. フィーチャーブランチを作成し、かんばんに通知。
git checkout -b feat/photo-import
curl -sS -X PUT $KB/plans/photo-import \
  -H 'Content-Type: application/json' \
  -d '{"git_branch":"feat/photo-import"}'

# 4. メモ付きでdoingに切り替え。ステータスPUTは冪等 — 同じステータスをメモなしで行うと何も起こらず、メモ付きで行うとアクティビティエントリが書き込まれます。
curl -sS -X PUT $KB/plans/photo-import/status \
  -H 'Content-Type: application/json' \
  -d '{"status":"doing","note":"starting Phase 2"}'

# 5. 進捗に応じてメモを残す（ステータス変更より軽い）。
curl -sS -X POST $KB/plans/photo-import/notes \
  -H 'Content-Type: application/json' \
  -d '{"text":"phase 2 done; running tests"}'

# 6. PRがオープンしたら、awaiting_mergeに移動。
curl -sS -X PUT $KB/plans/photo-import/status \
  -H 'Content-Type: application/json' \
  -d '{"status":"awaiting_merge","note":"PR #123 open"}'

# 7. マージされたら、doneに切り替えてファイルをアーカイブ。
curl -sS -X PUT $KB/plans/photo-import/status \
  -H 'Content-Type: application/json' \
  -d '{"status":"done","note":"merged in v0.3.0"}'
# その後 `git mv plans/photo-import.md plans/done/photo-import.md`

計画を作成または移動したばかりの場合は、人間のUIリンク — http://localhost:8000/board（または開発モードでは:4200） — に言及してください。

ルールと注意点

• ステータスenumは固定: todo、doing、blocked、awaiting_merge、done、backlog。新しいものを発明しないでください。
• 未知のproject_slugは422 unknown project_slug "X"を返す — 割り当てる前にプロジェクトを作成してください。暗黙の自動生成はありません。
• **project_slug: ""**はプロジェクトをクリアし、project_id: nullと同等です。
• Upsertは本当のupsert — PUT /plans/:slugを{}で呼び出すと、「不在なら主張、存在すればパッチ」の呼び出しになります。再実行しても重複しません。最初の呼び出しのみがcreateアクティビティエントリを書き込みます。
• 同じステータスへのステータスPUTはnoteを渡さない限りno-opです。これを利用して、安全に再試行できます。
• アクティビティログは追記のみで、$KB/plans/<slug>/activityで表示可能です。本文で説明する代わりに、メモを使って足跡を残してください（「Phase 2完了、Phase 3開始」など）。
• 本文はUIの/task/<task_id>でレンダリングされるマークダウンです。標準的なマークダウン（見出し、リスト（- [ ] / - [x]を含む）、コードブロック、リンク）を使用してください。テーブルや引用もレンダリングされます。

使用しなくてよい場合

• 一回限りのバグ修正、リファクタリング、ドキュメントの微調整。かんばんは計画を追跡します — 複数セッションにまたがる、または重要なコンテキストを持つ複数ステップのイニシアチブです。単一コミットの作業にはチケットは必要ありません。
• かんばんリポジトリ自体が作業中のプロジェクトである場合、そのCLAUDE.mdに独自の規約が文書化されています。代わりにそれを読み、このファイルは無視してください。
• ヘルスチェックが失敗した場合、ボードは実行されていません。起動しようとせず、そのまま続行し、ユーザーに伝えてください。