SeemSeam/plan-tree

Plan Tree（計画ツリー）

このスキルは、持続可能なプロジェクトの方向性、実行準備、進捗状態、およびMarkdown計画ツリーのための計画ワークフロー権限として使用します。ユーザーの意図、既存のドキュメントスタイル、推論の軌跡、そしてセッションやエージェントを越えた計画から実装までの証拠を保持します。

必須の運用モード

すべてのplan-treeタスクにおいて、編集や実装を行う前に作業モードを決定します。

• モードが不明な場合は、execute-ready（実行準備完了）ではなく、clarify（明確化）またはready-check（準備確認）をデフォルトにします。
• 既存のplan-tree状態が利用可能な場合は、方向性を変更する前に関連するエントリポイントと現在の計画状態を検査します。
• ソリューションが実装に十分成熟するまでは、計画および明確化モードを維持します。ユーザーの意図を目標、非目標、制約、オプション、トレードオフ、リスク、依存関係、受け入れ基準、検証パス、ロールアウト/ロールバックノートに拡張します。
• スコープ、アプローチ、影響を受ける表面、期待される動作、受け入れ基準、検証パス、またはリスクについての中核的なあいまいさが残っている間は、メインプロジェクト表面での正式な実装を開始しないでください。
• 小さな分離されたプロトタイプまたはサンプルは、方向性を検証し、プロダクションパスから明確に分離されている場合にのみ許可されます。
• 計画は、中核的な決定について「コーディング中に解決する」ことに依存すべきではない場合にのみ、実装準備完了となります。
• 実装が完了したら、plan-treeのステータス、実装証拠、決定、未解決質問、引き継ぎノートを更新し、実装が永続的な計画状態に反映されるようにします。

作業モード

タスクの開始時に1つのプライマリモードを選択し、状態が変更された場合にのみ移行します。

• clarify（明確化）: 意図、スコープ、制約、成功基準、またはトレードオフが不明確。議論し、必要に応じて焦点を絞った質問を行い、有用な場合にplan-treeファイルに永続的な明確化結果を記録します。メインプロジェクトの実装ファイルは編集しません。
• shape-plan（計画策定）: 方向性はほぼ既知だが、具体的なソリューションマップが必要。ロードマップアイテム、トピック、前提、決定、リスク、受け入れ基準、未解決質問を作成または更新します。
• ready-check（準備確認）: ユーザーが実装または進行を希望しているが、準備状態が不確か。スコープ、アプローチ、影響を受ける表面、受け入れ基準、検証、リスクが十分に明確化されているかを評価します。不十分な場合は、clarifyまたはshape-planに戻ります。
• resume（再開）: 以前の作業から継続。ルートエントリポイント、関連するベースライン、ターゲット計画README、実装ステータス、ロードマップ、および現在アクティブなリンクファイルのみを読み取ります。編集前に、現在のフェーズ、アクティブなTODO、ブロッカー、次のターゲット、最後の検証を要約します。
• execute-ready（実行準備完了）: 計画は実装に十分準備ができている。合意されたスコープ内でのみプロジェクトファイルを変更し、その後plan-treeの状態と証拠を更新します。
• status-update（ステータス更新）: 作業またはレビュー後に、ロードマップ状態、実装ステータス、Last Landed、Next Target、ブロッカー、引き継ぎ、または計画レジストリを更新します。
• archive（アーカイブ）: 廃止された詳細、古いステータススナップショット、受け入れられた証拠、または参照専用資料を、検索リンクを保持したままアクティブファイルから移動します。
• normalize（正規化）: 既存の計画ツリーまたはサイズが大きくなりすぎたマルチロールソースファイルを、より小さな検索単位に再編成します。最初にindexes/migration-map.mdまたは最も近い有用なインデックスを作成または更新し、ソースマテリアルを検索ロールで分類し、短いカプセルとリーダータスク詳細シャードを作成し、受け入れられた検証をevidence/に移動し、古いステータスや推論ナラティブをhistory/に移動します。明示的に承認されない限り、ソースマテリアルは削除しません。
• audit（監査）またはmigrate（移行）: 一貫性、検索可能性、ドリフト、レガシールート、または移行マッピングを検査します。ユーザーが修復、正規化、または移行を要求しない限り、読み取り専用をデフォルトとします。

