priority-pilot

Imported from deleonio/priority-pilot (AGENTS.md). Install upstream with npx skills add deleonio/priority-pilot. Copyright stays with the author.

Agent Instructions

Zentrale Anweisungen für alle KI-Agents in diesem Repo. Die ausführliche, werkzeug-unabhängige Wissensbasis liegt in .ai-knowledge/. CI-Doku (für Menschen, nicht Agent-Kontext): docs/ci-architecture.md.

Wissensbasis

• Projekt & Konventionen — Zweck, Monorepo, Befehle, Konventionen, Mobile-First, Datenbank
• Ticket-Erstellung — neue Tickets template-konform erfassen, gezielte Nachfragen an den Autor
• Ticket-Triage — Analyse offener GitHub-Issues
• Ticket-UX — UX-Beratung für UI-Tickets
• Ticket-Spec — rote Tests (Vertrag) für ai:needs-spec-Issues
• Ticket-Umsetzung — freigegebene Issues (ai:needs-impl) umsetzen
• PR-Review (Kreuzverhör) — PRs adversarial prüfen, Findings kommentieren
• Code-Review-Team — tägliches Architektur-/Qualitäts-Review in vier Perspektiven plus Regelwerk-Prüfung (Widersprüche/Lücken in den Vorgaben), fortlaufendes Protokoll-Issue, genau ein unkritischer Fix je Lauf (Code oder Vorgaben-Konsolidierung)
• Dev-Team — Multi-Agent-Lauf (Architect orchestriert Developer/Tester/Reviewer/Documenter/Pädagoge): Ticket-Modus führt ein Issue bis zum grünen Kreuzverhör — lokal über /dev-team #N, in GitHub über das Label ai:needs-team (team.yml); freier Modus bearbeitet Aufgaben ohne Ticket. Liest die Kennzahlen aus .costs/ für Modell-/Effort-Wahl, je Lauf ein Kostensatz (phase: team)
• TDD-Strategie — test-getriebene KI-Workflows (Stufen 1+2+3 adoptiert)
• Design-Sprache „Cockpit" — Farbrollen, Skalen-Tokens, Komponentenwahl
• Dauergedächtnis — Erfahrungs-Log über Tickets hinweg (Protokoll: Memory)
• Browser-MCP — laufende App visuell prüfen (pnpm ui:inspect + Playwright-MCP)
• Deployment — Merge→Build→rsync→PM2, Host-Layout, Rollback
• Anmeldung & Zugang — Google-OAuth-Client, Allowlist, Konto entsteht beim ersten Login, Admin-Rollen, Fehlerbilder
• CI-Architektur — Provider, Modelle, Soft-Abort, Label-Pipeline, KoliBri MCP
• Pipeline-Flow — Diagramm + Tabellen zum label-getriebenen Ticket-Flows
• Kosten-Baseline #912 — Token/Kosten eines Tickets über alle Phasen
• ADRs — verbindliche Grundsatzentscheidungen: 0001 Workflows ungetestet, 0002 7-Phasen-Pipeline, 0003 Label-Schema, 0004 Analyse-getriebenes Routing, 0005 Fixup+Umsetzung = eine Phase, 0006 Issue-Storage = State-Branch (superseded), 0007 Issue-Storage = Harness-Branch (Transport superseded), 0008 Delegation + Mentor-Eskalation, 0009 Phasen-Ausgaben = Harness-Kommentar, 0010 Phasen-Notizen = Workflow-Artefakt, 0011 Worktree-Isolation (Vorschlag), 0012 MCP-Endpunkt ohne offizielles SDK, 0013 Zahlungsweg PayPal-Abos, 0014 Paketgrenzen ohne Angebots-Dialog
• Tailscale Exit Node — CI-Traffic über Tailscale-Exit-Node
• UX-Pattern: Sequenzielle Bestätigung — verbindliche Referenz für destruktive Aktionen
• Zifferblatt-Konzept — die fünf Bilder der Lebensbalance: gemeinsame Kennzahl, Rahmen, Regeln für ein neues Bild
• Mobile-UI-Regeln — Daumen-Zonen, Touch-Targets, async Zustände, Anti-Patterns (Schwesterdatei: Cockpit-Design)
• Design-Optimierungsplan — offene Findings aus Impeccable-Audit + Dashboard-Critique, Arbeitsliste mit Kommandos

Kernregeln

