cpm-planner

cpm-planner

cpm-planner は、エージェントの作業向けのクリティカルパスメソッド（CPM）プランナーで、MCP サーバーとして提供されます。タスクグラフを送信すると、最早・最遅の開始時刻と終了時刻、余裕時間、クリティカルパス、完了を妨げるボトルネックタスクを含むスケジュールを計算します。さらに、ファイルセットが互いに重複しない、準備完了済み成果物のロックを考慮したコホートをリースするため、複数のワーカーが衝突せずに並行して作業できます。計画は、分岐・比較可能なバリアントを持つ plan-as-code ファイルとしてリポジトリに保存できます。読み取り専用ツールで、リソース容量に基づくリントやレベル調整、モンテカルロリスク分析を実行できます。アーンドバリュー用ツールでは、固定ベースラインに対する PV、EV、AC、SPI、CPI を追跡できます。また、オプションの AI レビューにより、検証済みのスケジュール改善案を提案できます。任意の MCP クライアント（Claude Code、Cursor、VS Code、Codex、カスタムオーケストレーター、または praxec ワークフロー）から、stdio 経由で操作できます。praxec に依存しないスタンドアロンツールです。

目次

• インストール
  • ビルド済みバイナリ（推奨）
  • バージョンを固定する
  • npm
  • ソースからインストール
  • Docker
  • インストールを検証する
• クイックスタート：plan-as-code
• クイックスタート：アーンドバリュー
• AI エージェントで使用する
• MCP ツール
  • Plan-as-code ワークフロー
  • 計画レビュー（オプション）
• ライブラリとして使用する
• Praxec
• 環境変数
• ドキュメント
• コントリビュート
• ライセンス

インストール

事前ビルド済みバイナリ（推奨）

Linux、macOS、Windows 向けに、x86_64 および ARM64 用の事前ビルド済みパッケージを公開しています。

インストーラーは OS と CPU を判別し、対応するアーカイブをダウンロードします。インストール前に、リリースの checksums.sha256 と照合して SHA-256 を検証し、ユーザー専用ディレクトリ内のバイナリをアトミックに置き換えます。チェックサムが一致しない場合は、ゼロ以外の終了コードで中断し、何もインストールしません。インストーラーを再実行すると、その場でアップグレードされます。

# Linux / macOS  ->  ~/.local/bin/cpm-planner
curl -fsSL https://github.com/praxec/cpm-planner/releases/latest/download/install.sh | sh

# Windows (PowerShell)  ->  %LOCALAPPDATA%\Programs\cpm-planner\cpm-planner.exe
irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1 | iex

インストーラーはインストール先の絶対パスを表示します。GUI クライアントにサーバーを登録する際は、そのパスを使用してください。

# Linux / macOS
curl -fsSLO https://github.com/praxec/cpm-planner/releases/latest/download/install.sh
less install.sh
sh install.sh --version <version>

# Windows
irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1 -OutFile install.ps1
Get-Content install.ps1
.\install.ps1 -Version <version>

バージョンの固定

この README のコマンドで使う <version> は、v0.2.0 のようなリリースタグです。リリースページから選択してください。

# Linux / macOS
curl -fsSL https://github.com/praxec/cpm-planner/releases/latest/download/install.sh | sh -s -- --version <version>

