Valdr Packs
Valdr Packs
{"content":"### Ship agent workflows you can trust — in days, not weeks\n\nAd-hoc prompts crumble once you have more than a couple agents: reviews conflict, instructions drift, and no one remembers why decisions were made. Valdr packs give you a **portable, governed unit** of agent behavior - agents, prompts, capabilities, and context - so you can reuse, share, and evolve workflows without starting over.\n\n\u003e [!TIP]\n\u003e Repeatable + auditable: treat agents like productized infrastructure, not improvisation.\n\n\u003e [!NOTE]\n\u003e Recommended source locations for pack authoring are `~/.valdr/valdr-packs/\u003cpack-name\u003e` for user-wide packs or `./.valdr/valdr-packs/\u003cpack-name\u003e` for repo-local packs. Nikol defaults to checking those directories when helping you discover, validate, or generate packs.\n\nValdr packs are portable bundles defined by YAML manifests, workflow YAML, and annotated Markdown. A `pack.yaml` declares the pack, `.agent.yaml` files define each agent, `.workflow.yaml` files define durable processes, and `\u003c!--\u003ccapability\u003e--\u003e` annotations make instructions machine-discoverable.\n\n### What's inside a pack\n\n| Layer | Format | Purpose |\n|-------|--------|---------|\n| **Pack manifest** | `pack.yaml` | Pack identity, version, included directories |\n| **Agent definitions** | `.agent.yaml` | Agent identity, kind, capability bindings |\n| **Capabilities** | Annotated Markdown | Structured agent behavior with role-based loading |\n| **Prompts** | Annotated Markdown | Reusable instructions with tags and metadata |\n| **Workflows** | `.workflow.yaml` | Versioned processes with inputs, steps, and declared results |\n\n### Why not \"just prompts\"?\n\n| Just prompts | Valdr packs |\n|--------------|-------------|\n| Hard to reuse | YAML specs make packs portable and importable |\n| No governance | Capabilities and permissions are explicit |\n| Drift over time | Content-hash comparison detects changes |\n| People-dependent | System-enforced structure |\n| \"Trust me, it worked\" | Multi-dimensional scoring with evidence |\n| Fine for demos | Built for real systems |\n\n### Who this is for\n\n- **Engineering leads** tired of agents that work in dev but break in prod\n- **Platform teams** distributing governed AI capabilities across the org\n- **Compliance-conscious orgs** that need auditable decision trails\n- **Teams scaling past 3 agents** who've felt the pain of prompt sprawl\n\nIf you're experimenting with a single agent, you may not need packs yet. But once you've said \"we need this to work the same way every time\" — you're ready.\n\n### Official Valdr packs\n\nThe core pack supplies Gunnar, Mimir, Nikol, Skadi, specialists, task agents, capabilities, and prompts. The separately released Workflow pack adds Verdandi, workflow-owned agents, and durable workflow definitions. Start with [Official orchestrators](./what-comes-with-valdr/starter-packs/) to choose the right entry point.\n\nUse this section to:\n\n- Understand why packs exist and when they become worth it\n- See the starter agents Valdr ships and how to adapt them for your own stack\n- Learn how pack source directories, manifests, generated archives, and imports fit together\n- Understand how `.agent.yaml` files bind agents to capabilities and prompts\n- Learn the tag system for scoring, versioning, and model targeting\n- Build team-specific capabilities that encode your institutional knowledge\n- Validate and generate archives from the source pack directories Nikol already knows how to find\n- Author or adapt packs with the authoring workflow\n- Import packs through the Valdr UI\n\n{{\u003c cards \u003e}}\n {{\u003c card link=\"./overview/\" title=\"Overview\" subtitle=\"Why packs exist, what changes when behavior is portable, and where to go next\" icon=\"eye\" \u003e}}\n {{\u003c card link=\"./what-comes-with-valdr/starter-packs/\" title=\"Official orchestrators\" subtitle=\"Gunnar, Mimir, Nikol, Skadi, and Verdandi for PM, knowledge, registry, sprint, and workflow control\" icon=\"map\" \u003e}}\n {{\u003c card link=\"./what-comes-with-valdr/included-agents/\" title=\"Built-in specialist agents\" subtitle=\"Freya, Sigrid, and Tyr for planning, review, and audit\" icon=\"clipboard-check\" \u003e}}\n {{\u003c card link=\"./what-comes-with-valdr/starter-agents/\" title=\"Starter agents\" subtitle=\"Java, Go, Security, CI/CD, infrastructure, docs, and audit starters\" icon=\"terminal\" \u003e}}\n {{\u003c card link=\"./what-comes-with-valdr/team-capabilities/\" title=\"Team capabilities\" subtitle=\"Encode your codebase conventions and tribal knowledge\" icon=\"user-group\" \u003e}}\n {{\u003c card link=\"./how-packs-work/pack-structure/\" title=\"Pack structure\" subtitle=\"Source directories, manifests, generated archives, and import preflight\" icon=\"cube\" \u003e}}\n {{\u003c card link=\"./how-packs-work/agent-definitions/\" title=\"Agent definitions\" subtitle=\"How .agent.yaml files declare runnable agents and bindings\" icon=\"user\" \u003e}}\n {{\u003c card link=\"./how-packs-work/capabilities-and-prompts/\" title=\"Capabilities and prompts\" subtitle=\"How annotated Markdown becomes reusable agent behavior\" icon=\"speakerphone\" \u003e}}\n {{\u003c card link=\"./building-your-own/workflow/\" title=\"Authoring workflow\" subtitle=\"Build, validate, generate, and import packs\" icon=\"adjustments\" \u003e}}\n {{\u003c card link=\"./building-your-own/prompt-ordering/\" title=\"Prompt ordering\" subtitle=\"How system prompts are composed from capabilities\" icon=\"clipboard-list\" \u003e}}\n {{\u003c card link=\"./advanced-reference/tag-system/\" title=\"Tag system\" subtitle=\"Scoring, versioning, and model targeting\" icon=\"tag\" \u003e}}\n{{\u003c /cards \u003e}}\n\n## Product view\n\nFor the platform-level story behind packs and capabilities, read [Team Capabilities for AI Agents](/valdr/docs/features/team-capabilities/). It explains how packs turn repeated team instructions into reusable operational behavior for agents.","description":"Portable bundles of agents, capabilities, prompts, and workflows that make behavior reusable, reviewable, and importable.","title":"Valdr Packs"}
Ship agent workflows you can trust — in days, not weeks
Ad-hoc prompts crumble once you have more than a couple agents: reviews conflict, instructions drift, and no one remembers why decisions were made. Valdr packs give you a portable, governed unit of agent behavior - agents, prompts, capabilities, and context - so you can reuse, share, and evolve workflows without starting over.
Tip
Repeatable + auditable: treat agents like productized infrastructure, not improvisation.
Note
Recommended source locations for pack authoring are ~/.valdr/valdr-packs/<pack-name> for user-wide packs or ./.valdr/valdr-packs/<pack-name> for repo-local packs. Nikol defaults to checking those directories when helping you discover, validate, or generate packs.
Valdr packs are portable bundles defined by YAML manifests, workflow YAML, and annotated Markdown. A pack.yaml declares the pack, .agent.yaml files define each agent, .workflow.yaml files define durable processes, and <!--<capability>--> annotations make instructions machine-discoverable.
What’s inside a pack
| Layer | Format | Purpose |
|---|---|---|
| Pack manifest | pack.yaml | Pack identity, version, included directories |
| Agent definitions | .agent.yaml | Agent identity, kind, capability bindings |
| Capabilities | Annotated Markdown | Structured agent behavior with role-based loading |
| Prompts | Annotated Markdown | Reusable instructions with tags and metadata |
| Workflows | .workflow.yaml | Versioned processes with inputs, steps, and declared results |
Why not “just prompts”?
| Just prompts | Valdr packs |
|---|---|
| Hard to reuse | YAML specs make packs portable and importable |
| No governance | Capabilities and permissions are explicit |
| Drift over time | Content-hash comparison detects changes |
| People-dependent | System-enforced structure |
| “Trust me, it worked” | Multi-dimensional scoring with evidence |
| Fine for demos | Built for real systems |
Who this is for
- Engineering leads tired of agents that work in dev but break in prod
- Platform teams distributing governed AI capabilities across the org
- Compliance-conscious orgs that need auditable decision trails
- Teams scaling past 3 agents who’ve felt the pain of prompt sprawl
If you’re experimenting with a single agent, you may not need packs yet. But once you’ve said “we need this to work the same way every time” — you’re ready.
Official Valdr packs
The core pack supplies Gunnar, Mimir, Nikol, Skadi, specialists, task agents, capabilities, and prompts. The separately released Workflow pack adds Verdandi, workflow-owned agents, and durable workflow definitions. Start with Official orchestrators to choose the right entry point.
Use this section to:
- Understand why packs exist and when they become worth it
- See the starter agents Valdr ships and how to adapt them for your own stack
- Learn how pack source directories, manifests, generated archives, and imports fit together
- Understand how
.agent.yamlfiles bind agents to capabilities and prompts - Learn the tag system for scoring, versioning, and model targeting
- Build team-specific capabilities that encode your institutional knowledge
- Validate and generate archives from the source pack directories Nikol already knows how to find
- Author or adapt packs with the authoring workflow
- Import packs through the Valdr UI
Why packs exist, what changes when behavior is portable, and where to go next
Gunnar, Mimir, Nikol, Skadi, and Verdandi for PM, knowledge, registry, sprint, and workflow control
Freya, Sigrid, and Tyr for planning, review, and audit
Java, Go, Security, CI/CD, infrastructure, docs, and audit starters
Encode your codebase conventions and tribal knowledge
Source directories, manifests, generated archives, and import preflight
How .agent.yaml files declare runnable agents and bindings
How annotated Markdown becomes reusable agent behavior
Build, validate, generate, and import packs
How system prompts are composed from capabilities
Scoring, versioning, and model targeting
Product view
For the platform-level story behind packs and capabilities, read Team Capabilities for AI Agents. It explains how packs turn repeated team instructions into reusable operational behavior for agents.