leocrm/AGENTS.md

# LeoCRM — AGENTS.md

**Projekt:** leocrm | **Stack:** FastAPI + SQLAlchemy + PostgreSQL 16 (pgvector) + React/TypeScript/Vite/Tailwind

---

## 0. BINDENDE REGEL: Auf bestehendem Code aufbauen (NICHT VERHANDELBAR)

**Gültig für jegliche Arbeit an diesem Projekt — egal ob Erweiterung, Umbau, Neubau, Bugfix oder Refactoring.**

### 0.1 Pflicht zur Analyse vor Implementierung

Der Agent MUSS vor jeder Implementierung das bestehende System analysieren:

1. **Backend lesen:** Welche Models, Routes, Services, Plugins, Contracts, Hooks, ARQ-Jobs existieren bereits für den betroffenen Bereich? Der Agent greppt und liest die relevanten Dateien BEVOR er Code schreibt.
2. **Frontend lesen:** Welche Pages, Components, Stores, Hooks, API-Clients, Block-Typen, Sidebar-Tabs existieren bereits für den betroffenen Bereich? Der Agent greppt und liest die relevanten Dateien BEVOR er Code schreibt.
3. **Datenbank lesen:** Welche Tabellen, Foreign Keys, RLS-Policies, Migrationen existieren bereits? Der Agent prüft `alembic/versions/` und die Produktions-DB BEVOR er neue Migrationen schreibt.
4. **Plugin-System lesen:** Welche Contracts, Manifests, Search Provider, Tools, Hooks existieren bereits in den betroffenen Plugins? Der Agent liest `plugin.py`, `contracts.py`, `manifest.py` BEVOR er neue Plugins oder Erweiterungen baut.

### 0.2 Pflicht zum Aufbau auf bestehendem Code

Der Agent MUSS auf bestehendem Code aufbauen. Es ist VERBOTEN:

- ❌ Parallele Systeme zu bauen die vorhandene Funktionalität duplizieren (z.B. ein separates Workstream-System wenn das `kommunikation` Plugin schon Conversations, Messages, Blocks, WebSocket hat)
- ❌ Neue Frontend-Pages zu bauen wenn vorhandene Pages die Funktion aufnehmen können (z.B. Dashboard, Communication, AgentDashboard, Workflows, Wiki, Settings)
- ❌ Neue Sidebars oder Panels zu bauen wenn die AISidebar (5 Tabs) oder MessageSidebar die Funktion aufnehmen können
- ❌ Neue Stores zu bauen wenn vorhandene Stores (commStore, uiStore, authStore, etc.) die Funktion aufnehmen können
- ❌ Neue API-Clients zu bauen wenn vorhandene API-Clients (api/comm.ts, api/ai.ts, api/automation.ts, etc.) die Funktion abdecken können
- ❌ Neue Block-Typen zu bauen wenn vorhandene Block-Typen (action_card, contact_card, miniapp, etc.) die Funktion abdecken können
- ❌ Dataclasses zu schreiben wenn echte SQLAlchemy Models + FastAPI Routes die richtige Lösung sind
- ❌ Mock-Tests zu schreiben wenn echte Integration-Tests mit der Test-DB möglich sind
- ❌ Module zu bauen die 0 Referenzen aus Routes/Plugins haben (unverbundener Code)
- ❌ Tasks als "done" zu markieren ohne echte Verifizierung (curl gegen echte API, grep-Beweis für Import-Verbindungen, tsc clean, Backend import OK)

### 0.3 Pflicht zur Verbindung

Jeder neue Code MUSS mit dem bestehenden System verbunden werden:

- **Backend:** Neue Module müssen in `app/main.py` oder in Plugin `routes.py` registriert werden. Neue Models müssen in `alembic/versions/` migriert werden. Neue Tools müssen im `tool_registry` registriert werden. Neue Hooks müssen in `plugin.py on_activate` registriert werden. Neue ARQ-Jobs müssen in `worker.py` registriert werden.
- **Frontend:** Neue Components müssen in vorhandene Pages integriert werden (nicht als neue Page). Neue API-Calls müssen vorhandene API-Clients nutzen oder erweitern. Neue Block-Typen müssen im `BlockRenderer.tsx` registriert werden. Neue Sidebar-Tabs müssen in der `AISidebar.tsx` registriert werden.
- **Verifizierung:** Der Agent beweist mit grep dass neue Module importiert/referenziert werden. Der Agent beweist mit curl/pytest dass die API funktioniert. Der Agent markiert nichts als "done" ohne diese Beweise.

