Skip to content

AGENTS.md

Latest commit

 

History

History
71 lines (59 loc) · 7.72 KB

AGENTS.md

File metadata and controls

71 lines (59 loc) · 7.72 KB
Raw

AI Agent Constraints & Architecture (KAiOSS)

Global context and technical constraints for AI coding agents working on this repository. Repo: github.com/diebugger-tech/KAiOSS

🖥 Aktuelle Arbeitsumgebung (Stand: 08.07.2026)

  • Betriebssystem: Ubuntu (kein NixOS-System).
  • Paketverwaltung: Nix via Home-Manager (home-manager), nicht nixos-rebuild. Deklarative Paket-/Service-Pins laufen über home.nix / Home-Manager-Module, nicht über System-Flakes.
  • Konsequenz für dieses Dokument: Alle Abschnitte unten, die "NixOS-native" formulieren (systemd-Services als NixOS-Module, nixos-rebuild-basierte Erkennung), beschreiben eine mögliche Zielarchitektur für ein separates NixOS-System — nicht die aktuelle Maschine. Auf dieser Maschine sind deklarative User-Services über Home-Manager (systemd.user.services.*) der richtige Ansatz, keine System-weite NixOS-Rebuild-Kette.
  • Das Pflanternen-Modul (modules/pflanternen/) bleibt NixOS-exklusiv und ist auf dieser Maschine korrekt deaktiviert (PFLANTERNEN_ENABLED=false).
  • SurrealDB ist auf 3.0.5 gepinnt (via Home-Manager home.nix). Andere Versionen können das surrealkv-Manifest in data/ unlesbar machen — das war die Ausfallursache am 08.07.2026. start.sh prüft die Version vor jedem DB-Start und verweigert bei Abweichung. Upgrade-Prozedur und Begründung: docs/adr/ADR-001-surrealdb-version-pinning.md.
  • Start/Stop: make start → ./start.sh start (SurrealDB 8000 + Vite 5174, detached mit PID-Files in logs/). ./start.sh stop|status zum Stoppen/Prüfen.
  • Backup-first: Vor jeder DB- oder Schema-Änderung surreal export (Ziel: backups/, gitignored). SurrealDB = Single Source of Truth.
  • Container: Komplett-Stack via make podman-up (compose.yaml: SurrealDB v3.0.5 + Schema/Seed-Import + App). Frontend nutzt @sveltejs/adapter-node; npm run dev bleibt unverändert Vite. Details: docs/DEPLOY.md.
  • Branch-Modell: main = stabiler öffentlicher Stand (nur Code + Demo-Seed, keine persönlichen Projektdaten), dev = Arbeitsbranch. Feature-Branches von dev abzweigen, dorthin zurückmergen. Keine direkten Main-Pushes (HITL).

🏗 Project Structure

  • frontend-svelte/src/lib/components/: Modular UI components (Columns, Cards, DetailPanel, ObsidianGraph).
  • frontend-svelte/src/lib/db.svelte.js: Centralized SurrealDB connection singleton.
  • frontend-svelte/src/lib/surrealDbService.svelte.js: Svelte reactive state store for projects and tasks.
  • frontend-svelte/src/routes/: SvelteKit routes (including /api/open to open files/folders).
  • system-check.sh: Automated environment diagnostics.

👥 Agent-Orchester & Roster

Die KAiOSS-Plattform wird von einer Reihe spezialisierter KI-Agenten gesteuert, die über das Model Context Protocol (MCP) miteinander und mit dem System kommunizieren:

  • KAi (primär): Task-Reasoning, Planung und Code-Generierung.
  • LearnAgent: Kontinuierliches Scannen von GitHub Trending, Hacker News und ArXiv.
  • GitAgent: Event-driven Ausführung über Git-Hooks.
  • MarketAgent: Periodische Markt- und Wettbewerbsanalysen.
  • SecurityAgent: On-demand Sicherheits-Audits und Schwachstellen-Scans via MCP.

⚙️ Framework & Execution

  • Framework: Goose + Ollama + Qwen2.5 (oder qwen2.5:32b).
  • NixOS-native Integration (Zielarchitektur): Ausführung als deklarative systemd-Services. Auf der aktuellen Ubuntu+Home-Manager-Maschine (siehe "Aktuelle Arbeitsumgebung" oben) über Home-Manager systemd.user.services.* statt via nixos-rebuild.
  • HITL-Prinzip (Human-in-the-Loop): Kritische Operationen (z. B. direkte DB-Resets, destructive system changes oder direkte Main-Pushes) werden niemals ohne menschliche Freigabe ausgeführt.

