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

| Spec | Defines | Key rules |
|------|---------|-----------|
| **PACK-SPEC** | `pack.yaml` manifest format | `schemaVersion`, `includes`, discovery rules |
| **AGENT-SPEC** | `.agent.yaml` agent definitions | Handle, kind, capabilities, prompts, roles |
| **PROMPT-SPEC** | Markdown annotation format | `<!--<capability>-->` and `<!--<prompt>-->` tags |

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

```bash
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:

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

```yaml
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:**
```markdown
<!--<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:**
```markdown
<!--<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:

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

Or, for a repo-local pack:

```bash
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:

```bash
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:

```bash
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