werkkompass/docs/prs/2026-10-14-PR#1-project-foundation.md

# PR#1: Project foundation for the taken-over SPA

> **WARNING:** This document describes only the change applied in this PR.
> It may already be outdated once the next PR is merged.
> Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

## Related Links

- Published version: https://javagil.de/vibe-engineering
- Workflow master copy: https://git.javagil.de/mi/werkregie/src/branch/main/doc/agentic-workflow.md

## Problem

The interactive demo on Vibe Coding, Vibe Engineering and Agentic AI existed only as one published HTML file.
It continues as Werkkompass, a repository of the Werk family, under the shared agentic workflow.
The first commit on `main` took the published file over unchanged; the repository lacks everything else.

## Non-Goals

- No functional change of `index.html`, no restructuring.
- No branding as Werkkompass, no DE/EN switch in the UI.
- No CI yet; the human decided to add checks together with the build step.
- No publication; installing a new version on javagil.de stays a step of its own.

## Solution

### Starting Point

Before the takeover, the candidates were compared:

| File | Result |
|------|--------|
| https://javagil.de/vibe-engineering, last modified 2026-09-07 | taken over as `index.html` |
| `~/agentic-ai-software-development.html`, 2026-09-07 14:02 | byte-identical with the published one, SHA-256 `55da7ca6…` |
| the path given in the task, `…/outputs/agentic-ai-software-development.html` | does not exist |
| `…/outputs/agentic-ai-workflow.html`, 2026-09-07 13:57 | the workflow view alone; the embedded one adds only the `postMessage` glue |
| `~/Downloads/agentic-ai-ballistik.html`, 2026-07-31 | an older predecessor, not taken over |

So no change was dropped.
The first commit on `main`, `27da462`, holds `index.html` and `LICENSE`, the MIT license from the head comment of `index.html`.
It went to `main` directly, by decision of the human, so that the unchanged state stays traceable apart from this PR.

### Files

- `README.md`: purpose, views, local start, the browser check, installation.
- `AGENTS.md`: architecture, the invariants of the content, the background of the workflow view, the exceptions to the workflow.
- `CLAUDE.md`, `docs/agentic-workflow.md` from the master copy in werkregie, `docs/prs/README.md` and `TEMPLATE.md`.
- `docs/werkkompass.werkbaum`: the plan; it parses without warnings.
- `docs/risk-analysis.md`: criticality low, set by the human as a deviation from the table of the workflow.
- `.werkrevisor.toml`: the template `typescript-frontend` without the categories for login, tokens, API and forms.
  werkrevisor reads it from `main`, so it applies from the next PR on.
- `.gitignore`: editor files and the local state of coding agents; nothing is generated yet.
- `VERSION`: 1.0.0, the first version of werkkompass.

### Browser Check

Checked on https://javagil.de/vibe-engineering, byte-identical with `index.html`, in Chromium on 2026-10-14:

| Check | Result |
|-------|--------|
| the three views are reachable by their arrows | passed |
| each hash route: `#profile`, `#practices`, `#iterations`, `#coverage`, `#engineering-activities`, `#workflow` | passed |
| back and forward in the browser history | passed |
| the seven profile presets set the sliders; a slider change switches the profile to "Custom" | passed |
| the four tabs | passed |
| human involvement and delegation are independent | passed: each slider leaves the other one unchanged |
| the iterative simulation has no fixed maximum of about 16 steps | passed: "Traditional · Junior" took 32 steps to "Target reached" |
| the info popups: open, close with × and with Escape | passed |
| 375 px wide: no horizontal scrolling of the page; titles and arrows usable | passed; the staircase table scrolls inside its frame |
| no messages in the console | passed |
| the links to copyright, imprint and privacy in each view | **failed** in the staircase and the workflow view |

The links of the two framed views load inside their `iframe`.
michael.hoennig.de sends `X-Frame-Options: DENY`, so the view turns blank.
This PR changes no behaviour, so the fix is a follow-up PR.

Opened as a file with `file://`, the page works too, but the workflow view keeps an inner scroll bar;
the README therefore starts a local HTTP server.

## Open Questions

- [x] Who creates the repository `mi/werkkompass`?
  The human; `claude-code` may not create repositories in the namespace `mi`.
- [x] How does the unchanged state reach `main`?
  As one commit pushed directly to `main` by `claude-code`; everything else in this PR.
- [x] In which language are the documents?
  English for now; a German version follows with the DE/EN switch.
- [x] Which criticality?
  low, as a deviation from the table, set by the human.
- [x] Which tool for checks and CI?
  None for now; checks and Werkator build come together with the build step.
- [x] Where is Werkkompass served?
  At javagil.de/vibe-engineering for now; later at werkkompass.javagil.de,
  with a permanent redirect from the old address.
  The human first sets up the subdomain and a Unix user for it at Hostsharing.

## Prerequisite PRs

- [werkrevisor PR#110](https://git.javagil.de/mi/werkrevisor/pulls/110):
  the host config, so that werkrevisor reviews werkkompass.

## Follow-up PRs

- The links of the framed views open in the top window (`#bug.frame-links`),
  and the back arrow names the current file (`#bug.back-href`).
- Readable sources and a build step that writes one installable HTML file (`#repo.sources`),
  with an automated check and a Werkator build (`#repo.check`).
- Branding as Werkkompass (`#ui.brand`), served at werkkompass.javagil.de (`#ops.domain`).
- DE/EN switch throughout (`#ui.i18n`).