plan-importer

Plan Importer

このスキルを使用すると、既存のプロジェクト計画資料を PlanWeave Plan Package に変換できます。

コマンドのエントリーポイント

ファイルを書き込む前に、コマンドを解決してください。

1. ユーザーがコマンドを指定している場合は、それを使用します。
2. それ以外の場合は、グローバルの planweave を試します。
3. PlanWeave リポジトリでは、pnpm --filter @planweave-ai/cli planweave を優先します。
4. リポジトリで別のローカルスクリプトが定義されている場合は、そのエントリーポイントをそのまま使用し、レポートに記載します。

例では <pw> ... の形式で記述します。ここで <pw> は解決済みのコマンドです。

ファイルを書き込む前に、CLI を使って対象のワークスペースを解決してください。

<pw> init --json
<pw> paths --json
<pw> validate --json

このワークフローでは、コマンドの検出、ワークスペース／パスの解決、検証に CLI を使用してください。インポートした内容を具体化する際は、CLI が返す PlanWeave ワークスペースパスにパッケージファイルを直接書き込んでください。

ワークスペース

• PlanWeave 自体が対象プロジェクトでない限り、<pw> は PlanWeave リポジトリではなく、対象プロジェクトのルートから実行してください。
• 対象プロジェクト内に ./.planweave を手作業で作成したり、書き込んだりしないでください。
• PlanWeave は、PLANWEAVE_HOME が設定されている場合はそこにプロジェクト計画を保存し、設定されていない場合は次の場所をデフォルトとして使用します。
  • macOS：~/.planweave
  • Linux：~/.planweave
  • Windows：%USERPROFILE%\.planweave
• <pw> init --json と <pw> paths --json から、正確なワークスペースパスを読み取ってください。
• workspaceRoot、projectGraphPath、およびそのワークスペース配下のパッケージディレクトリなど、CLI が返す PlanWeave ワークスペースパスの内部にのみ書き込んでください。
• 明示的に指定された既存の対象キャンバスに単一キャンバスをインポートする場合は、そのキャンバスのパッケージディレクトリ内にのみ書き込んでください。
• 明示的な対象キャンバスを指定せずに単一キャンバスをインポートする場合、既存のデフォルト／現在のキャンバスを上書きしないでください。project-graph.json に新しい正式なキャンバスエントリーを作成し、重複しないキャンバス ID を割り当て、そのキャンバスのパッケージディレクトリにインポートしたパッケージを書き込んでください。
• 正式な複数キャンバスの計画では、返されたプロジェクト／ワークスペースルートに project-graph.json を書き込み、各キャンバスのパッケージはそのプロジェクトグラフで指定されたパッケージディレクトリにのみ書き込んでください。
• CLI が返すプロジェクト／ワークスペースとパッケージのディレクトリのみを、PlanWeave の書き込み可能な場所として扱ってください。

計画ファイルの編集範囲

• キャンバスの作成、パスの割り当て、ID の重複排除、アクティブキャンバスの選択、検証、復旧トランザクション、ランタイムの状態／結果の変更といった機械的なワークスペース操作には、CLI／ランタイムコマンドを使用してください。
• Plan Package の意味的なファイルは、CLI が返すワークスペースパスの内部で直接編集してください。対象は、キャンバスの意図と依存関係を記述する project-graph.json、タスク／ブロック／エッジ／受け入れ条件／プロンプトパスを記述する各キャンバスの manifest.json、およびソースプロンプトの Markdown です。
• 意味的な変更を正確に表現できる場合は、範囲を限定した CLI 編集コマンドを使用してください。それ以外の場合は、ソースパッケージファイルとプロンプトを直接更新してください。
• 計画を直接編集した後、編集したキャンバスを対象とする検証を実行してください。また、project-graph.json、キャンバスのエッジ、または crossTaskEdges を変更した場合は、プロジェクトの検証も実行してください。

ワークフローのインポート

