Je helpt mij de fundering te ontwerpen voor een diep persoonlijke AI-assistent.

Dit is geen SaaS-product en het hoeft niet te generaliseren naar duizenden gebruikers. Het moet steeds nuttiger worden voor één persoon, terwijl opgebouwde kennis onafhankelijk blijft van één AI-model, agentruntime of leverancier.

Begin niet met het bouwen van functies.

Maak eerst de architectuur, documentatie en minimale technische fundering die toekomstige agents veilig kunnen uitbreiden.

## Kernprincipes

1. Mijn data en opgebouwde context blijven van mij.
2. AI-modellen zijn vervangbare redeneerlagen.
3. Ook de orchestration-/gatewaylaag moet vervangbaar blijven.
4. Stabiele interfaces moeten modellen, tools en de kennislaag scheiden.
5. Bronbewijs is belangrijker dan een zelfverzekerde gevolgtrekking.
6. "Geen resultaat gevonden" mag nooit stilzwijgend "dit bestaat niet" worden.
7. Feiten, gevolgtrekkingen, voorstellen en acties moeten onderscheidbaar blijven.
8. Leeshandelingen en acties met gevolgen moeten onder verschillend beleid vallen.
9. Gebruik bij voorkeur bestaande applicaties en databronnen in plaats van nog een dashboard te maken.
10. Optimaliseer voor continuïteit: help mij minder context zelf te reconstrueren.
11. Bouw alleen wat door een concrete gebruikssituatie wordt gerechtvaardigd.
12. Documenteer belangrijke architectuurkeuzes voordat ze in de code verdwijnen.

## Begin met inventariseren

Inspecteer de bestaande omgeving voordat je een architectuur voorstelt.

Breng in kaart:

- besturingssysteem en apparaten
- bestaande repositories
- databases
- notities
- bestanden en cloudopslag
- e-mail
- agenda’s
- taken/herinneringen
- contacten
- browsercontext
- berichtenapps
- bronnen voor audio/transcriptie
- bestaande AI-tools
- MCP-servers of vergelijkbare interfaces
- lokale modellen
- automatiseringsmechanismen
- bestaande toegangsgegevens en grenzen van toestemming

Neem geen geheimen of privé-inhoud op in de documentatie.

Maak onderscheid tussen:

- nu beschikbaar
- gedeeltelijk beschikbaar
- gepland
- onbekend / nog niet gecontroleerd

Beschrijf een mogelijkheid nooit als werkend voordat die is gevalideerd.

## Definieer eerst de vragen

Maak `docs/USE_CASES.md`.

Begin met concrete vragen die de assistent uiteindelijk moet kunnen beantwoorden, bijvoorbeeld:

- Wat verdient op dit moment mijn aandacht?
- Welke gesprekken vereisen waarschijnlijk nog iets van mij?
- Waar wacht ik op iemand anders?
- Waar werkte ik gisteren aan en waar moet ik verdergaan?
- Bereid mij voor op mijn volgende meeting.
- Wat hebben we hierover eerder besloten?
- Welke bron ondersteunt die conclusie?
- Wat is er veranderd sinds ik hier voor het laatst naar keek?
- Hoe ziet mijn dag eruit en waar is nog ruimte?

Leg voor iedere gebruikssituatie vast:

- gebruikersvraag
- benodigde bronnen
- minimaal bewijs
- nuttige aanvullende context
- verwachte uitvoer
- omstandigheden waarin onzekerheid bestaat
- mogelijke acties
- acties waarvoor goedkeuring nodig is
- acceptatietest

Verzin geen bronnen om een gebruikssituatie mogelijk te maken.

## Maak de architectuurdocumentatie

Maak minimaal:

docs/
  README.md
  VISION.md
  PRINCIPLES.md
  USE_CASES.md
  ARCHITECTURE.md
  DATA_SOURCES.md
  KNOWLEDGE_MODEL.md
  RETRIEVAL.md
  PROVENANCE.md
  SECURITY.md
  PERMISSIONS.md
  OBSERVABILITY.md
  TESTING.md
  ROADMAP.md
  CURRENT_STATE.md
  adr/

### VISION.md

Beschrijf:

- welke cognitieve belasting dit systeem moet wegnemen
- wat het bewust niet zal worden
- waarom duurzame context onafhankelijk moet blijven
- hoe succes eruitziet voor één persoon

### ARCHITECTURE.md

Definieer heldere, vervangbare lagen:

AI-client / model
↓ toolprotocol / interface
↓ orchestration- / uitvoeringslaag
↓ bronadapters
↓ retrieval + gestructureerde kennis + graph
↓ duurzame persoonlijke data

Beschrijf interfaces tussen de lagen in plaats van ze rechtstreeks aan elkaar vast te koppelen.

### DATA_SOURCES.md

Leg voor iedere bron vast:

- eigenaar
- adapter
- toegangsmethode
- lees-/schrijfmogelijkheid
- actualiteit
- gezaghebbende velden
- bekende beperkingen
- mechanisme voor bronherkomst
- vereiste toestemmingen
- gedrag bij fouten

### KNOWLEDGE_MODEL.md

Ontwerp het eerste entiteitenmodel.

Overweeg entiteiten zoals:

- Person
- Organisation
- Project
- Conversation
- Message
- Meeting
- Document
- Note
- Task
- Decision
- Commitment
- Topic
- Source

Maak geen relaties alleen omdat twee entiteiten samen voorkomen.

Leg bij iedere duurzame relatie de bronherkomst vast en, waar relevant, de mate van zekerheid.

### RETRIEVAL.md

Ontwerp retrieval als een keten, niet als alleen "vector search".

