feat(openclaw): implement 9-agent specialist architecture and agents-as-code (ADR 0001)

2026-09-16 08:29:29 +02:00
parent bcff777228
commit 707a1b02ef
6 changed files with 49 additions and 35 deletions
@@ -119,7 +119,31 @@ The main conductor is guided by explicit system prompt rules:

 ## Future Roadmap: Monorepo Refactoring Blueprint

-This Hybrid MCP architecture serves as the official template for future refactorings in `infrapuzzle`:
-1. **Shopping & Supermarket Deals**: Migrate current static MCP tools behind Tool Search; delegate multi-store price comparisons and recipe cart generation to a shopping subagent.
-2. **Jellyfin & Media Management**: Keep playback/resume queries direct; delegate complex media recommendations and library reorganizations to a media subagent.
-3. **Local News & Stadtrat Research**: Provide direct search for council dates; delegate deep legislative research, PDF document extraction, and meeting summarization to an isolated Stadtrat research subagent.
+This Hybrid MCP architecture serves as the official template for all agentic workflows in `infrapuzzle`. On 2026-09-16, this architecture was formally expanded into the **Full-Spectrum Multi-Agent Architecture** with 9 specialized subagents:
+
+### 1. Agents-as-Code in the Knowledge Wiki (`knowledge-wiki/agents/`)
+Subagent specifications, system prompts, tool assignments, and domain guidelines are decoupled from Kubernetes deployment manifests and stored as versioned Markdown files in `knowledge-wiki/agents/<name>.md`.
+* **Zero-Deployment Tuning**: Adding or refining an agent requires no Kubernetes pod restarts; changes synced via Git are immediately effective.
+* **Extensibility Blueprint**: Adding a 10th agent requires simply adding `agents/<new-agent>.md` with YAML frontmatter specifying model, tools, and owned concepts.
+
+### 2. The 9 Specialized Subagents Roster
+1. 🩺 **Digitale Hebamme Agent** (`agents/hebamme.md`): Baby milestones, sleep windows, BLW, pediatrician safety boundaries.
+2. 🍳 **Koch Agent** (`agents/koch.md`): Ninja CREAMi Deluxe, Airfryer, KitchenAid, leftover utilization, exact recipes.
+3. 🏡 **Grabengasse Agent** (`agents/grabengasse.md`): Home Assistant, Philips Hue, Sonos multiroom, house systems.
+4. 🏰 **Regensburg Agent** (`agents/regensburg.md`): Regensburg & Stadtamhof insider, local places, RVV transit, city notices.
+5. ✈️ **Travel Agent** (`agents/travel.md`): Vacation planning, itineraries, packing checklists, on-the-road travel concierge.
+6. 🎬 **Media Agent** (`agents/media.md`): Jellyfin streaming/requests, Jellyseerr, Spotify audiobooks & playlists.
+7. 🔍 **Recherche Agent** (`agents/recherche.md`): Deep research engine (iterative multi-hop), ALLRIS Stadtrat, Friday bridge updates.
+8. 🛒 **Shopping Agent** (`agents/shopping.md`): Deal hunter, Geizhals all-time lows, supermarket deals, multi-tier webshop extraction.
+9. 🏋️ **Fitness Coach Agent** (`agents/fitness.md`): Garmin Connect (148 tools), Tacx Flux 2 (FTP 275 W), home gym supersets.
+
+### 3. Multi-Turn Continuity: Domain Stickiness & Rich State Bridge
+To prevent context loss during ongoing step-by-step dialogues (e.g. interactive cooking or workout design):
+* **Domain Stickiness**: Follow-up questions on the active topic remain within the specialized subagent domain until an explicit topic shift occurs.
+* **Rich State Bridge (`<!-- DOMAIN_STATE -->`)**: Every subagent embeds a compact JSON state comment at the end of its response. The Conductor uses this state to answer trivial micro-checks in < 1s, or feeds it back into the subagent for complex modifications.
+
+### 4. 3-Tier Session Lifecycle (Preventing Unbounded Session Growth)
+1. **Conversational Close**: Topic shifts or explicit user completion (*"Danke, das war's"*) reset the active domain pointer.
+2. **Ephemeral Inactivity Cleanup**: Subagent child sessions inactive for > 60 minutes (`subagents.archiveAfterMinutes: 60`) are automatically archived.
+3. **Deterministic Nightly Compaction**: Nightly 03:30 AM CET compaction vacuums expired child sessions from the SQLite store.
+
@@ -25,6 +25,21 @@ The multi-container pod structure is managed natively by the operator controller
 | `skill-stabilizer` | Retained under `spec.sidecars` to copy skills to the flat PVC structure |
 | `install-uv-python` (init) | Managed natively by the operator under `spec.runtimeDeps.python: true` |

