Progressive disclosure: CLI-vensters naar agentsystemen

Cijfers in deze post weerspiegelen het systeem op het moment van publicatie (januari 2026). Zie onze teampagina voor actuele cijfers.

Agentsystemen zijn van nature ondoorzichtig. Ze nemen beslissingen, roepen tools aan en coördineren werk over tientallen specialisten heen. Maar wanneer er iets misgaat — of wanneer je simpelweg wilt begrijpen wat er gebeurt — waar kijk je dan?

Het antwoord is progressive disclosure: een gelaagde interface die precies zoveel complexiteit onthult als je nodig hebt, precies wanneer je het nodig hebt.

Het ondoorzichtigheidsprobleem

Een modern agent-orchestratiesysteem kan het volgende hebben:

• 40+ gespecialiseerde agents, elk met eigen capaciteiten
• 700+ skills die interne automatisering en vendor-integraties omvatten
• 470+ architecturale beslissingen die gedrag vormgeven
• Tientallen MCP-toolservers die externe capaciteiten bieden

Deze complexiteit is opzettelijk. Agents hebben toegang tot rijke context nodig — domeinkennis, code intelligence, databaseschema’s — om goede beslissingen te nemen. Maar diezelfde rijkdom creëert een zichtbaarheidsprobleem.

Hoe weet je welke agent databasemigraties afhandelt? Welke beslissingen hebben het rankinggedrag van het zoeksysteem gevormd? Tot welke tools heeft de architecture advisor toegang?

Zonder gestructureerde toegang blijf je over met broncode lezen of hopen dat de documentatie actueel is.

Progressive disclosure als architectuur

Progressive disclosure is niet zomaar een UI-patroon. Het is een architecturaal principe: organiseer informatie in lagen, elk dieper dan de vorige, zodat gebruikers kunnen stoppen op het niveau dat hun vraag beantwoordt.

Voor agentsystemen vertaalt zich dat naar CLI-commando’s op toenemende diepte:

Niveau	Commando	Beantwoorde vraag
1	orkestra system status	Is alles gezond?
2	orkestra agents list	Welke agents bestaan er?
3	orkestra agents info <name>	Wat doet deze agent?
4	orkestra decisions search	Waarom werkt het op deze manier?
5	Maguyva MCP-tools	Laat me de code zien.

Elk niveau beantwoordt een natuurlijke vervolgvraag. Je hoeft zelden direct naar niveau 5 te springen.

Niveau 1: systeemgezondheid

De eerste vraag is altijd: werkt alles?

$ orkestra system status

on
{
  "agents": 40,
  "skills_internal": 466,
  "skills_vendor": 240,
  "skills_total": 706,
  "commands": 17
}

Eén commando. Vier cijfers. Genoeg om te weten dat het systeem geconfigureerd is en de registers gevuld zijn.

Als een agentaantal onverwacht daalt of skills niet laden, zie je dat hier het eerst. Geen logs induiken nodig.

Niveau 2: agentinventaris

Zodra je weet dat het systeem gezond is, is de volgende vraag: wat is er beschikbaar?

$ orkestra agents list

Dit geeft gestructureerde data terug — agentnamen, beschrijvingen, modelvoorkeuren, domeindekking. De output is standaard JSON, wat het makkelijk maakt om te pipen naar jq voor filtering:

$ orkestra agents list | jq '.agents[] | select(.model == "opus") | .name'

Wil je agents die databasewerk afhandelen? Het zoekcommando maakt het specifieker:

$ orkestra agents search "database"

Dit scant namen, beschrijvingen en capaciteiten. Je vindt de juiste specialist zonder 40 agentdefinities te lezen.

Niveau 3: agent-deep-dive

Een relevant lijkende agent gevonden? Het commando info onthult alles:

$ orkestra agents info architecture-advisor

De output bevat:

• Metadata: naam, categorie, modelvoorkeur, beschrijving
• Domains: welke kennisgebieden deze agent bestrijkt
• Identity: karaktertrekken (architect, strategist, knowledge-architect)
• Toolgidsen: welke tooldocumentatie in de context wordt geïnjecteerd
• Tools: de volledige lijst MCP-tools die deze agent beschikbaar heeft

Hier is een voorbeeld van wat je ziet:

on
{
  "metadata": {
    "name": "architecture-advisor",
    "model": "opus",
    "description": "Strategic decision-making and architectural guidance..."
  },
  "domains": [
    "product",
    "development/architecture",
    "meta/strategy"
  ],
  "tools": {
    "mcp_tools": [
      "mcp__maguyva__intelligent_search",
      "mcp__maguyva__analyze_dependencies",
      "mcp__supabase__execute_sql",
      ...
    ]
  }
}

Dit vertelt je precies wat de agent kan doen. Geen broncode nodig.

Niveau 4: decision archaeology

Agents gedragen zich volgens gedocumenteerde beslissingen. Wanneer je wilt begrijpen waarom iets op een bepaalde manier werkt, is het decisions-register de source of truth.

