AGENTS.md - Kids AI Train Projekt

Letzte Aktualisierung: 2025-12-16

WICHTIG: LIES DIES KOMPLETT BEVOR DU ARBEITEST

1. Projekt-Übersicht

Kids AI Train ist ein Multi-Repo Projekt für Kinder-Lern-Apps mit KI-Sprachassistent.

Repos auf GitHub (Organisation: devshift-stack)

Repo	Beschreibung	GitHub URL
Kids-AI-Shared	Gemeinsamer Code (Widgets, Services, Models)	https://github.com/devshift-stack/Kids-AI-Shared
Kids-AI-Train-Alanko	Alanko App (Kinder 3-12)	https://github.com/devshift-stack/Kids-AI-Train-Alanko
Kids-AI-Train-Lianko	Lianko App (Kinder 3-12)	https://github.com/devshift-stack/Kids-AI-Train-Lianko
Kids-AI-Train-Parent	Eltern-Dashboard	https://github.com/devshift-stack/Kids-AI-Train-Parent

Lokale Pfade

~/devshift-stack/
├── Kids-AI-Shared/         ← Gemeinsamer Code
├── Kids-AI-Train-Alanko/   ← Alanko App
├── Kids-AI-Train-Lianko/   ← Lianko App
└── Kids-AI-Train-Parent/   ← Eltern-Dashboard

2. GOLDENE REGEL: NUR MIT PULL REQUESTS ARBEITEN

NIEMALS direkt auf main pushen!

Immer:

Neuen Branch erstellen
Änderungen committen
Pull Request erstellen
Review abwarten
Erst nach Approval wird gemerged

3. Workflow für jeden Task

Schritt 1: Repo klonen (falls nicht vorhanden)

# Für Shared
cd ~/devshift-stack
gh repo clone devshift-stack/Kids-AI-Shared

# Für Alanko
gh repo clone devshift-stack/Kids-AI-Train-Alanko

# Für Lianko
gh repo clone devshift-stack/Kids-AI-Train-Lianko

# Für Parent
gh repo clone devshift-stack/Kids-AI-Train-Parent

Schritt 2: Aktuellen Stand holen

cd ~/devshift-stack/[REPO-NAME]
git checkout main
git pull origin main

Schritt 3: Neuen Branch erstellen

Branch-Naming-Convention:

feature/beschreibung - Neue Features
fix/beschreibung - Bug Fixes
refactor/beschreibung - Code Refactoring
docs/beschreibung - Dokumentation

git checkout -b feature/mein-neues-feature

Schritt 4: Änderungen machen und committen

# Änderungen machen...

git add -A
git commit -m "feat: Beschreibung der Änderung"

Commit-Message-Format:

feat: - Neues Feature
fix: - Bug Fix
refactor: - Code Refactoring
docs: - Dokumentation
style: - Formatting, keine Code-Änderung
test: - Tests hinzufügen

Schritt 5: Branch pushen

git push -u origin feature/mein-neues-feature

Schritt 6: Pull Request erstellen

gh pr create --title "feat: Mein neues Feature" --body "## Summary
- Was wurde gemacht

## Test plan
- [ ] Getestet auf iOS
- [ ] Getestet auf Android"

4. Welches Repo für welche Änderung?

Kids-AI-Shared (Gemeinsamer Code)

Hier ändern wenn:

Widgets die in ALLEN Apps genutzt werden
Services die in ALLEN Apps genutzt werden
Models die in ALLEN Apps genutzt werden
Utility-Funktionen für ALLE Apps

Struktur:

Kids-AI-Shared/
├── lib/
│   ├── kids_ai_shared.dart    ← Haupt-Export
│   └── src/
│       ├── widgets/           ← Gemeinsame Widgets
│       ├── services/          ← Gemeinsame Services
│       ├── models/            ← Gemeinsame Models
│       └── utils/             ← Utility-Funktionen
└── pubspec.yaml

Nach Push in Shared: Alle Apps müssen flutter pub get ausführen um die Änderungen zu holen!

Kids-AI-Train-Alanko (Alanko App)

Hier ändern wenn:

Features NUR für Alanko
Alanko-spezifische UI
Alanko-spezifische Logik
Alanko Assets (Bilder, Sounds, Übersetzungen)

Struktur:

Kids-AI-Train-Alanko/
├── lib/
│   ├── main.dart
│   ├── screens/               ← Alanko Screens
│   ├── widgets/               ← Alanko-spezifische Widgets
│   └── services/              ← Alanko-spezifische Services
├── assets/
│   └── locales/               ← Übersetzungen
└── pubspec.yaml

Kids-AI-Train-Lianko (Lianko App)

