brain-ios – Projektsteuerung für Claude Code

Auftrag: @ARCHITECTURE.md (Single Source of Truth) Log: @SESSION-LOG.md | Reviews: @REVIEW-NOTES.md

Ein Dokument, eine Wahrheit. ARCHITECTURE.md definiert Vision, Runtime-Engine, Primitives, Phasen und alle Architektur-Entscheidungen. Bei Widersprüchen gilt ARCHITECTURE.md.

Kern-Konzept

brain-ios ist eine Runtime-Engine, keine App mit fest codierten Modulen.

.brainskill.md  →  KI (Ribosom)  →  skill.json  →  Runtime Engine  →  Native UI + Aktionen
   (DNA)                              (Protein)       (Zelle)

• UI Primitives: Vorkompilierte SwiftUI-Komponenten (~90 Stück), via JSON zusammengesetzt
• Action Primitives: Vorkompilierte Swift-Handler (~60 Stück), via JSON aufgerufen
• Logic Primitives: Bedingungen, Schleifen, Variablen, Templates (~15 Stück)
• Skill Engine: KI übersetzt .brainskill.md → skill.json
• Proaktive Intelligenz: Mustererkennung als nativer Code (nicht JSON-getrieben)

Die App shipped mit dem Bootstrap-Skill Dashboard, der genauso via JSON definiert ist wie user-generierte Skills; Mail, Kalender, Kontakte und Schnellerfassung sind seit Maerz 2026 native Views (ARCHITECTURE.md, Implementierungsstand). Kein Unterschied zwischen "eingebaut" und "generiert".

Dokumentations-Pflicht bei Commits

Bei jedem Commit muessen folgende Dokumentationen aktualisiert werden:

1. SESSION-LOG.md: Was wurde geaendert, warum, welche Entscheidungen
2. REVIEW-NOTES.md: Neue Findings oder Status-Updates bestehender Findings
3. ARCHITECTURE.md: NUR wenn architektonische Aenderungen gemacht wurden

Bei jedem Push zusaetzlich: 4. Pruefen ob Build-Nummer in project.pbxproj erhoeht werden muss (Xcode Cloud triggered bei push auf main)

Build & Test

# Xcode Build + Test (auf macOS mit Xcode)
xcodebuild test -scheme brain-ios -destination 'platform=iOS Simulator,name=iPhone 16'

# SPM-only Packages (auch auf Linux/VPS möglich)
swift test

WICHTIG: brain-ios Entwicklung erfordert macOS mit Xcode. Auf dem VPS kann man Swift Packages entwickeln und testen, aber UI-Code und iOS-Simulator-Tests brauchen einen Mac. Wenn Tests nicht ausführbar sind: im SESSION-LOG dokumentieren, weitermachen.

Package-Struktur für VPS-Entwicklung: Die Runtime-Engine (Render Engine, Action Engine, Logic Engine, Expression Parser) wird als eigenständiges Swift Package entwickelt, das auch auf Linux testbar ist. Nur die SwiftUI-Views und iOS-Bridge-Schicht brauchen Xcode.

Deployment (Xcode Cloud → TestFlight)

Deployment läuft über Xcode Cloud → TestFlight. Kein manuelles Signing nötig.

Seit 03.09.2026 gibt es zusaetzlich den GitHub-Actions-Workflow TestFlight (manuell via workflow_dispatch), der ohne Mac und ohne Xcode Cloud archiviert, mit fastlane match signiert und zu TestFlight hochlaedt. Setup und benoetigte Secrets: docs/TESTFLIGHT-CI.md.

# Build-Nummer erhöhen (im Xcode-Projekt oder via Script)
# Push zu main → Xcode Cloud baut automatisch → TestFlight
git push origin main

Bei Deployment-Fragen, Build-Fehlern oder TestFlight-Builds: Der installierte Desktop-Skill /xcode-cloud-deploy kennt alle bekannten Fehler (Exit Code 65/70, Signing, Package Resolution) und den korrekten Workflow. Wird automatisch ausgelöst bei Erwähnung von brain-ios, TestFlight, Xcode Cloud oder Build-Fehlern.

Lessons Learned: Skills/xcode-cloud-lessons-learned.brainskill.md dokumentiert den gesamten Xcode Cloud Setup-Prozess und alle gelösten Build-Probleme (51+ Builds).

Wichtig:

• Automatisches Signing (Xcode Cloud verwaltet Zertifikate)
• Echte Identifier (Bundle-ID-Basis, Team-ID, Google-Client-ID) kommen aus Config/Local.xcconfig (gitignored; Vorlage Config/Local.xcconfig.example) bzw. auf Xcode Cloud aus den Environment-Variablen BRAIN_BUNDLE_ID_BASE, BRAIN_TEAM_ID, BRAIN_GOOGLE_CLIENT_ID, die ci_post_clone.sh in die Local.xcconfig schreibt. Nie echte IDs committen.
• Package.resolved muss im Repo sein
• objectVersion 56 in .pbxproj (Kompatibilität)

Git Remote

• Repo: IjonTychy/brain-ios (Public seit 28.03.2026, Unlicense)
• Branch: main (seit Public Release; vorher master)
• Push: git push origin main

Sicherheitsregel: Der PAT wird ausschliesslich via $GITHUB_TOKEN oder ~/.git-credentials konfiguriert. Nie in Dokumenten, Commits oder Agent-Outputs.

Lokale Kopien

Das Projekt existiert an mehreren Orten:

Nach Commits: git push origin main, dann auf VPS und Backup jeweils git pull.

Code-Konventionen

• Swift 6 mit strict concurrency (-strict-concurrency=complete)
• SwiftUI für alle Views — kein UIKit ausser wo nötig (PencilKit, Scanner)
• MVVM mit @Observable (Observation framework)
• async/await überall — kein Combine (ausser wo SwiftUI es erfordert)
• Tests: XCTest + Swift Testing (@Test macro)
• Formatting: swift-format (Apple)
• UI-Texte: Deutsch
• Code-Kommentare: Englisch
• Kein Force-Unwrapping (!) ausserhalb von Tests
• Naming: Swift API Design Guidelines (camelCase, clear at point of use)
• Error Handling: Typed errors wo sinnvoll, Result oder throws
• Access Control: Explizit — internal ist OK, public nur für Module-API

Architektur-Entscheidungen (unveränderlich ohne explizite Freigabe)

1. Runtime-Engine Architektur: App ist eine Engine, keine Sammlung von Modulen. Alles wird via JSON-Skills gerendert und ausgeführt.
2. Kein VPS — alles lokal auf dem Gerät
3. SwiftUI only — kein UIKit ausser wo nötig (PencilKit, Scanner)
4. GRDB + SQLiteData statt SwiftData/CoreData
5. Offline-First: Alles funktioniert ohne Internet
6. Multi-LLM Router: Nie an einen Anbieter gebunden
7. Skill-Format: .brainskill.md (Markdown + YAML Frontmatter), KI kompiliert zu JSON
8. Bootstrap-Skills: Dashboard, Inbox, Kalender sind Skills (nicht hardcodiert)
9. Proaktive Intelligenz: Nativer Code, nicht JSON-getrieben (Performance-kritisch)
10. Geschäftsmodell: Einmalkauf, kein Abo
11. iPhone + iPad + Vision Pro (ein Codebase)
12. Face ID statt Passwort/JWT
13. API-Keys in iOS Keychain — nie im Binary
14. Entry als Herzstück — alles ist ein Entry
15. App-Store-Konformität: JSON ist Konfiguration, nicht Code. Alle Komponenten vorkompiliert. Kein Hot-Code-Loading.
16. Kein eigener Skill-Marktplatz: Offene Import/Export-Schnittstelle

Agent-Architektur (Middle-Manager-Muster)

Du bist der "Middle Manager". Du implementierst nicht alles selbst, sondern delegierst an spezialisierte Worker-Agents.

Verfügbare Agents

Pflicht-Workflow pro Implementierungsschritt

1. Architektur-Frage?  → Agent: arch-consultant
2. Implementieren (du selbst)
3. Tests              → Agent: test-architect
4. Pre-Commit         → Agent: code-reviewer
5. Commit (nur wenn code-reviewer OK meldet)

Kontextfenster-Hygiene

• Delegiere IMMER an Agents statt selbst grosse Dateien zu lesen
• Wenn Kontext voll → Session sauber beenden, SESSION-LOG sichert Kontinuität

Phase-Gate-Modell

Innerhalb einer Phase (autonom):

1. Implementiere Schritt für Schritt gemäss Phasen-Scope
2. Nach jedem Schritt: Tests ausführen
3. Tests rot → Fix, wiederholen bis grün
4. Tests grün → Committen, nächsten Schritt beginnen
5. Bei Unklarheiten: SESSION-LOG dokumentieren, weitermachen wenn möglich

Am Phasenende (manuelles Gate):

1. Alle Tests grün (oder dokumentiert warum nicht)
2. SESSION-LOG aktualisieren
3. Dokumentieren: "Phase X abgeschlossen. Bereit für Review."
4. Committen und Session beenden
5. NICHT eigenständig die nächste Phase beginnen