• Kurz halten: Antworten extrem knapp und präzise — keine unnötigen Erklärungen, Begründungen oder langen Code-Blöcke außer auf ausdrücklichen Wunsch. Keine Gedankengänge oder Live-Details während der Arbeit: Aufgaben still ausführen, am Ende nur das nackte Ergebnis. Output-Pflichten der Pipeline-Phasen (PR-Beschreibung, Job-Summary, Phasen-Notiz) bleiben unberührt.
• Minimalprinzip: Nur so viel programmieren, dokumentieren und testen wie wirklich notwendig — und so wenig wie irgend möglich; jede Zeile ist Wartungslast. Ein Test entsteht nur, wenn er etwas auswertet, einen Spiegel absichert oder vor stillen/teuren Ausfällen schützt (TDD-Strategie → Testumfang).
• Turns bündeln: Erst kurz planen, dann gebündelt ausführen — jeder Turn reißt den Kontext erneut an den LLM (Cache-Read) und zählt im Abo als eigener Prompt. Mechanisch heißt das: unabhängige Lese-/Such-Schritte in einem Tool-Call statt fünf einzelnen, Shell-Befehle verketten statt sequenziell aufrufen, nichts erneut lesen, was schon im Kontext steht, und wiederholbare Prüfläufe (GATE, Tests, Linter) einmal am Ende über alle Änderungen fahren statt je Einzeländerung. Keine Bestätigungs-Rückfragen im Arbeitsfluss — der needs-human-Weg der Pipeline-Phasen bleibt davon unberührt. Qualität geht vor: Ein nachgebesserter Schritt kostet mehr Turns als ein gründlicher erster — eine Fixup-Schleife kostet ~54 Turns (Ø Fixup 36,3 + Re-Review 17,8, Stand 2026-09, Quelle .costs/). Nie einen Prüfschritt überspringen, um Turns zu sparen: der Tausch geht immer zulasten des Kontingents.
• Verbessern vs. Erweitern: Soll Funktionierendes verbessert werden, zuerst fragen: Ist der Gewinn den zusätzlichen Code und seine Wartung wert — oder entsteht er durch Optimieren vorhandenen Codes? Neue Mechanismen nur, wenn kein bestehendes Muster passt. Beispiel: Der Push-Schalter flackerte beim Seitenwechsel, weil sein Zustand nur async ermittelbar war — behoben mit einem localStorage-Spiegel nach dem Muster der Nachbar-Switches (frontend/src/lib/push.ts, ~15 Zeilen am vorhandenen Hook statt eines neuen Mechanismus).
• Muster-Treue: Reproduktion, Erweiterung und Adaption setzen das vorhandene Muster einheitlich fort — gleiche Struktur, Namen, Ablagen und Style wie der Nachbar-Code (Konventionen). Kein zweites Muster für dasselbe Problem; wer bewusst abweicht, begründet es im PR und führt die Abweichung konsequent überall durch. Nur so bleiben Muster langfristig nachvollziehbar, pflegbar, review- und refaktorierbar.
• KoliBri-First: Komponenten nur selbst stylen, wenn keine KoliBri-Komponente passt (Shadow-Web-Components; Shadow-DOM-CSS ist unpublizierte API).
• Schichten-Trennung Pipeline: .github/ orchestriert (Trigger, Gates, Label-Mechanik; Ein-/Ausgabeprotokoll der LLM-Läufe in .github/prompts/), .claude/skills/ tragen die orchestrator-neutrale Rollen-Methode — dort gehören keine Workflow-Namen, .github-Pfade, VERDICT-Tokens, {{Platzhalter}} oder Laufzeit-Mechanik hinein. GitHub-Plattform-Vertrag (gh-Befehle, Label-Namen, HTML-Marker, Kommentarformate) bleibt im Skill.
• Monorepo mit pnpm; TypeScript strict, ESM überall, Node >=26.
• ASCII in maschinen-gelesenen Feldern: YAML-Frontmatter, Verdict-Zeilen, HTML-Marker und ähnliche strukturierte Felder ohne sprachspezifische Sonderzeichen/Umlaute halten — gemischte Anführungszeichen („"“/") haben schon Parser gebrochen (Extension-Load, Verdict-Auswertung). Fließtext in Doku/Prompts bleibt unverändert Deutsch.
• pnpm format (Prettier, zentrale Root-Config) und pnpm lint — gezielt statt repo-weit: pnpm --filter server build|lint.
• Nicht automatisch committen ohne ausdrücklichen Wunsch. Ausnahme: die Ticket-Workflows (Spec, Umsetzung — beide Eingänge) committen, pushen und erstellen/aktualisieren PRs als ausdrücklichen Teil ihres Auftrags, inkl. eines etwaigen Memory-Eintrags im Phasen-Commit.
• Kanonisches Gate (Spiegel der CI-Verify-Kette, TDD-Strategie Stufe 2): Jeder PR führt vor dem Push pnpm format && pnpm exec prettier --check . && pnpm lint && pnpm -r build && pnpm test aus — grün ist Pflicht; E2E scoped: nur die Playwright-Specs der berührten UI-Fläche, sofern eine existiert (CI fährt die volle Suite sharded über jeden App-Code-PR). Ergebnisse in die PR-Beschreibung. pnpm knip bleibt bewusste Zusatzschärfe des Implement-Skills, nicht Teil des kanonischen Gates.

