Add "Agent Operating Model"

Agent-Operating-Model.md

@@ -0,0 +1,283 @@
+# Agent Operating Model
+
+## 1. Overzicht
+
+Dit document beschrijft het voorstel voor de inrichting van agentrollen, hun samenwerking, autonomiegrenzen en het werkmodel voor de ontwikkeling en werking van het innovatieplatform.
+
+Er zijn twee lagen van agents:
+
+1. **Bouwagents** — agents die helpen bij het ontwerpen en bouwen van het platform
+2. **Platformagents** — agents die in het uiteindelijke platform opereren als onderdeel van de AI-laag
+
+---
+
+## 2. Bouwagents: Agentrollen voor ontwikkeling
+
+### 2.1 Orchestrator
+
+**Rol:** Coördinatie, planning, kwaliteitsbewaking
+
+**Verantwoordelijkheden:**
+- Vertaalt opdrachten naar taken voor specialistische agents
+- Bewaakt samenhang en consistentie tussen outputs
+- Consolideert resultaten
+- Signaleert conflicten en open vragen
+- Escaleert beslissingen die mensvalidatie vereisen
+
+**Autonomie:** Mag taken verdelen en coördineren; mag geen architectuurbeslissingen nemen zonder validatie
+
+### 2.2 Domein- & Productarchitect
+
+**Rol:** Domeinmodellering, productvisie, functioneel ontwerp
+
+**Verantwoordelijkheden:**
+- Uitwerking domeinmodel en informatiemodel
+- Functionele decompositie
+- Gebruikersscenario's
+- Acceptatiecriteria
+
+**Autonomie:** Mag voorstellen doen; definitieve domeinbeslissingen vereisen mensvalidatie
+
+### 2.3 Solution Architect
+
+**Rol:** Technische architectuur, integratieontwerp, technologiekeuzes
+
+**Verantwoordelijkheden:**
+- Systeemarchitectuur ontwerp
+- Technologieselectie en -motivering
+- Integratiepatronen
+- Performance- en schaalbaarheidsontwerp
+- Security-architectuur
+
+**Autonomie:** Mag technische keuzes maken op basis van best practices; fundamentele architectuurwijzigingen vereisen mensvalidatie
+
+### 2.4 Backend Engineer
+
+**Rol:** Laravel-ontwikkeling, API-ontwerp, domeinimplementatie
+
+**Verantwoordelijkheden:**
+- Laravel-applicatie bouwen
+- Database-migraties en models
+- API-endpoints
+- Business logic en services
+- Tests
+
+**Autonomie:** Mag code schrijven conform goedgekeurd ontwerp; architectuurafwijkingen vereisen review
+
+### 2.5 Frontend / UX Engineer
+
+**Rol:** Vue-ontwikkeling, interface-implementatie, interactieontwerp
+
+**Verantwoordelijkheden:**
+- Vue-componenten bouwen
+- Layout en navigatie
+- Interactiepatronen
+- Responsive design
+- Component tests
+
+**Autonomie:** Mag bouwen conform goedgekeurd design; visuele keuzes volgen de stijlgids uit het designinterview
+
+### 2.6 Data & Informatiemodelleur
+
+**Rol:** Database-ontwerp, datamigratie, informatiestructuur
+
+**Verantwoordelijkheden:**
+- Database-schema ontwerp
+- Migratiescripts
+- Seed data
+- Query-optimalisatie
+- pgvector-configuratie
+
+**Autonomie:** Mag schema-wijzigingen voorstellen; destructieve wijzigingen vereisen review
+
+### 2.7 AI / Agent Engineer
+
+**Rol:** AI-service ontwikkeling, RAG-pipeline, agentlogica
+
+**Verantwoordelijkheden:**
+- Python AI-service bouwen
+- LangGraph-workflows ontwerpen
+- RAG-pipeline implementeren
+- Prompt engineering
+- Agent-tools ontwikkelen
+
+**Autonomie:** Mag AI-logica implementeren; prompts en agentgedrag vereisen review vanwege impact op gebruikerservaring
+
+### 2.8 DevOps / Platform Engineer
+
+**Rol:** Infrastructuur, deployment, monitoring
+
+**Verantwoordelijkheden:**
+- Docker-configuratie
+- Deployment-scripts
+- Monitoring opzetten
+- Backup-strategie
+- CI/CD (wanneer relevant)
+
+**Autonomie:** Mag infra-configuratie maken; productie-wijzigingen vereisen validatie
+
+### 2.9 Security / Governance Specialist
+
+**Rol:** Beveiligingsreview, compliance, autorisatieontwerp
+
+**Verantwoordelijkheden:**
+- Security review van code en architectuur
+- Autorisatiemodel ontwerp
+- Audit logging
+- Compliance-check
+
+**Autonomie:** Mag security-issues signaleren en fixes voorstellen; blokkeert niet-veilige releases
+
+### 2.10 Document & Overdrachtsontwerper
+
+**Rol:** Documentstructuur, overdrachtsprocessen, kennisontwerp
+
+**Verantwoordelijkheden:**
+- Documentatiestructuur ontwerpen
+- Overdrachtsprocessen definiëren
+- Templates voor projectdocumentatie
+- Kennistaxonomie
+
+**Autonomie:** Mag structuurvoorstellen doen; proceswijzigingen vereisen mensvalidatie
+
+---
+
+## 3. Werkmodel
+
+### 3.1 Orchestrator-model
+
+```
+                    ┌──────────┐
+                    │  MENS    │
+                    │(opdracht-│
+                    │ gever)   │
+                    └────┬─────┘
+                         │ opdracht + validatie
+                         ▼
+                    ┌──────────┐
+                    │ORCHESTR. │
+                    └────┬─────┘
+                         │ taken + review
+           ┌─────────────┼─────────────┐
+           ▼             ▼             ▼
+     ┌──────────┐ ┌──────────┐ ┌──────────┐
+     │Specialist│ │Specialist│ │Specialist│
+     │  Agent   │ │  Agent   │ │  Agent   │
+     └──────────┘ └──────────┘ └──────────┘
+```
+
+### 3.2 Workflow per taak
+
+1. **Opdracht ontvangen** — Orchestrator ontvangt opdracht van mens of vanuit plan
+2. **Decompositie** — Orchestrator splitst in deeltaken per specialisatie
+3. **Uitvoering** — Specialistische agents voeren uit (parallel waar mogelijk)
+4. **Review** — Orchestrator reviewt outputs op samenhang en kwaliteit
+5. **Consolidatie** — Resultaten worden samengebracht
+6. **Validatie** — Output wordt voorgelegd aan mens indien nodig
+7. **Integratie** — Goedgekeurde output wordt verwerkt
+
+### 3.3 Wat door mensvalidatie moet lopen
+
+| Categorie | Voorbeeld | Waarom |
+|-----------|----------|--------|
+| Architectuurbeslissingen | Keuze voor framework, database-schema wijziging | Langetermijnimpact |
+| Domeinmodelwijzigingen | Nieuwe entiteiten, gewijzigde relaties | Beïnvloedt hele applicatie |
+| UX/designkeuzes | Kleurenpalet, navigatiestructuur, layoutkeuzes | Subjectief, merkidentiteit |
+| Scopewijzigingen | Features toevoegen of schrappen | Strategisch |
+| AI-gedrag | Prompttemplates, autonomiegrenzen | Gebruikerservaring |
+| Security-bevindingen | Kwetsbaarheden, autorisatiewijzigingen | Risico |
+| Overdrachtsprocessen | Criteria, workflows | Organisatorisch |
+
+### 3.4 Wat autonoom mag worden uitgevoerd
+
+| Categorie | Voorbeeld | Voorwaarde |
+|-----------|----------|-----------|
+| Code schrijven | Implementatie conform ontwerp | Binnen goedgekeurd design |
+| Tests schrijven | Unit, feature, integratie | Altijd |
+| Bugfixes | Duidelijke bugs in bestaande code | Geen architectuurwijziging |
+| Documentatie | Code-documentatie, README's | Altijd |
+| Refactoring | Kleine verbeteringen | Geen functionele wijziging |
+| Dependency-updates | Minor/patch updates | Geen breaking changes |
+
+---
+
+## 4. Platformagents: Agents in het uiteindelijke product
+
+### 4.1 Overzicht
+
+Zie [AI- en Agentstrategie](AI-en-Agentstrategie) voor de volledige beschrijving. Samengevat:
+
+| Agent | Doel | Autonomie |
+|-------|------|----------|
+| Projectassistent | Samenvatten, analyseren, signaleren | Laag |
+| Kennisassistent | Zoeken, ophalen, presenteren | Laag |
+| Documentassistent | Structureren, suggereren, concept-generatie | Midden |
+| Analysator | Portfolioanalyse, trends, checks | Laag |
+| Systeemtaken | Embeddings, tagging, caching | Hoog |
+
+### 4.2 Beslisbaarheid en uitlegbaarheid
+
+Elk agentisch resultaat moet:
+
+- **Traceerbaar** zijn — welke agent, welke input, welke bronnen
+- **Uitlegbaar** zijn — waarom dit resultaat, op basis van wat
+- **Controleerbaar** zijn — mens kan altijd verifiëren en overrulen
+- **Gelogd** worden — voor audit en kwaliteitsverbetering
+
+---
+
+## 5. Logging en terugkoppeling
+
+### Bouwproces
+
+- Alle agenttaken worden gelogd (wat, wie, wanneer, resultaat)
+- Elke validatiestap wordt vastgelegd
+- Beslissingen worden gedocumenteerd met motivatie
+- Afgewezen voorstellen worden bewaard (met reden)
+
+### Platformoperatie
+
+- Alle AI-interacties worden gelogd
+- Gebruikersfeedback wordt gekoppeld aan AI-responses
+- Periodieke review van AI-kwaliteit en -gedrag
+- Anomaliedetectie op agent-output
+
+---
+
+## 6. Grenzen en escalatie
+
+### Escalatiepaden
+
+```
+Agent detecteert onzekerheid
+        │
+        ├── Technische onzekerheid ──▶ Orchestrator ──▶ Solution Architect
+        │
+        ├── Domeinonzekerheid ──▶ Orchestrator ──▶ Mensvalidatie
+        │
+        ├── Designonzekerheid ──▶ Orchestrator ──▶ Designinterview
+        │
+        └── Securityconcern ──▶ Direct naar mens + Security specialist
+```
+
+### Nooit door agents
+
+- Productie-deployment zonder menselijke trigger
+- Data-verwijdering zonder expliciete bevestiging
+- Communicatie naar externen
+- Budgettaire beslissingen
+- Wijzigingen aan autorisatiemodel zonder review
+
+---
+
+## 7. Evolutie van het model
+
+Dit operating model is een startpunt. Na de MVP-fase wordt geëvalueerd:
+
+- Welke rollen daadwerkelijk waarde toevoegen
+- Waar autonomie kan worden vergroot
+- Waar extra menscontrole nodig blijkt
+- Welke agents in het platform het meest worden gebruikt
+- Waar de kwaliteit van AI-output verbeterd moet worden
+
+Het model groeit mee met het platform en het team.