vmp (Valdr Mini-Planner)
{"content":"{{\u003c badge content=\"Sovereign\" color=\"purple\" class=\"tier-badge\" \u003e}}\n\n{{\u003c callout type=\"info\" \u003e}}\n**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.\n{{\u003c /callout \u003e}}\n\nThe `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.\n\nYou can use `vmp` programmatically to generate plans from markdown, commit plan bundles, or orchestrate planner sessions with agent assistance.\n\n## Actions\n\n`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`\n\n---\n\n## list_plans\n\nList stored plans with task counts and completion metrics.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `projectKey` | string | No | Scope to a project |\n| `projectId` | string | No | Alternative to projectKey |\n| `limit` | number | No | 1–500 |\n\n---\n\n## get_plan\n\nFetch a plan with its spec and tasks.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `planId` | string | One of |\n| `planKey` | string | One of |\n\n---\n\n## get_plan_spec\n\nFetch 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.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `planId` | string | One of |\n| `planKey` | string | One of |\n\n---\n\n## session_create\n\nCreate a planner session — the conversational workspace where a planning agent drafts a plan.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `idea` | string | Yes | The initial idea or problem statement |\n| `templateId` | string | No | Optional template to start from |\n| `projectKey` | string | No | Target project |\n| `createdBy` | string | No | Actor handle |\n\n### Example\n\n```text\nvmp {\n action: \"session_create\",\n idea: \"Add rate limiting to authentication endpoints\",\n projectKey: \"my-api\",\n createdBy: \"@alice\"\n}\n```\n\n---\n\n## session_draft_with_agent\n\nDraft a plan using a planner agent (e.g., Freya). The agent explores the codebase, drafts the plan, and populates the session.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `sessionId` | string | Yes | |\n| `agentId` | string | Yes | |\n| `agentName` | string | No | |\n| `agentHandle` | string | No | |\n| `maxRepairAttempts` | number | No | Auto-repair iterations |\n| `mode` | string | No | `sync` or `async` |\n| `provider` | string | No | |\n| `model` | string | No | |\n| `temperature` | number | No | |\n| `reasoningEffort` | string | No | `low`, `medium`, `high` |\n\n---\n\n## session_get\n\nGet planner session details.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `sessionId` | string | Yes |\n\n---\n\n## write_plan\n\nWrite/upsert a plan record.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `plan` | object | Yes | The plan payload |\n| `schemaVersion` | string | Yes | Must be `\"1.0\"` |\n| `idempotencyKey` | string | Yes | |\n| `txnId` | string | Yes | Transaction ID |\n| `projectId` | string | No | Falls back to `plan.projectId` / `plan.projectKey` |\n\n---\n\n## commit_bundle / commit_plan_bundle\n\nCommit 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`.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `plan` | object | Yes | Plan payload |\n| `spec` | object | Yes | Plan spec |\n| `tasks` | array | Yes | Task definitions |\n| `schemaVersion` | string | Yes | |\n| `idempotencyKey` | string | Yes | |\n| `txnId` | string | Yes | |\n| `projectId` / `projectKey` | string | No | |\n| `plannerAgentHandle` | string | No | Who drafted it |\n| `vmpSessionId` | string | No | Source session |\n\n---\n\n## update_meta / update_plan_meta\n\nUpdate plan metadata (title, project assignment). `update_plan_meta` is an alias.\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `planId` | string | Yes |\n| `title` | string | No |\n| `projectKey` | string | No |\n\n---\n\n## delete_plan\n\nDelete a plan and all linked tasks. **Destructive.**\n\n### Parameters\n\n| Field | Type | Required |\n|-------|------|----------|\n| `planId` | string | Yes |\n\n---\n\n## commit_markdown\n\nCommit 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.\n\n### Parameters\n\n| Field | Type | Required | Notes |\n|-------|------|----------|-------|\n| `markdown` | string | Yes | Full plan document |\n| `idempotencyKey` | string | Yes | |\n| `plannerAgentHandle` | string | Yes | |\n\n### Supported markdown structure\n\n```markdown\n---\ntitle: \"Implement rate limiting\"\nprojectKey: \"my-api\"\n---\n\n## Problem\nCurrent auth endpoints have no rate limiting...\n\n## Approach\nAdd middleware-level rate limiting using token bucket...\n\n## Requirements\n- REQ-001: Per-IP rate limit on /auth/login\n- REQ-002: Per-IP rate limit on /auth/signup\n\n## Tasks\n- [ ] Implement token bucket middleware\n- [ ] Wire middleware into /auth/login\n- [ ] Wire middleware into /auth/signup\n- [ ] Add integration tests\n```\n\nYAML frontmatter supports `title` and `projectKey`. Sections are parsed for Problem, Approach, Requirements (with `REQ-xxx` identifiers), and Tasks (with checkbox status).\n\n---\n\n## help\n\n```text\nvmp { action: \"help\" }\n```\n\n## Related\n\n- [Planner UI](/valdr/docs/ui/planner/) — the visual planning interface\n- [pm_task](../tasks/) — tasks committed by plans live here\n- [pm_project](../projects/) — plans belong to projects","description":"Create, draft, and commit plans with requirements and tasks via the vmp planner MCP tool.","title":"vmp (Valdr Mini-Planner)"}
Sovereign
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 but not the MCP surface.The vmp tool (Valdr Mini-Planner) manages plans — the structured idea-to-tasks flow that powers the Planner UI. 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
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
---
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 testsYAML frontmatter supports title and projectKey. Sections are parsed for Problem, Approach, Requirements (with REQ-xxx identifiers), and Tasks (with checkbox status).
help
vmp { action: "help" }Related
- Planner UI — the visual planning interface
- pm_task — tasks committed by plans live here
- pm_project — plans belong to projects