beans

Beans - タスク管理

CLI ベースのフラットファイル型課題トラッカーです。タスクは .beans/ に Markdown ファイルとして保存され、コードと一緒にバージョン管理されます。

リポジトリ： https://github.com/hmans/beans（760 以上のスター）

インストール、beans init、エージェント連携の手順は references/setup.md にあります。

このスキルを使う場面

• CLI からプロジェクトのタスク、バグ、機能を管理する
• コーディングエージェントに作業を追跡させる
• Beans を作成、一覧表示、更新、クローズする
• エピック、タグ、優先度を使って作業を整理する（milestone 型は使わない）
• beans list のフィルターでプロジェクトの状態を照会する

---

ワークフローモデル

ライフサイクルには 3 つのレベルがあり、ステータスは厳密な順序で進みます。Beans を作成する前に、このセクションを読んでください。

ツリー構造

すべての Bean は 3 階層のツリーに属します。以下の名称は慣例であり、Bean の type 値ではありません。type は引き続き task / bug / feature / idea です。

レベル	表すもの	Bean の type	子
エピック	1 つの目標。セッションで目標に達するまで取り組む成果です。	epic（複数エピックのプログラムのルート：親を持たない epic）	N 個のタスク
タスク	目標の達成に必要な要件、課題、または機能です。	task または bug	なし - 葉ノード
サブタスク	範囲が明確で、委任可能な約 10 分の作業です。小さなサブエージェントに任せます。	所属するタスク内の AC チェックボックス（Bean ではありません。CLI はタスクの下にタスクを置くことを拒否します）	なし

階層は parent フィールドで強制されます。また、作成時に CLI が不正な親子の型の組み合わせを明示的なエラーとともに拒否します。検証済みの強制マトリクス（大量インポートの前に、各レベルにつき使い捨ての作成を 1 回行って確認してください。文書化された慣例より CLI のエラーが正しい情報です）：epic の親 ∈ {なし}、feature の親 ∈ {epic}、task の親 ∈ {epic, feature}。task を親にすることは絶対にできません。フラットなタスクに後から本当に Bean の子が必要になった場合は、その場で型を変更してください。beans update <id> -t epic は ID と履歴を保持したまま型を切り替えるため（CLI で検証済み）、子の作成が可能になります。階層に関する主張は、頼る前に検証してください。CLI が拒否する文書上の慣例は、それを基にしたすべての手順に悪影響を及ぼします。milestone 型は使わないでください（チーム内ルール：これは上流 CLI の不要な機能であり、作成しません）。リリースをまとめる必要が本当にある場合は、代わりに Beans にタグ（--tag rel-v1）を付けてください。CLI が追加の階層を許可しない場合は、別の Bean を作るのではなく、所属するタスク内の数えられる受け入れ条件のチェックボックスで、10 分単位の粒度を維持してください。

一括インポートの手順（ID は CLI が生成するため、決して決めつけないでください）：パス 1 ですべての Bean を作成し、返された ID をマップに記録します。パス 2 でマップを参照し、--parent / --blocked-by を設定します。型または親のエラーによってバッチの一部が拒否された場合は、ID マップを読み込み、作成済みの Bean をスキップする冪等な修復スクリプトを再実行してください。

epic (GOAL)
├─ task (requirement)
├─ task
└─ task

サブタスクは Bean ではありません（CLI はタスクの下にタスクを置くことを拒否します）。タスクを分割するには、本文に受け入れ条件のチェックボックスを追加するか、要件に本当に子の Bean が必要な場合は feature のグループを作成してください。

セッションごとに目標は 1 つ

エピックはセッションの目標です。アクティブなエピックは最大 1 つ選び、目標に達するか取り下げるまで取り組んでください。オープンなエピックが 2 つあると、集中が分散して作業が遅くなります。beans list --ready が自然な進捗確認手段です。受け入れ条件にチェックが入り、最後の子が completed になったら、エピックを完了と見なしてください。

ステータスの推移：すべてのビーンはdraftから始まります

デフォルトの初期ステータス：draft。 todoとして直接作成されるビーンはありません。ビーンは、実行可能な状態になる前にトリアージ（詳細な調査）を通過する必要があります。

draft  →  todo  →  in-progress  →  completed
                 ↘  scrapped

• draft - トリアージが必要です。昇格させる前に調査してください。本文には質問、リンク、不明点、トリアージ調査の結果を記載します。
• todo - 実行可能です。トリアージで回答済みです。スコープが明確で、受け入れ条件が記載され、参考資料がそろっています。担当者が決まるのを待つ状態です。
• in-progress - 担当者が決まっています。同時に担当できるのは、エージェントまたは人間のいずれか1人だけです。
• completed - 検証済みです。本文に## Summary of Changesと## Proof of Workがあります。
• scrapped - 対応中止です。本文に## Reasons for Scrappingがあります。

