Prompt Ordering

TL;DR: Section order is fixed. Capability ordering is deterministic: sorted by capability role first, then backing prompt role, then alphabetically by key.

How system prompts are built

When Valdr launches an agent, it composes a system prompt from multiple sources. Understanding this composition is essential for predictable agent behavior.

The four prompt sections

System prompts are built in a fixed order with four distinct sections:

┌─────────────────────────────────────────────┐
│  1. Agent System Charter                    │  ← Identity and mission
├─────────────────────────────────────────────┤
│  2. Guidance                                │  ← Operational instructions
├─────────────────────────────────────────────┤
│  3. Capability Playbooks                    │  ← Domain-specific behaviors
├─────────────────────────────────────────────┤
│  4. Checklists                              │  ← Required steps to follow
└─────────────────────────────────────────────┘

Each section is separated by --- dividers in the final prompt.

Section composition

1. Agent System Charter

Source: Prompts with useFor containing system

The charter establishes the agent’s identity, purpose, and guardrails. This is the foundational context that shapes all subsequent behavior.

Best practices:

• Keep charters focused on identity and mission
• Define clear boundaries and constraints
• One system prompt per agent is typical

2. Guidance

Source: Prompts with useFor containing guide

Guidance prompts provide operational instructions, communication styles, and workflow patterns. They tell the agent how to work.

Best practices:

• Use for communication guidelines, execution loops, tool policies
• Can have multiple guide prompts for different concerns
• Order within this section follows binding order

3. Capability Playbooks

Source: Prompts linked via agent capabilities (capability → promptId)

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

Structure in the prompt:

# Capability Playbooks

## Capability Name

[Capability prompt content]

---

## Another Capability

[Another capability prompt content]

Best practices:

• One prompt per capability
• Name your prompts clearly—the prompt name becomes the section header
• Capabilities are included when the agent has them assigned

4. Checklists

Source: Prompts with useFor containing checklist

Checklists define required steps the agent must complete. Auditors score against these.

Best practices:

• Use for validation steps, review criteria, completion requirements
• Keep checklists actionable and verifiable
• Order within this section follows binding order

Ordering within sections

Ordering within sections is deterministic but not configurable—it is derived from binding order or alphabetical sorting to keep composition simple and predictable.

How ordering works

1. Direct prompt bindings (useFor: system/guide/checklist): Order follows the sequence they were added to the agent
2. Capability prompts: Multi-level ordering (see below)

Capability ordering hierarchy

Capabilities within the Capability Playbooks section are sorted using a three-level hierarchy:

┌─────────────────────────────────────────────────────────┐
│  1. Capability Role                                     │
│     core → workflow → constraints → context →           │
│     validation → integration                            │
├─────────────────────────────────────────────────────────┤
│  2. Backing Prompt Role (tiebreaker)                    │
│     system → guide → checklist → policy → context       │
├─────────────────────────────────────────────────────────┤
│  3. Capability Key (final tiebreaker)                   │
│     Alphabetically by lowercase key                     │
└─────────────────────────────────────────────────────────┘

Level 1: Capability role

Each capability has a role attribute that determines its primary sort position:

Level 2: Backing prompt role

When two capabilities have the same capability role, the system falls back to the role of the backing prompt. Each capability has a 1:1 relationship with a prompt that provides its content.

Prompt roles are sorted: system → guide → checklist → policy → context

Level 3: Capability key

When capabilities share the same capability role AND backing prompt role, they sort alphabetically by their lowercase key.

Example: An agent with these capabilities:

Resulting order:

1. typescript.core — core role (0)
2. valdr.task-runner.checks — workflow role (1), guide prompt, alphabetically first
3. valdr.task-runner.fetch — workflow role (1), guide prompt, alphabetically second
4. review.security — constraints role (2)

Shared prompts are deduplicated

When multiple capabilities link to the same prompt, the prompt appears once under the first capability (by the ordering hierarchy above). This prevents prompt inflation while preserving predictable ordering.

For example, if both review.code (workflow role) and review.security (constraints role) link to the same prompt:

• The prompt appears once, under review.code (workflow comes before constraints)
• review.security does not duplicate the content

Capability key naming convention

Lowercase dot notation is the standard for capability keys in Valdr. Use it to create logical groupings and predictable ordering:

