# werkkompass Agent Instructions

## Project

Werkkompass is an interactive demo of Vibe Coding, Vibe Engineering and Agentic AI in software development,
with traditional development without AI for comparison; see [README.md](README.md).
[docs/risk-analysis.md](docs/risk-analysis.md) holds the criticality,
[docs/werkkompass.werkbaum](docs/werkkompass.werkbaum) the plan.

## Architecture

- `index.html` is the whole application: one file, no framework, no build step, nothing loaded from other hosts.
- The profiles view is part of the page itself.
- The staircase view and the workflow view are complete HTML documents,
  escaped into the `srcdoc` attribute of an `iframe` each.
- The views talk to the page with `postMessage`: `show-practices`, `show-workflow`, `show-staircase`,
  and `stair-height` or `workflow-height` to size their `iframe`.
- The page routes by the URL hash; see the end of `index.html`.

## Check

There is no automated check and no CI yet; the human decided to add both together with the build step.
Each PR checks the list under "Check" in [README.md](README.md) in a browser and reports the result in its PR document.

## Install

`install-vibe-engineering-webapp` deletes the file it uploads; install a copy, never `index.html` of the checkout.
Installing is a step of its own, after the merge and only when the human asks for it.

## Invariants of the Content

- Colors: AI petrol `#147f8e`, human orange `#d58b32`, shared involvement violet `#8064a2`,
  activities not done or gaps grey, background `#f6f8f9`; content at most 1480 px wide.
- The model values are illustrative assumptions, not empirical benchmarks; the page says so.
- Authorship is who does the work; engineering coverage is how well it is assured.
  Never treat the two dimensions as one.
- For "Automated Quality Checks", authorship is who writes or configures the checks, not who runs them.
- Human involvement and delegation are independent parameters.
- The iterative simulation has no fixed maximum number of steps; it ends when the target is reached.
- Each view keeps the links to copyright, imprint and privacy.

## Background of the Workflow View

The workflow view shows the personal workflow of Michael Hönnig, not a general standard:

- Werkbaum with PSP and Lean-Path guides the work at the top level.
- An RFC adds the solution design and its trade-offs to the plan where needed.
- The human cuts CRs in discussion with the AI.
  A CR holds goals, non-goals, background, compatibility requirements, acceptance criteria and relevant risks.
- In the structured path, an RFC is implemented as a sequence of CR/PR pairs;
  each CR gets its own branch and PR and is merged on its own.
- The Werkbaum status is updated while the work goes on.
- A review finding leads to reasons and evidence, the human's assessment, and if needed rework and a new review.
- After the RFC is implemented completely, the RFC document is removed; the CR and PR documents stay.
- Multiple-choice questions can be explored in side chats; the answer often comes through "Other",
  with a result of one's own.
- Guardrails are adjusted continuously, mostly starting from the human;
  a change of them by an agent gets a human review.
- With growing complexity, the work escalates from a mid-tier to a frontier model.
- Deployment after the merge stays outside this view on purpose.

## Workflow

Follow [docs/agentic-workflow.md](docs/agentic-workflow.md), the workflow of all Werk repositories.
In addition, for werkkompass:

- Documents are in English; the UI gets a DE/EN switch later.
- The version stands in `VERSION`.
- The required checks for vulnerabilities and licenses have nothing to check: there are no dependencies.
  The mutation tests apply to Kotlin and Java only.
  The first dependency or build tool brings its checks along; see [docs/risk-analysis.md](docs/risk-analysis.md).