<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:

```json
{
  "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](https://skills.sh) (`npx skills`):

```sh
# 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](https://herdr.dev). |
| `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.

```sh
npm install -g @joschuadev/masterplan
```

## Develop

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