# Starter agents
Starter agents are examples you can actually use. They are not meant to be a perfect fit for every codebase on day one; they are pack-ready agent shapes that show how Valdr turns a role, a handle, a core system capability, and hot-loaded domain guidance into runnable behavior.

Use them in two ways:

- Run them as built-in executors or reviewers when the default behavior matches the task.
- Copy the pattern when you want to build a team-specific Java, Go, security, CI/CD, infrastructure, or documentation agent.

> [!TIP]
> Treat starter agents like project templates. Keep the structure, then replace generic capability guidance with your repository conventions, build commands, review gates, and operational standards.

## What ships as starter agents

The Valdr Vanguard pack includes language-focused task agents and utility agents that demonstrate the most common extension points.

| Agent | Handle | Default role | Use when |
|-------|--------|--------------|----------|
| **Java Task Agent** | `java-task-agent` | `executor` | Java 17+, Maven/Gradle, package design, JUnit validation |
| **Go Task Agent** | `go-task-agent` | `executor` | Go modules, idiomatic package boundaries, error handling, table tests |
| **Python Task Agent** | `python-task-agent` | `executor` | Python typing, package tooling, pytest validation |
| **Rust Task Agent** | `rust-task-agent` | `executor` | Cargo workspaces, ownership, traits, property-oriented testing |
| **CI/CD Pipeline Agent** | `cicd-agent` | `executor` | GitHub Actions, deployment workflows, quality gates |
| **Infrastructure-as-Code Agent** | `infra-agent` | `executor` | Terraform/OpenTofu, containers, cloud, networking, observability |
| **Security Audit Agent** | `security-audit-agent` | `reviewer` | Vulnerability review, dependency audit, secrets checks, control-alignment notes |
| **Refactoring Scout** | `refactor-scout` | `planner` | Code health discovery and refactoring task shaping |
| **Hugo Documentation Steward** | `hugo-docs-agent` | `planner` | Docs drift audits, source-truth checks, screenshot and shortcode upkeep |
| **Dependency Audit Scout** | `dependency-audit-scout` | `planner` | Multi-ecosystem dependency reachability, unused dependency, and upgrade planning |

## How starter agents are built

Every starter agent follows the same pack pattern:

1. A stable `.agent.yaml` file declares the handle, name, kind, default role, tags, and capability bindings.
2. Exactly one `role: core` capability defines the agent identity and baseline workflow.
3. Domain capabilities attach deeper guidance as `constraints`, `workflow`, `validation`, `context`, or `integration`.
4. Most domain capabilities are `hot-load: true`, so the agent starts lean and loads deeper instructions only when the task needs them.
5. The same agent can be reused across workspaces because its behavior is source-controlled pack content.

That structure is the important part. The built-in Java and Go agents both use four hot-loaded domain capabilities (`build`, `code.rules`, `design.solid`, and `testing`). The Security Audit Agent uses scanning and policy capabilities (`vulnerability-patterns`, `dependency-audit`, `secrets-detection`, and `compliance`). Your own agents can use the same model with names and capabilities that match your stack.

## When to use starter agents

Use a starter agent when the task already has a clear implementation or review target:

- `/valdr-agent java-task-agent implement this JVM bug fix and run the affected Maven tests.`
- `/valdr-agent go-task-agent implement the module boundary cleanup and run package tests.`
- `/valdr-agent security-audit-agent review this auth change for exploitable paths.`

Do not use starter agents as general command centers. For navigation and task creation, start with [Gunnar](../starter-packs/gunnar/). For pack design, use [Nikol](../starter-packs/nikol/). For sprint staffing and launch readiness, use [Skadi](../starter-packs/skadi/).

## Starter agent docs

{{< cards >}}
  {{< card link="./java/" title="Java task agent" subtitle="Maven/Gradle, Java 17+, package design, and JUnit validation" icon="code" >}}
  {{< card link="./go/" title="Go task agent" subtitle="Go modules, package boundaries, explicit errors, and table tests" icon="terminal" >}}
  {{< card link="./security/" title="Security audit agent" subtitle="Evidence-backed vulnerability, dependency, secrets, and policy review" icon="shield-check" >}}
  {{< card link="./build-your-own/" title="Build your own" subtitle="Copy the starter pattern for your own stack, role, and team rules" icon="sparkles" >}}
{{< /cards >}}

Start with one of the examples, then adapt the structure in [Build your own](./build-your-own/) when your codebase needs stricter conventions than the generic starter pack can safely assume.