diff --git a/AGENTS.md b/AGENTS.md index 049456d..9531331 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,6 +4,98 @@ --- +## 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