task-forest

Task Forest

目的

現在のワークスペースのタスク構造、提案、履歴、進捗を管理します。別のタスクリストや内部ファイルを開かなくても、初めて読む人が理解できる、単独で完結した HTML 成果物を 1 つ作成します。

タスクの内容、提案、レポート、HTML にはユーザーの言語を使用します。不明な場合は中国語を既定とします。

ポータビリティ

このスキルは特定のエージェントに依存しません。task-forest ディレクトリ全体を、ホストでサポートされている任意のスキル配置場所にインストールし、スクリプト、参照、アセットの場所は、この SKILL.md があるディレクトリを基準に解決してください。特定のエージェント名、スキルルート、ホームディレクトリの構成、シェル、パス区切り文字、オペレーティングシステムを前提にしないでください。

ホストで利用できる Python 3 の起動方法（python3、python、py -3）を使用してください。スクリプトは Python 標準ライブラリを使用し、macOS、Linux、Windows に対応しています。呼び出し元のエージェントをタスク履歴に記録するには、COMPASS_AGENT_NAME または AGENT_NAME を設定するか、--actor を渡してください。それ以外の場合は、中立的な値 agent が使用されます。

基本ルール

1. タスクフォレストのデータの読み書きには scripts/task_forest.py のみを使用してください。.agent-workbench/task-forest/ の正規ファイルを手作業で編集してはいけません。
2. 各ノードには主な親を 1 つ child_of で指定し、副次的な所有関係には contributes_to、前提条件には depends_on を使用してください。
3. グラフの変更は提案として保存し、ユーザーの確認を得てから proposal-apply --yes を実行してください。
4. 確信度の低い推測は質問または提案として扱ってください。実行時に生じた重要な逸脱は逸脱として記録してください。
5. 目に見えるタスクのタイトルと目的は、平易な言葉で記述してください。内部コード（P04 など）を知らなくても、別のファイルを読まなくても、タスクで何がもたらされるのか、なぜ存在するのか、何が完了しているのかを読者が理解できる必要があります。
6. HTML の表示先は exports/task-forest.html 1 つにしてください。履歴の再生機能を備え、done、in_progress のタスクと、それらに必要な child_of の祖先を表示します。HTML に内部の議論、証拠、キュー、ファイルシステムのパス、セッション、提案の内容を公開してはいけません。
7. HTML の操作は読み取り専用にしてください。正式な変更は必ず提案ワークフローを通じて反映します。
8. タスクデータと検出メタデータは、既定ではリポジトリ内に保持してください。ワークスペース横断の検出は任意です。ユーザーが TASK_FOREST_ENABLE_GLOBAL_REGISTRY=1 を明示的に設定してオプトインした場合にのみ有効にしてください。この設定により、軽量なワークスペースのパスと健全性の概要が AGENT_WORKBENCH_DB に書き込まれます。この変数が未設定の場合は ~/.agent-workbench/agent-workbench.sqlite3 に書き込まれます。タスクの内容は保存されません。

主なワークフロー

初期化、更新、またはセッション終了の際は、次の手順を実行してください。

1. init を実行します。
2. list --json と todo --json を読み取ります。
3. セッションが達成する全体目標と、表示状態を維持する必要があるタスク構造を特定します。
4. ワークスペースに正式なタスクリストがある場合、すべての done または in_progress タスクについて、意味のある goal -> phase -> module -> concrete task の階層と兄弟間の順序を維持します。必要な祖先を含め、未着手の分岐はすべて省き、追加の修正は改善対象となる機能の下に配置します。複数のフェーズを 1 つのノードにまとめたり、エッジの作成順に依存したりしてはいけません。兄弟ノードのいずれかに display_order を設定する場合は、その兄弟グループ全体に一意の数値を設定してください。一部のみ、重複、または無効な値がある場合は、検証に失敗する必要があります。
5. 表示されるすべてのノードを、それぞれ単独で理解できるようにします。明確なタイトルに加えて、summary または purpose を指定してください。成果や受け入れ基準を記載すると、成果物が明確になる場合は追加します。内部コードは補助的なラベルとして扱い、タスク名には使用しないでください。
6. 提案を表示して保存します。確認を得る前に適用してはいけません。
7. 確認を得た後、proposal-apply --yes、validate、export を実行します。
8. 提案のパスと、単一の HTML のパスを返します。

ユーザーの意図または対象となる全体目標が本当に不明確な場合は、$task-clarifier を使用してください。

コマンド

このファイルを基準に <skill-dir> を解決し、利用可能な Python 3 実行ファイルを使用してください。例では python3 を使っています。必要に応じて、ホストで利用可能なランチャーに置き換えてください。

python3 <skill-dir>/scripts/task_forest.py init
python3 <skill-dir>/scripts/task_forest.py list --json
python3 <skill-dir>/scripts/task_forest.py todo --json
python3 <skill-dir>/scripts/task_forest.py proposal-save --proposal-file /path/to/proposal.json
python3 <skill-dir>/scripts/task_forest.py proposal-apply <proposal-id> --yes
python3 <skill-dir>/scripts/task_forest.py validate
python3 <skill-dir>/scripts/task_forest.py export

デフォルトのワークスペースは現在のディレクトリです。別のワークスペースが明示されている場合にのみ、--workspace を使用してください。呼び出し元がデフォルト以外のタスクフォレストのルートを明示的に選択した場合にのみ、--root を使用してください。

グローバルレジストリとの統合はデフォルトで無効です。ホストが有効化フラグをグローバルに設定している場合も、TASK_FOREST_DISABLE_GLOBAL_REGISTRY=1 は明示的なオーバーライドとして機能します。

出力

ユーザー向けの成果物は次のとおりです。

proposals/<proposal_id>.json
exports/task-forest.html

エクスポーターは、gap-router と local-agent-control-room 用の内部互換ファイルも 3 つ維持します。

exports/task-forest.graph.json
exports/task-forest.todos.json
exports/task-forest.timeline.json

ユーザーが機械可読データを明示的に求めていない限り、これらの JSON ファイルを納品物として提示しないでください。

参照資料と検証

• ノードのフィールド、提案アクション、標準的な不変条件については、references/schema.md を読んでください。
• グローバル目標への適合性や、競合する候補プランを判断する場合にのみ、references/goal-alignment.md を読んでください。
• ノードの分類が不明確な場合にのみ、references/node-types.md を読んでください。
• 古くなった提案や同時書き込みを解決する前に、references/concurrency.md を読んでください。
• HTML を変更または検証する場合は、references/html-visualization-contract.md を読んでください。
• JSON またはレジストリとの互換性を変更する場合にのみ、references/integration-contract.md を読んでください。

HTML またはエクスポーターを変更した場合は、次を実行してください。

python3 <skill-dir>/scripts/validate_task_forest_export.py --skill-dir <skill-dir>

HTML は引き続き派生した読み取り専用ビューです。正規のタスクデータと提案履歴はリポジトリ内に保持されます。