beans list --readyは、todoとin-progressのビーンを返します。draftを担当しようとしていることに気づいたら、トリアージを飛ばしています。戻って対応してください。

トリアージ＝詳細な調査

draftのビーンは仮説です。todoに変更する前に、トリアージを行うエージェントまたは人間は、次のことを行う必要があります。

1. 元の依頼を読み直す - 実際に求められていることは何ですか？

2. 詳細に調査する - 影響を受けるコード、関連ドキュメント、仕様、先行事例を確認します。リポジトリ内の情報だけでは不十分な場合は、オンライン調査（ウェブ検索、Context7、ベンダーのドキュメント）を利用します。本文に出典を記載してください。

3. 作業範囲を定める - タスク／サブタスクに分割します。1つの大きなビーンに要件を詰め込むのは問題の兆候です。エピックと子ビーンに分割してください。

4. 受け入れ条件を記述する - 外部のレビュアーが独立して検証できる- [ ]チェックボックスを記載します。

5. コーディングエージェント向けのスキルを見つける - リーフタスクをコーダーが実装する場合は、プロジェクトとユーザーのスキルルート（.agents/skills/、~/.agents/skills/、およびランタイムが使用するエージェント固有のスキルディレクトリ）を確認し、スキルの説明に基づいて、このスタックとタスクに合うスキルを選びます。次の形式でビーンの本文に記載してください。

   ## Skills for coder
   
   - `~/.agents/skills/<name>/SKILL.md` - why this leaf needs it
   

   言語やプロジェクトのパックをハードコードしないでください。リーフタスクごとに見つけ直してください。このセクションがないコーディングサブタスクは、todoにする準備ができていません。スキルを渡すときは、ディスパッチにそのPATHを記載し、編集前にワーカーがスキルをすべて読むよう指示してください。スキルのルールをタスクのコンテキストに要約して渡すのは、渡したことにはなりません。要約には、要約者が含める必要がないと判断した内容が抜け落ちます。その抜けが、削除済みのルール群が正常なゲートのもとで再び持ち込まれる原因になります。ゲートで検証する必要があるスキルのルールは、明示的で検証可能な項目として契約に転記してください。スタイルルールに違反していても、ビルド／lint／gofmtは正常なままなので、未検証のスタイルルールがあると、不備のあるものがリリースされます。

6. ブロッカーと依存関係を特定する - まだ開始できない子ビーンには--blocked-byを指定します。

7. 昇格させる - 本文が調査に裏付けられ、受け入れ条件があり、コーディングを行う場合はコーダー向けのスキルが記載され、ビーンが担当可能な大きさである場合に限り、beans update <id> -s todoを実行します。

回答できない疑問が明らかになったdraftは、質問を## Reasons for Scrappingに記載して対応を中止します。

トリアージ担当者（必須）

トリアージは、利用可能な中で最適な調査サブエージェントが実施します。その場にいる人や、チケットにざっと目を通したメインセッションが担当するわけではありません。

• トリアージ時点で利用可能な最強のモデルを動的に選びます。エージェントのランタイムが備えるモデル選択の仕組み（モデル一覧、ルーター、プロバイダーカタログ）に問い合わせ、現時点で到達可能な最適な推論モデルを特定して委任してください。モデル名をハードコードしないでください。最適な選択肢は時とともに変わり、到達可能なモデルはセットアップごとに異なります。
• トリアージサブエージェントは、リポジトリに対して読み取り専用で作業します（調査のみで、実装はしません）。調査結果は bean の本文に記載します。
• トリアージ出力の要件 — ドラフト本文には次の内容が必要です。
  1. 根本原因／未解決の質問への回答 — ファイル名と行番号、または引用した URL を示します。「不明」はトリアージ結果として認められません。
  2. ローカル調査 — 影響を受けるコードパス、設定、読み取って要約した契約をパスとともに記載します。
  3. オンライン調査 — リポジトリ内の証拠だけでは不十分な場合に参照した上流ドキュメント、課題、仕様を記載し、リンクを記録します。
  4. スコープ — タスク／サブタスクを分割し、末端の項目は約10分単位とします。ブロッカーは --blocked-by で関連付けます。
  5. 受け入れ条件 — 独立して検証できる - [ ] チェックボックスを記載します。
  6. コーダー向けスキル — 末端の項目がコーディングエージェント向けの場合、発見したスキルのパスを含む ## Skills for coder を記載します（トリアージ手順5を参照）。コードを変更しない純粋なドキュメント／運用の末端項目に限り省略できます。

