# Build your own starter agent
Starter agents are most valuable when you copy the shape and replace the generic guidance with your own operating rules. A good starter agent is small at launch, specific about its role, and able to hot-load deeper instructions only when needed.

Use this page when you want to build an agent like `java-task-agent`, `go-task-agent`, or `security-audit-agent`, but tuned to your codebase.

## The starter-agent pattern

Every starter agent needs four things:

| Piece | Purpose |
|-------|---------|
| Stable handle | The name a user passes after `/valdr-agent`, or that Skadi/Gunnar can assign work to |
| Default role | The workflow lane: `executor`, `reviewer`, or `planner` |
| Core capability | Identity, mission, boundaries, and baseline workflow |
| Hot-loaded capabilities | Detailed rules for build, testing, architecture, security, or integration concerns |

The structure should answer three questions quickly:

1. What kind of work should this agent own?
2. What should it never do?
3. Which deeper capabilities should it load for specific situations?

## Start with the `.agent.yaml`

Create a source directory in your pack:

```text
my-team-pack/
`-- agents/
    `-- payments-java/
        |-- payments-java-agent.agent.yaml
        |-- acme.agents.payments-java.system.md
        |-- acme.agents.payments-java.build.md
        |-- acme.agents.payments-java.persistence.md
        `-- acme.agents.payments-java.testing.md
```

Then define the agent:

```yaml
schemaVersion: 1.0
agent:
  handle: payments-java-agent
  name: Payments Java Agent
  kind: bot
  defaultRole: executor
  tags:
    - java
    - payments
    - task-agent
capabilities:
  - key: acme.agents.payments-java.system
    role: core
  - key: acme.agents.payments-java.build
    role: constraints
    hot-load: true
  - key: acme.agents.payments-java.persistence
    role: workflow
    hot-load: true
  - key: acme.agents.payments-java.testing
    role: validation
    hot-load: true
```

Keep the core capability lean. Put deep framework, persistence, security, and testing details into hot-loaded capabilities so routine tasks do not pay for every rule up front.

## Write the core capability

The core capability should define identity and boundaries, not every technical rule:

```markdown
<!--<capability id="acme.agents.payments-java.system" pack="acme" role="core">-->
# Payments Java Agent

You are a task execution agent for the Payments service.

## Mission
- Implement scoped Java changes in the Payments codebase.
- Preserve public API contracts unless the task explicitly authorizes a change.
- Validate with the affected Maven modules and focused tests.

## Boundaries
- Do not create new work items; ask Gunnar or Freya to shape unclear work.
- Do not approve your own work; send reviewable output to Sigrid or the assigned reviewer.
- Do not change payment data semantics without explicit acceptance criteria.

## Hot-load when needed
- `acme.agents.payments-java.build` for Maven module and dependency questions.
- `acme.agents.payments-java.persistence` for database or transaction work.
- `acme.agents.payments-java.testing` for fixture and integration-test guidance.
<!--</capability>-->
```

That is enough for the agent to know who it is, where its authority stops, and what to load next.

## Choose capabilities by failure mode

The best starter agents encode the mistakes you keep correcting:

| Repeated failure | Capability to add |
|------------------|-------------------|
| Wrong build command | `build` or `tooling` capability |
| Native framework patterns ignored | `framework` or `architecture` capability |
| Tests are too broad or too weak | `testing` or `validation` capability |
| API errors shaped incorrectly | `api-contracts` capability |
| Secrets or auth rules missed | `security` capability |
| Review feedback repeated often | `review-readiness` capability |

Start with three or four capabilities. Add more only after you see repeated misses in real sessions.

## Pick the right default role

| Role | Use for |
|------|---------|
| `executor` | Agents that implement scoped task changes |
| `reviewer` | Agents that inspect work and publish findings or gate decisions |
| `planner` | Agents that discover, shape, split, or prepare work before execution |

If the agent changes code, `executor` is usually right. If it reports findings, `reviewer` or `planner` may be safer.

## Validate and import

After authoring the pack:

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

Then import the archive through **Settings > Packs** and review the preflight plan. The preflight view is where you confirm which agents and capabilities will be created, overwritten, skipped, or left unchanged.

## How to know it is working

A strong starter agent produces fewer repeated corrections:

- You stop re-explaining build and test commands.
- Agent summaries cite the expected validation evidence.
- Review feedback shifts from "wrong conventions" to real product questions.
- Team-specific rules live in source-controlled pack files instead of chat history.

That is the point of packs: not more prompts, but reusable behavior your team can inspect and improve.

## Next step

Read [Agent definitions](../../../how-packs-work/agent-definitions/) for the full `.agent.yaml` contract, then use [Authoring workflow](../../../building-your-own/workflow/) to validate, generate, and import your pack.