# Windows (PowerShell): the piped form cannot take parameters, so use the environment variable...
$env:PRAXEC_VERSION = '<version>'; irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1 | iex
# ...or a script block
& ([scriptblock]::Create((irm https://github.com/praxec/cpm-planner/releases/latest/download/install.ps1))) -Version <version>

npm

Node 18 以降では、npm から cpm-planner コマンドをインストールできます。

npm install -g @matthew-cochran/cpm
cpm-planner --version

このパッケージは小さなランチャーです。プラットフォームに対応したリリースバイナリをダウンロードしてチェックサムを検証し、インストール時、または npm がインストールスクリプトをスキップする場合は初回実行時にキャッシュします。パッケージのバージョンはリリースのバージョンと同じなので、npm install -g @matthew-cochran/[email protected] のように指定してバージョンを固定できます。インストールせずに実行するには、npx -y @matthew-cochran/cpm を使用してください。詳細と環境変数については、npm/README.mdを参照してください。

ソースからのインストール

Cargo でタグ付きリリースをビルドしてインストールします（Rust 1.99 以降）。

cargo install --git https://github.com/praxec/cpm-planner --tag <version> --locked

crates.io の掲載内容は、次回の cargo publish まで GitHub のリリースより古いままです。そのため、cargo install cpm-planner ではまだ最新バージョンをインストールできません。上記のようにタグからインストールしてください。

Docker

docker pull ghcr.io/praxec/cpm-planner
docker run -i --rm -v cpm-planner-data:/data ghcr.io/praxec/cpm-planner

-i は stdio トランスポート用に標準入力を開いたままにします。

イメージは CPM_PLANNER_DB=/data/cpm-planner.db を設定し、特権を持たない app ユーザーが所有するボリュームとして /data を宣言します。そのため、名前付きボリュームを使うと、実行をまたいで計画の状態を保持できます。バインドマウント（-v "$PWD:/data"）を使う場合は、ディレクトリを書き込み可能にするため、自分のユーザーとして実行してください：--user "$(id -u):$(id -g)"。パスを変更する場合に限り、-e CPM_PLANNER_DB=... を渡してください。

クライアントにイメージを登録するには、command に docker を設定し、残りを args に指定します。たとえば、Claude Code では次のようにします。

claude mcp add cpm-planner --scope user -- docker run -i --rm -v cpm-planner-data:/data ghcr.io/praxec/cpm-planner

インストールの確認

cpm-planner --version

cpm-planner <version> が出力されます。クライアントを使わずに MCP 側を確認するには、リポジトリからスモークテストスクリプトを実行します。このスクリプトは MCP の initialize と tools/list のハンドシェイクを実行し、plan.submit、plan.status、plan.get のいずれかが欠けている場合は失敗します。

node scripts/mcp-smoke.mjs /absolute/path/to/cpm-planner

クイックスタート：コードとしてプランを作成する

.cpm-planner/plans/<name>/<variant>.json にプラン（PlanGraph）を記述します。

1. plan.lint {path: ".cpm-planner/plans/checkout/main.json"} — 状態を書き込まずに静的チェックを行います。
2. plan.sync {path: ".cpm-planner/plans/checkout/main.json"} — バリアントを登録し、その plan_id を返します。
3. plan.status {plan_id} — スケジュール、クリティカルパス、準備完了セット、ロックを確認します。

plan.sync はコンテンツハッシュでファイルを追跡します。追跡中のファイルと保存されている最新のグラフが一致しない場合、plan.status は definition_drift を報告します。

クイックスタート：アーンドバリュー

ベースラインを確定し、進捗を記録してからレポートを確認します（earning_rule: "weighted" では earned_pct は比率に応じて計上されます。fifty_fifty では成果物が進行中になるか、報告された earned_pct がある時点で 50％が計上され、デフォルトの zero_hundred では完了時に計上されます）。

1. plan.baseline {plan_id} — CPM スケジュールと予算をベースライン 1 として確定します。
2. plan.mark_status {plan_id, deliverable_id, caller_id, status: {"status": "in_progress"}, earned_pct: 50, actual_effort_hours: 4} — 進捗と実コストを報告します。
3. plan.ev {plan_id} — PV、EV、AC、SV、CV、SPI、CPI、EAC、アラートを確認します。
4. plan.snapshot {plan_id, format: "markdown"} — レポートを追記し、Markdown テーブルとしてエクスポートします。

分母がゼロの比率は null となり、undefined で説明されます。アラート（SPI_BELOW_0_9、CPI_BELOW_0_9）は、保存されている直近 2 件の測定値を比較します。

AI エージェントでの使用

任意の MCP クライアントで、stdio 経由で cpm-planner を実行できます。cpm-planner バイナリをコマンドとして登録するか、Node 18 以降では npx -y @matthew-cochran/cpm を使用します。GUI クライアントでは、インストーラーが出力した絶対パスを使用してください。

cpm-planner skills install --target <tool> --user（または --project <dir>）を実行して、エージェントスキル（/cpm-plan など）をインストールします。<tool> には claude、codex、cursor、copilot、gemini、all、agents-md（プロジェクトのみ）を指定できます。

docs/AGENT-INSTALL.md に、クライアントごとの手順（Claude Code、Claude Desktop、Codex、Cursor、VS Code、Gemini CLI など）、env ブロック、確認方法、トラブルシューティングが記載されています。llms.txt では、LLM 向けのドキュメントを案内しています。

MCP ツール

plan.lint、plan.simulate、plan.reviewでは、インラインのgraph、保存済みのplan_id、プランファイルのpathのいずれか1つだけを指定します。plan.scheduleではgraphまたはplan_idを指定します。 plan.scheduleとplan.simulateは、plan.submitが拒否する入力を拒否し、plan.lintはそれらを指摘事項として報告します。モンテカルロ出力は、同じプラットフォームとツールチェーンであれば同じシードに対して再現可能ですが、浮動小数点演算関数に差異が生じることがあるため、ターゲットやコンパイラのバージョンをまたいでビット単位で同一の結果になるとは限りません。

プランをコードとして扱うワークフロー

.cpm-planner/plans/<name>/<variant>.jsonにプランファイルを作成し、plan.lint {path}でチェックしてから、plan.sync {path}で登録し、返されたplan_idを使って実行します。名前付きラインには複数のバリアントがありますが、選択されるのは常に1つだけです。plan.forkは構造化編集からドラフトを作成し、plan.compareはバリアントを採点し、plan.selectは1つを実行可能にします。定義は追跡対象のファイルに保存し、未追跡の一時的なグラフは決して保存しないでください。

計画レビュー（任意）

plan.review は OpenRouter 経由で、TypeSafe の較正済み判断モデルである Jev（typesafe/jev-1.13）に、lint を通過する計画について問い合わせます。1 回のレビューで最大 64 件の質問をまとめて送信します。OPENROUTER_API_KEY（または CPM_OPENROUTER_KEY_FILE）を設定するまで無効です。キーがなくてもツールは応答し、review_unavailable と lint レポートを返します。LLM の設定が無効でもサーバーは停止しません。起動時にログへ記録され、plan.review は設定名を示す理由とともに review_unavailable を報告します。

• 確率は参考情報です。 検出結果はセカンドオピニオンとして扱ってください。提案は機械的に検証されます（編集後の計画が lint を通過し、シミュレーションでメイクスパンが短くなる必要があります）。plan.fork {edits} で適用し、その後 plan.compare を実行してください。

• コスト。 判定モデルへの呼び出しに到達した plan.review は、1 回につき OpenRouter の課金対象リクエスト 1 件です。OpenRouter での Jev の料金は、入力トークン 100 万件あたり約 0.042 ドルです。レポートには、プロバイダーから提供された場合に usage が含まれます。サーバーあたり、判定モデルを呼び出すレビューは同時に最大 2 件まで実行され、それ以降の呼び出しは空き枠ができるまで待機します（キーがない場合や lint エラーの場合など、判定モデルを呼び出す前に終了するレビューは待機しません）。

• プライバシー。 この 1 件のリクエストで OpenRouter に送信される情報は次のとおりです。

  • 固定のタスク文、計画のメイクスパン、クリティカルパス（ID）。
  • 質問：各質問について、その種類、対象として挙げる成果物の ID、それらの ID を引用した質問文。質問の種類に応じて、前提条件の consumes テキスト、成果物のスケジュール済み時間、計画のスケジュール済み時間の中央値、依存関係の欠落に関する質問を促したヒューリスティック信号（説明文が他の項目に言及していること、同じディレクトリまたは入れ子のディレクトリにファイルがあること、metadata.owner が共通していること）も含まれます。
  • 質問で挙げられた各成果物について、その ID、スケジュール済み時間、余裕時間、critical と milestone のフラグ、所有するファイルパス（省略せず完全な形で送信）、前提条件（ID、consumes、種類）、および description、artifact、owner のメタデータ。description、artifact、owner、consumes はそれぞれ 500 文字で切り詰められます。

  グラフ内のそれ以外の情報（他の成果物、その他のメタデータキー、見積もり）は送信されません。内容を OpenRouter と共有できない可能性がある計画はレビューしないでください。

• 監査。 キーがログに記録されたり返されたりすることはありません。LLM 変数に誤って設定された値も同様です。結果にかかわらず、すべての plan.review 呼び出しで plan.review 監査イベントが 1 件記録されます（計画が見つからない場合、パスが不正な場合、レビューに失敗した場合を含みます）。監査されないのは、パラメーターが原因で呼び出しが拒否された場合（invalid_params）のみです。イベントには次のフィールドのみが含まれます。

  • status：ok、review_unavailable、invalid_graph、error のいずれか（レビュー失敗時は PLAN_NOT_FOUND、INVALID_PATH、INVALID_CAPACITIES など）。
  • code：error の場合はエラープレフィックス、それ以外は null。
  • failure_class：判定モデル呼び出しの失敗が原因で review_unavailable になった場合は、そのクラス（unauthorized、rate_limited、timeout、upstream、decode、transport、invalid_request）。それ以外は null（キーがない場合や、使用できない LLM 設定の場合を含む）。
  • plan_id：レビューされた保存済み計画。インラインの graph または path の場合は null。
  • question_count：送信された質問の数（判定モデルが呼び出されなかった場合は 0）。
  • jev_called：判定モデルが呼び出されたかどうか。
  • prompt_hash：正規化されたリクエストの sha256。判定モデルが呼び出されなかった場合は null。
  • model：プロバイダーが報告したモデル。呼び出しに失敗した場合は設定済みのモデル。判定モデルが呼び出されなかった場合は null。
  • endpoint：判定モデルのエンドポイントのホスト。判定モデルが設定されていない場合、lint でエラーが見つかった場合、またはレビューが error で終了した場合は null。

  プロンプト自体が記録されることはありません。

ライブラリとして使用する

CPM カーネルは、MCP に依存しない通常の Rust ライブラリとしても利用できます。

use cpm_planner::{CpmAlgorithm, Task, TaskKind};

let mut tasks = vec![
    Task::new("design", "Design", TaskKind::Custom { description: "design".into() }, 4.0),
    Task::new("build", "Build", TaskKind::Custom { description: "build".into() }, 8.0)
        .depends_on("design"),
    Task::new("test", "Test", TaskKind::Custom { description: "test".into() }, 2.0)
        .depends_on("build"),
];

let result = CpmAlgorithm::calculate(&mut tasks);
println!("critical path: {:?}", result.critical_path); // ["design", "build", "test"]
// also: result.bottlenecks, result.optimal_duration_parallel,
// and per-task .float (slack) / .is_critical on each Task.

クレートレベルのドキュメント（cargo doc --open、または現行バージョンが公開された後は docs.rs）には、submit、lease、complete を通じてプランナーを動作させる実行可能な例があります。

llm::jev::JevJudge（plan.review の判定処理）は、HTTP クライアントと接続プールを所有します。プールされた接続は、それを開いた tokio ランタイムによって駆動されるため、判定処理とそのクローンは同じランタイムで使用し、別のランタイムには新しい判定処理を作成してください。

Praxec

cpm-planner は完全に単独で動作し、通常の MCP で通信するため、特定のクライアントにコード依存しません。Praxec のパックでは、MCP ツールとして使用されています。praxec のワークフローに接続するには、MCP 接続を宣言します（プロトコルのみで、コード共有はありません）。

connections:
  planner:
    kind: mcp
    command: cpm-planner

このツールと、それを使うワークフローパックを最も簡単にセットアップして実行する方法は、次のワンコマンドセットアップです。

curl -fsSL https://raw.githubusercontent.com/praxec/packs/main/setup.sh | bash

このツールのプロバイダー座標（コンテナーイメージまたはリリースバイナリ）と、それに依存するパックについては、パックレジストリをご覧ください。

環境変数

クライアントの env ブロック（または -e／--env フラグ、あるいは docker run -e）で設定します。すべて任意です。

リースのデフォルトは 5 分です。長時間の作業では、取得／ハートビート時に ttl_seconds（サーバーの最大値以下）を渡し、少なくとも ttl/3 ごとにハートビートしてください。

ドキュメント

• docs/README.md：プロジェクトドキュメントの目次です。
• docs/AGENT-INSTALL.md：AI コーディングツールに cpm-planner をインストール、登録し、動作を確認する方法です。
• docs/architecture.md：モジュール、リクエストフロー、ストアのスキーマ、並行処理について説明しています。
• docs/releasing.md：リリース手順書です。
• CONTRIBUTING.md、SECURITY.md、SUPPORT.md、CHANGELOG.md。

コントリビューション

コントリビューションを歓迎します。ツールチェーン、ゲート、ブランチモデルについては、CONTRIBUTING.mdをご覧ください。参加するすべての方は、行動規範に同意するものとします。

ライセンス

Apache-2.0。