vmp (Valdr Mini-Planner)

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 draft a plan in markdown, validate it before saving, and use vmp to commit it 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, validate_markdown, commit_markdown, help

list_plans

List stored plans with task counts and completion metrics.

Parameters

get_plan

Fetch a plan with its spec and tasks.

Parameters

get_plan_spec

Compatibility alias for get_plan. It returns the same full plan payload, including tasks.

Parameters

session_create

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

Parameters

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

session_get

Get planner session details.

Parameters

write_plan

Write/upsert a plan record.

Parameters

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

update_meta / update_plan_meta

Update plan metadata (title, project assignment). update_plan_meta is a compatibility alias for update_meta.

Parameters

delete_plan

Delete a plan and all linked tasks. Destructive.

Parameters

validate_markdown

Check a plan document before saving it. This action accepts only markdown and does not create a plan or task record.

Parameters

Example

vmp {
  action: "validate_markdown",
  markdown: "<full plan document>"
}

When the document passes validation, structured content returns valid: true, errors: [], the full parsed plan object, and a report. The report includes schemaVersion and checks; each check has an id, label, status, and optional details. Validation also checks that requirement and task IDs are unique and that each task references declared requirements.

When validation finds issues, it returns a normal result with valid: false and errors containing all detected issues. It does not return a partial plan. A report may be present when checks could be completed, but errors is authoritative. Repair the markdown using those errors and validate it again. Validation checks plan content; project existence, planner attribution, and commit idempotency are checked when you call commit_markdown.

Repair, validate, then commit

Call validate_markdown with the complete document. If it returns valid: false, use errors to repair the markdown and validate again. After it returns valid: true, pass the same markdown to commit_markdown with a registered plannerAgentHandle and a fresh idempotencyKey.

Use validation in a workflow

Map outputs.valid to $.normalized.valid and outputs.errors to $.normalized.errors. Classify the boolean for the condition as valid:${steps.validate.outputs.valid}, with outcomes valid:true and valid:false; on valid:false, use loop_back to send errors to the planner. Set a fixed pass limit so the workflow stops if the plan still needs repairs.

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

Supported markdown structure

---
schemaVersion: 1.0
projectKey: "my-api"
---

# Plan: Implement rate limiting

## Idea
Limit repeated authentication attempts per client IP.

## Constraints
- Preserve the existing authentication response format.

## Success
- Excess attempts receive a rate-limit response and legitimate traffic succeeds.

## Design

### Problem
Authentication endpoints currently accept repeated attempts without a limit.

### Approach
Add token-bucket middleware and integration tests for the authentication routes.

### Risks
- [R1] Shared IP addresses may hit the limit | Mitigation: make the threshold configurable.

## Requirements
- [REQ-1] Limit authentication attempts
  Description: Enforce the configured per-IP threshold on login and signup.
  Scenario: Excess attempts - GIVEN an exhausted bucket WHEN another request arrives THEN return a rate-limit response.

## Tasks
- [TASK-1] Implement and verify authentication rate limiting
  Summary: Add middleware to login and signup with integration coverage.
  Requirements: REQ-1
  Acceptance:
    - Requests beyond the threshold receive a rate-limit response.
    - Requests within the threshold preserve existing behavior.

Use # Plan: ... for the title. Include Idea, Constraints, Success, Design with Problem, Approach, and Risks subsections, Requirements, and Tasks. Requirements and tasks use bracketed IDs, and task Requirements values must reference declared requirements. Supply this complete document as markdown, with an existing project key and registered plannerAgentHandle.

Keep idempotencyKey unchanged when retrying the same commit. A new or revised plan commit needs a new key; reusing an already completed key returns its stored result.

To commit a plan saved in a file, have the agent read that file and pass its full text to commit_markdown.

help

vmp { action: "help" }

help returns structured, read-only guidance for the planner MCP surface.

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