### 0.4 Referenz-Architektur (was existiert und genutzt werden MUSS)

**Frontend-Struktur:**
- `AISidebar.tsx` — 5 Tabs: chat (KI Chat), proactive (Live KI/Suggestions), notifications, team, chatroom (Communication)
- `MessageSidebar.tsx` (671 Zeilen) — voller Chat mit Conversations, Messages, WebSocket, BlockRenderer
- `Communication.tsx` (859 Zeilen) — volle Chat-Seite mit Conversations (system/ai/colleague), Messages, Blocks, Pin/Unpin, Read
- `comm/blocks/` — 10 Block-Typen: text, markdown, html, image, audio, video, file, action_card, contact_card, miniapp
- `BlockRenderer.tsx` — rendert alle Block-Typen
- `Dashboard.tsx` — StatCards, ActivityFeed, DashboardGrid mit Widgets
- `AgentDashboard.tsx` — Agent CRUD, Execute, Test Run, Versions, Restore, Tools, Send Message
- `Workflows.tsx` — Workflow CRUD, Instances, Editor, Step Config
- `Wiki.tsx` — Categories, Articles, Markdown Editor, Version History, Restore
- `components/knowledge/` — AskKnowledge.tsx, KnowledgeGraph.tsx
- `components/onboarding/` — OnboardingTour.tsx, WelcomeDialog.tsx
- `components/agents/` — AgentChat, AgentEditor, AgentMonitor, AgentRunLog
- `components/workflows/` — StepConfigPanel, WorkflowEditor, WorkflowInstanceList, WorkflowInstanceDetail
- `components/dashboard/` — DashboardGrid, RecentContactsWidget, TasksSummaryWidget, CalendarUpcomingWidget
- `store/commStore.ts` — Conversation, Message, MessageBlock, MessageAttachment, Participant
- `store/uiStore.ts` — aiSidebarCollapsed, aiSidebarTab, notifications
- `api/comm.ts` — listConversations, getMessages, sendMessage, markRead, createConversation
- `api/ai.ts` — createSession, fetchSessions, streamChat, fetchAgents
- `api/automation.ts` — useAgents, useCreateAgent, useUpdateAgent, useDeleteAgent, useExecuteAgent, useTestRunAgent, useAgentRuns, useAgentVersions, useRestoreAgentVersion, useAgentTools, useSendAgentMessage
- `api/workflows.ts` — useWorkflows, useDeleteWorkflow, useUpdateWorkflow
- `api/knowledge.ts` — createWikiArticle, deleteWikiArticle, fetchWikiArticle, fetchWikiCategories, fetchWikiVersions, restoreWikiVersion, updateWikiArticle

**Backend-Struktur:**
- `kommunikation` Plugin — CommConversation, CommParticipant, CommMessage, CommMessageBlock, WebSocket, Contracts, MiniAppRegistry
- `automation` Plugin — AgentDefinition, AgentRun, AgentRunStep, Triggers, Schedules, Pre-built Agents
- `unified_search` Plugin — 14 Search Provider, Hybrid Search, Embeddings
- `graph_rag` Plugin — Knowledge Graph, Relationships, Entities
- `wiki` Plugin — WikiArticle, WikiCategory, WikiArticleVersion, Entity Links
- `ai_assistant` Plugin — Tool Registry, CRM API Tool, AI Chat
- `ai_proactive` Plugin — Proactive Suggestions, Context Tools
- `agent_memory` Plugin — Agent Memory with Embeddings
- `permissions` Plugin — ABAC/RBAC, Entity Permissions, Share Links
- `app/ai/` — agent_loop.py, agent_runner.py, llm_client.py, context_builder.py, agent_permissions.py, agent_tools.py, data_policy.py, transparency.py, oversight.py, agent_stream.py, skill_registry.py, ai_use_case.py
- `app/workflows/` — engine.py, step_handlers.py, decision_guard.py
- `app/core/` — approval.py, hooks.py, outbox.py, worker.py, storage.py, monitoring.py, notifications.py
- `app/routes/` — 468 API Routes über alle Plugins und Core-Module