Documenteer:

1. vraaginterpretatie
2. harde voorwaarden
3. lexicale retrieval
4. semantische retrieval
5. gestructureerde retrieval
6. graph-retrieval
7. samenvoeging van kandidaten
8. reranking
9. actualiteit
10. deduplicatie
11. samenstelling van contextpakketten
12. controles op beantwoordbaarheid
13. begrensde iteratieve retrieval

Definieer wanneer iedere laag nuttig is en wanneer die zich van een conclusie moet onthouden.

### PROVENANCE.md

Definieer hoe iedere belangrijke bewering kan worden herleid naar:

- oorspronkelijke bron
- bronidentificatie
- datum/tijd
- documentsectie/pagina/bericht/tijdcode waar mogelijk
- extractieversie
- afgeleide relatie waar relevant

Een gegenereerd antwoord is op zichzelf geen bron.

### SECURITY.md / PERMISSIONS.md

Maak onderscheid tussen:

READ
WRITE
EXTERNAL EFFECT
ADMINISTRATIVE

Begin standaard met alleen-lezen.

Voor acties zoals e-mail verzenden, agenda’s wijzigen, bestanden veranderen, apparaten bedienen of code uitrollen moet expliciet beleid bestaan.

Documenteer waar menselijke goedkeuring vereist is.

### OBSERVABILITY.md

Definieer meetbare gezondheid voor:

- beschikbaarheid van bronnen
- actualiteit van bronnen
- extractiedekking
- embedding-/indexdekking
- achterstand in gestructureerde verrijking
- vertraging van de graph
- mislukte retrieval
- latency
- toolfouten
- schemawijzigingen
- agentacties

Onbekend moet een geldige systeemstatus blijven.

### CURRENT_STATE.md

Maak een matrix op basis van bewijs:

| Mogelijkheid | Status | Bewijs | Beperking | Volgende validatie |
|---|---|---|---|---|

Gebruik uitsluitend:

- validated
- implemented_not_validated
- partial
- planned
- blocked
- unknown

Gebruik geen vage labels zoals "klaar" zonder bewijs.

## Architecture Decision Records

Maak ADR’s voor belangrijke keuzes.

Overweeg minimaal:

- local-first versus cloud-first
- duurzame kennisopslag
- strategie voor vectoropslag
- tool-/interfaceprotocol
- orchestrationlaag
- bronherkomst
- goedkeuringsmodel
- knowledge-graphstrategie
- modelonafhankelijkheid
- privacy van persoonlijke data

Iedere ADR moet bevatten:

Context
Besluit
Overwogen alternatieven
Gevolgen
Omkeerbaarheid

## Werkinstructies voor agents

Maak `AGENTS.md`.

Dit moet toekomstige coding agents instrueren om:

- eerst de architectuur- en huidige-statusdocumentatie te lezen
- te inspecteren voordat ze wijzigingen aanbrengen
- bestaande interfaces te behouden, tenzij ze bewust een nieuwe versie krijgen
- nooit stilzwijgend rechten te verruimen
- nooit validatie te claimen op basis van alleen implementatie
- tests toe te voegen bij iedere mogelijkheid
- documentatie bij te werken wanneer de architectuur verandert
- de voorkeur te geven aan afgebakende wijzigingen
- belangrijke besluiten als ADR vast te leggen
- bronfeiten te onderscheiden van afgeleide conclusies
- privé-inhoud uit logs en testfixtures te houden
- de repository in een hervatbare staat achter te laten

## Minimale repositoryfundering

Maak pas nadat de documentatie bestaat de kleinste bruikbare boilerplate.

Gebruik bij voorkeur een structuur zoals:

src/
  adapters/
  retrieval/
  knowledge/
  orchestration/
  permissions/
  observability/
tests/
  unit/
  integration/
  fixtures/
docs/
config/
scripts/

Implementeer geen twintig integraties.

Bouw:

- één interface voor bronadapters
- één tool-/interfacecontract
- één retrievalinterface
- één model voor bronherkomst
- één rechtenmodel
- basiscomponenten voor gezondheid/status
- testfixtures
- configuratie-inlezing
- gestructureerde logging

Implementeer vervolgens ÉÉN smalle end-to-end-keten.

Bijvoorbeeld:

"Vind één bekend document en geef een antwoord met brononderbouwing."

Die keten moet aantonen:

bron → adapter → retrieval → bronherkomst → assistentcontext → antwoord

Breid pas daarna uit.

## Roadmap

Bouw de roadmap vanuit gebruikerswaarde, niet vanuit technische nieuwigheid.

Ieder roadmap-item moet bevatten:

- gebruikersprobleem
- benodigde bronnen
- afhankelijkheden
- afgebakende implementatiestap
- validatiemethode
- faalcondities
- privacy-impact
- definitie van gereed

Geef de voorkeur aan één gevalideerde end-to-end-keten boven tien gedeeltelijk gebouwde subsystemen.

## Eindresultaat

Geef na afronding terug:

1. aangetroffen huidige staat
2. voorgestelde architectuur
3. gegenereerde documentatiestructuur
4. belangrijkste architectuurkeuzes
5. repositoryskelet
6. eerste end-to-end-keten
7. gemaakte tests
8. onopgeloste risico’s
9. aannames waarvoor mijn bevestiging nodig is
10. volgende drie afgebakende implementatiestappen

Blijf niet meer functionaliteit toevoegen alleen omdat er nog tijd over is.

Bouw een fundering die een andere agent morgen begrijpt, zonder het oorspronkelijke gesprek nodig te hebben waarin die fundering is ontstaan.