# werkregie Agent Instructions

## Project

werkregie orchestrates software development with AI agents.
So far it is the dashboard in `dashboard/`, a Kotlin web app that shows what the coding agents
and the build pipeline are doing right now; see [dashboard/README.md](dashboard/README.md).
[doc/system-architektur.md](doc/system-architektur.md) describes the system,
[doc/werkregie.werkbaum](doc/werkregie.werkbaum) holds the plan.

## Build and Test

Run from `dashboard/`:

```sh
./gradlew build         # compile and test; needs Node for jsTest
./gradlew jsTest        # the JavaScript of the page with node --test, TZ=Europe/Berlin (ADR 0002); part of build
./gradlew installDist   # build/install/werkregie-dashboard/bin/werkregie-dashboard → http://localhost:4747/
./gradlew checkLicense            # licenses against config/allowed-licenses.json; part of build
./gradlew dependencyCheckUpdate   # loads the NVD data; Werkator's nightly build "vulnerability-data"
./gradlew dependencyCheckAnalyze  # all known vulnerabilities from CVSS 4, from that data; main each night
./gradlew checkNewVulnerabilities -PvulnerabilityBaseline=origin/main  # only those this branch brings; each PR
./gradlew dependencies --configuration runtimeClasspath --write-locks  # gradle.lockfile, after a dependency change
./gradlew pitestPartial mutationCrapCheck  # mutation tests of the classes changed against origin/main, limit 15; each build
./gradlew pitestFull mutationCrapCodeCharta mutationCrapCheck  # all classes, ratchet limit; Werkator's nightly build "mutation"
```

The levels of these checks come from [doc/risk-analysis.md](doc/risk-analysis.md), criticality high.
OWASP Dependency-Check reads the NVD API key from `NVD_API_KEY` or the Gradle property `OWASP_API_KEY`.

## Workflow

Follow [doc/agentic-workflow.md](doc/agentic-workflow.md), the workflow of all Werk repositories:
roles, steps of a PR, review rounds, PR documents, the plan, versions and the writing style.
In addition, for werkregie:

- Its documents live in `doc/`, not `docs/`: `doc/agentic-workflow.md`, `doc/prs/`, `doc/werkregie.werkbaum`.
- werkregie holds the master copy of the shared workflow.
- `dashboard/build.gradle.kts` derives the version from the PR documents, from the base version 0.50.0 on;
  `./gradlew changelog` writes their release notes into `build/changelog/CHANGELOG.md`.
  For the version, each Gradle run needs the full history and `origin/main`; a shallow clone fails with a hint.
- GitHub `mhoennig/werkregie` is only a mirror of `main`; branches go to Gitea only.
- Werkator deploys each green `main` to mih09 with its build `deploy`; after the merge the agent only checks
  that https://werkregie.javagil.de answers with the new version, e.g. by `/api/dashboard`.