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:

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

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

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

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

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

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

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

<!--<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)
`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)
`version`	Optional version
`model`	Optional model selector (see Model targeting)

`guideline`

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

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

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

Reuse existing tags — only add new ones if nothing fits; this prevents ecosystem rot
Use version attributes on behavioral tags when making breaking changes
Keep id attributes stable so they can be referenced in tests and scoring
Default content is required — model-specific content is optional
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.

Scoring