# Java task agent
The Java Task Agent is a starter executor for JVM codebases. It gives you a working baseline for Java 17+, Maven or Gradle projects, package design, and test validation without forcing every team to accept the same architecture forever.

Use it as a starting point when you want an implementation agent that already understands Java build hygiene, explicit contracts, dependency injection, null-safety, and JUnit-style validation.

> [!NOTE]
> This is a starter agent. It gives you a good default shape, but your best Java executor will include your own framework choices, module boundaries, testing commands, and review standards.

## Agent shape

| Field | Value |
|-------|-------|
| Handle | `java-task-agent` |
| Name | Java Task Agent |
| Kind | `bot` |
| Default role | `executor` |
| Source pattern | `valdr-packs/valdr/vanguard/agents/java/` |

The agent definition starts with one core identity capability, then binds hot-loadable capabilities for deeper Java guidance:

```yaml
schemaVersion: 1.0
agent:
  handle: java-task-agent
  name: Java Task Agent
  kind: bot
  defaultRole: executor
  tags:
    - java
    - valdr
    - task-agent
capabilities:
  - key: valdr.agents.java.java-task-agent.system
    role: core
  - key: valdr.agents.java.build
    role: constraints
    hot-load: true
  - key: valdr.agents.java.code.rules
    role: constraints
    hot-load: true
  - key: valdr.agents.java.design.solid
    role: workflow
    hot-load: true
  - key: valdr.agents.java.testing
    role: workflow
    hot-load: true
```

## What it is good at

| Need | Why this agent fits |
|------|---------------------|
| Maven or Gradle changes | It can hot-load build guidance for multi-module projects and dependency metadata |
| Java API changes | It is biased toward explicit contracts, constructor injection, and intentional `Optional<T>` usage |
| Package refactors | It can load SOLID and architecture guidance when the task touches boundaries |
| Test work | It can load JUnit/testing guidance for unit and integration coverage |

The core system capability tells the agent to implement targeted Java changes, update tests, run impacted validations, and summarize evidence. It also makes an important boundary clear: the Java starter agent executes code work; it does not manage the Valdr task lifecycle by itself.

## How to use it

Launch the agent with `/valdr-agent` and pass the starter handle first:

```text
/valdr-agent java-task-agent implement the validation service change in PAY-142.
Focus on the billing module, preserve the public API, and run the affected Maven tests.
```

Good launch prompts name:

- the project or task
- the module or package
- the expected behavior
- the validation command or test scope
- any framework conventions the starter pack cannot infer

## When not to use it

Do not use `java-task-agent` to decide what work should exist. Use [Gunnar](../../starter-packs/gunnar/) to create tasks, [Freya](../../included-agents/freya/) to turn ambiguous work into a plan, and [Skadi](../../starter-packs/skadi/) to route sprint execution.

Also avoid using the generic Java starter as-is when the project has strict framework rules that are not encoded yet. If your team requires Spring-specific transaction boundaries, Hibernate fetch-plan rules, Micronaut conventions, or generated client patterns, add those as team capabilities before relying on the agent for broad implementation work.

## How to adapt it

Start by copying the structure, not the exact content:

1. Rename the handle to match your team, such as `payments-java-agent`.
2. Keep exactly one `role: core` capability for identity and baseline workflow.
3. Replace generic Java capabilities with team-specific capabilities:
   - `acme.java.spring-transactions`
   - `acme.java.persistence-rules`
   - `acme.java.test-fixtures`
   - `acme.java.api-errors`
4. Mark detailed guidance as `hot-load: true` so the agent stays lean.
5. Validate the pack and import it through the Valdr UI.

The result is still a familiar starter agent, but it now speaks your codebase instead of generic Java.

## Next step

Use [Build your own](../build-your-own/) to turn this pattern into a team-specific executor.