Hier ändern wenn:

Features NUR für Lianko
Lianko-spezifische UI
Lianko-spezifische Logik
Lianko Assets (Bilder, Sounds, Übersetzungen)

Struktur:

Kids-AI-Train-Lianko/
├── lib/
│   ├── main.dart
│   ├── screens/               ← Lianko Screens
│   ├── widgets/               ← Lianko-spezifische Widgets
│   └── services/              ← Lianko-spezifische Services
├── assets/
│   └── locales/               ← Übersetzungen
└── pubspec.yaml

Kids-AI-Train-Parent (Eltern-Dashboard)

Hier ändern wenn:

Features für Eltern-Dashboard
Statistiken und Reports
Kinderprofil-Verwaltung
Parent-spezifische UI

Struktur:

Kids-AI-Train-Parent/
├── lib/
│   ├── main.dart
│   ├── screens/               ← Dashboard Screens
│   ├── widgets/               ← Dashboard Widgets
│   └── services/              ← Dashboard Services
├── assets/
│   └── locales/               ← Übersetzungen
└── pubspec.yaml

5. Vollständiges Beispiel: Feature für Lianko

# 1. Ins Repo wechseln
cd ~/devshift-stack/Kids-AI-Train-Lianko

# 2. Main aktualisieren
git checkout main
git pull origin main

# 3. Neuen Branch erstellen
git checkout -b feature/neuer-lernspiel-screen

# 4. Änderungen machen
# ... Code schreiben ...

# 5. Committen
git add -A
git commit -m "feat: Add new learning game screen for numbers"

# 6. Branch pushen
git push -u origin feature/neuer-lernspiel-screen

# 7. Pull Request erstellen
gh pr create --title "feat: Add new learning game screen for numbers" --body "$(cat <<'EOF'
## Summary
- Added new numbers learning game screen
- Includes voice feedback
- Age-adaptive difficulty

## Test plan
- [ ] Tested on iOS Simulator
- [ ] Tested on Android Emulator
- [ ] Voice feedback works
EOF
)"

Output: PR URL wird angezeigt

6. Vollständiges Beispiel: Gemeinsames Widget in Shared

# 1. Ins Shared Repo wechseln
cd ~/devshift-stack/Kids-AI-Shared

# 2. Main aktualisieren
git checkout main
git pull origin main

# 3. Neuen Branch erstellen
git checkout -b feature/animated-button-widget

# 4. Widget erstellen
mkdir -p lib/src/widgets
cat > lib/src/widgets/animated_button.dart << 'EOF'
import 'package:flutter/material.dart';

class AnimatedButton extends StatelessWidget {
  final String text;
  final VoidCallback onPressed;

  const AnimatedButton({
    super.key,
    required this.text,
    required this.onPressed,
  });

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: onPressed,
      child: Text(text),
    );
  }
}
EOF

# 5. Export hinzufügen
echo "export 'src/widgets/animated_button.dart';" >> lib/kids_ai_shared.dart

# 6. Committen
git add -A
git commit -m "feat: Add AnimatedButton widget"

# 7. Branch pushen
git push -u origin feature/animated-button-widget

# 8. Pull Request erstellen
gh pr create --title "feat: Add AnimatedButton widget" --body "$(cat <<'EOF'
## Summary
- Added reusable AnimatedButton widget
- Can be used in all Kids AI apps

## Usage
```dart
import 'package:kids_ai_shared/kids_ai_shared.dart';

AnimatedButton(
  text: 'Click me',
  onPressed: () {},
)

Test plan

Widget renders correctly
OnPressed callback works EOF )"


**WICHTIG: Nach Merge in Shared müssen alle Apps aktualisiert werden:**

```bash
# In Alanko
cd ~/devshift-stack/Kids-AI-Train-Alanko
flutter pub get

# In Lianko
cd ~/devshift-stack/Kids-AI-Train-Lianko
flutter pub get

# In Parent
cd ~/devshift-stack/Kids-AI-Train-Parent
flutter pub get

7. Entscheidungshilfe: Wo gehört mein Code hin?

Frage: Wird dieser Code in mehr als einer App genutzt?
│
├─► JA → Kids-AI-Shared
│
└─► NEIN → Welche App?
    │
    ├─► Alanko App → Kids-AI-Train-Alanko
    ├─► Lianko App → Kids-AI-Train-Lianko
    └─► Eltern-Dashboard → Kids-AI-Train-Parent

8. Verbotene Aktionen

❌ NIEMALS:

Direkt auf main pushen
git push --force auf main
Secrets/API-Keys committen
.env Dateien committen
node_modules oder build-Ordner committen

✅ IMMER:

Neuen Branch erstellen
Pull Request erstellen
Aussagekräftige Commit-Messages
Code vor Push testen

9. Shared Code importieren

In jeder App (Alanko, Lianko, Parent):

import 'package:kids_ai_shared/kids_ai_shared.dart';

// Dann nutzen:
AnimatedButton(text: 'Klick', onPressed: () {});

Die Dependency ist bereits in pubspec.yaml:

dependencies:
  kids_ai_shared:
    git:
      url: https://github.com/devshift-stack/Kids-AI-Shared.git

10. Firebase Setup

Accounts & Projekte

Account	Firebase Projekt	Apps
`admin@step2job.com`	`wonderbox-a944e`	Alanko, Lianko, Parent

Firebase CLI Login

# Status prüfen
firebase login:list

# Falls nicht eingeloggt oder Token abgelaufen:
firebase logout
firebase login
# → Browser öffnet sich → Mit admin@step2job.com einloggen

# Projekte anzeigen (Test ob Login funktioniert)
firebase projects:list

FlutterFire CLI Setup

# CLI installieren
dart pub global activate flutterfire_cli

# Konfigurieren (erstellt Config-Dateien automatisch)
flutterfire configure \
  --project=wonderbox-a944e \
  --platforms=android,ios \
  --android-package-name=com.alanko.ai \
  --ios-bundle-id=com.alanko.ai

Config-Dateien

Datei	Plattform	Pfad
`google-services.json`	Android	`android/app/google-services.json`
`GoogleService-Info.plist`	iOS	`ios/Runner/GoogleService-Info.plist`
`firebase_options.dart`	Flutter	`lib/firebase_options.dart`

Manuelle Konfiguration (falls CLI nicht funktioniert)

Firebase Console öffnen: https://console.firebase.google.com/project/wonderbox-a944e
Android App hinzufügen:
- Package name: com.alanko.ai
- Download google-services.json → android/app/
iOS App hinzufügen:
- Bundle ID: com.alanko.ai
- Download GoogleService-Info.plist → ios/Runner/

Firebase im Code initialisieren

// main.dart
import 'package:firebase_core/firebase_core.dart';
import 'firebase_options.dart';

void main() async {
  WidgetsFlutterBinding.ensureInitialized();
  await Firebase.initializeApp(
    options: DefaultFirebaseOptions.currentPlatform,
  );
  runApp(MyApp());
}

Häufige Probleme

"Authentication Error: Your credentials are no longer valid"

firebase logout
firebase login

"No projects found"

Falscher Account eingeloggt
Mit firebase login:list prüfen welcher Account aktiv ist

"Project not found"

Projekt-ID falsch geschrieben
Account hat keinen Zugriff auf das Projekt

Firebase Services in Alanko

Service	Status	Verwendung
Firebase Auth	🔜 Geplant	Anonyme Auth für Kinder
Cloud Firestore	🔜 Geplant	Profile, Leaderboards sync
Firebase Analytics	🔜 Geplant	Nutzungsstatistiken

11. Kontakt

Bei Fragen: Pull Request mit Frage erstellen oder Issue auf GitHub.

Owner: devshift-stack (dsactivi)

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

AGENTS.md - Kids AI Train Projekt

WICHTIG: LIES DIES KOMPLETT BEVOR DU ARBEITEST

1. Projekt-Übersicht

Repos auf GitHub (Organisation: devshift-stack)

Lokale Pfade

2. GOLDENE REGEL: NUR MIT PULL REQUESTS ARBEITEN

3. Workflow für jeden Task

Schritt 1: Repo klonen (falls nicht vorhanden)

Schritt 2: Aktuellen Stand holen

Schritt 3: Neuen Branch erstellen

Schritt 4: Änderungen machen und committen

Schritt 5: Branch pushen

Schritt 6: Pull Request erstellen

4. Welches Repo für welche Änderung?

Kids-AI-Shared (Gemeinsamer Code)

Kids-AI-Train-Alanko (Alanko App)

Kids-AI-Train-Lianko (Lianko App)

Kids-AI-Train-Parent (Eltern-Dashboard)

5. Vollständiges Beispiel: Feature für Lianko

6. Vollständiges Beispiel: Gemeinsames Widget in Shared

Test plan

7. Entscheidungshilfe: Wo gehört mein Code hin?

8. Verbotene Aktionen

9. Shared Code importieren

10. Firebase Setup

Accounts & Projekte

Firebase CLI Login

FlutterFire CLI Setup

Config-Dateien

Manuelle Konfiguration (falls CLI nicht funktioniert)

Firebase im Code initialisieren

Häufige Probleme

Firebase Services in Alanko

11. Kontakt