これらを本文に記載した後に限り、トリアージ担当者は beans update <id> -s todo を実行できます。根本原因または受け入れ条件が本文にない todo bean は、トリアージの失敗です。draft に戻してください。 ## Skills for coder のないコーディング項目も、トリアージの失敗です。

バグを見つけた場合（必須）

バグを見つけた場合は、正しい beans のプロセスに従う必要があります。まず記録し、トリアージを実施してください。

先にパッチを適用しないでください。todo や in-progress に進めないでください。テストで検出されたからといって「そのまま修正」しないでください。

1. コーディングを停止します。 証拠（httpyac のログ、ワーカーログ、失敗したテストの出力）を保管します。
2. 記録します — beans create "<short title>" -t bug -s draft。本文には、何が失敗したか、期待値と実際の値、ID、時刻、スタック、証拠のパスを記載します。
3. トリアージします — 詳細な調査（コード、契約、ドキュメント）を行います。受け入れ条件を記載します。必要であれば分割します。その後、beans update <id> -s todo を実行します。
4. 担当を引き受けます — トリアージ後に限り、beans update <id> -s in-progress を実行します。その後、実装します。

実際に不一致が起きていても、トリアージで実在し、範囲が定まり、対応可能なバグだと確認されるまでは draft のままです。環境の誤り、データが空であること、未サポートの型は、何も言わずにコードを変更する理由にはなりません。

手順: references/patterns.md。

---

詳細は 再オープンのパターン（ユーザーの発見が完了済みの bean と矛盾する場合） を参照してください。

詳細は コード修正タスクの bean 作成（ALL-CODE-DELEGATED） を参照してください。

CLI コマンド

すべてのサブコマンドとフラグは references/cli.md に記載されています。このセクションは、エージェントがセッションの95％で使う4つのコマンドをすぐに確認できるようにまとめたものです。

コマンド	使用する場面
beans prime	セッション開始時 — プロジェクトの現在の bean 状態を読み込みます。
beans list --json	一覧表示／フィルタリング。トリアージ後の作業には --ready、トリアージ待ちの一覧には -s draft、トップレベル（エピック）の一覧には --no-parent を指定します。
beans create	新しい bean を作成します。既定値は -s draft です。トリアージ後、update -s todo で進めます。
beans update	担当を引き受け、進捗を更新し、PoW を追記し、クローズします。対象を絞って編集するには --body-replace-old/new、## Summary of Changes と ## Proof of Work を追記するには --body-append を使います。
beans show	詳細を確認します。パイプ処理には --body-only、安全な同時更新には --etag-only を使います。

