Agents

The Agents view is your command center for everything that acts in your system—human operators, bots, and CI integrations. Every agent gets a clear identity, composable prompts, and capability assignments that define what it can do and how it behaves.

Agents are the unit Valdr reasons about: ownership, behavior, execution history, and audit all attach here.

System Prompt Preview removes the guesswork. See exactly what your agent receives at launch—prompts, capabilities, and ordering—before you ship.

What this page covers

Agent registry with kinds, handles, and status filtering
System prompt composition from linked prompts and capabilities
Capability assignment with searchable selection
Notes for coordination, alerts, and status tracking
Inline editing for agent names and handles
Creating new agents with tags and metadata

Quick start

1 — Browse the registry

Filter agents by kind (human, bot, ci) to find the operator you need. Handles (@coder-nova) make agents addressable across your system.

2 — Check the system prompt

Open any agent and review the System Prompt Preview on the Overview tab. This is exactly what the agent receives at launch—no guessing.

3 — Assign capabilities

Use the searchable Capabilities tab to grant domain-specific behaviors. Capabilities link to playbook prompts that shape how the agent works.

4 — Link prompts for context

Add system, guide, or checklist prompts on the Prompts tab. These compose with capability playbooks to build the full system prompt.

Agent kinds and handles

Every agent has a kind that signals its nature:

Kind	Use case
`human`	Human operators and reviewers
`bot`	AI agents and automations that execute tasks autonomously
`ci`	CI/CD integrations that post results back to PM MCP

Handles (e.g., @valdr-auditor) make agents addressable in tasks, reviews, and mentions. Once set, handles cannot be cleared—only changed to a new value.

Tip

Use lowercase handles with dashes for consistency: @coder-nova, @security-reviewer, @nightly-build.

Overview tab: System Prompt Preview

The Overview tab shows what matters most: the fully composed system prompt that will be sent to the agent at launch time. No more wondering what your agent actually receives.

Prompt composition order

Valdr assembles the system prompt in a fixed, predictable order:

Agent System Charter — Identity and mission (prompts with system context)
Guidance — Operational instructions (prompts with guide context)
Capability Playbooks — Domain behaviors sorted alphabetically by capability key
Checklists — Required steps for validation (prompts with checklist context)

This ordering is deterministic. Capability playbooks sort alphabetically by lowercase key, so naming conventions like auditor.base, auditor.schema, auditor.tooling produce predictable prompt structure.

Note

See Prompt Ordering for the full specification on how prompts compose and how to control ordering with capability key naming.

Sidebar widgets

The Overview sidebar provides quick access to:

Tags — Editable labels for filtering and organization
Prompts summary — Count of system, guide, checklist, and capability prompts
Latest Note — Most recent coordination or status update
Activity — Creation and last update timestamps

Prompts tab: Direct bindings

The Prompts tab manages direct prompt bindings—prompts linked to the agent outside of capabilities. Use these for:

System prompts: Agent identity, mission, and guardrails
Guide prompts: Communication style, tool policies, execution patterns
Checklist prompts: Validation steps auditors score against

Tip

Use direct prompts for agent-specific identity and workflow. Use capabilities for reusable domain behavior shared across agents.

Linking a prompt

1 — Search for the prompt

Type in the searchable dropdown to find prompts by name or ID.

2 — Set contexts

Add comma-separated contexts like system, guide, or checklist to control where the prompt appears in composition.

3 — Click Link Prompt

The binding is saved immediately. The Overview tab updates to show the new system prompt preview.

Tip

Prompts can have multiple contexts. A prompt with system, guide appears in both sections of the composed prompt.

Capabilities tab: Domain behaviors

Capabilities encode domain-specific behaviors. Each capability can link to a playbook prompt that provides detailed instructions for that capability.

Assigning capabilities

1 — Search for capabilities

Type in the searchable dropdown. Results filter by key or category, and already-assigned capabilities are excluded.

2 — Select from the list

Click or press Enter on a highlighted suggestion. Free-text entry is not allowed—you must select a valid capability definition.

3 — Click Add Capability

The capability is assigned with its linked playbook prompt (if any). The system prompt preview updates automatically.

Capability naming for ordering

Capabilities sort alphabetically by lowercase key. Use dot notation to control grouping and order:

auditor.base          ← Sorts first (foundation)
auditor.prompt_integrity
auditor.schema
auditor.task_correctness
auditor.tooling       ← Sorts last in auditor group

For explicit ordering, use numeric prefixes:

auditor.01_identity
auditor.02_instructions
auditor.03_guardrails

Numeric prefixes affect presentation order only; they do not imply priority, severity, or execution order.

Notes tab: Coordination and status

Notes capture coordination, alerts, and status updates for agents. Each note has a type that signals its purpose:

Type	Use case
`status`	Current state or availability
`preference`	Working style or preferences
`alert`	Important notice or warning
`coordination`	Process coordination or workflow notes
`summary`	Overview or recap

Notes support Markdown for rich formatting. Edit or delete notes with the hover actions on each entry.

Tip

Use alert notes to flag agents that are temporarily unavailable or have known issues. The latest note shows on the Overview tab for quick visibility.

Creating agents

Click Add Agent from the agent list to register a new operator, bot, or CI integration. Create agents sparingly—start by inspecting and extending existing ones.

1 — Set primary details

Enter the agent name, select a kind, and optionally set a handle. Handles must be lowercase with letters, numbers, and dashes.

2 — Add tags

Comma-separated tags help with filtering and organization (e.g., typescript, frontend).

3 — Create

The agent is registered immediately. Navigate to the detail view to assign capabilities and link prompts.

Inline editing

Agent names and handles are editable inline on the detail view header:

Double-click (or press Enter/Space) to enter edit mode
Enter to save, Escape to cancel
Names cannot be empty; handles cannot be cleared once set

Why this matters

Predictable behavior: System Prompt Preview shows exactly what agents receive—no guessing, no surprises, no post-deployment mysteries.
Composable prompts: Mix system, guide, checklist, and capability prompts without manual concatenation or fragile config files.
Searchable assignment: Find and assign capabilities instantly; already-assigned items are excluded so you can’t double-assign.
Audit-ready: Every agent has clear ownership, typed notes, and traceable capability assignments.
Full visibility: See the complete agent configuration in one view—no hunting through scattered config files or prompt directories.

Next steps

Prompt Ordering — Deep dive on how prompts compose and how to control ordering with capability key naming
Capabilities — Manage capability definitions and playbook prompts
Agent Sessions — See agent activity and execution history

Sprints Prompts