+### 3. Multi-Agent Architecture & Agents-as-Code (ADR 0001)
+*   **Conductor**: The main session runs as the lean front-of-house coordinator (`SOUL.md`), handling fast actions (< 2s) directly with MCP tools and delegating complex domain tasks via `sessions_spawn`.
+*   **Specialist Subagents**: 9 specialized subagents defined as code in the knowledge wiki:
+    - 🩺 `agents/hebamme.md` (Baby development & sleep, pediatrician safety boundaries)
+    - 🍳 `agents/koch.md` (Ninja CREAMi Deluxe, Airfryer, KitchenAid, leftover utilization)
+    - 🏡 `agents/grabengasse.md` (Home Assistant, Hue, Sonos multiroom, Grabengasse 7)
+    - 🏰 `agents/regensburg.md` (Stadtamhof insider, RVV, playgrounds, local dining)
+    - ✈️ `agents/travel.md` (Vacation itineraries, packing lists, travel concierge)
+    - 🎬 `agents/media.md` (Jellyfin streaming/requests, Jellyseerr, Spotify audiobooks)
+    - 🔍 `agents/recherche.md` (Deep research, ALLRIS Stadtrat, Friday bridge tracking)
+    - 🛒 `agents/shopping.md` (Supermarket deals, Geizhals best prices, Bring! lists)
+    - 🏋️ `agents/fitness.md` (Garmin Connect 148 tools, Tacx Flux 2, home gym supersets)
+*   **Modifying & Adding Agents**: To update prompt logic, tone, or tool instructions for any agent, edit its markdown file directly in `knowledge-wiki/agents/<name>.md` and commit to git. No Kubernetes pod restarts required!
+*   **Multi-Turn Domain Stickiness**: When a conversation spans multiple turns in a subagent domain (e.g. refining a recipe or planning a trip), the Conductor detects domain continuity and routes to the same agent with the state bridge `<!-- DOMAIN_STATE -->`.
+
 ---

 ## 🔧 Applying Configuration Changes
@@ -34,7 +49,6 @@ To perform modifications or rotate api keys:
 2. **Declarative Base Config**: Edit fields under `spec.config.raw` in [openclaw-instance.secret.yaml](file:///Users/moritz/src/infrapuzzle/k8s/openclaw/openclaw-instance.secret.yaml).
 3. **Apply & Rollout**: Apply the files. The operator tracks config hashes and performs an automated rolling update of the StatefulSet automatically (no manual restart needed!):
   ```bash
-   kubectl apply -f k8s/openclaw/attachment-patch.yaml
   kubectl apply -f k8s/openclaw/openclaw.secret.yaml
   kubectl apply -f k8s/openclaw/openclaw-instance.secret.yaml
   kubectl apply -f k8s/openclaw/cronjob-wiki-backup.secret.yaml
@@ -20,6 +20,11 @@ The deployment is managed by the official **OpenClaw Operator** (`openclaw-opera
    *   **Vector Search**: Semantic memory search via OpenRouter `/v1/embeddings` (`text-embedding-3-small`).
    *   **Memory Wiki**: Bundled `memory-wiki` compiles structured entities, concepts, and dashboards into an Obsidian-compatible vault (`wiki/main`).
    *   **Automated Backup**: `openclaw-wiki-backup` CronJob runs daily at 03:30 AM UTC to commit and push the knowledge vault to `git.moritzgraf.de/moritz/knowledge-wiki`.
+*   **Multi-Agent Specialist Delegation (ADR 0001)**:
+    *   **Conductor + 9 Subagents**: Lean front-of-house coordinator orchestrates 9 specialized domain subagents defined as code in the knowledge wiki (`agents/*.md`).
+    *   **Direct Fast Path (< 2s)**: Simple status, home automation toggles, and single calendar entries run directly in-place.
+    *   **Domain Stickiness**: Multi-turn dialogue (e.g. step-by-step cooking or vacation planning) stays pinned to the active subagent with state carried over via `<!-- DOMAIN_STATE -->`.
+    *   **Active MCP Servers**: `stadtrat` (ALLRIS Net), `supermarket` (Marktguru), `geizhals` (price histories), `ebay`, `garmin` (148 health tools), `bring` (4 lists), `spotify`, `calendar` (family + city), `jelly` (Jellyfin/Jellyseerr), `homeassistant`, `prometheus`, `gitea`, `weather`.

 ---

@@ -1,29 +0,0 @@
-apiVersion: v1
-kind: ConfigMap
-metadata:
-  name: openclaw-attachment-patch
-  namespace: openclaw
-data:
-  attachment-allowlist-loader.mjs: |
-    import { register } from "node:module";
-    register(new URL("./attachment-allowlist-hook.mjs", import.meta.url));
-
-  attachment-allowlist-hook.mjs: |
-    export async function load(url, context, nextLoad) {
-      const result = await nextLoad(url, context);
-      if (url.includes("web-media-") && result.source) {
-        let source = typeof result.source === "string"
-          ? result.source
-          : Buffer.isBuffer(result.source)
-            ? result.source.toString("utf8")
-            : new TextDecoder().decode(result.source);
-        if (source.includes("function assertHostReadMediaAllowed(params) {")) {
-          source = source.replace(
-            "function assertHostReadMediaAllowed(params) {",
-            "function assertHostReadMediaAllowed(params) { return; /* allow all files */ "
-          );
-          return { ...result, source };
-        }
-      }
-      return result;
-    }