# 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**.

> [!NOTE]
> **Most users never need this.** If you're using one prompt or a small set of capabilities, Valdr's defaults handle ordering automatically. This page is for advanced scenarios where you need precise control.

## 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.

> [!NOTE]
> **Design intent:** Prompt ordering in Valdr favors predictability over configurability. Simple rules (fixed sections + naming-based sorting) make agent behavior easier to reason about and debug at scale.

### 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.

> [!TIP]
> Ordering affects how instructions are presented to the model, not the sequence of tool calls or task execution. Playbooks are instruction blocks, not execution steps.

**Structure in the prompt:**
```markdown
# 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:

| Role | Priority | Purpose |
| --- | --- | --- |
| `core` | 0 | Foundational system-level behavior |
| `workflow` | 1 | Operational instructions and execution patterns |
| `constraints` | 2 | Rules, policies, and behavioral boundaries |
| `context` | 3 | Background information and domain knowledge |
| `validation` | 4 | Verification steps and completion criteria |
| `integration` | 5 | External system interfaces and API behaviors |

#### 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:

| Capability | Capability Role | Backing Prompt Role |
| --- | --- | --- |
| `typescript.core` | core | system |
| `valdr.task-runner.fetch` | workflow | guide |
| `valdr.task-runner.checks` | workflow | guide |
| `review.security` | constraints | policy |

**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:**
| Capability Key | Pack | Purpose |
|----------------|------|---------|
| `auditor.base` | auditor | Base auditor behavior |
| `auditor.prompt_integrity` | auditor | Prompt integrity checking |
| `auditor.schema` | auditor | Schema validation |
| `auditor.task_correctness` | auditor | Task correctness evaluation |
| `auditor.tooling` | auditor | Tooling compliance |

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.

> [!NOTE]
> Numeric prefixes affect presentation order only—they do not imply priority, severity, or execution order.

### 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

> [!TIP]
> The layering model means you build once, specialize many times. A well-designed `*.base` capability becomes the foundation for an entire family of domain-specific extensions.

### Naming anti-patterns

Avoid capability names that undermine predictable ordering:

| Avoid | Why | Better |
|-------|-----|--------|
| `capabilityA`, `capabilityB` | No semantic meaning, fragile ordering | `review.style`, `review.security` |
| `misc.rules`, `other.stuff` | Vague, ungrouped | `typescript.linting`, `typescript.testing` |
| `my-capability` | Hyphens break the standard; sort differently | `my.capability` |
| `AUDITOR.Base` | Case affects sorting | `auditor.base` (lowercase) |

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

| Layer | Pattern | Example |
|-------|---------|---------|
| Base | `{domain}.base` | `auditor.base`, `review.base` |
| Domain | `{domain}.{focus}` | `typescript.react`, `backend.api` |
| Specialization | `{team}.{domain}.{focus}` | `acme.ui.components` |

### 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):**
```markdown
# 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:**
```markdown
# 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.

> [!TIP]
> If behavior looks wrong, check capability roles and names—ordering issues are usually due to incorrect roles or naming conventions. Remember: capabilities sort by role first, then by backing prompt role, then alphabetically by key.