powerplan

powerplan

エージェント型開発の運用基盤となる PLAN.md。

powerplan は、プロジェクトの PLAN.md を人間の言葉で操作できる API をコーディネーターやワーカー エージェントに提供する MCP サーバーです。 進捗の表示、イテレーションの作成、タスクの完了、ヘッダーの正確な維持を、 自由形式でファイルを何度も編集することなく実行できます。

mcp-name: io.github.CynaCons/powerplan

MCP サーバー名	powerplan
PyPI	powerplan-mcp（powerplan は別の無関係なパッケージです）
レジストリ	io.github.CynaCons/powerplan
ステータス	v0.9.0 — ターン終了時のステータス表示（PLAN.md）
サイト	GitHub Pages
組み合わせて使うツール	PowerSpawn（任意）

---

インストール

uv（uvx を提供）または Python 3.10 以降が必要です。

uvx powerplan-mcp

これは stdio MCP サーバーです。クライアントの接続先に指定してください。

Claude Code / Cursor / .mcp.json

{
  "mcpServers": {
    "powerplan": {
      "command": "uvx",
      "args": ["powerplan-mcp"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

Claude Desktop

同じブロックを claude_desktop_config.json（mcpServers）に設定します。

Grok（~/.grok/config.toml またはプロジェクト設定）

[mcp_servers.powerplan]
command = "uvx"
args = ["powerplan-mcp"]
env = { PYTHONUNBUFFERED = "1", PYTHONIOENCODING = "utf-8" }
enabled = true

pip（uv なし）

pip install powerplan-mcp

{
  "mcpServers": {
    "powerplan": {
      "command": "python",
      "args": ["-m", "powerplan"],
      "env": {
        "PYTHONIOENCODING": "utf-8",
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

---

エージェント向けガイド

スコープを限定したツールを優先してください。作業内容を把握するために、 PLAN.md 全体を読み込まないでください。

1. ツールが「no PLAN.md」で失敗した場合は、まず create_plan を実行します。
2. show_miniplan — 計画独自の形式で、今取り組む内容を表示します。現在の イテレーションをそのまま表示し、隣接するヘッダーも含めます。すべての セッションはここから始めてください。
3. get_current_iteration — 同じ内容を JSON で表示します。
4. get_iteration(version) — 1 つのイテレーションのタスクと進捗を表示します。
5. add_task / add_tasks / complete_task（複数の場合は indexes）/ start_iteration / close_iteration で変更を加えます。
6. show_plan は人間が概要を確認するためのもので、全内容の出力ではありません。
7. すべての主要なターンの最後（ファイルの変更、タスクの完了や追加、 チェックの実行、イテレーションの終了）に、show_current_iteration の出力を コードブロックにそのまま貼り付けてください。ユーザーがステータスと進捗を ひと目で確認できます。サーバーは MCP の指示を通じて、このルールを すべてのクライアントに伝えます。

すべてのツールで任意の plan_path（相対パスまたは絶対パス）を指定できます。 既定では、cwd から上位へたどり、最も近い PLAN.md を探します。

変更系ツールで任意の agent を指定すると、変更した行の末尾に [agent: id] タグが追加されます。

---

理由

エージェントはしばしば PLAN.md を手作業で編集します。ヘッダーの整合性が 崩れ、「COMPLETE」が根拠なしに記され、複数エージェントの群れが互いの作業に 干渉します。powerplan は、寛容な読み取りと精密な書き込みを備えた 単一の書き込み担当です。任意で [agent: …] タグも付けられます。

---

ツール

ツール	動作
create_plan	./PLAN.md（または plan_path）がない場合に初期化します。上書きするには force を指定します
show_miniplan	セッション開始時に使用 — PLAN.md のスニペットをそのまま表示します。現在の（または指定した）イテレーションをバイト単位でそのまま示し、前後の内容はヘッダー行（before / after）にまとめます
get_current_iteration	エージェント向け推奨 — 現在の作業をスコープ限定の JSON で表示します
get_iteration	1 つのバージョンの JSON を表示します（タスク、進捗）
list_iterations / find_task / get_backlog	ファイル全体を読み込まずに移動できます
create_major / create_iteration / add_task / add_tasks	精密な変更を行います（複数のタスクを 1 回の書き込みで追加）
complete_task / reopen_task / remove_task / defer_task	1 つまたは複数を処理します（indexes / tasks）。[agent: id] は任意です
start_iteration / close_iteration	ACTIVE/current と COMPLETE のライフサイクルを管理します
check_plan	構造をチェックします
show_current_iteration	ターンの締めくくり — ステータス表示（ステータス、進捗数、目標、タスク）を行います。すべての主要なターンの最後に貼り付けてください
show_plan	人間が概要を簡潔に確認できます（全内容の出力ではありません）

---

管理対象の計画形式

構成要素	パターン
メジャー	## vX.Y — Title
イテレーション	### vX.Y.Z — Title
目標	**Goal:** …
タスク	- [ ] / - [x]
バックログ	## Backlog

フェーズに似たヘッダーやその他の文章は、不透明なブロックとしてそのまま保持されます。

---

ソースから

コントリビューター向け：クローン、編集可能なインストール、または PowerSpawn のサブモジュールとしての利用。

git clone https://github.com/CynaCons/powerplan.git
cd powerplan
pip install -e ".[dev]"
python -m powerplan          # same stdio server
# or: powerplan-mcp

PowerSpawn では、このリポジトリを Git サブモジュールとしてベンダー化できます。MCP サーバーを両方登録してください。統合はされません。

{
  "mcpServers": {
    "powerplan": {
      "command": "uvx",
      "args": ["powerplan-mcp"]
    },
    "powerspawn": {
      "command": "python",
      "args": ["-m", "powerspawn.mcp_server"]
    }
  }
}

パスのみ（インストール不要）：python /path/to/powerplan/powerplan_server.py

ランディングページ：cd site && npm ci && npm run dev

---

リリース（メンテナー向け）

手順、ID、失敗の履歴については、docs/RELEASING.md を参照してください。 エージェント向けチェックリスト：プロジェクトスキル release-powerplan（/release-powerplan）。

簡易手順：ガイドに記載されたすべてのバージョンファイルを更新 → pytest -q → vX.Y.Z のタグを作成 → タグをプッシュします。.github/workflows/publish.yml が powerplan-mcp を PyPI にアップロードし、その後 server.json を io.github.CynaCons/powerplan として MCP Registry にアップロードします。

---

ライセンス

MIT — LICENSE を参照してください。