1. README、計画ドキュメント、ADR、課題、仕様書、ドメインノート、および参照されているソースファイルを確認します。
2. 作成を始める前に、確認したソースの一覧を記録します。
3. PlanWeave パッケージの構造を抽出します。プロジェクトグラフ、キャンバス、タスク、ブロック、依存関係、プロンプトの配置、レイアウトのヒント、検証戦略が対象です。
4. コンテキストノードは作成しないでください。目標、要件、制約、リスク、参照、アーキテクチャ上のゲートは、プロジェクト／グローバルプロンプト、タスクの受け入れ条件、タスクプロンプト、またはブロックプロンプトに記載します。
5. 作成前に、以下の計画品質ゲートを実行します。網羅性マップを作成し、各タスクに具体的な受け入れ条件があること、各ブロックに検証可能な完了基準があること、主要な要件に明示的なプロンプトの配置先があることを確認します。
6. 既存のキャンバス、新規の単一インポートキャンバス、または正式な複数キャンバスのプロジェクトグラフから、明示的に選択します。ユーザーが既存のキャンバスを置き換えるよう明示的に依頼していない場合は、default には書き込まず、新しいキャンバスを作成します。
7. <pw> init --json と <pw> paths --json を実行し、ワークスペースの場所はそれらの出力を基準にします。
8. 計画を具体化します。新しいキャンバスまたは複数キャンバスの計画を作成する場合は、まず project-graph.json を更新し、その後、宣言したパッケージディレクトリに各キャンバスの manifest.json、タスクプロンプト、ブロックプロンプトを記述します。
9. <pw> validate --json を実行し、検証エラーとインポーターによって作成された網羅性の不足を修正します。
10. ソースドキュメント、コマンドのエントリーポイント、該当する場合はプロジェクトグラフのパス、パッケージのパス、プロンプトの配置、キャンバス戦略、レビュー戦略、検証結果を記載した計画インポートレポートを出力します。

計画品質ゲート

• 権威あるすべての目標をタスク、ブロック、受け入れ項目、またはプロンプトに対応付け、省略、弱体化、または不適切に先送りされた要件を指摘します。
• ユーザーが明示的に対象範囲を限定していない限り、デモ用の一部機能を完全な納品として受け入れないでください。
• 中核となるオブジェクトを特定し、作成、構造化、検証、変換、状態、保存、利用側、副作用、最終出力、失敗、再試行、ロールバック、手動介入まで追跡します。
• スキーマ、型、API、CLI フラグ、イベント、ファイル、プロンプトの入出力について、生成側と利用側で一貫性を保ちます。
• 契約を変更するタスクでは、該当する場合、呼び出し元、テスト、フィクスチャ、ドキュメント、マイグレーションも対象に含めます。フォールバック、デフォルト値、any、またはモック専用の経路で、契約の欠落を覆い隠さないでください。
• 実際の実行順序をモデル化します。並列タスクは互いに独立させ、逐次的なゲートは明示し、各キャンバスをステージ、機能領域、サブシステム、ワークフロー、または並列作業グループに対応付けます。
• 複数キャンバスのインポート計画では、デフォルトで crossTaskEdges: [] とします。
• 複数キャンバスをインポートする場合、キャンバスレベルの順序は正式なプロジェクトグラフのエッジで表現する必要があります。タスク間エッジを追加する前に、密接に関連するタスクを同じキャンバスに移すか、ステージ全体の順序をキャンバス依存エッジに昇格させます。
• 明確に分離できず、他の点ではまとまりがあり独立して実行できるキャンバス間のタスクを妨げる場合に限り、明示的な crossTaskEdges を使用します。また、タスクの移動やキャンバスエッジが不適切な理由を記録します。
• 同じキャンバス間で密集または反復するタスク間エッジ、タスクエッジで表現されたステージ全体の順序、キャンバス順序と重複するタスクエッジは、キャンバス境界の欠陥として扱います。書き出す前に、タスクを再分割するか、依存関係を昇格させます。
• キャンバスの順序やキャンバス間のブロッカーの唯一の情報源として、プロジェクト／グローバルプロンプトの文章に依存しないでください。
• 実行時に使われないスキーマ、呼び出し元のない API、振る舞いのない UI、読み込まれない設定、実際のクライアントを伴わないプロバイダー抽象化、利用側のないキュー、実体のないファイルパス、実行経路のないドライラン、またはフィクスチャのみのテストなど、見せかけの完了を却下します。
• ドメインで信頼性の高い実行が必要な場合、エラー、再試行、キャンセル、タイムアウト、権限エラー、一部成功、外部サービスの停止、人によるレビューの失敗、復旧を対象に含めます。
• すべてのブロックで、具体的な検証方法を指定します。コマンド、テスト、出力成果物、観測可能な状態変化、またはエンドツーエンドのフローを明記します。
• 複雑なブロックでは、完了条件にアーキテクチャ境界、テストの配置場所、設定／環境変数の扱い、該当する場合は README または .env.example の更新、実際のプロバイダーとモック／ドライランの想定を明記します。
• 対象リポジトリで明示的に要求されていない限り、他のプロジェクトのスキル、ブートストラップルール、プロンプト規約をこの計画にコピーしないでください。
• レポートでは、計画の欠陥と PlanWeave ツールチェーンの欠陥を分けて記載します。

プロンプトの配置

