Authoring workflow

Follow this workflow to build or update a Valdr pack. Packs use structured specs so that authoring is consistent and validation is automatic.

The specs

Three specification documents define the pack format. Reference these when authoring:

0) Choose the source directory

Store the unpacked source pack in one of the locations Nikol checks by default:

• ~/.valdr/valdr-packs/<pack-name> for a user-wide pack library
• ./.valdr/valdr-packs/<pack-name> for a pack that belongs to the current repo

Examples:

mkdir -p "$HOME/.valdr/valdr-packs/my-team"
mkdir -p "$PWD/.valdr/valdr-packs/my-team"

Use one of those directories as the pack root in the remaining steps.

1) Create the pack manifest

Start with a pack.yaml at your pack root:

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
  - path: shared
    description: Shared capabilities and prompts

The includes field tells tooling which directories to scan. Only included paths are discovered — nothing else in the pack root is imported automatically.

2) Define agents

Create an .agent.yaml for each agent:

schemaVersion: 1.0
agent:
  handle: my-reviewer
  name: My Team Reviewer
  kind: bot
  defaultRole: reviewer
capabilities:
  - key: myteam.reviewer.system
    role: core
  - key: myteam.reviewer.workflow
    role: workflow
    hot-load: true
prompts:
  - key: myteam-review-guide
    role: guide
    hot-load: true

Rules:

• Exactly one capability with role: core is required
• handle must be unique across your workspace
• kind must be bot, ci, or human
• hot-load: true capabilities are loaded on demand, keeping initial context small

3) Author capabilities and prompts

Write Markdown files with HTML comment annotations:

Capability:

<!--<capability id="myteam.reviewer.system" pack="my-team" role="core">-->
# My Team Reviewer

You are a code reviewer for the My Team codebase. You follow our
team conventions and review standards.

## Responsibilities
- Review code changes against acceptance criteria
- Flag violations of team conventions
- Score work quality

## Tools
- `pm_task` — Fetch task details
- `pm_review` — Submit review feedback
<!--</capability>-->

Prompt:

<!--<prompt key="myteam-review-guide" pack="my-team" role="guide" tags="review,quality,conventions">-->
# Review Guidelines

## Code style
- Follow ESLint config in repo root
- Prefer composition over inheritance
- All public functions need JSDoc

## Testing requirements
- Unit tests for business logic
- Integration tests for API endpoints
<!--</prompt>-->

Naming conventions:

{pack}.{domain}.{agent}.{capability-name}

Examples:

• myteam.reviewer.system — Core identity
• myteam.reviewer.workflow — Review execution flow
• myteam.core.tools.pm-task — Tool documentation

4) Organize the directory

my-team-pack/
├── pack.yaml
├── agents/
│   └── reviewer/
│       ├── my-reviewer.agent.yaml
│       ├── myteam.reviewer.system.md
│       └── myteam.reviewer.workflow.md
└── shared/
    └── prompts/
        └── myteam-review-guide.md

Place agent YAML and capability Markdown in the same directory. Shared prompts go in a common location.

5) Validate the source pack

Run validation against the source pack directory before you build the archive:

valdr validate-pack "$HOME/.valdr/valdr-packs/my-team"

Or, for a repo-local pack:

valdr validate-pack "$PWD/.valdr/valdr-packs/my-team"

Validation checks that:

• pack.yaml has schemaVersion: 1.0 and valid includes
• Every agent has exactly one role: core capability
• Capability IDs referenced in .agent.yaml match actual <!--<capability>--> annotations
• Prompt keys referenced in .agent.yaml match actual <!--<prompt>--> annotations
• Tags are lowercase, comma-separated, and deduplicated
• No obvious manifest wiring errors exist before import

6) Generate the archive

Build the importable archive from the same source directory:

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

Or, for a repo-local pack:

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

The generated .valdr-pack.tar.gz archive is the file you import through the UI.

7) Import via UI

Import your pack through Settings > Packs in the Valdr UI:

1. Validate the source pack directory
2. Generate the .valdr-pack.tar.gz archive
3. Upload the archive in the Import dialog
4. Review the preflight action plan — every entity shows its status (create, overwrite, unchanged, skip)
5. Resolve conflicts if entities already exist — choose to overwrite or skip per entity
6. Commit the import

The import is atomic — either everything succeeds or nothing changes.

8) Verify

After import, confirm your entities are visible:

• Agents — Check the Agents page in the UI or run pm_agent list
• Capabilities — Check Capabilities page or run pm_capability list
• Prompts — Check Prompts page or run pm_prompt list

Updating an existing pack

When you need to update agents or capabilities:

1. Edit the source Markdown and YAML files in ~/.valdr/valdr-packs/<pack-name> or ./.valdr/valdr-packs/<pack-name>
2. Re-run valdr validate-pack <pack-dir>
3. Re-run valdr generate-valdr-pack <pack-dir> --output <archive>
4. Re-import the archive

The preflight plan shows which entities changed — overwrite only what’s updated.

The content hash comparison means unchanged entities are automatically skipped.

Tips

• Prefer the default source directories — Nikol already knows to look in ~/.valdr/valdr-packs and ./.valdr/valdr-packs
• Keep capabilities focused — one capability per domain, not one giant file
• Use hot-loading — mark non-core capabilities as hot-load: true to keep context lean
• Version your pack — update the version field in pack.yaml when making changes
• Validate before generating — catch wiring issues before you build and import the archive
• Reuse shared prompts — extract common patterns into shared prompts that multiple agents reference