**Datenbank:**
- 130 Tabellen, 159 Foreign Keys, 590 Indexes
- 114 Tabellen mit RLS (Row Level Security)
- 130 Alembic Migrationen (Head: 0130)
- `set_tenant_context()` setzt `app.current_tenant_id` für RLS

### 0.5 Konsequenzen bei Verstoss

Wenn der Agent gegen diese Regel verstösst:
1. Der Code wird nicht akzeptiert
2. Der Agent muss den Code löschen und auf bestehendem Code neu aufbauen
3. Der Agent muss den Verstoß dokumentieren und erklären warum er die Regel ignoriert hat
4. Der Agent muss PROVE dass der neue Code mit grep-imports verbunden ist BEVOR er als done markiert wird

---

## 1. Build & Test Commands

```bash
# Backend
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
python -m pytest -v --tb=short
python -m pytest tests/test_auth.py -v --tb=short
alembic upgrade head
alembic revision --autogenerate -m "description"

# Frontend
cd frontend && npm run dev
cd frontend && npm run build
cd frontend && npx vitest run --reporter=verbose
cd frontend && npx tsc --noEmit

# Docker
docker compose up -d
docker compose logs -f backend
```

---

## 2. Test Rules

- TDD: failing test first → implement → refactor
- NEVER modify tests to make them pass — fix the code
- Test DB: ephemeral PostgreSQL, NEVER production DB
- Mock external services (SMTP, IMAP, OnlyOffice) with AsyncMock
- Tests must be deterministic and isolated

---

## 3. Code Conventions

### Backend
- Async first: all routes/services `async def`
- UUID primary keys only, never integer auto-increment
- TIMESTAMPTZ only, never naive datetime
- Soft-delete via `deleted_at IS NULL`; hard-delete only with `?gdpr=true`
- Pydantic schemas validate input, never validate in routes
- All mutations create audit log entries
- snake_case files/functions, PascalCase classes
- Schemas: `<Entity>Create`, `<Entity>Update`, `<Entity>Read`

### Frontend
- TypeScript strict, no `any`
- Functional components only, no class components
- TanStack Query for server state, Zustand for client state only
- React Hook Form + Zod for all forms
- Tailwind utility classes, no inline styles
- i18n via `t()` from react-i18next, no hardcoded strings
- ARIA attributes on all interactive elements, 44px touch targets
- PascalCase.tsx for components, camelCase.ts for utilities

### Git
- Conventional Commits: `feat(core): ...`, `fix(dms): ...`
- Squash merge to main after review

---

## 4. Forbidden Patterns

### Backend
- ❌ SQLite — PostgreSQL 16 only
- ❌ Jinja2/server-side HTML rendering — API-only backend
- ❌ Cross-tenant data access — ORM auto-filter must not be bypassed
- ❌ Plaintext passwords — bcrypt cost=12
- ❌ JWT auth — session-based with HttpOnly cookies only
- ❌ Naive datetime — TIMESTAMPTZ only
- ❌ Integer IDs — UUID only
- ❌ Hard-delete without `?gdpr=true`
- ❌ Manual tenant filter — ORM auto-filter handles it
- ❌ Sync I/O in routes — use asyncpg, aiofiles
- ❌ Raw SQL without tenant_id check
- ❌ Secrets in code — env vars only
- ❌ Unvalidated input — Pydantic schemas required
- ❌ Missing audit log on mutations
- ❌ Plugin tables without tenant_id