Memory

.ai-memory/ (nativer Claude-Code-Memory, autoMemoryDirectory in .claude/settings.json) hat zwei Ebenen:

Lesen: immer beide, MEMORY.md zuerst — auch beim ersten Lauf an einem Ticket.

Schreiben (nur MEMORY.md, Aufnahmekriterium streng — im Zweifel kein Eintrag): nur was einen zukünftigen Lauf an einem anderen Ticket vor demselben Fehler oder Umweg bewahrt: nicht-offensichtliche Werkzeug-/CI-Eigenheiten, ein Befehl, der erst nach Fehlversuchen funktionierte. Nicht hierher: Ticket-Spezifisches (→ Phasen-Notiz), in AGENTS.md/.ai-knowledge Stehendes, Selbstverständliches, Erfolgsmeldungen. Die meisten Läufe schreiben gar nichts — Normalfall.

Format: eine Zeile - YYYY-MM-DD · <Bereich> — <was schiefging> → <Lösung>. ans Ende von ## Learnings & Erfahrungen. Bestehende Zeilen nie umschreiben oder umsortieren — die Datei mergt per union (.gitattributes), was nur bei reinem Anhängen konfliktfrei trägt; Prettier fasst sie bewusst nicht an (.prettierignore).

Wer committet: niemand — Phasen-Notizen sind gitignored und reisen als Workflow-Artefakt (ADR 0010). MEMORY.md reist allein im normalen Phasen-Commit (Spec, Umsetzung — beide Eingänge), kein eigener Commit, kein Push auf main. Phasen ohne Branch (Triage, UX, Review) legen den Kandidaten unter ## Fallstricke ihrer Phasen-Notiz ab. Lokale Sessions dürfen anhängen, aber nicht selbst committen — Eintrag vorschlagen, er reist mit dem nächsten regulären Commit mit.

Kuratierung: max. ~40 Einträge. Zur festen Regel Gewordenes nach Konventionen überführen und die Zeile entfernen — MEMORY.md ist ein Erfahrungs-Log, kein Regelwerk.

KI-Pipeline (CI)

Sechs KI-gesteuerte Phasen über Claude Code in GitHub Actions: Triage → UX-Beratung → Spec → Umsetzung (Erstumsetzung und Review-Nacharbeit, ADR 0005) → Review → PR-Documenter (nach dem Merge). Gesteuert über die Label-Kette ai:needs-* → ai:<Vergangenheitsform>; Start immer manuell durch ai:needs-analyse. Ablauf, Trigger, Info-Labels: Pipeline-Flow. Provider, Modelle, Soft-Abort, MCP-Integration (KoliBri-MCP in allen Phasen außer Documenter, Playwright-MCP in Umsetzung und Fixup): CI-Architektur.

Jede Phase liest nur ihren eigenen Phase-Skill (siehe Wissensbasis) plus das Issue/PR — kein domänenübergreifendes Lesen. Routing (Modell-Label ai:model:*, Spec-Skip) entscheidet die Triage je Subtask im KI-ANALYSE-Abschnitt des Harness-Kommentars (ADR 0009) — Details: ADR 0004, Triage-Skill.

Tests (Server)

Testkonzept: docs/testing.md. pnpm --filter server test — node:test + tsx, In-Memory-SQLite, Tests unter server/src/**/*.test.ts.

Tests (Frontend)

pnpm --filter frontend test — Vitest + jsdom + Testing Library, Tests unter frontend/src/**/*.test.{ts,tsx}.

pnpm --filter frontend test:e2e — Playwright (nur Chromium), Specs unter frontend/e2e/, gegen das echte Backend (temporäre In-Memory-DB, kein page.route-Mocking). Läuft nicht als Teil von pnpm test — nur separat über test:e2e.