werkkompass/AGENTS.md

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. docs/risk-analysis.md holds the criticality, 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 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, 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.