# Use Valdr You've installed Valdr, activated your license, installed packs, and configured a provider. Now put it all together. This page walks through the core loop that every Valdr workflow is built on: **create a task, launch an agent, review the output.** Once this loop clicks, everything else — sprints, orchestration, multi-agent workflows — is just composition on top of it. ## What this page covers - Starting Valdr - Creating a project and your first task - Launching an agent session - Reviewing agent output - Understanding the review loop --- ## Start Valdr Launch Valdr from the terminal: ```bash # Point `--pm-home` to your local data directory (e.g., `~/.valdr/pm`) and specify a port for the UI (e.g., `7777`). valdr --pm-home ~/.valdr/pm --port 7777 ``` You will then be prompted for username and password. This is the authentication layer for your Valdr UI and the MCP data (you will add this to your mcp config). You can use any credentials you like — this is not connected to any external identity provider. Just pick something you can remember for now: ```bash Valdr userName: yourname Valdr password: yourpassword ``` {{< callout type="info" >}} Protecting your Valdr data keeps your agent work private and secure. (Also safe from the agents that will try to update it directly) {{< /callout >}} The Valdr UI opens in your browser. You'll see the dashboard — this is your home base for everything that follows. {{< callout type="tip" >}} If you completed the [Configure](/valdr/docs/getting-started/configure/) steps, you should see your registered agents in the sidebar and no license warnings. If something's missing, go back and verify your setup. {{< /callout >}} --- ## Create a project If you don't already have a project, create one now. Projects group tasks, sprints, and agent work under a single umbrella. {{% steps %}} ### Open Projects Click **Projects** in the sidebar. ### Create a new project Click **New Project** and fill in: - **Name** — e.g., "My First Project" - **Key** — a short slug like `first-project` - **Description** — what this project covers ### Set status Mark it **In Progress** and save. {{% /steps %}} --- ## Create your first task Tasks are the unit of work in Valdr. Every agent session runs against a task, inheriting its description, acceptance criteria, and context. A well-written task means the agent knows exactly what to do without you re-explaining anything. {{% steps %}} ### Open Tasks Click **Tasks** in the sidebar. ### Create a new task Click **New Task** and fill in: - **Title** — what needs to be done (e.g., "Add input validation to the signup form") - **Project** — select your project - **Description** — enough context for an agent to work independently: what the current behavior is, what the desired behavior is, and any constraints - **Acceptance criteria** — concrete, verifiable conditions for "done" (e.g., "Email field rejects invalid formats", "Error messages display below the field") ### Set priority and assign Give it a priority, assign yourself as the owner, and set status to **To Do**. {{% /steps %}} {{< callout type="info" >}} The more specific your acceptance criteria, the better the agent performs. Agents treat acceptance criteria as their success checklist — vague criteria produce vague results. {{< /callout >}} --- ## Launch an agent This is where Valdr earns its keep. Instead of copy-pasting task details into an AI chat, you click **Launch** and the agent picks up the full task context automatically. {{% steps %}} ### Open the task Click into the task you just created. ### Go to Agent Sessions Click the **Agent Sessions** tab in the task detail view. ### Select a preset Choose one of your configured [agent presets](/valdr/docs/ui/settings/#agent-presets) from the launcher dropdown — e.g., your Claude or Codex coding preset. ### Launch Click **Launch**. Valdr: 1. Creates an isolated git worktree (if your preset has worktree creation enabled) 2. Assembles the agent's prompt from its capabilities, the task context, and acceptance criteria 3. Starts the agent session The agent is now working. You can watch the session in real time or come back later. {{% /steps %}} --- ## Monitor the session While the agent runs, the session view gives you full visibility: | Tab | What you see | |-----|-------------| | **[Transcript](/valdr/docs/ui/agent-sessions/transcript/)** | Every message, tool call, and command in chronological order | | **[Terminal](/valdr/docs/ui/agent-sessions/terminal/)** | Live shell access to the agent's worktree | | **[Diff](/valdr/docs/ui/agent-sessions/diff/)** | File-by-file code changes the agent has made | | **[Metadata](/valdr/docs/ui/agent-sessions/metadata/)** | Session profile — tokens used, provider, timing, raw spec | You don't need to watch the whole session. The transcript is recorded, so you can review it after the agent finishes. This is one of the things that makes Valdr different from a chat window — **nothing disappears.** --- ## Review the output When the session completes, it's time to review. This is the human checkpoint that makes agent work trustworthy. {{% steps %}} ### Check the diff Open the **Diff** tab to see exactly what the agent changed. Review it like you'd review any pull request — file by file, with full context. ### Read the transcript If anything in the diff looks unexpected, the **Transcript** tab shows you the agent's reasoning: what it tried, what tools it called, and why it made specific choices. ### Start a review Navigate to the task's **Reviews** tab and start a review. Score the work against the acceptance criteria: - **Approve** if it meets all criteria - **Request changes** if it needs work — the agent can be re-launched with your feedback ### Score the session Run the [Auditor skill](/valdr/docs/skills/valdr-auditor/) on the session to evaluate execution quality using the auditor prompt your team has configured. Audit scores surface issues reviewers might miss and build a quality history over time. {{% /steps %}} --- ## The complete loop That's the core Valdr workflow: ``` Create task → Launch agent → Review output → Approve or iterate ``` Every feature in Valdr builds on this loop: - **Sprints** group tasks and move them through the loop in batches - **Orchestrators** (like Skadi) automate the sequencing — launching agents, routing reviews, advancing tasks - **Reviewers** (like Sigrid) automate the review step with structured criteria - **Auditors** (like Tyr) automate scoring with seven-dimension evaluation - **Planners** (like Freya) generate the tasks that feed into the loop Start with the manual loop. Once you're comfortable, layer in automation with the [workflow building blocks](/valdr/docs/getting-started/workflows/). --- ## What to try next {{% steps %}} ### Launch a second agent on the same task Use a different preset (different provider or model) and compare the results in the Agent Sessions tab. Same task, different approach — see which produces better output. ### Try the orchestrator Open the [Orchestrator](/valdr/docs/ui/orchestrator/) from the sidebar and start a conversation with Gunnar. Ask it about your projects, tasks, or agents. This is the natural-language interface to your workspace. ### Build a workflow Read [Build Your Own Workflow](/valdr/docs/getting-started/workflows/) to understand how agents, capabilities, and MCP tools compose into automated pipelines. {{% /steps %}} > **Local-first:** Everything you just did — tasks, sessions, diffs, scores — lives on your machine. No data left your workspace. The session transcript, the agent's changes, and the review history are all locally stored and locally inspectable for as long as you keep them.