Bei Session-Start:

1. STOP-SESSION.md prüfen
2. REVIEW-NOTES.md lesen → Offene Findings haben Priorität
3. SESSION-LOG.md lesen → Aktueller Stand
4. Dieses Dokument lesen → Current Objective
5. Findings abarbeiten, DANN Phasen-Scope fortsetzen

Stop-Bedingungen:

• STOP-SESSION.md existiert
• Nativer Build-Fehler der nicht ohne Xcode lösbar ist
• Externe Dependency nicht via SPM verfügbar
• 3+ aufeinanderfolgende Testfailures ohne Fortschritt
• Scope-Erweiterung über den Auftrag hinaus

SESSION-LOG Format:

## Session [Datum]
### Abgeschlossen
- **Phase X, Step Y: [Name]** (Commit `hash`) – Stichpunkte
### Entscheidungen
- [Entscheidung]: Begründung
### Tests
- [Testname]: OK/FAIL
### Offene Probleme
- [Problem]: Beschreibung
### Nächster Schritt
- Phase/Step oder "Phase X abgeschlossen. Bereit für Review."
### Systemzustand
- OK/Ausstehend

Kontinuitäts-Garantie

Master Agent (liest nur Signale)
  └── Middle Manager Session N (startet frisch)
        ← SessionStart: CLAUDE.md + SESSION-LOG + REVIEW-NOTES
        ├── @arch-consultant   (stateless)
        ├── @test-architect    (stateless)
        ├── @code-reviewer     (stateless)
        → Stop-Hook: SESSION-LOG aktualisieren
  └── Middle Manager Session N+1 (startet frisch)
        ← Liest aktualisiertes SESSION-LOG

Verfügbare Claude Code Skills (Desktop-App)

Diese Skills sind in Andys Claude Desktop-App installiert und stehen in jeder Session zur Verfügung:

Current Objective

Update 03.09.2026 (Deploy): Erster TestFlight-Build ohne Mac: Der GitHub-Actions-Workflow TestFlight (fastlane match + pilot) hat Build 1005 signiert und hochgeladen (Lauf 5). Xcode Cloud bleibt beim Export an einem Apple-seitigen Auth-Fehler haengen; Startbedingung dort auf manuell. Fix auf dem Weg: Google-Client-ID-Platzhalter RFC-1738-konform (placeholder-google-client-id). Details: SESSION-LOG 03.09.2026.

Update 03.09.2026: God Objects gesplittet: EmailBridge, MailTabView, SkillManagerView und OnboardingView entlang der Top-Level-Deklarationen in 16 Dateien zerlegt (groesste Datei jetzt 690 Zeilen), um Type-Checker-Timeouts im Xcode-Cloud-Build vorzubeugen. Zudem akzeptieren die Rohtext-LLM-Steps ein explizites privacyLevel (vom Router durchgesetzt), und die Kompilier-Views zeigen das tatsaechlich bedienende Modell. Details: SESSION-LOG 03.09.2026.

