# Tag System
### The infrastructure that makes prompts auditable

Raw prompts are opaque. You can't version them reliably, you can't score agent behavior against them, and you can't adapt them to different models without forking. Valdr's tag system solves all three.

Tags are structured metadata embedded in prompts and charters. They're invisible to the model but visible to tooling—enabling automated scoring, hash-based version tracking, and model-specific content selection.

The tag system is **Valdr's governance layer**—it's how agent behavior becomes inspectable, enforceable, and evolvable over time.

> [!TIP]
> Tags turn "a folder of prompts" into governed infrastructure. This is how you answer: "How do we know the AI did what it was supposed to?"

**Who this is for:** This page is for pack authors and advanced users who want to understand how Valdr governs prompts. Most users will only touch a subset of these concepts—the [Tag reference](./tags/) exists for completeness and tooling integration.

## What tags enable

| Capability | Without tags | With tags |
| --- | --- | --- |
| **[Scoring](./scoring/)** | Manual review of transcripts | Automated compliance scoring across seven dimensions |
| **Versioning** | File timestamps, hope for the best | Hash-based drift detection between environments |
| **[Model targeting](./model-targeting/)** | Fork prompts per model | Single pack, model-adaptive behavior |
| **Traceability** | "It's somewhere in the prompt" | Link findings to exact sections with line numbers |
| **Auditability** | Trust the operator | Evidence-backed verdicts with root cause analysis |

## Tag syntax

All tags are embedded in HTML comments—invisible to the model, parseable by tooling:

```markdown
<!--<capability id="auditor.base" pack="valdr" role="core">-->
# Capability Prompt — `auditor.base`

<!--<identity>-->
You are the Agent Session Auditor.
<!--</identity>-->

<!--<instructions>-->
- Validate agent sessions across seven dimensions...
<!--</instructions>-->
<!--</capability>-->
```

Tags support attributes like `id`, `version`, `pack`, `role`, and `model` for fine-grained control.

### Capability roles

The `role` attribute classifies how a capability behaves in prompt composition. Valdr supports six roles, ordered by their position in the final prompt:

| Role | Priority | Purpose |
| --- | --- | --- |
| `core` | 0 | Foundational system-level behavior and identity |
| `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 |

Capabilities are sorted by role priority first, then alphabetically within each role—ensuring predictable prompt composition.

## Three layers of tags

### 1. Charter-level tags

Structure full agent definitions. Used in `agents/*.md` files.

- `charter`, `metadata`, `purpose` — agent identity and mission
- `workflow`, `tooling`, `tool_policy` — how the agent operates
- `success_conditions`, `definition_of_done` — completion criteria

**When you need this:** Required when defining new agents. Every agent charter should use these tags.

### 2. Behavioral fragment tags

Define reusable prompt components. Used in `agents/prompts/**/*.md`.

- `identity`, `instructions` — core behavioral content
- `communication_guidelines`, `execution_loop` — operational patterns
- `safety_and_data`, `tool_usage_policy` — guardrails

**When you need this:** Optional, for reuse. Use these when you want to share behavioral patterns across multiple agents without copy-pasting.

### 3. Capability metadata tags

Bind content to registered capabilities for scoring and versioning.

- `capability` — wrap prompt content for hash-based version tracking
- `guideline`, `checklist` — normative rules and required steps
- `prompt`, `prompt_fragment` — top-level prompts and reusable chunks

**When you need this:** Required for scoring and versioning. If you want auditors to validate behavior or tooling to detect drift, wrap content in these tags.

## Model-specific targeting

Different models need different instructions. Tags support model selectors so you can ship one pack that adapts to Claude, Ollama, GPT, or any other model.

```markdown
<!--<instructions>-->
Base instructions for all models.

<model type="claude-*">
Use extended thinking for complex reasoning.
</model>

<model type="ollama-*">
Break complex tasks into explicit steps.
</model>
<!--</instructions>-->
```

**The business case:** Start with Ollama locally, scale to Claude in production—same pack, no prompt rewrites.

## Learn more

The **[Tag reference](./tags/)** is the canonical list of all supported tags and attributes. If it's not documented there, it's not part of the system.

{{< cards >}}
  {{< card link="./tags/" title="Tag reference (canonical)" subtitle="Full list of charter, behavioral, and capability tags" icon="book-open" >}}
  {{< card link="./scoring/" title="Scoring" subtitle="Multi-dimensional auditing with evidence-backed verdicts" icon="chart-bar" >}}
  {{< card link="./model-targeting/" title="Model targeting" subtitle="Adapt prompts to different models without forking" icon="switch-horizontal" >}}
{{< /cards >}}