From ebf15081e1eca2ce977cb2c2ac39035d78828e0c Mon Sep 17 00:00:00 2001 From: fs Date: Fri, 6 Mar 2026 09:55:58 +0100 Subject: [PATCH] Skill Updates --- tools/codex-skills/core-guardrails/SKILL.md | 12 ++++++----- .../references/boundaries-core.md | 16 ++++++++------ .../references/boundaries-ui.md | 21 +++++++++++++++++++ .../core-guardrails/references/source-map.md | 2 ++ .../codex-skills/starterkit-planner/SKILL.md | 19 ++++++++++++++--- .../references/plan-template.md | 9 ++++++++ 6 files changed, 65 insertions(+), 14 deletions(-) diff --git a/tools/codex-skills/core-guardrails/SKILL.md b/tools/codex-skills/core-guardrails/SKILL.md index ece9e2e..a4d2ea3 100644 --- a/tools/codex-skills/core-guardrails/SKILL.md +++ b/tools/codex-skills/core-guardrails/SKILL.md @@ -12,12 +12,14 @@ Durchgaengig dieselben technischen Grenzen durchsetzen, damit Core robust, wartb ## Verbindliche Regeln 1. MUST Layering einhalten (`pages` -> `Service` -> `Repository`, Templates nur Rendering). -2. MUST Request/Input/Validation-Contract einhalten (`requestInput()`, `FormErrors`, API-Validation ueber `ApiResponse::validationFromFormErrors(...)`, kein `ApiResponse::readJsonBody(...)` in `pages/api/v1/**`). +2. MUST Request/Input/Validation-Contract einhalten (`requestInput()`, `FormErrors`, API-Validation ueber `ApiResponse::validationFromFormErrors(...)`, kein `ApiResponse::readJsonBody(...)` in `pages/api/v1/**`, keine direkten Superglobals in `pages/**`). 3. MUST AuthZ/RBAC serverseitig durchsetzen und im UI nur ueber `$viewAuth` steuern. -4. MUST UI-Standards und Data-Contracts fuer Listen/Detailseiten nutzen (Wrapper, Partials, keine inline `confirm(...)`, inklusive globaler Grid-Standards fuer rowInteraction/pageSize). -5. MUST Quality-Gates ausfuehren und Ergebnis transparent berichten. -6. MUST bei Konflikten den regelkonformen Weg waehlen oder den Konflikt als Blocker markieren. -7. MUST NOT Extension-Architektur erfinden; dieses Thema ist aktuell Out of Scope. +4. MUST Security-Guards einhalten (CSRF auf POST-Endpunkten, keine unredacted PII/Secrets in Logs/Audit-Meta, SQL nur vorbereitet ueber Repository). +5. MUST UI-Standards und Data-Contracts fuer Listen/Detailseiten nutzen (Wrapper, Partials, globaler Confirm-Dialog statt `window.confirm`, inklusive globaler Grid-Standards fuer rowInteraction/pageSize). +6. MUST Frontend-Hardcuts einhalten (keine inline ESM-Module in Templates/Pages, JS-`src` mit `assetVersion(...)`, zentrale Telemetrie fuer relevante Frontend-Warnings/Fetch-Fehler). +7. MUST Quality-Gates ausfuehren und Ergebnis transparent berichten. +8. MUST bei Konflikten den regelkonformen Weg waehlen oder den Konflikt als Blocker markieren. +9. MUST NOT Extension-Architektur erfinden; dieses Thema ist aktuell Out of Scope. ## Vorgehen je Aufgabe diff --git a/tools/codex-skills/core-guardrails/references/boundaries-core.md b/tools/codex-skills/core-guardrails/references/boundaries-core.md index 1f09173..c0d20b1 100644 --- a/tools/codex-skills/core-guardrails/references/boundaries-core.md +++ b/tools/codex-skills/core-guardrails/references/boundaries-core.md @@ -18,9 +18,10 @@ 1. MUST Input in `pages/**` ueber `requestInput()` lesen. 2. MUST NOT `$_POST`, `$_GET`, `$_FILES`, `REQUEST_METHOD` in `pages/**` verwenden. -3. MUST Form-Validation ueber `FormErrors` fuehren. -4. MUST API-Validation-Fehler ueber `ApiResponse::validationFromFormErrors(...)` ausgeben. -5. MUST NOT `ApiResponse::readJsonBody(...)` in `pages/api/v1/**` verwenden. +3. MUST NOT `$_SESSION`, `$_SERVER`, `$_COOKIE`, `$_ENV` in `pages/**` direkt verwenden. +4. MUST Form-Validation ueber `FormErrors` fuehren. +5. MUST API-Validation-Fehler ueber `ApiResponse::validationFromFormErrors(...)` ausgeben. +6. MUST NOT `ApiResponse::readJsonBody(...)` in `pages/api/v1/**` verwenden. ## List-Data Endpoints @@ -32,9 +33,12 @@ 1. MUST AuthZ serverseitig erzwingen. 2. MUST Tenant-Scope serverseitig erzwingen. -3. MUST extern UUID-first bleiben. -4. MUST API-Fehler konsistent halten (`error`, optional `errors`). -5. MUST OpenAPI im selben Merge aktualisieren, wenn API geaendert wird. +3. MUST CSRF auf POST-Endpunkten vor Body-Verarbeitung verifizieren. +4. MUST NOT PII/Secrets unredacted in Logs oder Audit-Metadata schreiben. +5. MUST SQL nur ueber Repository mit prepared statements ausfuehren. +6. MUST extern UUID-first bleiben. +7. MUST API-Fehler konsistent halten (`error`, optional `errors`). +8. MUST OpenAPI im selben Merge aktualisieren, wenn API geaendert wird. ## Pruef-Hinweis diff --git a/tools/codex-skills/core-guardrails/references/boundaries-ui.md b/tools/codex-skills/core-guardrails/references/boundaries-ui.md index c842bb1..8708381 100644 --- a/tools/codex-skills/core-guardrails/references/boundaries-ui.md +++ b/tools/codex-skills/core-guardrails/references/boundaries-ui.md @@ -17,6 +17,20 @@ 3. MUST Detail-Aktionen ueber Action-Policy-Contract (`data-detail-action-policy`, `data-detail-action-kind`, `data-detail-confirm-message`) steuern. 4. MUST NOT inline `confirm(...)` (`onclick` / `onsubmit`) auf standardisierten Detailseiten nutzen. +## Confirm + Telemetry Standard + +1. MUST Confirm-Dialoge zentral ueber den globalen Confirm-Service abwickeln. +2. MUST NOT `window.confirm(...)` in App-JS oder inline HTML-Handlern verwenden. +3. MUST relevante Frontend-Warnpfade zentral ueber Frontend-Telemetrie erfassen. +4. MUST NOT relevante UX-/Fehlerpfade nur als Console-Warnung implementieren. + +## Frontend Page-Module Hard Cut + +1. MUST Seiteninitialisierung ueber dedizierte Module unter `web/js/pages/*` umsetzen. +2. MUST Page-Config ueber `script[type="application/json"]` + `readPageConfig(...)` bereitstellen/lesen. +3. MUST alle JS-`src` in `pages/**` und `templates/**` ueber `assetVersion('...js...')` laden. +4. MUST NOT inline `` in `pages/**` oder `templates/**` verwenden. + ## Shared Partials 1. MUST Listen-Titlebar ueber `templates/partials/app-list-titlebar.phtml` rendern. @@ -28,3 +42,10 @@ 1. MUST UI-Capabilities nur ueber `$viewAuth` lesen. 2. MUST NOT `can('...')` in Templates verwenden. + +## CSS Boundaries + +1. MUST Styles moeglichst lokal in `web/css/components`, `web/css/layout` oder `web/css/pages` halten. +2. MUST NOT globale unscoped Overrides ohne klaren Scope einfuehren. +3. MUST Vendor-Overrides nur in `web/css/vendor-overrides/**` pflegen. +4. MUST bestehende CSS-Variablen bevorzugen statt neue Inline-Farbwerte zu verteilen. diff --git a/tools/codex-skills/core-guardrails/references/source-map.md b/tools/codex-skills/core-guardrails/references/source-map.md index ff99abb..70feb01 100644 --- a/tools/codex-skills/core-guardrails/references/source-map.md +++ b/tools/codex-skills/core-guardrails/references/source-map.md @@ -10,7 +10,9 @@ ## UI-/Frontend-Contracts - JavaScript-Standards und Wrapper: `/docs/frontend-javascript.md` +- CSS-Standards und Scope-Regeln: `/docs/frontend-css.md` - DoD-Checks: `/docs/entwickler-checkliste.md` +- Rollen-Workflow (Planner/Executor/Reviewer/Finalizer): `/docs/agents/overview.md` ## Security / RBAC diff --git a/tools/codex-skills/starterkit-planner/SKILL.md b/tools/codex-skills/starterkit-planner/SKILL.md index a47327d..a0847a8 100644 --- a/tools/codex-skills/starterkit-planner/SKILL.md +++ b/tools/codex-skills/starterkit-planner/SKILL.md @@ -8,6 +8,7 @@ description: Planungs-Skill fuer Architektur-, Rollout-, Refactor- und Standardi ## Ziel Planungen so strukturieren, dass Implementierung ohne offene Entscheidungen moeglich ist. +Bei Agent-Workflows muss der Plan maschinenlesbar in die Projekt-Contracts passen. ## Verbindliches Ausgabeformat @@ -19,20 +20,29 @@ Planungen so strukturieren, dass Implementierung ohne offene Entscheidungen moeg 6. Risiken/Migrationshinweise 7. Annahmen/Defaults +Wenn `agent-system/` verwendet wird: + +1. Plan muss dem Schema `agent-system/contracts/planner.schema.json` entsprechen. +2. Success Criteria muessen stabile IDs tragen (`SC-001`, `SC-002`, ...). +3. Success Criteria muessen so formuliert sein, dass Reviewer Acceptance sie direkt gegen `criterion_id` pruefen kann. +4. Guard- und Quality-Gate-IDs muessen aus den Katalogen kommen (`GR-*`, `QG-*`). + ## Vorgehen 1. Ist-Zustand kurz aus Repo-Fakten ableiten. 2. Entscheidungen mit Tradeoffs transparent machen. 3. Oeffentliche Contracts explizit benennen. -4. Reihenfolge und Rollout so planen, dass Rueckbau moeglich bleibt. -5. Teststrategie nach Risiko priorisieren. +4. Success Criteria frueh mit stabilen IDs (`SC-*`) definieren. +5. Reihenfolge und Rollout so planen, dass Rueckbau moeglich bleibt. +6. Teststrategie nach Risiko priorisieren. ## Qualitaetskriterien 1. Keine vagen TODO-Entscheidungen im Plan. -2. Jeder betroffene Bereich hat klare Akzeptanzkriterien. +2. Jeder betroffene Bereich hat klare Akzeptanzkriterien mit stabiler ID (`SC-*`). 3. Risiken sind priorisiert und beobachtbar. 4. Ungeklaerte Themen stehen explizit unter Annahmen. +5. Guard-/Gate-Referenzen sind vollstaendig und pruefbar (`GR-*`, `QG-*`). ## Out of Scope @@ -43,3 +53,6 @@ Planungen so strukturieren, dass Implementierung ohne offene Entscheidungen moeg - Plan-Grundgeruest: `references/plan-template.md` - Entscheidungsraster: `references/tradeoff-matrix.md` +- Agent Planner Contract: `agent-system/contracts/planner.schema.json` +- Guard Catalog: `agent-system/checks/guard-catalog.json` +- Quality Gates: `agent-system/checks/quality-gates.json` diff --git a/tools/codex-skills/starterkit-planner/references/plan-template.md b/tools/codex-skills/starterkit-planner/references/plan-template.md index 17c1488..8e530da 100644 --- a/tools/codex-skills/starterkit-planner/references/plan-template.md +++ b/tools/codex-skills/starterkit-planner/references/plan-template.md @@ -4,16 +4,24 @@ - Was wird verbessert? - Woran ist messbar, dass es erfolgreich ist? +- Success Criteria immer mit stabilen IDs formulieren (`SC-001`, `SC-002`, ...). + +Beispiel: + +- `SC-001`: Delete-Aktion zeigt Confirm-Dialog mit korrekter Gefahr-Variante. +- `SC-002`: Nach Confirm erfolgt genau ein Submit (kein Doppel-Submit). ## 2) Scope - In Scope - Out of Scope +- Scope-Typ explizit markieren (`core`, `ui`, `api`, `mixed`), wenn der Workflow es verlangt. ## 3) Oeffentliche Interfaces / Contracts - Neue/angepasste APIs, Data-Contracts, CLI-Flags, Markup-Contracts - Backward-Compatibility-Entscheidung +- Bei Agent-Workflow: verwendete `GR-*` und `QG-*` IDs explizit nennen. ## 4) Implementierungsschritte @@ -29,6 +37,7 @@ Regel: Jeder Schritt ist direkt umsetzbar ohne Nachentscheid. - Contract-/Architekturtests - Fachliche Smoke-Tests - Abnahmekriterien (klar messbar) +- Abnahme-Checks 1:1 auf `SC-*` Kriterien-ID referenzieren. ## 6) Risiken / Migration