• PlanWeave グローバルプロンプト／プロジェクトプロンプト：横断的なルール、アーキテクチャ上の制約、参照ファイル、コーディング規約、共通のリスク。
• タスクプロンプト：タスク固有のコンテキスト、受け入れの理由、依存関係、変更される可能性が高いファイル。
• ブロックプロンプト：具体的な実行手順、検証コマンド、出力／レポートへの期待事項。
• レンダリング済みのプロンプト出力をソースのプロンプトファイルに書き戻さないでください。レンダリング済みプロンプトは <pw> prompt <ref> から取得される派生成果物です。
• ブロックプロンプトを空のままにしないでください。別途記載する詳細が不要な場合は、タスク／プロジェクトのコンテキストを継承することを明記し、具体的な完了条件を列挙します。

タスクとブロックの粒度

• 分割すること自体を目的に分割しないでください。データフロー、所有権の境界、依存関係、リスク、または独立して検証可能な受け入れ基準に基づいて分割してください。
• 個別に引き受け、テストし、報告するには細かすぎるタスクは統合してください。
• 実行可能な作業には implementation ブロックを使用し、完了基準、検証コマンド、またはレビューゲートで検証内容を明示してください。
• レビューブロックを追加するのは、複雑なコード、契約をまたぐ変更、データベース／スキーマの移行、プロバイダー統合、セキュリティ／プライバシー、アーキテクチャの変更、またはリスクの高いユーザー向けの動作に限ります。
• ユーザーから求められない限り、単純なドキュメント、設定の微調整、局所的な文言の編集、またはリスクの低い単一ファイルの変更にはレビューブロックを追加しないでください。

複数キャンバス戦略

• 小規模な計画には、単一のパッケージキャンバスを使用してください。
• 大規模な計画、特にタスク／ノードが100件以上ある場合は、ステージ、機能領域、サブシステム、ワークフロー、または担当者ごとにタスクキャンバスへ分割してください。
• 各キャンバスは、通常、元の計画で可能な範囲内で10～30件のタスクにまとめ、一覧しやすくしてください。
• 大規模または複数ステージにわたるインポートは、正式な project-graph.json と、キャンバスごとの manifest.json で具体化してください。
• キャンバス間の順序には、プロジェクトグラフのキャンバス依存関係エッジを使用してください。
• Plan Quality Gate を通過した、疎で不可避なブロッカーでない限り、crossTaskEdges は空のままにしてください。
• 単一キャンバスの manifest.json の意味は変更せず、キャンバスマニフェスト内にキャンバス間エッジを配置しないでください。
• プロジェクト／グローバルのプロンプトで戦略を説明してもかまいませんが、依存関係を強制する正本として扱わないでください。
• キャンバス間の並列実行が自動的に可能になるわけではありません。必須の順序は、プロジェクトグラフのエッジと crossTaskEdges から導き出してください。潜在的な競合は parallel.sharedResources に参考情報として記録し、実行を妨げるものとして示さないでください。

プロジェクトグラフの形式

正式な複数キャンバス計画を作成する場合は、以下を含めてください。

• PlanWeave のプロジェクト／ワークスペースルートに project-graph.json を配置します。
• 安定したID、タイトル、パッケージディレクトリ、スキーマで必要な場合は状態／結果パスを含み、不可視のレガシー専用キャンバスレコードを含まない canvases エントリ。
• ステージ、機能、サブシステム、またはワークフローの順序を示すキャンバス依存関係エッジ。
• タスクの配置やキャンバス依存関係エッジでは表現できない、文書化された疎な例外に限る、明示的な crossTaskEdges。
• コンテキストノード、フィードバックノード、実行時状態、またはレイアウトのみのグラフミラーを含めないでください。

作成後、<pw> validate --json で検証してください。不足しているキャンバス参照、不足しているクロスタスク参照、循環など、プロジェクトグラフのスキーマ／読み込み／コンパイル診断は、成功を報告する前に解消してください。

ブロックの形式

各ブロックには、id、type、title、prompt、depends_on、省略可能な parallel.sharedResources のヒント、完了基準、検証、報告要件が必要です。レビューが妥当な場合は、実装ブロックの後に review.required: true と明確なレビュープロンプトを指定した R-001 を追加してください。

ルール

• （存在する場合）project-graph.json、各キャンバスの manifest.json、ソースプロンプト、タスク／ブロックのプロンプトファイルを、計画内容の正本として扱ってください。
• ユーザーが既存のパッケージ形式のファイルを提供した場合は、その構造を確認し、対象のワークスペースファイルに直接具体化してください。
• feedback ブロックタイプを作成しないでください。フィードバックは実行時状態です。
• 実装状態をマニフェストに書き込まないでください。
• 実行時のタスク／ブロック／フィードバック状態には state.json のみを使用してください。
• 実行時のグラフミラー、.plan/、SQLite ストア、HTTP API、Docker サービス、または MCP サーバーを作成しないでください。
• Plan Import Report を、マニフェストのエッジ、タスクの受け入れ基準、またはプロンプト内容の代わりに使用しないでください。