# Tag reference
> [!NOTE]
> **This is a canonical reference.** Most users interact with a small subset of tags. This page exists for pack authors, advanced workflows, and tooling integration. See the [Tag system overview](../) for conceptual grounding.

## Why tags exist

Tags make agent behavior **auditable, scorable, and evolvable**:

- **Deterministic scoring** — auditors map behavior to specific rules and checklists
- **Reproducible behavior** — hash content to detect drift between environments
- **Tooling enforcement** — tags are machine-readable, not just documentation

Without tags, prompts are opaque blobs. With tags, every instruction can be traced, versioned, and validated.

---

## Conventions

All tags are embedded in HTML comments:

```markdown
<!--<tag attribute="value">-->
Content here
<!--</tag>-->
```

**Why HTML comments?** This is an intentional design choice:
- Survives Markdown rendering (invisible to readers)
- Invisible to models unless explicitly referenced
- Deterministic for hashing and scoring
- Git-friendly (clean diffs)
- Tooling-friendly (easy to parse)

**Naming rules:**
- Tag names are lowercase with underscores
- Versions are carried via a `version` attribute, not in the tag name
- Attributes use standard `key="value"` syntax

---

## Charter-level tags

Used in agent charters (`agents/*.md`) to structure full agent definitions.

> **Most commonly used:** `charter`, `purpose`, `workflow`, `tooling`, `validation`, `definition_of_done`

### Document structure

| Tag | Purpose | Example attributes |
| --- | --- | --- |
| `charter` | Wraps entire charter document | `name`, `version`, `scope` |
| `metadata` | Charter version, last reviewed, maintainer | — |
| `agentic_preamble` | High-level identity, autonomy, mission | — |
| `purpose` | Core role and goals | — |

**Example:**

```markdown
<!--<charter name="Documentation Author" version="1.0" scope="docs">-->
# Documentation Author Agent

<!--<purpose>-->
Produce authoritative, action-oriented documentation for the TypeScript MCP
ecosystem, covering runbooks, feature guides, and integration references.
<!--</purpose>-->

...

<!--</charter>-->
```

### Inputs and outputs

| Tag | Purpose | Example attributes |
| --- | --- | --- |
| `inputs` | Expected inputs and context sources | — |
| `output_spec` | Required outputs and their shape | — |
| `payload_schema_hint` | Minimal schema hint for structured outputs | — |

### Research and planning

| Tag | Purpose | Example attributes |
| --- | --- | --- |
| `research_loop` | Default research/exploration workflow | — |
| `research_priority` | Precedence rules for sources of truth | — |
| `planning_checklist` | Planning steps before implementation | — |

**Example:**

```markdown
<!--<planning_checklist>-->
1. Confirm scope and audience via PM MCP task
2. Review existing docs for voice and structure
3. Create outline with section headers
4. Gather validation evidence requirements
<!--</planning_checklist>-->
```

### Responsibilities

Container tag `responsibilities` with nested sub-tags:

| Sub-tag | Purpose |
| --- | --- |
| `context_synthesis` | How the agent aggregates domain info |
| `prompt_authoring` | How prompts are written and structured |
| `quality_review` | Quality gates and review behaviors |
| `library_stewardship` | Maintaining prompt libraries and mappings |
| `portfolio_hygiene` | Keeping agents, prompts, capabilities current |

These tags signal that **agents are maintained assets**, not fire-and-forget prompts.

### Operations

> **Most commonly used:** `workflow`, `tooling`, `tool_policy`, `definition_of_done`

| Tag | Purpose | Example attributes |
| --- | --- | --- |
| `workflow` | Step-by-step from intake to completion | — |
| `tooling` | CLI tools, MCP tools, utilities | — |
| `tool_policy` | Allowed/disallowed tool usage | — |
| `success_conditions` | When the task is considered done | — |
| `deliverables` | Artifacts produced | — |
| `validation` | Lint, MCP validation, consistency checks | — |
| `definition_of_done` | Final, user-facing completion criteria | — |

**Example:**

```markdown
<!--<definition_of_done>-->
- Documentation merged with validation evidence linked
- Reviewer feedback addressed
- Templates stored in repo and referenced in guide
<!--</definition_of_done>-->
```

### Registry operations

Container tag `registry` with nested sub-tags:

| Sub-tag | Purpose |
| --- | --- |
| `discover` | How to discover existing agents via MCP |
| `update` | How to update existing agents |
| `register` | How to register new agents |
| `housekeeping` | Ongoing registry hygiene |

### Other charter tags

| Tag | Purpose |
| --- | --- |
| `collaboration` | Coordination with other agents |
| `self_reflection` | Agent self-evaluation |
| `fallback` | Degraded mode guidance |

---

## Behavioral fragment tags

Used in reusable prompt fragments (`agents/prompts/base/*.md`).

> **Most commonly used:** `identity`, `instructions`, `tool_usage_policy`

### Core behavior

| Tag | Purpose | Attributes |
| --- | --- | --- |
| `identity` | Short identity paragraph | — |
| `instructions` | Main behavioral instructions | `model` (optional) |

**Example:**

```markdown
<!--<identity>-->
You are the Agent Session Auditor. Your only job is to produce a valid
audit JSON for the run.
<!--</identity>-->

<!--<instructions>-->
- Mode: `strict` (default)
- Required inputs: transcript, declared + observed prompts/versions
- Dimensions (0–100): instructionsAdherence, promptIntegrity, toolingCompliance...
<!--</instructions>-->
```

### Operational patterns

| Tag | Purpose | Attributes |
| --- | --- | --- |
| `communication_guidelines` | Tone, Markdown usage, when to ask questions | `version` |
| `execution_loop` | Planning/execution loop, modes, stop conditions | `version` |
| `tool_usage_policy` | MCP tool rules, what's canonical/forbidden | `version` |