idea（アイデア）、promote（昇格）、question（質問）、decision（決定）などのドキュメントアクションは、これらのモード内で発生します。

• idea: 低コミットメントの考えをideas/inbox.mdまたは同等のローカルファイルに追加します。
• promote: アイデアをロードマップアイテム、トピック、未解決質問、または決定に昇格させ、元のアイデアにリンクします。
• question: 未解決の質問を追加、絞り込み、または解決します。
• decision: 安定した決定レコードを作成または更新します。

コアワークフロー

すべてのplan-treeタスクについて:

1. 作業モードと許可された書き込み対象（なし、plan-treeのみ、分離プロトタイプ、またはプロジェクトファイル＋plan-tree更新）を選択します。
2. plan-treeルート、ターゲット計画ルート、およびユーザーの意図を特定します。
3. ルートインデックスと、関連するロードマップ、ステータス、トピック、決定、質問、アイデア、履歴、またはベースラインファイルのみを読み取ります。
4. タスクが明示的に再編成することである場合を除き、既存のエントリポイント、登録されたルート、フォルダ名、ドキュメントスタイル、および権限順序を保持します。
5. アクティブなロードマップ、引き継ぎ、およびトピックカプセルファイルを小さく保ち、詳細、証拠、および履歴をアクティブ状態から移動します。
6. 永続ファイルを追加、移動、昇格、アーカイブ、または分割する際に、インデックス、検索ヘッダー、およびリンクを更新します。
7. 返信前に最終チェックを実行します。
8. 変更されたファイル、未解決の質問、アクティブモード、および関連する場合に次に有用なメンテナンスアクションを報告します。

デフォルトのファイルシステム

docs/plantree/ を、plan-treeで管理されるマテリアルのデフォルトのクロスプロジェクトファイルシステムとして使用します。これはplan-treeシステムルートおよびレジストリであり、単一の計画ルートではありません。この名前は、プロバイダー固有またはフレームワーク固有の plans/ フォルダとの衝突を避けます。

デフォルトの構造:

• docs/plantree/README.md: レジストリ、権限順序、ベースラインリンク、アクティブ計画テーブル、およびツリーの読み方。
• docs/plantree/baseline/: モジュールマップ、ランタイムフロー、状態/ストレージ境界、テスト/リリースゲート、リスクホットスポットなどのプロジェクト全体のコンテキスト。
• docs/plantree/plans/<NNN>-<plan-name>/: 安定した数値順序、ロードマップ/ステータス、トピック、決定、未解決質問、証拠、インデックス、および（プロジェクトに確立された命名規則がない場合の）オプションの履歴を持つ特定の計画ルート。
• docs/plantree/ideas/inbox.md: 低コミットメントのアイデア受信箱。

検出順序:

1. 明示的なユーザーパスが指定された場合はそれを使用します。
2. それ以外の場合、docs/plantree/README.md が存在する場合は docs/plantree/ を使用します。
3. それ以外の場合、現在のタスク用に明確にアクティブな確立されたツリーを保持し、ユーザーが採用、正規化、または移行を要求した場合にのみ移行を評価します。
4. それ以外の場合、計画を作成または更新する前に docs/plantree/ をブートストラップします。

新しい特定の計画は、ローカルな規則がない場合、デフォルトで docs/plantree/plans/<NNN>-<plan-name>/ になり、docs/plantree/README.md に登録する必要があり、グローバルコンテキストをコピーする代わりに関連するベースラインファイルにリンクする必要があります。ユーザーが明示的に移行を承認しない限り、確立された番号なしまたは異なる方法で編成されたツリーを保持します。

初回使用

docs/plantree/ がないプロジェクトでplan-treeタスクが呼び出された場合、ユーザーが明示的にファイル作成を拒否しない限り、最小限のルートを作成します。

ブートストラップ:

• ルート: docs/plantree/README.md
• ベースライン: baseline/README.md、module-map.md、runtime-flows.md、storage-and-state.md、test-and-release-gates.md、risk-hotspots.md
• コンテナ: plans/、ideas/inbox.md

