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@auto-implement
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. | | auto-implement | Orchestrate a full plan: spawn one herdr agent per phase, watch, commit, repeat. Needs herdr. | | 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