**Example:**

```markdown
<!--<execution_loop version="1.0">-->
1. Parse task requirements
2. Plan approach (emit outline if complex)
3. Execute steps, updating status after each
4. Validate outputs against acceptance criteria
5. Summarize results and next steps
<!--</execution_loop>-->
```

### Guardrails

| Tag | Purpose | Attributes |
| --- | --- | --- |
| `safety_and_data` | Data handling and secrecy rules | `version` |
| `status_update_spec` | Requirements for progress updates | `version` |
| `summary_spec` | Requirements for final summaries | `version` |

### Examples

| Tag | Purpose | Attributes |
| --- | --- | --- |
| `examples` | Container for example interactions | — |
| `user_query` | Labeled input example | `id` |
| `assistant_response` | Corresponding response example | `id` (matches `user_query`) |

---

## Capability metadata tags

Used in prompt fragments to bind content to registered capabilities.

> **Most commonly used:** `capability`, `guideline`, `checklist`

### `capability`

Wraps a full capability prompt for hashing and version tracking.

```markdown
<!--<capability id="planning.vmp" pack="valdr" role="workflow">-->
# Capability Prompt — `planning.vmp`
...
<!--</capability>-->
```

| Attribute | Purpose | Example |
| --- | --- | --- |
| `id` | Canonical capability identifier | `planning.vmp`, `auditor.base` |
| `pack` | Logical prompt pack or directory | `valdr`, `acme` |
| `role` | Capability role (determines prompt ordering) | `core`, `workflow`, `constraints` |

#### Capability roles

The `role` attribute determines where the capability appears in the composed system prompt. Valdr supports six roles:

| Role | Priority | Purpose | Use for |
| --- | --- | --- | --- |
| `core` | 0 | Foundational system-level behavior | Agent identity, base capabilities, system guardrails |
| `workflow` | 1 | Operational instructions and execution patterns | Step-by-step processes, execution loops, task runners |
| `constraints` | 2 | Rules, policies, and behavioral boundaries | Tool policies, security rules, compliance requirements |
| `context` | 3 | Background information and domain knowledge | Domain definitions, reference material, terminology |
| `validation` | 4 | Verification steps and completion criteria | Checklists, acceptance criteria, quality gates |
| `integration` | 5 | External system interfaces and API behaviors | MCP tool usage, API patterns, external service interactions |

Capabilities are sorted by role priority first, then alphabetically by key within each role.

> [!WARNING]
> **Deprecated roles:** The following legacy role values are deprecated and will be removed in a future release:
>
> | Deprecated Role | Migration Target | Notes |
> | --- | --- | --- |
> | `base` | `core` | Use `core` for foundational capabilities |
> | `system` | `core` | Use `core` for system-level behavior |
> | `guide` | `workflow` | Use `workflow` for operational instructions |
> | `policy` | `constraints` | Use `constraints` for rules and boundaries |
> | `checklist` | `validation` | Use `validation` for verification steps |
> | `specialization` | `context` or `integration` | Choose based on purpose |
>
> Update existing capabilities to use the new role enum values.

**Scoring note:** Canonical version is derived by hashing content inside the block. Map `(id, hash)` to semantic version externally. This avoids "v1-final-final" drift.

### `prompt`

Wraps a top-level prompt registered in MCP.

```markdown
<!--<prompt id="typescript.agent.guide" pack="valdr" role="workflow" version="1.1">-->
...
<!--</prompt>-->
```

| Attribute | Purpose |
| --- | --- |
| `id` | Canonical prompt identifier |
| `pack` | Workspace/focus area (e.g., `valdr`, team name) |
| `role` | Capability role (see [Capability roles](#capability-roles)) |
| `version` | Optional version number |

### `prompt_fragment`

Wraps reusable chunks when you need fragment-level hashing without a standalone capability.

| Attribute | Purpose |
| --- | --- |
| `id` | Fragment identifier |
| `pack` | Logical grouping (e.g., `valdr`, team name) |
| `role` | Capability role (see [Capability roles](#capability-roles)) |
| `version` | Optional version |
| `model` | Optional model selector (see [Model targeting](../model-targeting/)) |

### `guideline`

Wraps normative guidance blocks for scoring. Auditors use the `type` attribute to map findings to specific rule categories.

```markdown
<!--<guideline type="testing" id="unit-test-coverage" pack="valdr">-->
All new functions require unit tests with ≥80% coverage.
<!--</guideline>-->
```

| Attribute | Purpose | Examples |
| --- | --- | --- |
| `type` | Guideline category | `testing`, `security`, `observability`, `performance` |
| `id` | Optional identifier | — |
| `pack` | Logical grouping | — |
| `version` | Optional version | — |

### `checklist`

Wraps actionable checklists agents must follow. Auditors score against these—missing items become findings.

```markdown
<!--<checklist type="pull-request" id="pr-checklist" pack="valdr">-->
- [ ] Tests pass
- [ ] No lint errors
- [ ] Docs updated
<!--</checklist>-->
```

| Attribute | Purpose | Examples |
| --- | --- | --- |
| `type` | Checklist category | `pull-request`, `release`, `validation` |
| `id` | Optional identifier | — |
| `pack` | Logical grouping | — |
| `version` | Optional version | — |

---

## Authoring guidelines

1. **Reuse existing tags** — only add new ones if nothing fits; this prevents ecosystem rot
2. **Use `version` attributes** on behavioral tags when making breaking changes
3. **Keep `id` attributes stable** so they can be referenced in tests and scoring
4. **Default content is required** — model-specific content is optional
5. **Tags are case-sensitive** — use lowercase with underscores

When adding a new tag, document it here with a short description before using it in prompts.