ブートストラップコンテンツは軽量で証拠に基づいたものにします。十分なコードが検査されていない場合は、プロジェクトの事実を発明する代わりに「Unknown / needs inventory（不明 / インベントリが必要）」と記述します。古いまたは馴染みのないプロジェクトの場合は、詳細な計画を作成する前にベースラインを作成またはリフレッシュします。

計画モデル

計画ルートを作成または維持する際に、以下の役割を使用し、名前をローカル規則に適合させます。

• README.md: plan-treeルートである場合のスコープ、権限、ファイルマップ、読み取りパス、アクティブレジストリ。アクティブな計画テーブルについては、軽量IDが使用されている場合、ID | Plan | Affected Modules | Status | Current Phase | Last Landed | Next Target を優先します。
• roadmap.md: ツリーがすでに別のモデルを使用していない限り、Done（完了）、In Progress（進行中）、Next（次）、Deferred（延期）でグループ化された永続的な状態。
• implementation-status.md: In Progress 計画のみの短い運用引き継ぎ。計画中または延期された計画は通常このファイルを必要としません。
• open-questions.md: 未解決の質問のみ。
• topics/: 永続的なコンテキスト、ソリューションマップ、オプション、制約、受け入れ基準、実装ノート、リポジトリ衛生計画、リスク分析。トップレベルのトピックファイルは短いカプセルとして保ち、大きなトピックは詳細シャードを持つトピックフォルダに分割します。
• decisions/: 安定した決定。セットが大きくなった場合はインデックスを作成します。
• evidence/: 現在または受け入れられた検証レコード、レビュー結果、アーティファクトノート、およびこれらを履歴から独立して取得する必要がある場合の証拠インデックス。
• history/: 受け入れられたチェックポイントログ、古いレビュー、廃止されたスナップショット、アーカイブ専用のソースノート、廃止された詳細。
• indexes/: フェーズマップ、トピックマップ、権限マップ、移行マップ、証拠マップなど、ローカルインデックスがナビゲーション問題を解決する場合のオプションの検索マップ。
• ideas/: ルートレベルのアイデアが十分に具体的でない場合のオプションの低コミットメントアイデアプール。

テンプレートの作成、大規模なツリーの処理、決定/ステータス/引き継ぎ/履歴/インデックスファイルの維持、リポジトリ衛生計画の追加、または詳細な最終チェックリストが必要な場合は、references/maintenance-patterns.md を参照してください。

軽量IDとモジュール分類

プロジェクトに確立された計画命名規則がない場合は、軽量IDを使用して、タスクデータベースを作成せずにファイルシステムスキャンと永続的な参照を改善します。

• プロジェクト全体で計画IDを P001、P002 などとして割り当てます。P001 を docs/plantree/plans/001-authentication/ のようなフラットルートにマッピングします。
• 固定幅3桁の10進数を使用します。保持されている最大計画番号に1を加えた値を割り当て、IDを再利用せず、番号の再割り当てによってギャップを埋めず、優先度、ステータス、モジュール、所有者、ワーカー、フェーズ、日付をエンコードしません。
• セマンティックスラッグは安定した小文字のケバブケースに保ちます。タイトルまたは影響を受けるモジュールは、計画IDまたはディレクトリを変更せずに変更される可能性があります。
• 計画レジストリが小さい間は、IDとライフサイクル登録を docs/plantree/README.md に保持します。検索が改善される場合にのみ、インデックスに分割し、デフォルトで並行する割り当て台帳を維持しないでください。
• ロードマップタスクID（T001 など）はオプションであり、計画ローカルです。安定したクロスファイル参照が役立つ場合にのみ使用します。存在する場合、roadmap.md がタスクID、ステータス、順序の唯一のアクティブ権限であり、デフォルトで別のタスクレジストリやタスクフォルダを作成しないでください。
• 決定ファイル名は 001-<decision>.md 規則を保持する場合があります。未解決質問は、永続的な参照が役立つ場合に Q001 を使用する場合があります。アイデアは昇格されるまで番号なしのままです。
• コードまたはプロダクトモジュールは、baseline/module-map.md で定義された安定したキーを使用して、Affected Modules などの計画メタデータとして扱います。デフォルトで計画ルートをフラットに保ち、実証されたナビゲーションの必要性と記録された決定の後にのみ、モジュールインデックスまたは物理モジュールディレクトリを追加します。
• 同一変更の一貫性を適用します。1回のメンテナンス変更で、権限ファイルと必要なエントリポイントサマリーを更新し、終了前にID、パス、モジュールキー、ロードマップの一意性、ステータス要求、相対リンクを確認します。
• 自動修復よりも読み取り専用のドリフト検出を優先します。観察された調整障害がそのコストを正当化するまで、ウォッチャー、自動再番号付け、割り当てロック、またはリカバリジャーナルを追加しないでください。

