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:

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

Start with the `.agent.yaml`

Create a source directory in your pack:

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:

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:

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

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 for the full .agent.yaml contract, then use Authoring workflow to validate, generate, and import your pack.

Security audit agent