masterplan

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/

Related MCP server: notes-mcp

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@auto-implement
npx skills add JoschuaSchneider/masterplan@handoff

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