Wanneer een AI-samenwerkingsrepo zijn eigen bron van waarheid aantast

Wanneer teams AI-agents dagelijks gaan gebruiken, groeien enkele prompts snel uit tot een gedeelde repository met Skills, Plugins, teamregels, projectingangen, procedures en verzamelde adviezen.

De repository die ik bestuurde volgde hetzelfde patroon. Voor ieder nieuw probleem leek een extra regel of Skill redelijk. Uiteindelijk begon de repo de single source of truth aan te tasten die zij juist moest beschermen.

Achtergrond

De repo coördineerde werkmethoden voor meerdere teams en AI-agents. Zij bevatte bedrijfsbrede contracten, interne teamacties, externe interfaces, lifecycle-regels en optionele productiviteitsmethoden.

Deze bestanden zijn geen documentatie die mensen af en toe lezen: ze komen in agentcontext terecht en veranderen direct gedrag. Iedere extra entiteit kost daarom blijvend onderhoud, veroorzaakt mogelijke conflicten, vergroot context en maakt gedrag minder voorspelbaar wanneer instructies elkaar tegenspreken.

De juiste vraag was niet alleen of tekst nuttig was. De gedragswaarde moest groter zijn dan de onderhoudskosten.

Pijnpunten

Concurrerende bronnen van waarheid

Eén regel kon tegelijk in een Team Contract, Skill, README, statische projectmap en handleiding staan. Zodra één kopie veranderde, dreven de projecties uiteen. Agents ontvingen meerdere plausibele maar incompatibele versies.

Verschillende soorten capabilities deelden één model

Verplichte bedrijfscontracten, externe teaminterfaces, interne procedures en persoonlijke productiviteitstips werden als gelijkwaardige Skills behandeld. Optioneel advies leek verplicht en teamlokale acties leken bedrijfsbreed.

De repo bouwde platformfuncties opnieuw

Eigen regels voor discovery, installatie, updates, review en release dupliceerden deels Codex Plugin/Skill-tools, GitHub Issue/PR-processen en release contracts. Die tweede lifecycle kostte onderhoud zonder uniek gedrag.

Meer context bewees geen hogere betrouwbaarheid

Voor de cleanup bevatten 22 SKILL.md-bestanden samen 2.975 regels. Het volume groeide, zonder bewijs dat ieder onderdeel agents sneller of correcter maakte.

Aanpak

Gebruik de deletion counterfactual

Voor iedere entiteit vroeg ik:

Als dit verdwijnt, handelt de agent dan verkeerd of wordt hij betekenisvol langzamer?

Als geen van beide veranderde, hoorde de entiteit niet als zelfstandige Skill te blijven. Uniek gedrag verhuisde naar de canonical home; duplicaten werden verwijderd.

Scheid vijf capabilityklassen

Ik bouwde de capability map opnieuw rond vijf verantwoordelijkheden:

1. Skill lifecycle — één ingang voor Find, Adopt, Contribute en Release;
2. Bedrijfscontracten — gedeelde SoT, autoriteit, status en deliverygrenzen;
3. Externe teaminterfaces — inputs, zichtbare status, outputs en acceptatie;
4. Interne teamcontracten en acties — beslissingen en grenzen binnen één domein;
5. Adhoc efficiency-capabilities — optionele methoden, geen verplichte contracten.

Dit model definieert eigenaarschap en autoriteit; het is niet slechts een directory-indeling.

Gebruik gemeenschappelijke toelatingspoorten

Iedere formele Skill moet dezelfde negen invariant gates doorstaan voor verantwoordelijkheid, bronnen van waarheid, autoriteit, statussemantiek en deliverybewijs. Wat niet slaagt blijft op HOLD.

Delegeer mechanismen aan native tools

Codex Plugin-commando’s beheren discovery, installatie, verwijdering en readback. GitHub Issues en PR’s bewaren implementatie- en reviewbewijs. Release contracts bewaren publicatiestatus. De gedeelde repo houdt alleen de unieke WHAT, beslisgrenzen en routinglogica van het bedrijf.

Resultaten

De vergelijking is strikt beperkt tot plugins/*/skills/*/SKILL.md:

Metriek	Voor	Na	Verandering
Regels Skill-instructies	2.975	1.437	-51,7%
Aantal Skills	22	18	-18,2%

Negen Skills werden verwijderd; toevoegingen en samenvoegingen vormden vijf capabilities. Netto verdwenen 1.538 regels. De grootste winst kwam uit het afslanken van behouden Skills, niet alleen uit verwijderde directories.

De source-refactor doorstond 98 tests en alle 18 Skill-folders slaagden voor onafhankelijke validatie. Belangrijker: SoT, projecties en capability-eigenaarschap zijn nu expliciet. Bedrijfsregels, teaminterfaces en persoonlijke methoden concurreren niet langer om dezelfde autoriteit.

Ik presenteer dit niet als een gekwantificeerde productiviteitswinst. Daarvoor ontbreekt bewijs. Het aantoonbare resultaat is governance: tegenstrijdige context werd verwijderd, agents krijgen minder en duidelijkere regels en iedere capability heeft een toetsbaar toelatings- en lifecyclemodel.

Voor AI-samenwerking betekent meer context niet automatisch meer capability. Duurzame waarde komt uit minder conflicten, duidelijke autoriteit en de eis dat iedere regel benoemt welk gedrag zij werkelijk verandert.