{pack}.{layer}.{specifics}

Examples:

This naming ensures capabilities from the same pack sort together alphabetically.

Forcing explicit order with numeric prefixes

When alphabetical sorting doesn’t give you the order you need, use numeric prefixes:

auditor.base
auditor.01_identity
auditor.02_instructions
auditor.03_guardrails
auditor.04_output_format

This guarantees 01_* comes before 02_*, regardless of the rest of the name. Use this pattern when you need precise control over capability sequence.

Layered domain specialization

For capabilities that extend a base with domain-specific behavior, use hierarchical naming:

auditor.base              ← Foundation (all auditors)
auditor.java.base         ← Java-specific auditing
auditor.java.spring       ← Spring framework specifics
auditor.typescript.base   ← TypeScript-specific auditing
auditor.typescript.react  ← React specifics

Resulting order (alphabetical):

1. auditor.base — foundation for all
2. auditor.java.base — Java layer
3. auditor.java.spring — Java + Spring
4. auditor.typescript.base — TypeScript layer
5. auditor.typescript.react — TypeScript + React

This pattern enables full reuse and extensibility:

• An agent can use just auditor.base for generic auditing
• Add auditor.java.base for Java projects
• Add auditor.java.spring for Spring Boot projects
• Mix and match as needed

Naming anti-patterns

Avoid capability names that undermine predictable ordering:

Consistent, semantic naming is the foundation of predictable prompt composition.

The capability layering model

Capabilities are designed to stack. The naming convention encodes the hierarchy:

┌─────────────────────────────────────────────┐
│  acme.ui.components (specialization)        │  ← Team-specific
├─────────────────────────────────────────────┤
│  typescript.react (domain)                  │  ← Domain patterns
├─────────────────────────────────────────────┤
│  review.code (base)                         │  ← Foundation
└─────────────────────────────────────────────┘

Recommended naming patterns

Why naming matters for ordering

Since capability key is the final tiebreaker when capabilities share the same role:

• auditor.base comes before auditor.schema within the same role
• Pack prefixes group related capabilities together
• Consistent naming creates predictable prompt composition when roles match

Practical examples

Example 1: Auditor agent

An auditor agent with these capabilities (all with workflow capability role):

• auditor.base
• auditor.prompt_integrity
• auditor.schema
• auditor.task_correctness
• auditor.tooling

Resulting capability playbooks section (same role, so alphabetical by key):

# Capability Playbooks

## Auditor Base
[base capability content]

---

## Prompt Integrity
[prompt integrity content]

---

## Schema Validation
[schema content]

---

## Task Correctness
[task correctness content]

---

## Tooling Compliance
[tooling content]

Example 2: TypeScript developer agent with mixed roles

An agent with:

• System prompt: typescript-agent-charter
• Guide prompt: communication-guidelines
• Capabilities with different roles:
  • typescript.core (core role)
  • review.code (workflow role)
  • acme.ui.components (context role)
• Checklist: pr-checklist

Resulting system prompt structure:

# Agent System Charter
[typescript agent charter content]

---

# Guidance
[communication guidelines content]

---

# Capability Playbooks

## TypeScript Core
[typescript core content]

---

## Code Review
[review code content]

---

## ACME UI Components
[acme ui components content]

---

# Checklists
[pr checklist content]

Note: Capabilities are sorted by role—typescript.core (core) before review.code (workflow) before acme.ui.components (context).

Best practices summary

1. Choose the right capability role — role determines primary ordering (core → workflow → constraints → context → validation → integration)
2. Use consistent naming — {pack}.{category}.{specifics} creates predictable ordering within the same role
3. Put foundational content in system prompts — identity, mission, guardrails
4. Use guide prompts for operational patterns — how to communicate, execute, use tools
5. Link capability prompts for domain behaviors — one prompt per capability
6. Reserve checklists for required steps — auditors score against these
7. Name prompts clearly — the name becomes the header in capability playbooks
8. Design capability keys to sort correctly — alphabetical ordering is the final tiebreaker

Debugging prompt composition

To see exactly what prompt an agent will receive:

1. Open the agent in the Valdr UI
2. Navigate to the Overview tab
3. Review the System Prompt Preview section

This shows the fully composed prompt with all sections in their final order.