🤖 Critical Rules for Agents

  1. db.svelte.js is Singleton: Do NOT initialize multiple connections. Use the shared instance.
  2. Environment Variables: Access all configuration via import.meta.env.VITE_*.
  3. LIVE SELECT: Always use Live Queries for real-time data synchronization.
  4. No Backend: All logic is handled via frontend and SurrealDB, with SvelteKit server routes only for OS integrations (e.g. xdg-open).
  5. NixOS Compatibility: All shell scripts must use #!/usr/bin/env bash.
  6. Code Style: Svelte 5 Runes only ($state, $derived, $effect, $props, snippets). No React legacy.
  7. SurrealDB 3.x Syntax: Do NOT use type::thing($id). Always use type::record($id) to cast string IDs to record IDs.
  8. Test-Isolation — Host bleibt schlank: Für Fresh-Clone-/Container-/„Fremder lädt das Projekt"-Tests NIEMALS zusätzliche Runtimes oder System-Pakete (Podman, Docker, Compose etc.) auf Andreas' Haupt-PC installieren oder Images dort bauen lassen. Solche Tests gehören ausschließlich in die Wegwerf-VM (GNOME Boxes, Linux Mint) — dort ist die Umgebung ohnehin sauber (wie bei einem echten Fremden) und alles kann danach rückstandslos gelöscht werden. Auf dem Host nur das, was für die tägliche Entwicklung nötig ist. Dies ist ausschließlich eine Test-Regel — bewusste, dauerhafte Setups (z. B. Podman produktiv auf dem PC) bleiben Andreas' eigene Entscheidung und werden von dieser Regel nicht eingeschränkt.

🔧 Verification

  • Verify changes using npm run dev.
  • Ensure new features adhere to the terminal dark theme aesthetic.

🔒 KAi Permissions & Access Isolation (Least-Privilege)

For a detailed mapping of agent system access rights, see the custom skill .kai/kaioss-kai-permissions.md.

Key isolation rules that every agent MUST respect:

  1. No FS Access: KAi has no read/write access to the file system (enforced via Goose Tool-Whitelist).
  2. SurrealDB User Isolation: KAi connects using the database user kai. Due to SurrealDB 2.x role hierarchies, this user has database-level ROLES EDITOR but is strictly isolated via table-level PERMISSIONS (SELECT, CREATE, and UPDATE guards).
  3. No Direct Kern-Field Overwrites: KAi must only write comments, actions, and suggestions to the custom nested object field kai.* (e.g. kai.notiz, kai.aktion) on the task and todo tables.
  4. No Destructive Operations: DELETE permissions are restricted to false for KAi across all tables.

🔮 Future Architecture (LISTE 2)

  • 3-Layer Memory System: Integration of Mem0 (Episodic Chat Memory) alongside Cognee (Semantic Document Memory) and SurrealDB (Central Vault).
  • Feature 1: Cross-Project Knowledge Bridge: Query and relate patterns across all active projects using SurrealDB Graph + Cognee. (Auto-detect shared code patterns and draw inter-project relations).
  • Feature 2: Proactive Code & Roadmap Sync: Watch local changes via FS/Git and check for doc-code drift, suggesting auto-updates for specs and documentation files.
  • Feature 3: Self-Healing Workspace: Terminal log error parser with side-by-side fix diffs and HITL execution.
  • Feature 4: Interactive GraphRAG Workspace-Tree: Hover preview summaries, dependencies, and file relationship scoring. (Implemented: ObsidianGraph.svelte SVG-based force layout; Pending: hover tooltips with AI-generated summaries).
  • Feature 5: Wiki Docs Assistant: A context-aware chatbot in the Wiki panel querying repository docs and linking to exact code/Obsidian vaults.
  • Constraint: Do NOT implement Mem0 until Cognee Phase 1 is fully deployed and KAi actually produces chat sessions (e.g. kai_chat table is active).
  • Requirement: Will require custom Vector Store adapters for both Mem0 and Cognee to route their internal local storage directly to SurrealDB HNSW indexes.
  • Out of Scope: Obsidian-Sync is explicitly removed from KAiOSS core scope (delegated to separate Obsidian vault collector scripts/dot-skill integration).