これらのデフォルトは段階的です。成熟したツリーのローカルID、課題、チケット、またはフォルダ規則を、その上に競合する名前空間を重ねる代わりに保持します。

動的ステータスと証拠

• In Progress 計画のみが implementation-status.md を必要とします。Planning 計画は、roadmap.md、トピック、未解決質問、または決定で準備状態を表現する必要があります。
• implementation-status.md は運用可能で短く保ちます。100行未満を優先し、成長した場合は古い詳細をアーカイブまたはインデックス化します。
• Active TODO は最大5つの現在のアイテムに保ちます。それ以上のアイテムは通常、作業にロードマップフェーズ、トピック、または分割が必要であることを意味します。
• ロードマップタスクIDが使用されている場合、タスクIDを Active TODO で再利用し、2番目のレジストリでタスクIDを再記述しないでください。
• 該当する場合は、具体的な Current Phase、Next Target、Last Landed、Active TODO、Blocked By、Last Verified または引き継ぎノートを含めます。
• Last Landed は、可能な場合、日付付きのコミット、アーティファクト、テスト結果、受け入れられたチェックポイント、またはその他の証拠を指す必要があります。
• フェーズ/パッケージ/ゲートレベルの証拠には、evidence/README.md、indexes/evidence-map.md、またはローカル相当物を使用します。廃止された証拠アーカイブには history/evidence-index.md のみを使用します。すべての小さなステップをそこに記録しないでください。
• アクティブなロードマップ/ステータスファイルは、古い証拠にリンクする必要がありますが、繰り返しのログ、古い自動化出力、レビュージョブの詳細、または履歴ナラティブを吸収しないでください。

検索モデル

Plan-treeは検索単位システムであり、大きな包括ドキュメントを成長させる場所ではありません。すべての永続ファイルは1つのプライマリロールを持つ必要があります。

• エントリポイントまたはインデックス: ルーティング、権限順序、読み取りパス、および1行サマリー。
• 現在の状態: アクティブなロードマップ、現在のフェーズ、ブロッカー、次のターゲット、引き継ぎ。
• トピックカプセル: 1つのドメイン、機能、制約セット、またはワークストリームの短いサマリーと、詳細シャードへのリンク。
• 詳細シャード: 1つのリーダータスクのための契約、代替案、エッジケース、実装ノート、ロールアウト、運用、準備、またはリポジトリ衛生の詳細。
• 決定: コンテキストと結果を持つ安定した選択。
• 証拠: 検証レコード、レビュー結果、アーティファクトリンク、受け入れられたテストサマリー、または証拠インデックス。
• 履歴/アーカイブ: 廃止されたステータス、古い実行ログ、移行されたソースマテリアル、廃止された詳細。

1つのファイルにサマリー、アクティブ状態、決定、長い推論、ログ、証拠、履歴を同時に持たせないでください。更新によってファイルがそのロール境界を越える場合は、最初にリンクされた検索単位を作成または更新し、アクティブファイルには簡潔なサマリーとリンクのみを残します。

これらの行数は分割トリガーとして使用し、厳密な正確性テストとしては使用しません。

• ルートREADME、計画README、ロードマップ、実装ステータス: 150行前後以下に保ちます。
• トピックカプセル: 250行前後以下に保ちます。
• 通常の詳細シャード: 400行前後で分割またはインデックス化します。
• 履歴または証拠ファイル: 500行前後でインデックス化または分割します。

分割する場合

…

[翻訳のため省略]