# Overview
## What is a Valdr pack?

A Valdr pack is a **portable, self-describing bundle** of agents, prompts, and capabilities. Packs use structured YAML manifests and annotated Markdown so that everything — agent identities, capability bindings, prompt content — can be discovered, validated, and imported automatically.

Packs are the distribution unit for agent workflows. Import one and you get a complete roster of agents with their capabilities, prompts, and orchestration wiring — ready to work.

## Recommended source directories

When you author or customize a pack, keep the unpacked source directory in one of these locations:

- `~/.valdr/valdr-packs/<pack-name>` for user-wide packs you want available across machines or workspaces
- `./.valdr/valdr-packs/<pack-name>` for repo-local packs that should travel with the current codebase

Nikol defaults to checking those locations when helping you find, validate, and generate packs, so putting source packs there avoids extra path wrangling.

## Pack structure

A pack is a directory with a `pack.yaml` manifest at the root:

```yaml
schemaVersion: 1.0
pack: my-team
name: My Team Pack
version: 0.1.0
description: Team-specific agents and capabilities
includes:
  - path: agents
    description: Team agents and role-specific capabilities
  - path: shared
    description: Shared prompts and reusable capability fragments
```

The `includes` field tells tooling which directories to scan for agents, prompts, and capabilities. Discovery is automatic — you don't enumerate every entity in the manifest.

### What's inside

| Layer | Format | Discovery |
|-------|--------|-----------|
| **Pack manifest** | `pack.yaml` | Root of each pack |
| **Agent definitions** | `.agent.yaml` | Inside agent directories |
| **Capabilities** | Annotated Markdown | `<!--<capability>-->` tags |
| **Prompts** | Annotated Markdown | `<!--<prompt>-->` tags |

## Agent definitions

Every agent in a pack has an `.agent.yaml` file that declares its identity, role, and capability bindings:

```yaml
schemaVersion: 1.0
agent:
  handle: sigrid
  name: Sigrid Reviewer
  kind: bot
  defaultRole: reviewer
capabilities:
  - key: valdr.reviewer.sigrid.system
    role: core
  - key: valdr.reviewer.sigrid.workflow
    role: workflow
    hot-load: true
  - key: valdr.reviewer.sigrid.severity
    role: constraints
    hot-load: true
prompts:
  - key: valdr-reviewer-guide
    role: guide
    hot-load: true
```

### Agent kinds

| Kind | Use case |
|------|----------|
| `bot` | AI agents and automations |
| `ci` | CI/CD pipeline integrations |
| `human` | Human operators and reviewers |

### Capability roles

| Role | Purpose | Loading |
|------|---------|---------|
| `core` | Foundational agent identity — exactly one required | Always loaded |
| `workflow` | Execution patterns and procedures | Often hot-loaded |
| `constraints` | Guardrails and limitations | Often hot-loaded |
| `context` | Background information | Often hot-loaded |
| `validation` | Quality checks and gates | Often hot-loaded |
| `integration` | External system connections | Often hot-loaded |

## Prompt and capability format

Prompts and capabilities are Markdown files with HTML comment annotations for machine-readable metadata:

**Capability:**
```markdown
<!--<capability id="valdr.reviewer.sigrid.system" pack="valdr" role="core">-->
# Sigrid Code Reviewer

You are Sigrid, a structured code review specialist...
<!--</capability>-->
```

**Prompt:**
```markdown
<!--<prompt key="valdr-reviewer-guide" pack="valdr" role="guide" tags="review,quality">-->
# Code Review Guidelines

When reviewing code, evaluate...
<!--</prompt>-->
```

Annotations include:
- `id` / `key` — Canonical identifier (lowercase, dashed)
- `pack` — Logical pack grouping
- `role` — Purpose classification
- `tags` — Comma-separated metadata (canonicalized to lowercase, unique, sorted)

## Hot-loading

Agents start with a compact system prompt (their `core` capability), then load detailed capabilities on demand:

```
pm_capability { action: "prompt", key: "valdr.reviewer.sigrid.workflow" }
→ Returns full workflow capability content
```

This keeps initial context small while preserving access to complete documentation. The `hot-load: true` flag in `.agent.yaml` signals that a capability should be loaded this way.

## Validate and generate archives

Treat the source pack directory as the canonical authoring location, then use the Valdr CLI to validate it and build the archive you import:

```bash
valdr validate-pack "$HOME/.valdr/valdr-packs/my-team"
valdr generate-valdr-pack "$HOME/.valdr/valdr-packs/my-team" \
  --output "$PWD/dist/packages/my-team.valdr-pack.tar.gz"
```

For repo-local packs, use the workspace path instead:

```bash
valdr validate-pack "$PWD/.valdr/valdr-packs/my-team"
valdr generate-valdr-pack "$PWD/.valdr/valdr-packs/my-team" \
  --output "$PWD/dist/packages/my-team.valdr-pack.tar.gz"
```

Validation checks the source directory structure, manifests, and capability references before you generate the archive. Generation produces the `.valdr-pack.tar.gz` bundle that the UI imports.

## Importing packs

Packs are imported through the Valdr UI via **Settings > Packs**:

1. Validate the source pack directory
2. Generate a `.valdr-pack.tar.gz` archive from that source directory
3. Upload the archive in the Import Valdr Pack dialog
4. Review the preflight action plan — see which entities will be created, overwritten, or skipped
5. Commit the import

{{< thumbcard src="/images/ui/valdr-packs/pack-import.png" alt="Import Valdr Pack dialog showing preflight action plan" caption="The import dialog shows a preflight action plan before committing changes to your workspace." >}}

The preflight plan shows every entity in the pack with its status:
- **Create** — New entity that doesn't exist yet
- **Overwrite** — Existing entity that will be updated
- **Unchanged** — Entity already matches, no action needed
- **Skip** — Conflict resolution chose to skip

No surprises. You see exactly what will change before it happens.

## What changes when you use packs

| Without packs | With packs |
|---------------|------------|
| Onboard agents manually, one by one | Import a pack, get a complete roster |
| "It worked on my machine" | Same behavior in dev, staging, and production |
| Prompt sprawl across files and configs | Structured, discoverable, versioned |
| Scaling means copy-paste and hope | Scaling means importing the same governed pack |
| No audit trail for agent configuration | Every capability and prompt version-tracked |

## Multi-platform support

Packs are authored once and deployed across platforms:

| Platform | Output format | Directory |
|----------|--------------|-----------|
| **Claude Code** | Markdown commands | `claude/commands/` |
| **Codex CLI** | Prompt files | `codex/prompts/` |
| **Gemini CLI** | TOML commands | `gemini/commands/` |
| **Cursor** | Markdown commands | `cursor/commands/` |

Build targets generate platform-specific output from the canonical source files in `commands/` and `skills/`.

## The cost of not using packs

| Stage | What happens | Impact |
|-------|-------------|--------|
| Week 1 | Prompts work in dev, break in prod | Delayed launches |
| Month 2 | Each team writes their own agent prompts | Duplicated effort, inconsistent outputs |
| Month 6 | No one remembers why an agent behaves a certain way | Compliance risk |
| Year 1 | Prompt sprawl makes changes terrifying | Innovation stalls |

Packs short-circuit this trajectory. You inherit battle-tested structure from day one.