kxkm_clown/docs/AGENTS.md

Agents, Sous-agents, Competences

"L'infrastructure est une decision politique deployee." -- electron rare

Orchestration

• Agent racine: Coordinateur — planifie, arbitre, synchronise PLAN/TODO/docs
• Sous-agents specialises: analyse code, veille OSS, audit securite, optimisation
• Cadence: synchroniser PLAN.md + TODO.md + docs apres chaque lot

Matrice des agents (lot 17+)

Agent	Competences	Perimetre	Etat
Coordinateur	planification, arbitrage, docs de pilotage	PLAN.md, TODO.md, AGENTS.md, README.md	actif
Securite	validation input, hardening, rate-limit, RBAC	apps/api, ws-chat, packages/auth	veille
Backend API	Express, WS, Ollama, RAG, multimodal pipeline	apps/api/src/	actif
Node Engine	DAG, queue, runs, sandbox, training adapters	packages/node-engine, apps/worker	actif
Personas	source/feedback/proposals/pharmacius, memoire	packages/persona-domain, ws-chat	actif
Frontend	React/Vite, UX Minitel, React Flow, chat, voice	apps/web/src/	actif
Ops/TUI	scripts, logs, rotate/purge, health, audit	ops/v2/, scripts/	actif
Training	DPO, SFT, Unsloth, eval, autoresearch, Ollama import	scripts/, packages/node-engine	actif
Multimodal	STT, TTS, vision, PDF, RAG, recherche web	apps/api/src/ws-chat.ts	actif
Veille OSS	recherche projets, libs, modeles, benchmarks	docs/OSS_WATCH, docs/HF_MODEL_RESEARCH	periodique

Sous-agents et skill routing

flowchart TD
    Coord[Coordinateur]

    Coord --> SecAgent[Securite]
    Coord --> BackAgent[Backend API]
    Coord --> EngAgent[Node Engine]
    Coord --> PersAgent[Personas]
    Coord --> FrontAgent[Frontend]
    Coord --> OpsAgent[Ops/TUI]
    Coord --> TrainAgent[Training]
    Coord --> MultiAgent[Multimodal]
    Coord --> OSSAgent[Veille OSS]

    SecAgent --> |audit| SecScan[Pattern scan P0/P1/P2]
    SecAgent --> |fix| SecFix[Correctifs chirurgicaux]

    BackAgent --> |analyse| APIAudit[Deep analyse app.ts, ws-chat.ts]
    BackAgent --> |refactor| APISplit[Extraction modules]

    EngAgent --> |test| EngTest[Tests unitaires node-engine]
    EngAgent --> |extend| EngNew[Nouveaux node types]

    PersAgent --> |pipeline| PersPipe[Editorial pipeline]
    PersAgent --> |finetune| PersDPO[DPO + PCL methodology]

    FrontAgent --> |ui| FrontUI[Minitel theme CSS]
    FrontAgent --> |perf| FrontPerf[Memoization, lazy load]

    OpsAgent --> |monitor| OpsHealth[health-check, deep-audit]
    OpsAgent --> |deploy| OpsDeploy[Docker, kxkm-ai]

    TrainAgent --> |train| TrainRun[Unsloth/TRL runs]
    TrainAgent --> |eval| TrainEval[Scoring, registry]

    MultiAgent --> |voice| MultiVoice[XTTS-v2, WebRTC]
    MultiAgent --> |search| MultiSearch[SearXNG]

    OSSAgent --> |web| OSSWeb[Recherche web]
    OSSAgent --> |hf| OSSHF[HuggingFace models]

Todo agents (lot 17+ — mis a jour 2026-03-24)

Coordinateur

• Consolider PLAN.md avec etat reel (lots 0-94 complets)
• Synchroniser FEATURE_MAP.md matrice
• Mettre a jour TODO.md avec backlog Phase session 2026-03-19/20
• Documenter actions dans ops/v2/logs/
• lot-95: Coordonner E2E Playwright test plan
• lot-100: Design public demo mode access control

Backend API

