# vmp (Valdr Mini-Planner)
{{< badge content="Sovereign" color="purple" class="tier-badge" >}}

{{< callout type="info" >}}
**Sovereign tier required.** All `vmp` actions route to Sovereign-gated underlying tools. Plan creation, drafting with agents, and commits are part of the Sovereign tier. Vanguard users can use the [Planner UI](/valdr/docs/ui/planner/) but not the MCP surface.
{{< /callout >}}

The `vmp` tool (Valdr Mini-Planner) manages plans — the structured idea-to-tasks flow that powers the [Planner UI](/valdr/docs/ui/planner/). Plans bundle requirements and tasks into a single cohesive unit that commits atomically into Valdr.

You can use `vmp` programmatically to generate plans from markdown, commit plan bundles, or orchestrate planner sessions with agent assistance.

## Actions

`list_plans`, `get_plan`, `get_plan_spec`, `session_create`, `session_draft_with_agent`, `session_get`, `write_plan`, `commit_bundle`, `commit_plan_bundle`, `update_meta`, `update_plan_meta`, `delete_plan`, `commit_markdown`, `help`

---

## list_plans

List stored plans with task counts and completion metrics.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `projectKey` | string | No | Scope to a project |
| `projectId` | string | No | Alternative to projectKey |
| `limit` | number | No | 1–500 |

---

## get_plan

Fetch a plan with its spec and tasks.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `planId` | string | One of |
| `planKey` | string | One of |

---

## get_plan_spec

Fetch plan detail for spec inspection. The current MCP implementation routes `get_plan_spec` through the same handler as `get_plan`, so it returns the full plan payload, including tasks.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `planId` | string | One of |
| `planKey` | string | One of |

---

## session_create

Create a planner session — the conversational workspace where a planning agent drafts a plan.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `idea` | string | Yes | The initial idea or problem statement |
| `templateId` | string | No | Optional template to start from |
| `projectKey` | string | No | Target project |
| `createdBy` | string | No | Actor handle |

### Example

```text
vmp {
  action: "session_create",
  idea: "Add rate limiting to authentication endpoints",
  projectKey: "my-api",
  createdBy: "@alice"
}
```

---

## session_draft_with_agent

Draft a plan using a planner agent (e.g., Freya). The agent explores the codebase, drafts the plan, and populates the session.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `sessionId` | string | Yes | |
| `agentId` | string | Yes | |
| `agentName` | string | No | |
| `agentHandle` | string | No | |
| `maxRepairAttempts` | number | No | Auto-repair iterations |
| `mode` | string | No | `sync` or `async` |
| `provider` | string | No | |
| `model` | string | No | |
| `temperature` | number | No | |
| `reasoningEffort` | string | No | `low`, `medium`, `high` |

---

## session_get

Get planner session details.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `sessionId` | string | Yes |

---

## write_plan

Write/upsert a plan record.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `plan` | object | Yes | The plan payload |
| `schemaVersion` | string | Yes | Must be `"1.0"` |
| `idempotencyKey` | string | Yes | |
| `txnId` | string | Yes | Transaction ID |
| `projectId` | string | No | Falls back to `plan.projectId` / `plan.projectKey` |

---

## commit_bundle / commit_plan_bundle

Commit a plan, spec, and tasks as a single atomic unit. Use this when you have a complete plan draft ready to persist. `commit_plan_bundle` is an alias for `commit_bundle`.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `plan` | object | Yes | Plan payload |
| `spec` | object | Yes | Plan spec |
| `tasks` | array | Yes | Task definitions |
| `schemaVersion` | string | Yes | |
| `idempotencyKey` | string | Yes | |
| `txnId` | string | Yes | |
| `projectId` / `projectKey` | string | No | |
| `plannerAgentHandle` | string | No | Who drafted it |
| `vmpSessionId` | string | No | Source session |

---

## update_meta / update_plan_meta

Update plan metadata (title, project assignment). `update_plan_meta` is an alias.

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `planId` | string | Yes |
| `title` | string | No |
| `projectKey` | string | No |

---

## delete_plan

Delete a plan and all linked tasks. **Destructive.**

### Parameters

| Field | Type | Required |
|-------|------|----------|
| `planId` | string | Yes |

---

## commit_markdown

Commit a plan from a markdown document with YAML frontmatter. This is the fastest way to persist a plan when you already have the structured content.

### Parameters

| Field | Type | Required | Notes |
|-------|------|----------|-------|
| `markdown` | string | Yes | Full plan document |
| `idempotencyKey` | string | Yes | |
| `plannerAgentHandle` | string | Yes | |

### Supported markdown structure

```markdown
---
title: "Implement rate limiting"
projectKey: "my-api"
---

## Problem
Current auth endpoints have no rate limiting...

## Approach
Add middleware-level rate limiting using token bucket...

## Requirements
- REQ-001: Per-IP rate limit on /auth/login
- REQ-002: Per-IP rate limit on /auth/signup

## Tasks
- [ ] Implement token bucket middleware
- [ ] Wire middleware into /auth/login
- [ ] Wire middleware into /auth/signup
- [ ] Add integration tests
```

YAML frontmatter supports `title` and `projectKey`. Sections are parsed for Problem, Approach, Requirements (with `REQ-xxx` identifiers), and Tasks (with checkbox status).

---

## help

```text
vmp { action: "help" }
```

## Related

- [Planner UI](/valdr/docs/ui/planner/) — the visual planning interface
- [pm_task](../tasks/) — tasks committed by plans live here
- [pm_project](../projects/) — plans belong to projects