powerplan

PLAN.md as the operational backbone of agentic development.

powerplan is a standalone MCP server that gives coordinators and worker agents a human-language API over your project’s PLAN.md: show progress, create iterations, complete tasks, keep the header truthful — without freeform file thrash.

Why

Agents often edit PLAN.md by hand. Headers drift, “COMPLETE” gets stamped without proof, and multi-agent swarms step on each other. powerplan is the single writer: tolerant reader, surgical writer, optional [agent: …] tags.

Related MCP server: plane-mcp-server

Install

Option A — clone + editable install

git clone https://github.com/CynaCons/powerplan.git
cd powerplan
pip install -e ".[dev]"

Option B — via PowerSpawn (submodule)

Projects that already use PowerSpawn can pull powerplan automatically:

git submodule update --init --recursive   # if PowerSpawn vendors powerplan/

Then point MCP at powerplan/powerplan_server.py or python -m powerplan with PYTHONPATH including the submodule root.

Option C — path-only (no install)

python /path/to/powerplan/powerplan_server.py

MCP registration

Claude Code / project .mcp.json

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

Grok (~/.grok/config.toml or project config)

[mcp_servers.powerplan]
command = "python"
args = ["-m", "powerplan"]
env = { PYTHONUNBUFFERED = "1" }
enabled = true

Alongside PowerSpawn

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

Register both as separate servers — nesting in a monorepo does not merge MCPs.

Tools (v0.2.2)

Every tool accepts optional plan_path (relative or absolute). Default: walk up from cwd to the nearest PLAN.md.

Agent rule: prefer get_current_iteration / get_iteration over reading all of PLAN.md. If no plan exists → create_plan first.

Managed plan format

Phase-like headers and other prose are preserved as opaque blocks (tolerant reader). See PRD for principles (single writer, no evidence journal in the tool).

Development

pip install -e ".[dev]"
pytest -q
python -m powerplan   # stdio MCP (use with an MCP client)

Landing page:

cd site && npm ci && npm run dev

License

MIT — see LICENSE.