Update 02.09.2026: LLMRouter im Chat verdrahtet -- Privacy Zones und Offline-Routing werden jetzt bei jedem Send durchgesetzt (fail-loud statt stillem Cloud-Fallback); Auto-Route-Sticky-Bug und "on-device"-als-OpenAI- Fehlrouting behoben. brain-api-Auth-Schicht restlos entfernt (Service, UI, Keychain-Keys, /claude-proxy-Suffix) -- Proxy-Modus ist jetzt generisch OpenAI-kompatibel. Zudem Provider-Auswahl in LLMProviderFactory konsolidiert: Auch der AI-Handler-Pfad (DataBridge.buildLLMProvider) laeuft jetzt ueber den Router; Entry-basierte Handler setzen Privacy Zones durch (PR #2 auf main). Deploy-Vorarbeit: deploy-relevante Identifier laufen ueber Config/*.xcconfig

• AppIdentifiers.swift; Extensions haben jetzt App-Group-Entitlements. Details: SESSION-LOG 02.09.2026.

Update 04.07.2026 (Wiederaufnahme nach Public Release): CI repariert (Trigger main + claude/**, pipefail, libsqlite3-dev), 2 rote Test-Assertions gefixt, Expression-Sprache auf das dokumentierte Vokabular ausgebaut (and/or/not, contains, matches, Array-Indexing, Datums-Mathematik, Filter mit Argumenten), executeSet-Template-Bug behoben, actions_json wird jetzt semantisch gegen den Handler-Katalog validiert, StoreKit-Trial in Keychain gehaertet, Gemma-4-On-Device-Backend (Katalog + Download + Provider) integriert, GRDB auf 7.11.1 (Linux-Fixes). Details: SESSION-LOG 04.07.2026.

Aktueller Snapshot (04.07.2026)

Bei Konflikten gilt dieser Snapshot vor aelteren Zahlen in diesem Dokument.

• Repo-Status: Public Release 28.03.2026 (Unlicense): Historie gesquasht (2 Commits + neue Arbeit), Default-Branch main, alle Identifier anonymisiert (com.example.brain-ios). Seit 02.09.2026 kommen die echten IDs fuer den privaten Build aus der gitignorierten Config/Local.xcconfig (bzw. Xcode-Cloud-Env-Vars) — das oeffentliche Repo bleibt anonym.
• CI: GitHub Actions laufen wieder (main + claude/** Branches). Linux-Job baut BrainCore erstmals nachweisbar; iOS-Job nutzt neuestes Xcode + dynamische Simulator-Wahl. pipefail aktiv — keine maskierten Fehler mehr.
• Engine: ExpressionParser implementiert das in ARCHITECTURE.md dokumentierte Vokabular vollstaendig. skill.create validiert actions_json semantisch (wahrscheinliche Root Cause des Skill-Qualitaetsproblems behoben).
• On-Device: Apple Foundation Models + Gemma 4 E2B/E4B (GGUF-Katalog, Download nach Bedarf). Gemma-Inferenz benoetigt einmalig das llama.cpp-Package in Xcode (docs/ON-DEVICE-MODELS.md).
• Datenhaltung: App, Widgets, Share Extension und App Intents greifen ueber SharedContainer auf dieselbe SQLite-Datei im App-Group-Container zu.
• LLM-Stack: Anthropic, OpenAI, Gemini, On-Device (Apple + Gemma) sowie xAI/custom ueber OpenAICompatibleProvider.
• Verifizierte Repo-Metriken (03.07.): 216 getrackte Swift-Dateien, ~53'400 LOC, 590 @Test-Funktionen, 6 gebuendelte .brainskill.md.
• Erledigt (Doku war veraltet): Mail-Delete-Sync (Tombstones + IMAP-Expunge) und StoreKit (StoreKit 2, Trial + Einmalkauf) sind implementiert.
• Offene Baustellen: Echte Bundle-IDs wiederherstellen, llama.cpp-Package aktivieren, Device-Verifikation (OAuth, Runtime-Fixes, Gemma). God Objects sind seit 03.09.2026 gesplittet. LLM-Routing ist seit 02.09.2026 konsolidiert (LLMProviderFactory): Chat- und AI-Handler-Pfad laufen ueber den LLMRouter mit Privacy-/Offline-Gate.

Historischer Snapshot 23.03.2026: App ist funktional, TestFlight aktiv, 540+ Tests grün. Google OAuth, Multi-Provider (7 LLM Provider), modularer System-Prompt. Grosse Dateien aufgeteilt (4 God Objects eliminiert), ~960 Zeilen Dead Code/Duplikate entfernt. 23 Bridges, 158+ Handler, 121+ Tools, 7 LLM Provider, 160+ Commits.

App Store Readiness

Aktuelle Prioritaeten (04.07.2026)

Siehe SESSION-LOG für letzten Stand und offene Punkte.

Phasen-Übersicht (alle abgeschlossen)

Bekannte Probleme

• Kein Certificate Pinning mehr (seit 03.09.2026): Die SPKI-Pins vom Maerz waren auf dem Geraet stale und blockierten jede LLM-Verbindung ("API-Key ungueltig" bei allen Providern). LLM-Requests laufen jetzt ueber LLMURLSession mit System-TLS; Pinning ist ohne Pin-Nachlieferung fuer CDN-gehostete APIs nicht betreibbar (Begruendung in LLMURLSession.swift).
• Runtime-Fixes noch nicht auf Device verifiziert: Kontakte-Tab, Skills, Skill-Import/Kompilierung, Self-Improve-Handoff und Shortcuts/App-Intents wurden code-seitig repariert, aber in dieser Umgebung nicht via Xcode/iOS-Geraet getestet.
• BrainTheme nur teilweise ausgerollt: Design-System existiert, wird aber noch nicht durchgaengig in allen produktiven Views genutzt.
• Primitive-Luecke: Wenn ein Skill ein Action Primitive braucht das nicht existiert, braucht es ein App-Update.
• 64 Notification Limit: Reschedule-on-Launch Pattern.
• Anonymisierte Identifier (vorbereitet, 02.09.2026): Bundle-IDs, App Group, iCloud-Container, BGTask-IDs und Google-Client-ID kommen aus Config/Base.xcconfig (Platzhalter) + gitignorierter Config/Local.xcconfig (echte Werte, Vorlage Local.xcconfig.example); Xcode Cloud erhaelt sie via Environment-Variablen (ci_post_clone.sh). Ohne befuellte Local.xcconfig baut die App weiterhin mit com.example-Platzhaltern (CI) — kein Device-Deploy.
• Gemma-Inferenz noch nicht aktiv: Provider/Katalog/Downloads sind eingebaut; das llama.cpp-Package muss einmalig in Xcode hinzugefuegt und auf einem Geraet verifiziert werden (docs/ON-DEVICE-MODELS.md).
• Rohtext-Privacy nur per Skill-Property: ai.draftReply und llm.*-Handler koennen kein Entry-Level ableiten; seit 03.09.2026 pinnt das optionale privacyLevel im Step den Router. Ohne Property laufen sie unrestricted (Default, kompatibel mit bestehenden Skills).
• Google OAuth braucht User-Setup: PKCE Flow, Token-Refresh und Keychain-Storage sind implementiert; die Client-ID muss weiterhin vom User in Google Cloud Console erstellt werden.
• brain-api abgeschaltet: VPS-Backend nicht mehr aktiv. Backup unter /home/andy/brain-api-backup/.
• User-Profil-Import ausstehend: brain-profil.md + user-profil.md unter /home/andy/brain-api-backup/ bereit.
• Background Fetch unzuverlaessig: Shortcuts Automations bleiben der Backup-Pfad.

Projekt-Inventar

Repo-Struktur

brain-ios/
├── ARCHITECTURE.md              # Architektur & Vision (Single Source of Truth)
├── CLAUDE.md                    # Projektsteuerung (dieses Dokument)
├── SESSION-LOG.md               # Session-Journal (Phase 17+)
├── REVIEW-NOTES.md              # Review-Protokoll (2 Gross-Reviews, 40+ Findings)
├── Package.swift                # SPM Package Definition (BrainCore)
├── Config/                      # Base.xcconfig (Platzhalter) + Local.xcconfig (gitignored, echte IDs)
├── BrainApp.xcodeproj/          # Xcode Projekt
├── Sources/
│   ├── BrainCore/               # SPM Package (auch auf Linux testbar)
│   └── BrainApp/                # iOS App (SwiftUI Views, Services; Bridges/, Handlers/, LLMProviders/)
├── Tests/                       # BrainCoreTests + BrainAppTests
├── Skills/                      # 6 .brainskill.md Dateien plus Prompt-Assets
├── ci_scripts/                  # Xcode Cloud Build-Scripts
├── .github/workflows/           # GitHub Actions CI (tests.yml + ios-build.yml)
├── docs/archive/                # Archivierte Plandokumente
└── .claude/
    ├── settings.json            # Hooks (SessionStart, PreToolUse, Stop)
    └── agents/                  # arch-consultant, test-architect, code-reviewer, zora-review

Inventar-Update (25.03.2026)

• Swift-Dateien: 215 getrackte .swift-Dateien im Repo
• Tests: 579 @Test(...)-Marker in Sources/ und Tests/
• Commits: 502 Commits in HEAD
• Skills: 6 gebuendelte .brainskill.md-Dateien in Skills/
• LLM-Provider-Dateien: AnthropicProvider, GeminiProvider, OpenAIProvider, OpenAICompatibleProvider, OnDeviceProvider
• Provider-Stack fachlich: Anthropic, OpenAI, Gemini, On-Device sowie xAI/custom ueber OpenAICompatibleProvider

Historische Kennzahlen (Stand 23.03.2026)

• Commits: 160+
• Tests: 540+ (BrainCore + BrainApp, alle grün)
• Gebundelte Dokumente: Ethiksystem + Alignment-Ableitung (als Entries importiert)
• Skills: 3 .brainskill.md Dateien
• Swift-Dateien: 190+ (BrainApp: 100+, BrainCore: 46, Tests: 34)
• UI Primitives: ~90
• Action Handler Klassen: ~158 (in 10 Handler-Dateien + Bridge-Dateien)
• iOS Bridges: 23
• Tool-Definitionen: 121
• LLM Provider: 7 (Anthropic, OpenAI, Gemini, xAI Grok, Custom, OnDevice, Shortcuts)
• Logic Primitives: ~15
• App Intents (Siri/Shortcuts): 12
• Xcode Cloud Builds: 234+ (Frontend Overhaul Session)
• TestFlight: Aktiv