# Valdr
## What is Valdr?

AI agents are impressive in demos. Then you try to use them for real work — and everything falls apart. Context disappears between sessions. Conventions get ignored. Nobody can explain why something changed or who approved it.

**Valdr is the layer where you manage, observe, and govern agent work** — so it compounds instead of resets.

{{< badge content="Control Plane" color="blue" >}} {{< badge content="Local-First" color="green" >}} {{< badge content="Traceable" color="purple" >}}

Think of it like a control plane for AI agents: it doesn't run the agents themselves, but it structures *how* they run — with plans that persist, tasks that trace to requirements, capabilities that encode your expertise, and sessions that capture evidence.

Every agent run is scoped, logged, reviewable, and connected to the plan that created it. Nothing disappears into chat history. Nothing ships without a trail.

> [!IMPORTANT]
> Valdr runs on hardware you control — local or private cloud — and treats agent output like engineering output: observable, inspectable, and accountable.

This is not an AI toy. It is infrastructure for using agents without losing control.

---

## Why Valdr exists

> [!WARNING]
> Ad-hoc agents fail the moment the work matters.

CLI agents and IDE copilots plan in memory, then discard everything when the session ends. Context you painstakingly built? Gone. The reasoning behind a decision? Lost. Your team's conventions? Re-explained every session.

The moment you add:
- more than one agent
- more than one person
- reviews, handoffs, or validation
- or the need to explain *why* something changed

…prompt files and copy-pasted scripts collapse.

Valdr exists because engineers need a way to use agents **without creating invisible risk**.

It turns agent work into structured execution with:
- {{< badge content="Plans" color="blue" >}} explicit plans that persist beyond sessions
- {{< badge content="Tasks" color="indigo" >}} traceable tasks linked to requirements
- {{< badge content="Reviews" color="yellow" >}} enforced review points
- {{< badge content="Capabilities" color="green" >}} encoded expertise that agents always follow

You can see what happened, who approved it, and why it was accepted — weeks later, not just while it's fresh in your head.

---

## What Valdr replaces

> [!NOTE]
> Valdr does **not** replace your IDE, your CI, or your code review tools.

It replaces:
- ❌ prompt folders no one trusts
- ❌ agent runs no one can explain later
- ❌ "it worked last time" automation
- ❌ context you re-explain every session
- ❌ tribal knowledge that lives in your head instead of agent prompts

Without Valdr, *you* are the context store, the reviewer, and the memory — until that breaks.

---

## Why engineers use Valdr

Engineers don't adopt Valdr to "run agents."

They adopt it to:
- ✅ stop firefighting brittle automation
- ✅ encode institutional knowledge once, not re-explain every session
- ✅ make agent behavior visible and reviewable
- ✅ ship faster **without guessing what broke**

> [!TIP]
> **The value shows up quickly:**
> - Capabilities encode your team's conventions — agents follow them automatically.
> - Plans capture intent and requirements that persist beyond sessions.
> - Tasks link to requirements, so nothing gets lost in translation.
> - Reviews are first-class, not an afterthought.
> - Sessions provide evidence of what happened and why.

This is what predictable delivery looks like when agents are involved.

---

## Who Valdr is for

{{< badge content="Opinionated" color="amber" >}} That's intentional.

{{< callout type="info" >}}
**Valdr is for:**
- **Solo developers** shipping real systems who want agent speed without regressions.
- **Engineers** who care about contracts, reviewability, and failure modes.
- **Operators** who need auditable, local-first workflows without cloud lock-in.
- **Vibe-coders who ship**, not vibe-coders who demo.
{{< /callout >}}

> [!CAUTION]
> **Valdr is NOT for:**
> - one-off prompts
> - throwaway scripts
> - black-box agent demos
> - "just trust the model" workflows

If that's what you want, Valdr will feel heavy — and that's the point.

---

## Where the value compounds

{{< badge content="Compounding Value" color="green" >}}

Most AI tools reset every time you start a new session. They forget what you decided last week, how your codebase works, why a change was approved, and what went wrong before.

That's why agent work feels impressive — but fragile.

> [!IMPORTANT]
> **Valdr makes agent work compound instead of resetting every session.**

It does that by layering four things most tools treat as disposable:

| Layer | Why it matters |
|-------|----------------|
| **Capabilities** | Expertise stops living in your head and starts living in the system |
| **Plans** | Intent persists beyond a single conversation |
| **Tasks** | Execution stays tied to requirements |
| **Sessions** | Decisions leave evidence, not guesses |

Individually, each layer helps. Together, they create something rare in AI workflows: **predictable outcomes over time**.

{{< badge content="Capabilities" color="green" >}} + {{< badge content="Plans" color="blue" >}} + {{< badge content="Tasks" color="indigo" >}} + {{< badge content="Sessions" color="purple" >}} = **work that gets better every time you run it**

> [!TIP]
> That's what compounding looks like — and why Valdr feels heavier than a chat prompt. Structure is the cost of compounding.

---

## What this looks like in practice

Here's a concrete example: **adding pagination to an API endpoint**.

**Without Valdr:**
1. You open Claude/Cursor and explain what you need
2. The agent writes code — maybe ignoring your team's pagination pattern
3. You fix it, re-prompt, iterate
4. A week later, someone asks "why did we do it this way?" — no answer exists
5. Next time, you re-explain the same conventions from scratch

**With Valdr:**
1. Your `api.conventions` [capability](/valdr/docs/ui/capabilities/) already encodes your pagination pattern — the agent knows it automatically
2. You describe the feature in the Planner; it generates a plan with requirements and acceptance criteria
3. Tasks are created, each linked to specific requirements
4. The agent writes code that follows your conventions *without being told*
5. The session captures what happened — decisions are traceable
6. Next time, the capability still applies. The plan is still there to reference.

The difference isn't speed — it's **accumulated context**. Every capability you encode, every plan you create, every session you run makes the next one better.

---

## Core principles

{{< cards >}}
  {{< card title="Local-first" icon="server" subtitle="Execution stays on hardware you control. Definitions can be shared and versioned." >}}
  {{< card title="Observable" icon="eye" subtitle="Sessions show what agents did, not just what they said." >}}
  {{< card title="Composable" icon="cube" subtitle="Capabilities, prompts, and plans are reusable across agents and projects." >}}
  {{< card title="Human-in-the-loop" icon="user" subtitle="Reviews and approvals are explicit, not afterthoughts." >}}
{{< /cards >}}

---

## Where to start

> [!NOTE]
> Don't start big. Start with a single tracked workflow.

Once you see agent output turn into auditable artifacts instead of chat transcripts, it's hard to go back.

{{< cards >}}
  {{< card link="/valdr/docs/getting-started/install/" title="Install Valdr" icon="download" subtitle="Get the CLI running in minutes" >}}
  {{< card link="/valdr/docs/ui/" title="Explore the UI" icon="desktop-computer" subtitle="See what the control plane looks like" >}}
  {{< card link="/valdr/docs/getting-started/configure/" title="Run local-only" icon="home" subtitle="Full air-gapped mode" >}}
{{< /cards >}}

---

## What we're focused on (and what we're not)

{{< callout type="info" >}}
**We're focused on:**
- ✅ encoding institutional knowledge into agent behavior
- ✅ connecting plans to tasks to sessions — full traceability
- ✅ making agent work reviewable and accountable
{{< /callout >}}

> [!CAUTION]
> **We are NOT chasing:**
> - novelty features
> - viral demos
> - "AI magic" without guardrails

---

> [!IMPORTANT]
> **Try this now:** Create a capability that encodes one team convention. Assign it to an agent. Watch the agent follow your rules without prompting. That's the difference.