• Extraire app-bootstrap.ts et app-middleware.ts de app.ts
• Extraire ws-conversation-router.ts de ws-chat.ts
• ws-chat.ts modularized (425 to 335 LOC, 3 modules extracted)
• app.ts extraction (540 to 131 LOC, create-repos.ts extracted)
• Zod validation on all 19 API route schemas
• Error telemetry (16 labels)
• Perf instrumentation (6 labels, p50/p95/p99), TTFC 284ms
• Smart routing (5 topic domains)
• Dynamic context window (4k-32k)
• NLP auto-detect generation intent (compose vs imagine)
• /speed command for latency diagnostics
• lot-178: ACE-Step API direct integration (duration fix)
• lot-180: Timeline data model
• lot-97: Multi-channel support (create/join channels)
• lot-100: Public demo mode read-only routes

Node Engine

• Extraire registry.ts du hotspot node-engine
• Ajouter node type music_generation (ACE-Step 1.5)
• Ajouter node type voice_clone (Chatterbox)
• Ajouter node type audio_mix (multi-track composition)
• Ajouter node type audio_effects (FX chain)
• lot-96: Automated DPO pipeline (feedback → pairs → training trigger)

Multimodal (composition pipeline)

• 35 music styles ACE-Step
• ComfyUI smart checkpoint selection (32 checkpoints + 24 LoRAs)
• lot-184: Multi-track composition (/layer, composition-store)
• lot-185: Composition UI (track lanes, play/pause/seek)
• lot-186: Arrangement tools (/comp structure, section markers)
• lot-187: Auto-mastering (/mix master, loudness normalization, limiter)
• lot-188: /voice TTS voiceover injected into composition
• lot-189: /noise 5 types (white, pink, brown, rain, wind)
• lot-190: /fx 9 audio effects (reverb, delay, chorus, flanger, distortion, bitcrusher, EQ, compressor, tremolo)
• lot-191: /ambient scene generator (forest, ocean, city, space, cave)
• lot-194: Waveform visualization (wavesurfer.js)
• lot-195: /remix re-generate specific track
• lot-199: Stem separation (Demucs v4 htdemucs, 6-stem, MIT)
• lot-200: Full DAW export (WAV stems + JSON project)

Personas

• Evaluer PCL (Persona-Aware Contrastive Learning) pour coherence
• Evaluer OpenCharacter pour generation profils synthetiques
• Ajouter /compose command (generation musicale)

Frontend

• Implementer lot 16 UI Minitel rose (phosphore, VIDEOTEX)
• VoiceChat push-to-talk + level meter + silence auto
• Player audio + viewer image plein ecran
• Mediatheque gallery/playlist
• Progress bars animees Compose/Imagine
• React.memo + useCallback on ChatSidebar, ChatInput, ChatHistory
• 17 lazy-loaded routes (-53% initial JS)
• CRT CSS-only effect (scanlines, vignette, phosphor glow, boot 0.8s)
• Chat virtualization (react-window, variable row heights)
• Markdown rendering (marked + DOMPurify)
• CRT boot animation (modem dial, scanline reveal)
• 5 CSS themes (minitel, crt, hacker, synthwave, default)
• Mobile responsive pass (touch, bottom nav, viewport units)
• Guest mode read-only UI
• lot-185: Composition timeline UI (waveform view, track lanes)
• lot-194: Waveform visualization (wavesurfer.js)
• lot-95: E2E Playwright tests (login, chat, upload, admin)
• lot-98: File sharing UI (upload → gallery)

Ops/TUI

• Deployer deep-audit.js sur kxkm-ai
• Ajouter SearXNG au docker-compose
• TTS sidecar HTTP (tts-server.py :9100, dual Chatterbox/Piper)
• deploy.sh migrated tmux → systemd
• Systemd services (kxkm-tts + kxkm-lightrag, auto-restart)
• health-check.sh TUI (19 checks)
• Docker compose 12 services with health checks
• Fix Docker transformers (rebuild propre avec torch)

Training

