masterplan

<div align="center">

<img src="assets/logo.png" alt="masterplan logo" width="400" />

<h1>masterplan</h1>

<p>Minimal MCP server that keeps implementation plans and handoffs as plain markdown in the CWD of your agent.</p>

<p>Skills are based on <a href="https://github.com/mattpocock/skills">mattpocock/skills</a>.</p>

</div>

Use with your coding agent

Add to your mcp.json / client config:

{
  "mcpServers": {
    "masterplan": {
      "command": "npx",
      "args": ["-y", "@joschuadev/masterplan"]
    }
  }
}

Plans and handoffs live in .masterplan/ in the working directory of your agent.

Optionally add this to your global .gitignore:

.masterplan/

Tools

• create_plan({ title }) — scaffold a plan, returns its path
• list_plans() — list plans with frontmatter
• latest_plan() — most recent plan plus its handoff paths
• prepare_handoff({ plan_stem }) — scaffold a handoff for a plan
• list_handoffs({ plan_stem }) — list a plan's handoffs

Skills

The plan/handoff workflow is driven by a set of agent skills that live in skills/ and call the tools above. Install them with the Skills CLI (npx skills):

# full workflow
npx skills add JoschuaSchneider/masterplan

# seperately
npx skills add JoschuaSchneider/masterplan@grill-me
npx skills add JoschuaSchneider/masterplan@create-plan
npx skills add JoschuaSchneider/masterplan@implement-plan
npx skills add JoschuaSchneider/masterplan@handoff

Skill	What it does
grill-me	Interview you relentlessly about a plan or design until you reach shared understanding.
create-plan	Turn that understanding into a phased, tracer-bullet plan via create_plan.
implement-plan	Read the latest plan via latest_plan and start implementing.
handoff	Compact a session into a handoff doc via prepare_handoff for the next agent.

Global install / CLI (optional)

You can install masterplan globally and use the CLI to interact with plans.

npm install -g @joschuadev/masterplan

Develop

bun install
bun src/mcp/server.ts   # run from source
bun run build           # bundle to dist/masterplan.js