ディスク上のファイル形式（YAML フロントマター、ファイル名の規則、フィールドのスキーマ）については、references/bean-file-format.md を参照してください。 このファイルは CLI が管理します。.beans/*.md を手動で編集しないでください。

書き戻しコメント（監査判定、レビューコメント）

beans comment サブコマンドはありません。CLI で Bean に日付入りのメモを追加します：

beans update <id> --body-append "## AUDIT (brainer, scope): verdict + evidence"

コンテキストの準備

beans prime

プロジェクトの現在の Bean、優先事項、推奨される次のアクションに関するコンテキストを出力します。エージェントはセッション開始時にこれを実行してください。

委任のパターン

Bean の作業をサブエージェントに割り当てる場合（特に小規模なモデルや無料モデルの場合）：

• プロンプトは短くします。 目標を1つに絞り、正確なコマンドとファイルパスを指定します。プロンプト内に設計を記述すると、忠実度が低下します。
• 設計上の判断は Bean の本文に記載します。 --body-replace-old/new を使い、タスクの全設計を Bean 内に記載します。Bean を唯一の信頼できる情報源とします。設計を複数の一時ファイルに分散させないでください。
• 1回停止したら、戦術を変えます。 ハングやテキストのみの返答は兆候です。同じプロンプトで再試行しないでください。タスクの規模、エージェント、ツールセットを切り替えます。2回失敗したら、その手順の委任を中止します。
• 診断ではラッパーを回避します。 正確なエラーや Lint の位置を確認するには、生のコマンドを使用します。

エージェントタスクのライフサイクル

1. beans prime                          → Get project context
2. beans list --json -s draft           → Find beans awaiting triage
3. Research the draft, scope it, write  → Triage the bean
   acceptance criteria, then promote
   with `beans update <id> -s todo`
4. beans list --json --ready            → Find actionable work
5. beans update <id> -s in-progress     → Claim the task
6. ... implement the change ...
7. beans update <id> --body-replace-*   → Check off acceptance criteria
8. VERIFY: run the project's tests/build/lint and observe results   ← gate
9. beans update <id> --body-append      → Add ## Proof of Work (commands + results + residual)
10. beans update <id> -s completed      → Mark done (only after verify + proof are present)

手順7～10の責任を負うのはオーケストレーターであり、作業者ではありません。作業者の報告は主張にすぎません。自分でゲートを再実行し、差分を読み、Bean の本文に PoW を記録してください。チャット内だけに記録された完了は、トラッカー上の完了ではありません。トラッカーに記録されていない内容は次のセッションで検証できません。全ファイルを対象とするタスクでは、PoW に現行のファイル数、判定数、および2つの集合が一致することを証明するコマンドを記載します。件数の一致とゲートの合格が証明するのは網羅性であり、内容ではありません。全件の確認を完了する前に、修正したすべてのファイルの差分を読み直し、問題のないファイルもいくつか抜き取りで確認してください。作業者が判定を付ける際にスタイル規則に違反する場合があり、スタイルは自動チェックされないため、ゲートは合格のままです。判定数だけを根拠にクローズすると、再びオープンになります。

リポジトリには、CLI よりも多くの項目をチェックする独自の Bean Lint を追加できます。そのような Lint がある場合は、Bean を変更するたびに実行してください。

スキルのパスを Bean の本文に記載する前に、そのパスがディスク上に存在することを確認してください。

子 Bean が必要な task として誤って型指定された Bean は、beans update <id> -t epic を使ってその場で変換できます。ID、本文、履歴は維持されます。破棄して作り直すと監査証跡が失われるため、破棄は目標が本当に不要になった場合に限ってください。

修正パスがすでに完了した後にトリアージ判定が届いた場合は、その判定を同じ Bean の本文に追記し、その Bean の下で追加パスとして差分に対応します。同じ対象範囲で2つ目の Bean を作成せず、最初のパスが合格したからといって、より厳しい判定を無視しないでください。

エピックでは、手順8～9を次の内容に置き換えます。エピック全体を対象とするエンドツーエンドテストと、ユーザーが目標を達成する場合と同じ手順を実行する ## Proof of Work セクションです。以下の**クローズゲート（必須）**を参照してください。

トリアージから着手可能になるまで（必須）

• draft は beans list --ready に表示されません。着手できません。
• 作業するには、まずトリアージを実施します（調査、対象範囲、受け入れ条件、子 Bean の --blocked-by）。その後、beans update <id> -s todo を実行します。この操作をして初めて、着手可能になります。
• トリアージを省略して Bean を直接 todo に変更するのは、プロセス違反です。これはテストせずに completed にするのと同じ分類の違反です。

クローズゲート（必須）

ルールは2つあります。どちらも、すべての beans update -s completed の実行に適用されます。どちらかのルールを満たさない Bean は、in-progress（またはトリアージが完了していない場合は draft／todo）のままにします。作業を完了できない場合に正当な終了方法となるのは、scrapped だけです。

1. タスク／サブタスクのクローズ

本文に ## Proof of Work セクションがなければ、タスクまたはサブタスクをクローズできません。 このセクションは、## Summary of Changes（変更内容を記録するセクション）とは別に、検証ゲートを実行した証拠となるものです。最低限、次の内容を含める必要があります。

• 実行したコマンドの正確な内容（ビルド、テスト、lint、スモークチェックなど、該当するもの）。
• 各コマンドで確認した結果（終了ステータス、主要な指標：件数、合否、出力のフィンガープリント）。
• 残作業を記載した Residual: 行。残作業がなければ none と記載します。

## Proof of Work がない場合、クローズは却下されます。まずセクションを追加してから、完了にしてください。

beans update myproj-a3x1 --body-append "## Proof of Work

\
make vet   → 0\n\
make test  → PASS (unit + integration + e2e, 148s)\n\
make lint  → 0 issues (452 → 0)

Residual: none."

beans update myproj-a3x1 -s completed

証拠を生成する検証ゲート自体も必須です。「動くと思います」では完了になりません。プロジェクトのテスト／ビルド／lintを実行し、結果を確認してください。ゲートが失敗した場合は根本原因を修正してください。検証できない場合は、beanを in-progress のままにして、その旨を明記してください。

2. エピックのクローズ

配下のタスクまたはサブタスクに未完了のものがある場合、エピックをクローズできません。また、エンドツーエンドテスト全体と ## Proof of Work がなければクローズできません。 2段階のゲートがあります。

• 未完了の子タスクがないこと。 エピック自体を completed にする前に、配下のすべてのタスクとサブタスクを completed または scrapped にする必要があります。次のコマンドで確認してください。

  # Find any non-terminal child of the epic
  beans list --json --parent myproj-epic --no-status completed --no-status scrapped
  # Empty output → safe to close the epic.
  

• エンドツーエンドテスト全体と ## Proof of Work。 エピックの証明は統合レベルのものです。「ユニットテストに合格した」だけではなく、目標全体がエンドツーエンドで達成された証拠が必要です。次の内容を網羅するコマンドを含む ## Proof of Work セクションを追加してください。

  • テストスイート全体（該当する場合は、ユニットテスト＋統合テスト＋e2eテスト）。
  • ユーザーが目標を利用する場合と同様に実行するエンドツーエンド／スモークチェック（ブラウザー、CLIの実行、APIの往復処理など）。
  • ビルド／デプロイのエピックでは、稼働中の成果物と、アクセス可能なURLまたはバージョン。

エンドツーエンドでXを実際に試さずに「機能Xをリリースする」としても、目標が達成された証明にはなりません。ゲートを実行できない場合（このプロジェクトにe2eテスト用のハーネスがないなど）は、その理由を Residual: の下に ## Proof of Work へ明記してください。何も記載せずに省略することは違反です。

子タスクが未完了のままエピックをクローズすること、またはエンドツーエンドテスト全体とProof of Workなしでクローズすることは、プロセス違反です。## Proof of Work なしでタスクをクローズする場合と同じ種類の違反です。

---

Proof of Workがなければ、completed にできない

これはすべてのbeanタイプに適用されます。上記の2つのサブセクションでは、タスク／サブタスクとエピックそれぞれで何が証明に当たるかを定義しています。これが、どのbeanにも適用される基本ルールです。

コミットメッセージの規約

コミットメッセージにはbean IDを含めてください。

feat(auth): add OAuth PKCE support

Refs: myproj-a3x1

---

アンチパターン

プロセスと CLI の運用上の注意事項です。上記の**完了ゲート（必須）**に記載されている完了ルールではありません。

やってはいけないこと	実施すること
セッション開始時に beans prime を省略する	必ず最初に beans prime を実行する
スクリプトで --json を付けずに beans list を使う	機械可読な出力には必ず --json を使う
CLI を使わずに .beans/ ファイルを直接編集する	一貫性を保つため、CLI コマンドを使う
並行更新時に etag を無視する	安全に並行編集するため、--if-match を使う
小さな変更に --body-file を使う	対象を絞って編集するには --body-replace-old/new を使う
作業開始時にステータスを更新し忘れる	タスクを引き受けるときは -s in-progress を設定する
完了後も beans を in-progress のままにする	必ず -s completed または -s scrapped でクローズする
1 つのセッションでアクティブなエピックを 2 つ開く	セッションごとに GOAL を 1 つ選び、達成するまで取り組む
バグを見つけてすぐに修正する	beans create -t bug -s draft を実行し、証拠を記録してトリアージしてから引き受ける
作業をクローズして状態の成果物を残したままにする	セッションを終了する前に、PR のタイトルと本文が HEAD と一致していること、触れたすべての bean が終端状態（completed／scrapped）であること、エピックのタイトルが空でないこと、孤立した draft がないことを確認する
CLI を使わずに bean のステータスを設定する、またはリリース済みのエピックを todo のままにする	セッション終了時に確認する：beans list を実行し、リリース済みの作業が対象とするすべての bean をクローズまたは破棄する。エピックのステータスは計画ではなく、作業の状態を反映する
ワーカーの申告を確認する前に --body-append で PoW を追記する	親が最初にゲートを再実行して差分を確認する。PoW に記録するのはワーカーの報告ではなく、自分のゲート実行結果
.beans/*.md を直接編集してコメントを追加する	beans update --body-append "## LABEL (context): ..." を使う。コメント用サブコマンドはありません。ファイルの管理は CLI が行います
-d だけを指定して作成し、後からタイトルを修正する	作成時にタイトルを位置引数で指定する。ファイル名のスラッグは固定され、後から --title で編集しても名前は変わりません

---

参考資料

• リポジトリ： https://github.com/hmans/beans
• リリース： https://github.com/hmans/beans/releases
• ドキュメント（Context7）： https://context7.com/hmans/beans/llms.txt

---

覚えておいてください： 必ず最初に beans prime を実行します。スクリプトでは --json を使います。beans をクローズします。