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{{\u003c callout type=\"tip\" \u003e}}\nUse `commit_markdown` for markdown-first planning workflows. The structured bundle actions are available for callers that already have validated plan/spec/task objects; new docs and agent workflows should start from markdown unless they explicitly need a lower-level structured commit.\n{{\u003c /callout \u003e}}\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\nCompatibility alias for `get_plan`. Use it when a caller expects the plan specification contract name; the current MCP implementation returns the same full plan payload as `get_plan`, 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 only when you already have validated structured objects. `commit_plan_bundle` is a compatibility alias for `commit_bundle`.\n\nFor markdown-first planning, prefer [`commit_markdown`](#commit_markdown) instead of manually assembling JSON objects.\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 a compatibility alias for `update_meta`.\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`help` returns structured, read-only guidance for the planner MCP surface.\n\n| Field | Contents |\n|-------|----------|\n| `actions` | Current accepted action names, including planner sessions, `commit_markdown`, and compatibility aliases `get_plan_spec`, `commit_plan_bundle`, and `update_plan_meta` |\n| `whenToUse` | Guidance for listing plans, fetching plans, drafting sessions, writing plans, committing bundles, updating metadata, deleting plans, and committing markdown |\n| `examples` | Representative calls for listing plans, using `get_plan_spec`, and committing a markdown plan |\n| `cautions` | Guardrails such as idempotency keys, validating markdown before commit, and alias behavior matching canonical actions |\n| `compatibility` | Notes that help is additive and provider-facing aliases remain accepted |\n\nUse this payload when an agent needs to discover the current VMP action surface before creating or committing plans.\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.
Use
commit_markdown for markdown-first planning workflows. The structured bundle actions are available for callers that already have validated plan/spec/task objects; new docs and agent workflows should start from markdown unless they explicitly need a lower-level structured commit.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
Compatibility alias for get_plan. Use it when a caller expects the plan specification contract name; the current MCP implementation returns the same full plan payload as get_plan, 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 only when you already have validated structured objects. commit_plan_bundle is a compatibility alias for commit_bundle.
For markdown-first planning, prefer commit_markdown instead of manually assembling JSON objects.
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 a compatibility alias for update_meta.
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" }help returns structured, read-only guidance for the planner MCP surface.
| Field | Contents |
|---|---|
actions | Current accepted action names, including planner sessions, commit_markdown, and compatibility aliases get_plan_spec, commit_plan_bundle, and update_plan_meta |
whenToUse | Guidance for listing plans, fetching plans, drafting sessions, writing plans, committing bundles, updating metadata, deleting plans, and committing markdown |
examples | Representative calls for listing plans, using get_plan_spec, and committing a markdown plan |
cautions | Guardrails such as idempotency keys, validating markdown before commit, and alias behavior matching canonical actions |
compatibility | Notes that help is additive and provider-facing aliases remain accepted |
Use this payload when an agent needs to discover the current VMP action surface before creating or committing plans.
Related
- Planner UI — the visual planning interface
- pm_task — tasks committed by plans live here
- pm_project — plans belong to projects