Build Agent Routines with Capabilities

The official Valdr Workflow pack provides definitions for planning, sprint delivery, review, verification, and pull-request publication without forcing every team into one process. This page covers the lighter agent-routine pattern: compose capabilities, prompts, and MCP tools as instructions an agent follows.

To build a durable, versioned definition with waits, evidence, and recovery, continue to Definition Authoring.

Note

An agent routine is expressed as capability instructions. A Valdr Workflow is a saved executable definition with durable runs, attempts, waits, and recovery.

The building blocks

An agent routine is built from four pieces:

Piece	What it is	What it does
Agent	A registered identity (bot or human) with a role	Defines who does the work — executor, reviewer, orchestrator, planner
Capability	A markdown prompt registered in the system	Defines how an agent behaves — its instructions, constraints, and routine steps
Prompt	A standalone instruction set	Reusable context an agent can load on demand (coding standards, review criteria, etc.)
MCP tools	The PM and agent APIs exposed via Model Context Protocol	The verbs — create tasks, change status, launch sessions, start reviews, score work

An agent on its own doesn’t do much. Its behavior comes from the capabilities you attach to it. And those capabilities tell the agent which MCP tools to call, in what order, with what constraints.

How an agent routine takes shape

Here’s a concrete example. The Valdr pack ships an agent called Skadi — a sprint orchestrator. Skadi’s routine looks like this:

Discover current state

Query projects, sprints, and tasks via pm_project, pm_sprint, pm_task.

Build a sprint scope

Select tasks from backlog, link them to a sprint.

Staff the work

Assign executor agents to tasks.

Route reviews

Assign reviewer agents and launch review sessions.

Enforce readiness

Check that every task has an assignee, priority, points, and reviewer before launch.

Launch execution

Dispatch agent sessions for each staffed task.

Each of those steps is a separate capability — a focused set of instructions that Skadi loads on demand. Skadi’s system prompt is just a routing layer: it maps user intent to the right capability, then follows that capability’s steps.

This is not the only way to run sprints. It is one routine built from the same building blocks available to you.

What the pack agents demonstrate

The Valdr pack ships several agents that show different routine patterns:

Gunnar

Navigation & discovery

Gunnar — Navigation and discovery

Role: Orchestrator (read-only)

Gunnar explores your workspace. Ask it what’s in a project, what tasks are blocked, or which agents are registered, and it queries the PM tools to find out. It doesn’t change anything — it just reads and reports.

Routine pattern: Single-query lookups and multi-entity exploration. One discovery naturally chains into the next (find a project → list its tasks → check task status).

Skadi — Sprint orchestration

Role: Orchestrator

Skadi manages the full sprint lifecycle. It has nine operation capabilities, each handling one part of the routine:

Operation	What it does
Sprint planning	Creates sprints, selects tasks from backlog, links them to the sprint, enforces readiness gates
Sprint prep	One-pass sprint creation from a plan — discovery through activation in a single run
Task staffing	Assigns executor agents to tasks using deterministic ordering
Review routing	Assigns reviewer agents, starts reviews, and launches reviewer sessions attached to the executor’s worktree
Launch readiness	Verifies a task has an assignee, reviewer, priority, points, and correct status before launch
Launch executor	Dispatches an agent session for a task (supports standard and skill-based launch modes)
Session messaging	Re-engages running sessions — sends review feedback to executors, re-review requests to reviewers
Task completion	End-to-end task close: review verification → status transition → worktree merge → session cleanup → next task
Worktree merge	Inspects the agent’s worktree for uncommitted work, auto-commits if needed, merges to the working branch

Routine pattern: Discover state → compute desired state → apply mutations → verify results → enforce readiness gates before proceeding.

Task completion in detail

The task completion routine shows how these capabilities chain together. When a reviewer approves a task, Skadi:

Verify the review gate

Checks that every review has status approved. If any review is changes_requested, pending, or in_progress, the routine stops.

Move the task through status gates

Transitions from in_review → verified → done, with verification at each step.

Merge the agent’s worktree

This is a hard gate. Skadi hot-loads its worktree-merge capability, which:

Checks the agent’s worktree for uncommitted or unstaged changes
Auto-commits any uncommitted work with a traceable commit message
Verifies the worktree branch has commits ahead of the working branch
Merges into the working branch with --no-ff for a clear merge commit
Confirms the merge introduced actual file changes — if it was a no-op, the routine stops

Important

The merge must succeed before anything else happens. If it fails or conflicts, the routine halts. No sessions are purged and no next task is launched until the merge is verified.

Clean up sessions

Purges reviewer sessions first (since they reference the executor’s worktree), then purges the executor session. Asks for confirmation unless you’ve told it to auto-purge.

Advance to the next task

Verifies the working branch HEAD shows the merge commit, then selects the next to_do task in the sprint. It presents the task for your confirmation, reuses the launcher config from the completed task, and dispatches a new executor session. If no tasks remain, it reports the sprint is ready to close.

One command from you and the sprint keeps moving — finished work lands on your branch, sessions are cleaned up, and the next task starts. You can review what happened at every step through the task timeline and session transcripts.

Nikol — Agent design

Role: Orchestrator

Nikol helps you design new agents. It walks through defining an identity, designing a capability set, authoring prompts, and registering everything in the system.

Routine pattern: Interactive design sessions — identity first, then capabilities, then assembly and validation.

Sigrid — Code review

Role: Reviewer

Sigrid reviews task output against acceptance criteria. It evaluates work, classifies findings by severity (blocker, high, medium, nit), publishes results, and gates the approval decision.

Routine pattern: Evaluate → classify findings → publish → approve or request changes → verify before completion.

Freya — Feature planning

Role: Planner

Freya structures feature work into plans with specs, requirements, and generated tasks. Plans feed into sprints, giving downstream agents (Skadi, executors, reviewers) structured context to work from.

Routine pattern: Define scope → write specs → generate tasks from plan → hand off to sprint orchestration.

The handoff chain

These agents aren’t isolated. They hand off to each other through sessions and status transitions:

Gunnar discovers → Freya plans → Skadi orchestrates sprint
                                        ↓
                                  Executor runs task
                                        ↓
                                  Sigrid reviews output
                                        ↓
                                  Task verified and done

Each handoff uses MCP tools: pm_session to launch or message sessions, pm_task to change status, pm_review to start reviews. The handoff pattern is explicit — no magic routing. Each agent knows exactly which tool to call to pass work to the next stage.

Building your own agent routine

You don’t need to use the pack agents. You can:

Start simple

Register a single executor agent with one capability that describes how you want tasks worked. Assign it tasks, let it run, review the output yourself.

Add a reviewer

Create a reviewer agent with capabilities that describe your team’s review criteria. Wire it into the task lifecycle so work pauses for review before completion.

Add orchestration

Build an orchestrator that automates the parts you do manually today — sprint planning, task assignment, session launching. Encode your team’s rules as capability instructions.

Encode your standards

Write your coding conventions, review criteria, and process rules as capabilities. Agents load them on demand instead of you re-explaining them every session.

Tip

In this capability-driven pattern, the process lives in your capabilities. Valdr provides the runtime records and MCP tools; the capabilities define how an agent uses them. For first-class durable orchestration, use a saved workflow definition.

Capabilities are just markdown

A capability is a markdown file with structured instructions. Here’s the general shape:

Example capability structure

# Capability Title

## Purpose
What this capability does and when to use it.

## Inputs
- What the agent needs before starting

## Steps
1. Query current state using pm_task, pm_project, etc.
2. Evaluate what needs to happen
3. Apply changes using the appropriate MCP tool
4. Verify the result

## Constraints
- Rules the agent must follow
- Anti-patterns to avoid

You register capabilities in Valdr, link them to agents, and mark them as hot-loadable (loaded on demand) or always-on. The agent’s system prompt references its capabilities by key and loads them when the user’s intent matches.

This means changing a routine is just editing a markdown file and re-registering the capability. No code changes, no deploys, no downtime.

What agent routines mean in practice

No lock-in to a process — Valdr doesn’t care if you do sprints, kanban, or something you invented last Tuesday
Routines are inspectable — Every capability is a readable document, not buried logic
Routines are versionable — Capabilities are files. Put them in git. Review changes like code
Routines are shareable — A capability pack can be shared across a team like an ESLint config or VS Code settings
Routines evolve — Start simple, then add sophistication as you learn what your team needs