• Spike BGE-M3 (resultat negatif sur Apple/Metal, baseline maintenue)
• TTS dual backend Chatterbox/Piper valide
• Tool-calling benchmark (llama3.1 vs qwen3 vs mistral)
• Sherlock migrated to llama3.1:8b-instruct-q4_0
• lot-96: Persona DPO automation pipeline
• Tester ACE-Step 1.5 sur RTX 4090

Veille OSS

• Veille mars 2026 complete (40+ projets analyses, top 10 recommandations)
• Suivre LLMRTC (WebRTC voice TypeScript)
• Suivre A2A Protocol (interop agents)
• Suivre MCP SDK updates
• Evaluer Kokoro TTS (82M params, ultra-leger)

Pipeline d'intervention

stateDiagram-v2
    [*] --> Analyse: agent lance
    Analyse --> Findings: scan code/docs/web
    Findings --> Triage: P0/P1/P2 classification
    Triage --> Fix_P0: P0 critique
    Triage --> Plan_P1: P1 important
    Triage --> Backlog_P2: P2 mineur
    Fix_P0 --> Test: correction chirurgicale
    Plan_P1 --> Test: correction planifiee
    Test --> Deploy: tests OK
    Deploy --> Log: log + purge
    Log --> [*]: cycle termine
    Backlog_P2 --> [*]: ajoute au TODO

Affectations en cours (2026-03-20)

Mission globale

• Deep analyse continue du code, optimisation chirurgicale, et synchronisation documentaire apres chaque lot.
• Priorite execution: P1 fiabilite, puis dette perf/complexite, puis features lot 18-19.

Assignations agents -> sous-agents -> competences

Agent	Sous-agent	Competences principales	Taches assignees immediates
Coordinateur	Planner/Docs	triage, synchronisation, runbook	Maintenir PLAN/TODO, chainer les lots, tracer actions
Backend API	WS/HTTP surgeon	websocket, express, validation input	Extraire ws-chat.ts en modules, reduire logs, limiter hot paths
Node Engine	DAG runtime	graph validation, queue, state machine	Ajouter nodes music_generation, voice_clone, document_extraction
Ops/TUI	Audit operator	TUI scripts, logs, rotation, cron	Rendre deep-audit zero faux positif critique, pipeline logs + purge
Veille OSS	Scout	benchmark OSS, licences, interop	Evaluer Open WebUI, LibreChat, LangGraph, SearXNG, Docling

Workflow d'enchainement

1. Executer audit + tests
2. Corriger de maniere chirurgicale
3. Re-executer audit + tests
4. Mettre a jour docs de pilotage
5. Alimenter TODO suivant avec ordre d'execution

Regles d'operation

• Interroger le user uniquement en cas de blocage reel (acces, choix irreversibles, secrets).
• Privilegier TUI et scripts avec logs lisibles, puis purge des logs obsoletes.
• Conserver la V1 comme reference comportementale, V2 comme cible active.

Etat de cycle (2026-03-20 22:00)

• 170+ lots termines (lot-24 a lot-191).
• 425 tests, 0 failures.
• 13 services en production.
• 53 chat commands, 33 personas.
• 35 music styles (ACE-Step), 9 audio effects, 5 CSS themes.
• Composition pipeline: multi-track, voice, noise, ambient, effects, mix.
• 32 ComfyUI checkpoints + 24 LoRAs, smart selection NLP.
• TTFC 284ms.
• Guest mode, mobile responsive.
• Structured logging complet (pino JSON, 0 console.log).
• Systemd services (TTS + LightRAG).
• Frontend: lazy routes (-53%), React.memo, CRT boot, chat virtualization.

Prochains lots (192-200) — Composition Advanced

1. lot-192: ws-commands modular extraction
2. lot-193: Composition tests (unit tests composition-store, /fx)
3. lot-194: Waveform visualization (wavesurfer.js @wavesurfer/react)
4. lot-195: /remix re-generate specific track
5. lot-196: MIDI export from composition
6. lot-197: Composition templates (preset multi-track arrangements)
7. lot-198: Collaborative composition (multi-user, shared comp)
8. lot-199: Stem separation (Demucs v4 htdemucs, MIT, 6-stem)
9. lot-200: Full DAW export (WAV stems + JSON project file)