# Planner
The Planner turns ideas into structured, actionable plans. Describe what you want to build, pick a project and a planning agent, and Valdr drafts a full plan: summary, design document, requirements, and tasks with acceptance criteria. Review it, edit it, approve it, and the plan writes directly into Valdr — ready for sprint planning and agent execution.

No more translating ideas into tickets by hand. **Describe the outcome, let the agent structure the work.**

## What this page covers

- Starting a planning session
- The split-view layout: chat and preview
- Plan output: summary, document, requirements, and tasks
- Reviewing and editing the draft
- Approving and writing the plan to Valdr

---

## Start a planning session

{{< thumbcard src="/images/ui/planner/plan-initial.png" alt="Planner launch screen showing project selection, agent launcher, and idea input" caption="Describe what you want to build — pick a project, choose a planning agent and launcher preset, and start planning" >}}

{{% steps %}}

### Pick a project

Select the project this plan belongs to. The planning agent uses the project context (description, services, existing tasks) to produce relevant output.

### Choose a planning agent and launcher

Select a planning agent from the dropdown — the default is **Freya**, Valdr's built-in planner. Then pick a launcher preset that determines which AI provider and model backs the session.

### Describe your idea

Write a description of what you want to build. This doesn't need to be formal — a paragraph describing the problem, the desired outcome, and any constraints is enough. The planning agent takes it from there.

### Start planning

Click **Start Planning**. The agent explores your codebase, asks itself clarifying questions, and drafts a structured plan.

{{% /steps %}}

---

## The split-view layout

The Planner uses a resizable split view:

- **Left panel** — The chat transcript showing the planning agent's work: codebase exploration, reasoning, and status updates
- **Right panel** — The plan preview with tabs for Summary, Document, Requirements, and Tasks

Use the layout buttons at the top to switch between **Chat focus**, **Split**, and **Preview focus** depending on whether you want to watch the agent work or review the output.

The chat panel also shows a **question counter** (e.g., "Questions 0/6") — the agent can ask you up to six clarifying questions during planning. You can nudge the agent with follow-up context at any time using the input box at the bottom.

---

## Plan output

When the agent finishes, the preview panel populates with four tabs:

### Summary

{{< thumbcard src="/images/ui/planner/plan-summary.png" alt="Plan summary showing title, description, requirement and task counts, project, agent, and status" caption="At a glance — what's being built, how many requirements and tasks, which project and agent, and current status" >}}

The summary shows:
- **Title and description** — what the plan covers
- **Requirement and task counts** — how much work the agent scoped
- **Project** — which project the plan belongs to
- **Planning agent** — which agent drafted it
- **Status** — `draft` until you approve
- **Session ID** — links back to the planning session for full traceability

### Document

{{< thumbcard src="/images/ui/planner/plan-document.png" alt="Plan document showing idea, constraints, success criteria, design, problem statement, and approach" caption="The full plan document — structured sections the agent generated from your idea" >}}

The document is the full plan in structured markdown. It typically includes:

- **Idea** — restated from your input with additional context the agent discovered
- **Constraints** — technical boundaries, compatibility requirements, project conventions
- **Success criteria** — concrete conditions for the plan to be considered complete
- **Design** — problem statement, approach, and architecture decisions
- **Risks** — potential issues the agent identified during exploration

This is a living document. You can edit it before approving (see [editing](#edit-before-approving) below).

### Requirements

{{< thumbcard src="/images/ui/planner/plan-requirements.png" alt="Requirements list showing five structured requirements with descriptions and acceptance criteria" caption="Each requirement is a specific, verifiable condition — the building blocks of your tasks" >}}

Requirements are the specific conditions the implementation must satisfy. The agent generates these from the plan document and your constraints. Each requirement has:

- **Title** — short, descriptive name
- **Description** — what the requirement means in detail
- **Acceptance criteria** — how to verify it's been met

Requirements flow into tasks — each task references the requirements it addresses.

### Tasks

{{< thumbcard src="/images/ui/planner/plan-task-unreviewed.png" alt="Task list showing generated tasks with descriptions, acceptance criteria, and linked requirements" caption="Tasks generated from the plan — each with a description, acceptance criteria, and linked requirements ready for agent execution" >}}

Tasks are the work items that implement the plan. The agent generates tasks scoped to the requirements, each with:

- **Title and description** — what needs to be done
- **Acceptance criteria** — verifiable checklist items agents use as their success measure
- **Linked requirements** — which requirements this task addresses
- **Review status** — indicates whether you've reviewed the task

Tasks are ready for assignment and agent execution once the plan is approved.

{{< thumbcard src="/images/ui/planner/plan-task-reviewed.png" alt="Task with review checkmarks showing reviewed acceptance criteria and requirements" caption="Mark tasks as reviewed — confirm acceptance criteria and requirements before approving the plan" >}}

---

## Edit before approving

{{< thumbcard src="/images/ui/planner/plan-edit.png" alt="Document editor showing source markdown with line numbers and edit controls" caption="Edit the plan source directly — refine constraints, add requirements, adjust scope before it becomes real work" >}}

Click into the **Document** tab and switch to the **Source** view to edit the raw markdown. You can:

- Refine the agent's language or add detail
- Tighten constraints or success criteria
- Add requirements the agent missed
- Remove scope you don't want

The editor shows line numbers and provides **Validate** and **Save** actions. Validate checks the document structure before saving. Switch between **Source** and **Preview** to see your edits rendered.

---

## Approve and write to Valdr

Once you're satisfied with the plan:

1. **Review tasks** — check acceptance criteria and linked requirements on each task
2. Click **Approve & Write to Valdr**

This writes the plan, requirements, and tasks into Valdr's PM system. From there:

- The plan appears in [Plans](/valdr/docs/ui/plans/)
- Tasks appear in [Tasks](/valdr/docs/ui/tasks/) under the project
- Tasks are ready for sprint planning and agent execution

{{< callout type="tip" >}}
**Plans feed the entire downstream workflow.** Once approved, an orchestrator like Skadi can pull these tasks into a sprint, assign agents, and start execution — all from the structured context the planner created. One planning session can kick off an entire sprint's worth of work.
{{< /callout >}}

---

## When to use the Planner

| Scenario | Why the Planner helps |
|----------|----------------------|
| **New feature** | Turns a rough idea into scoped requirements and implementation tasks |
| **Refactoring** | The agent explores the codebase first, so the plan accounts for what actually exists |
| **Bug investigation** | Describe the symptom, get a structured plan for diagnosis and fix |
| **Onboarding to a codebase** | Use the plan document as a structured overview of what needs to change and why |

The Planner is especially valuable when you know *what* you want but not *how to break it down*. The planning agent handles the decomposition — you review and approve the structure.

---

## Next steps

Plan approved? Head to [Sprints](/valdr/docs/ui/sprints/) to pull your new tasks into a sprint, or go directly to [Launching Agents](/valdr/docs/ui/tasks/agent-launch/) to start executing tasks immediately.