Leopoldadmin/leocrm
1
0
Fork 0
Code Issues 363 Pull Requests Actions 1 Packages Projects Releases 1 Wiki Activity
Files
88d96d4a496bc2f816387ddd8e44478f0f259b51
leocrm/AGENTS.md
T

18 KiB
Raw Blame History

LeoCRM — AGENTS.md

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

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

0.0 Sub-Agents / Subordinates — Nuancierte Regel

Sub-Agents (call_subordinate) nur für einfache Jobs verwenden.

  • Einfache Jobs: Research, Codebase-Exploration, Dokumentations-Zusammenfassung — Aufgaben ohne Code-Änderungen oder Schema-Migrationen.
  • Komplexe Jobs (Code-Änderungen, Tests, Migrationen, Deployments): vom Haupt-Agent selbst ausführen.
  • Wenn der User sagt "keine Sub-Agents verwenden": daran halten, keine Ausnahmen.
  • Sub-Agents haben in der Vergangenheit Code geschrieben der nicht gegen Produktion verifiziert wurde, Schema-Drifts verursacht und nicht getestet hat. Qualitätssicherung bleibt beim Haupt-Agent.

Gültig für jegliche Arbeit an diesem Projekt.

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

# 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.

10. Tracking-Ein-Datei-Regel (bindend seit 2026-08-27)

  • PROGRESS.md ist die einzige Source of Truth fuer Status und offene Punkte. Keine weiteren parallelen Tracking-Dateien (test-bugs.md/fix-plan-v3 sind in docs/archive/ historisiert).
  • Ein Finding wird nur eingetragen mit tagesaktueller Live-Messung (Befehl + Zaehler). 'Scanner sagt' oder Plan-Text allein reicht nie.
  • Tests duerfen nur zusammen mit Pflegeanspruch entstehen: UI-Aenderung zieht Test-Nachzug im selben Commit nach sich. Geister-Tests (Importziel geloescht) werden sofort geloescht.
  • Playwright-e2e bleibt dem eigenen Runner vorbehalten (vite.config exclude), kein Vitest-Collection.
Reference in New Issue View Git Blame Copy Permalink