### Frontend
- ❌ Class components
- ❌ Inline styles — Tailwind only
- ❌ Hardcoded strings — use `t()`
- ❌ Manual fetch/axios in components — use TanStack Query
- ❌ Server data in Zustand
- ❌ `any` types
- ❌ Missing ARIA attributes
- ❌ Touch targets < 44px
- ❌ Direct DOM manipulation — use React refs
- ❌ `dangerouslySetInnerHTML` without sanitization

### Deployment
- ❌ Running as root in container — use app:app
- ❌ Exposed DB port in production
- ❌ Missing Docker health checks
- ❌ Ephemeral storage — use named volumes
- ❌ Secrets in docker-compose.yml

---

## 5. Quality Gates

- Per-Task: tests pass, coverage met, tsc/ruff clean, build succeeds, no forbidden patterns
- Phase: all tasks pass → quality_reviewer review → user checkpoint
- Release: all tasks complete → release_auditor audit → Docker builds → health 200 → E2E pass

---

## 6. ADRs

- ADR-01: PostgreSQL 16 (not SQLite)
- ADR-02: ARQ (not Celery)
- ADR-03: Built-in plugins with manifest (not pip-install)
- ADR-04: TanStack Query (not Redux)
- ADR-05: Session-based auth (not JWT)
- ADR-06: Soft-delete with `deleted_at`

Full architecture: `architecture.md` | Full task graph: `task_graph.json`

---

## 7. Deploy

**Vor Deploy:** `docs/deploy-guide.md` lesen (Befehle, Credentials, Server-Info).

- Frontend-only: `bash /a0/usr/projects/leocrm/scripts/fast-deploy.sh frontend`
- Full (Backend): `bash /a0/usr/projects/leocrm/scripts/fast-deploy.sh full`
- Git Workflow: commit → push → deploy

---

## 8. Dokumentations-Pflichten

### Wichtige MD-Dateien im Projekt

| Datei | Zweck |
|-------|------|
| `README.md` | Projekt-Overview, Setup |
| `PLATFORM_ROADMAP.md` | EINZIGE Planungs-Datei für zukünftige Entwicklung, Umbauten, Roadmap. Alle Phasen, Tasks und Architekturentscheidungen |
| `PROGRESS.md` | Fortschritts-Tracking — pro Task: Status, Forgejo Issue, Verifiziert. Wird vom Agent bei jedem Status-Wechsel aktualisiert |
| `AGENTS.md` | Agent-Definitionen (diese Datei) |
| `docs/test-strategy.md` | Test-Strategie, Konventionen, Einschränkungen |
| `docs/security_kernel.md` | Security-Konzept (ABAC, RLS, Session) |
| `docs/permissions.md` | Permission-System-Dokumentation |
| `docs/permissions_plugin_dev.md` | Permission-Plugin-Entwicklung |
| `docs/monitoring.md` | Monitoring, Health-Checks |
| `docs/infrastructure.md` | Infrastruktur (Docker, PostgreSQL, Redis) |
| `docs/admin-guide.md` | Admin-Handbuch |
| `docs/api-documentation.md` | API-Dokumentation |
| `docs/INSTALL.md` | Installationsanleitung |
| `docs/plugin-development-guide.md` | Plugin-Entwicklungs-Guide |
| `docs/ui-design-guidelines.md` | UI-Design-Richtlinien |
| `docs/deploy-guide.md` | Deploy-Anleitung, Credentials, Server-Info |

### Pflicht: Aktualisierung nach größeren Änderungen

**Nach jeder größeren Änderung MÜSSEN die betroffenen MD-Dateien überarbeitet werden:**

1. Neue Plugins/Module → `docs/plugin-development-guide.md`, `docs/api-documentation.md`, `docs/test-strategy.md`
2. Security-Änderungen → `docs/security_kernel.md`, `docs/permissions.md`, `docs/test-strategy.md`
3. Neue Test-Infrastruktur → `docs/test-strategy.md`
4. CI-Pipeline-Änderungen → `docs/test-strategy.md`, `docs/infrastructure.md`
5. Größere Refactoring → `README.md`, betroffene `docs/`-Dateien, `docs/test-strategy.md`
6. Nach Bugfix-Session → `docs/test-strategy.md`, `docs/security_kernel.md`
7. Roadmap-Änderungen → `PLATFORM_ROADMAP.md`
8. Infrastruktur-Änderungen → `docs/infrastructure.md`, `docs/INSTALL.md`
9. UI/UX-Änderungen → `docs/ui-design-guidelines.md`
10. API-Änderungen → `docs/api-documentation.md`

