agent foundation

docs/agents/flow.md

@@ -0,0 +1,40 @@
+# Agent Workflow
+
+## State Machine
+- `planned`
+- `executing`
+- `review_guard`
+- `review_acceptance`
+- `finalize`
+- `done`
+
+If a reviewer returns `FAIL`, state goes back to `executing` with explicit findings.
+
+## Minimum Handover Artifacts
+- Planner: `plan.json`
+- Executor: `execution-report.json`
+- Reviewer Guards: `review-guards.json`
+- Reviewer Acceptance: `review-acceptance.json`
+- Finalizer: `finalize.json`
+
+## Guard and Gate Binding
+- Planner selects required guard IDs from `agent-system/checks/guard-catalog.json`.
+- Planner selects required quality gate IDs from `agent-system/checks/quality-gates.json`.
+- Planner assigns stable success criteria IDs (`SC-*`) in `plan.json`.
+- Executor must provide guard evidence and gate results by ID.
+- Guard reviewer verifies and reports verdict against the same IDs.
+- Acceptance reviewer verifies and reports verdict against the same `SC-*` IDs.
+
+## Fail Loop Rule
+- No free-text "please improve".
+- Every fail must include:
+  - `id`
+  - `severity`
+  - `file`
+  - expected fix
+
+## Practical Rollout
+- Start with one small issue.
+- Run workflow manually with templates.
+- Stabilize contracts first.
+- Add automation only after 3 to 5 successful runs.

docs/agents/overview.md

@@ -0,0 +1,27 @@
+# Agent Workflow Overview
+
+This project uses a multi-role workflow for issue and feature delivery.
+
+Roles:
+- Planner
+- Executor
+- Reviewer (guards and best practices)
+- Reviewer (feature acceptance)
+- Finalizer
+
+Primary goals:
+- predictable handovers
+- strict quality gates
+- fast retry loop from reviewers back to executor
+- explicit guard and gate IDs (`GR-*`, `QG-*`) across all roles
+
+Source of truth:
+- guardrails and planning standards in `tools/codex-skills/`
+- contracts and templates in `agent-system/`
+- guard catalog: `agent-system/checks/guard-catalog.json`
+- quality gates: `agent-system/checks/quality-gates.json`
+
+Entry points:
+- roles: `docs/agents/roles.md`
+- workflow: `docs/agents/flow.md`
+- schemas and prompts: `agent-system/`

docs/agents/roles.md

@@ -0,0 +1,47 @@
+# Agent Roles
+
+## Planner
+- Input: issue or feature request
+- Output: `plan.json` (see `agent-system/contracts/planner.schema.json`)
+- Must define:
+  - scope in and out
+  - required guard IDs (`GR-*`)
+  - required quality gate IDs (`QG-*`)
+  - success criteria with stable IDs (`SC-*`)
+  - implementation steps
+  - test and acceptance checks
+  - risks and mitigations
+
+## Executor
+- Input: approved `plan.json`
+- Output: `execution-report.json`
+- Must:
+  - implement the plan
+  - run relevant checks
+  - document changed files and commands
+
+## Reviewer Guards
+- Input: code diff and `execution-report.json`
+- Output: `review-guards.json`
+- Focus:
+  - architecture boundaries
+  - security
+  - coding standards
+  - guardrail compliance
+  - explicit validation against required `GR-*` and `QG-*` IDs
+
+## Reviewer Acceptance
+- Input: code diff and plan success criteria
+- Output: `review-acceptance.json`
+- Focus:
+  - feature correctness
+  - edge cases
+  - acceptance criteria coverage
+  - explicit check mapping by `SC-*` criterion IDs from `plan.json`
+
+## Finalizer
+- Input: both review files with PASS verdict
+- Output: `finalize.json`
+- Must:
+  - verify gates are green
+  - prepare merge and commit metadata

docs/frontend-javascript.md

@@ -1,6 +1,6 @@
 # Frontend JavaScript
 
-Letzte Aktualisierung: 2026-03-04
+Letzte Aktualisierung: 2026-03-05
 
 ## Ordnerstruktur
 
@@ -283,9 +283,24 @@ Für standardisierte Detailseiten gilt zusätzlich:
 Für allgemeine Form-/Button-Confirms außerhalb der Detail-Policy gilt:
 
 - zentral über `web/js/components/app-confirm-actions.js`
-- Confirm-Text über `data-confirm-message`
+- Dialog-Engine zentral über `web/js/core/app-confirm-dialog.js` (`confirmDialog.confirm(...)`)
+- Confirm-Text über `data-confirm-message` bzw. auf Detail-Aktionen `data-detail-confirm-message`
+- optionale Dialog-Meta über
+  - `data-confirm-title`, `data-confirm-confirm-label`, `data-confirm-cancel-label`, `data-confirm-variant`, `data-confirm-focus`
+  - analog für Detail-Aktionen: `data-detail-confirm-*`
+- kein direktes `window.confirm(...)` in App-JS
 - keine inline `onclick="return confirm(...)"` / `onsubmit="return confirm(...)"` verwenden
 
+### Frontend Telemetry Standard
+
+Für UX-/Fehler-Telemetrie im Frontend gilt:
+
+- zentral über `web/js/core/app-telemetry.js` (`telemetry.capture(...)`)
+- `warnOnce(...)` sendet standardisiert `frontend.warn_once`
+- AJAX-/Fetch-Fehler laufen zentral über den globalen Fetch-Hook als `frontend.ajax_error`
+- keine neuen Console-only-Warnpfade für relevante UX-Probleme ohne Telemetrie
+- Payloads nur mit Whitelist-Feldern und ohne sensitive Rohdaten (keine Tokens/Query-Parameter/Stacktraces)
+
 ### Detail Validation Summary Standard
 
 Für serverseitige Formularfehler in Create/Edit-Templates gilt:

docs/index.md

@@ -91,3 +91,14 @@ Diese Dokumentation folgt einem klaren Lernpfad (einfach -> fortgeschritten) und
   - Standard-Prompts für Skill-basierte Planung und Implementierung.
 - `/docs/dokumentation-erweitern.md`
   - Regeln für konsistente, wachsende Doku.
+
+## Agent Workflow
+
+- `/docs/agents/overview.md`
+  - Einstieg in das Rollenmodell und die Artefakte.
+- `/docs/agents/roles.md`
+  - Klare Verantwortung je Rolle (Planner, Executor, Reviewer, Finalizer).
+- `/docs/agents/flow.md`
+  - State-Flow mit Fail-Loop zur Executor-Iteration.
+- `/agent-system/README.md`
+  - Technische Basis mit Contracts, Templates, Prompts und Checks.