$ orkestra decisions search "agent"

Dit geeft de bijpassende architecturale beslissingen terug:

on
{
  "results": [
    {
      "id": "DEC-SR-049",
      "title": "AI-Agent-First Defaults with Graph Intelligence",
      "domain": "search",
      "status": "active"
    }
  ]
}

Elke beslissing heeft volledige herkomst — wanneer die werd genomen, waarom, welke trade-offs werden overwogen, welke commits haar implementeerden:

$ orkestra decisions info DEC-SR-049

on
{
  "id": "DEC-SR-049",
  "title": "AI-Agent-First Defaults with Graph Intelligence",
  "summary": "Changes default values for search tools to AI-agent-optimal behavior...",
  "rationale": [
    "AI agents work better with pre-ranked, importance-weighted results",
    "Graph metrics already computed by pipeline - leverage them",
    "Community context helps agents understand feature scope in single query"
  ],
  "source_commits": [
    {
      "sha": "156a880d05eae295669ef7c194b039023f245511",
      "message": "feat(maguyva): enable boost_by_importance..."
    }
  ]
}

Dit is architecturale documentatie die actueel blijft omdat ze wordt gemined uit commits, niet handmatig onderhouden.

Niveau 5: directe code intelligence

Wanneer je de daadwerkelijke implementatie moet zien — niet metadata erover — bieden de MCP-tools van Maguyva directe toegang.

Vanuit een agentsessie:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Dit routeert automatisch over semantisch, tekst- en AST-zoeken om relevante code te vinden. Voor specifieke symbolen:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Voor afhankelijkheidsanalyse:

mcp__maguyva__analyze_dependencies
  target: "packages/orchestration/core/agents.py"

Dit zijn geen simpele grep-vervangers. Ze zijn graafbewust, semantisch geïndexeerd, en geïntegreerd met dezelfde code intelligence die de agents zelf aandrijft.

Uniform zoeken over registers heen

Soms weet je niet welk register het antwoord bevat. Het uniforme zoeken bestrijkt alles:

$ orkestra search "database" --summary

on
{
  "query": "database",
  "total": 254,
  "counts": {
    "agents": 40,
    "skills": 59,
    "decisions": 476,
    "truths": 2,
    "packages": 1
  }
}

254 matches over vijf registers. De samenvatting vertelt je waar je moet doorklikken. Verwijder --summary voor gedetailleerde resultaten, of voeg --limit 5 toe om de output behapbaar te houden.

Waarom dit ertoe doet

Progressive disclosure gaat niet alleen over gemak. Het verandert hoe je met complexe systemen omgaat.

Debuggen wordt behapbaar. Wanneer een agent een onverwachte beslissing neemt, grep je niet door logs. Je controleert tot welke tools hij toegang heeft (agents info), welke beslissingen zijn gedrag vormgeven (decisions search), en traceert indien nodig de implementatie (intelligent_search).

Onboarding versnelt. Nieuwe teamleden hoeven niet de hele codebase te lezen. Ze beginnen met system status, verkennen met agents list, en gaan pas dieper wanneer ze iets tegenkomen dat ze niet begrijpen.

Documentatie blijft actueel. Omdat de CLI leest uit dezelfde registers die de agents configureren, is de output altijd accuraat. Er is geen drift tussen wat de documentatie zegt en wat het systeem doet.

De CLI als interface

We hadden een webdashboard kunnen bouwen. We hadden uitgebreide documentatie kunnen schrijven. In plaats daarvan bouwden we een CLI die leest uit de source of truth.

De CLI heeft voordelen:

• Composeerbaar: pipe output door jq, integreer met scripts
• Scriptbaar: automatiseer checks, genereer rapporten
• Snel: geen paginaladingen, geen authenticatieflows
• Accuraat: leest de daadwerkelijke configuratie, geen gecachte representatie

Voor systemen waar correctheid belangrijker is dan esthetiek, wint de CLI.

Je eigen progressive disclosure bouwen

Als je agentsystemen bouwt, bedenk dan hoe gebruikers ze zullen inspecteren:

1. Begin met health checks. Eén commando dat je vertelt of dingen werken.
2. Bied inventarisweergaven. Lijst wat bestaat voordat je uitlegt wat het doet.
3. Maak gerichte queries mogelijk. Zoeken verslaat bladeren op schaal.
4. Toon herkomst. Laat gebruikers beslissingen terugtraceren naar hun oorsprong.
5. Koppel aan code intelligence. Uiteindelijk moeten gebruikers de implementatie kunnen zien.

Elke laag beantwoordt een vervolgvraag. Bouw ze op volgorde van frequentie — de meeste gebruikers stoppen bij laag 2 of 3. Alleen powerusers bereiken laag 5.

Het doel is niet om alles bloot te leggen. Het is om precies te tonen wat nodig is, precies wanneer het nodig is. Dat is progressive disclosure toegepast op agentarchitectuur.