**Verantwortlich:** Agent/Entwickler der die Änderung durchführt.

### Test-Konventionen (MUST FOLLOW)

**Vor Tests:** `docs/test-strategy.md` lesen für vollständige Konventionen und Einschränkungen.

1. Plugin-Aktivierung: `init_permission_registry(active_plugin_names={...})` in jeder Plugin-Test-Datei
2. Entity-Typen: Korrekte ENTITY_MODELS-Keys (`file` nicht `dms_file`, `mail_account` nicht `mailbox`)
3. URLs: Korrekte API-Pfade (`/api/v1/entity-links/` nicht `/api/v1/dms/`)
4. Dedup-Tests: Unterschiedlichen Dateiinhalt pro Upload verwenden
5. Keine zufälligen UUIDs: Echte Entity-IDs aus der DB verwenden
6. Test-Dateien: `tests/test_<modul>.py` | Fixtures: `tests/conftest.py`

---

## 9. Progress-Tracking & Forgejo-Issue-Verwaltung

### Planungs- und Fortschrittsdateien

| Datei | Zweck | Wann aktualisieren |
|-------|------|-------------------|
| `PLATFORM_ROADMAP.md` | EINZIGE Planungs-Datei. Alle Phasen, Tasks, Architekturentscheidungen | Bei Planungsänderungen |
| `PROGRESS.md` | Fortschritts-Tracking. Pro Task: Status, Forgejo Issue, Verifiziert | Bei jedem Task-Status-Wechsel |

### Task-Status-Verwaltung

Jeder Task in der Roadmap hat einen Status der in `PROGRESS.md` verfolgt wird:

- `not_started` — Task noch nicht begonnen
- `in_progress` — Task wird bearbeitet
- `blocked` — Task blockiert (Abhängigkeit fehlt, Entscheidung ausstehend)
- `review` — Task implementiert, wartet auf Review/Tests
- `done` — Task hat Definition of Done (DoD) erfüllt

**Der Agent MUSS `PROGRESS.md` bei jedem Status-Wechsel aktualisieren.** Kein Task-Wechsel ohne PROGRESS.md-Update.

### Forgejo Issues & Milestones

- **Pro Phase (A-J):** Ein Forgejo Milestone (z.B. "Phase A — Stabilität", "Phase B — System-Konsolidierung")
- **Pro Task:** Ein Forgejo Issue mit Label `task` + Milestone der jeweiligen Phase
- **Pro Bug:** Ein Forgejo Issue mit Label `bug` + Priorität (`critical`, `high`, `medium`, `low`)
- **Pro Feature-Request:** Ein Forgejo Issue mit Label `enhancement`

**Der Agent MUSS für jeden Task ein Forgejo Issue erstellen** und die Issue-Nummer in `PROGRESS.md` eintragen.

### Commit-Messages

- Commit-Messages enthalten die Task-ID: `feat(B-LLM): zentraler LLM Client implementiert`
- Bug-Fixes referenzieren das Issue: `fix(#123): Redis-Connection-Leak behoben`
- `fixes #123` oder `closes #123` im Commit schließt das Issue automatisch

### Definition of Done (DoD)

Ein Task gilt erst als **DONE** wenn alle 8 DoD-Kriterien erfüllt sind (siehe `PLATFORM_ROADMAP.md`). Ein Task ohne Test ist NICHT done. Der Agent darf keinen Task als `done` markieren ohne DoD erfüllt zu haben.

### Phase-Gate-Review

Eine Phase gilt erst als **ABGESCHLOSSEN** wenn alle 7 Phase-Gate-Kriterien erfüllt sind (siehe `PLATFORM_ROADMAP.md`). Der Agent darf nicht zur nächsten Phase übergehen ohne Phase-Gate-Review bestanden zu haben.