# Planner
`valdr-planner` is a thin wrapper around a planner agent prompt. Its job is not to hardcode plan structure itself. Its job is to resolve which planner should own the request, load that planner's prompt, and then defer the planning workflow to the loaded prompt.

> [!IMPORTANT]
> The current wrapper does not auto-pick a planner. If the user did not specify a handle, it lists the available planner agents and asks the user which one should create the plan.

Planner is available on **Vanguard** and **Sovereign** plans with MCP access.

## Use Planner When You Need

- A structured plan for new work
- Requirements or specs before implementation
- Task generation from an approved plan
- A planner-owned prompt that can be updated centrally without changing the wrapper

## How To Use It

Start with:

```text
/valdr-planner
```

Then describe the planning request in the same message or the next one:

- Basic planning prompt:

```text
Create a plan for adding audit-log export to the admin UI.
```

- Named planner prompt:

```text
Use freya to turn this feature brief into a plan with requirements, risks, and 3-5 executable tasks.
```

- Project-specific prompt:

```text
Use freya to create a plan for the payments-platform project that adds invoice retry visibility without changing the existing billing API.
```

If you omit the planner handle, the wrapper will list the available planners and ask you which one should create the plan.

## Wrapper Contract

The packed wrapper always does three things:

1. Resolve the planner handle.
2. Load the planner prompt for that handle.
3. Follow the loaded planner prompt as the single source of truth.

### Step 1: Resolve the Planner

If the user already named a planner handle, use that handle and proceed to prompt loading.

If the user did not specify one, list planner agents:

```json
mcp__valdr__pm_agent → { "action": "list", "defaultRoles": ["planner"] }
```

Resolution rules:

- If one or more planners exist, present the handles and ask the user which should create the plan.
- If none exist, stop and route the user to [Orchestrator](../valdr-orchestrator/) for registry setup.

### Step 2: Load the Planner Prompt

```json
mcp__valdr__pm_agent → { "action": "get_prompt", "handle": "<planner handle>" }
```

If the prompt cannot be loaded, stop and ask the user how to proceed.

### Step 3: Execute the Loaded Planning Workflow

Once the prompt is loaded, that prompt owns the plan shape, approval flow, required research, task generation strategy, and any follow-on references it hot-loads.

The wrapper stays thin on purpose. If you want to change how planning works, update the planner prompt or the linked capabilities, not the wrapper.

## Why the Thin Wrapper Matters

The current design keeps planning behavior centralized:

- Change the planner prompt once and every CLI session gets the update.
- Keep role selection explicit instead of silently choosing a planner.
- Separate wrapper stability from planning methodology changes.

## Related Skills

- **[Orchestrator](../valdr-orchestrator/)** — Find project context or route registry setup before planning
- **[Executor](../valdr-executor/)** — Execute the tasks created by the planner flow
- **[Reviewer](../valdr-reviewer/)** — Review work produced from planned tasks