Progressive Disclosure: Mga Bintanang CLI Papasok sa Agent Systems

Ang mga numero sa post na ito ay sumasalamin sa system noong publication (Enero 2026). Tingnan ang aming team page para sa kasalukuyang mga figure.

Opaque by design ang agent systems. Gumagawa sila ng mga desisyon, tumatawag ng mga tool, at nagko-coordinate ng trabaho sa daan-daang specialist. Pero kapag may nasira—o kapag gusto mo lang maintindihan kung ano ang nangyayari—saan ka titingin?

Ang sagot, progressive disclosure: isang layered na interface na nagbubunyag lang ng eksaktong dami ng complexity na kailangan mo, sa eksaktong sandaling kailangan mo ito.

Ang Problema sa Opacity

Puwedeng magkaroon ang isang modernong agent orchestration system ng:

• 40+ specialist agent, bawat isa may natatanging capabilities
• 700+ skill na sumasaklaw sa internal automation at vendor integrations
• 470+ architectural decision na humuhubog sa behavior
• Dose-dosenang MCP tool server na nagbibigay ng external capabilities

Sinadya ang complexity na ito. Kailangan ng mga agent ng access sa mayamang context—domain knowledge, code intelligence, database schemas—para gumawa ng magagandang desisyon. Pero ang parehong kayamanang iyon, gumagawa ng problema sa visibility.

Paano mo malalaman kung aling agent ang humahawak ng database migrations? Anong mga desisyon ang humubog sa ranking behavior ng search system? Aling mga tool ang na-access ng architecture advisor?

Kung walang structured na access, mababasa mo na lang ang source code o umaasang updated ang documentation.

Progressive Disclosure Bilang Architecture

Hindi lang isang UI pattern ang progressive disclosure. Isa itong architectural principle: i-organisa ang impormasyon sa mga layer, bawat isa mas malalim sa huli, para makapag-stop ang mga user sa level na sumasagot sa tanong nila.

Para sa agent systems, isinasalin ito sa mga CLI command sa tumataas na lalim:

Level	Command	Tanong na Nasasagot
1	orkestra system status	Malusog ba ang lahat?
2	orkestra agents list	Anong mga agent ang umiiral?
3	orkestra agents info <name>	Ano ang ginagawa ng agent na ito?
4	orkestra decisions search	Bakit ganito ito gumagana?
5	Mga MCP tool ng Maguyva	Ipakita mo sa akin ang code.

Sinasagot ng bawat level ang natural na follow-up na tanong. Bihira mong kailanganing tumalon deretso sa level 5.

Level 1: Kalusugan ng System

Ang unang tanong, palaging: gumagana ba ang lahat?

$ orkestra system status

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

Isang command. Apat na numero. Sapat na para malaman na naka-configure ang system at populated ang mga registry.

Kung biglang bumaba ang bilang ng agent o nabigo ang paglo-load ng skills, makikita mo ito rito muna. Walang kailangang log diving.

Level 2: Inventory ng Agent

Kapag alam mo nang malusog ang system, ang susunod na tanong: ano ang available?

$ orkestra agents list

Nagbabalik ito ng structured data—mga pangalan ng agent, descriptions, model preferences, domain coverage. JSON by default ang output, madaling i-pipe papunta sa jq para sa filtering:

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

Gusto mo ng mga agent na humahawak ng database work? Pinapaliit ito ng search command:

$ orkestra agents search "database"

Sini-scan nito ang mga pangalan, deskripsyon, at capabilities. Mahahanap mo ang tamang specialist nang hindi na kailangang basahin ang 40 agent definition.

Level 3: Deep Dive sa Agent

Nakahanap ng agent na mukhang relevant? Ibinubunyag ng command na info ang lahat:

$ orkestra agents info architecture-advisor

Kasama sa output:

• Metadata: Pangalan, kategorya, model preference, deskripsyon
• Domains: Aling mga knowledge area ang sinasaklaw ng agent na ito
• Identity: Mga katangian ng karakter (architect, strategist, knowledge-architect)
• Mga gabay sa tool: Aling tool documentation ang ini-inject sa context
• Tools: Ang buong listahan ng MCP tool na available sa agent na ito

Narito ang sample ng makikita mo:

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",
      ...
    ]
  }
}

Sinasabi nito sa iyo nang eksakto kung ano ang kaya ng agent. Hindi na kailangan ng source code.

Antas 4: Arkeolohiya ng desisyon

Kumikilos ang mga agent ayon sa mga naitalang desisyon. Kapag kailangan mong maintindihan ang bakit gumagana ang isang bagay sa isang particular na paraan, ang decisions registry ang source of truth.

$ orkestra decisions search "agent"

Nagbabalik ito ng mga tumutugmang architectural decision:

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

Bawat desisyon, may buong provenance—kailan ito ginawa, bakit, anong mga trade-off ang isinaalang-alang, aling mga commit ang nag-implement nito:

$ 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..."
    }
  ]
}

Ito ang architectural documentation na nananatiling current dahil kinukuha ito mula sa mga commit, hindi manually maintained.

Level 5: Direktang Code Intelligence

Kapag kailangan mong makita ang aktwal na implementation—hindi metadata tungkol dito—nagbibigay ng direktang access ang mga MCP tool ng Maguyva.

Mula sa loob ng isang agent session:

mcp__maguyva__intelligent_search
  query: "agent context loading"

Auto-routes ito sa semantic, text, at AST search para mahanap ang relevant na code. Para sa mga specific na symbol:

mcp__maguyva__find_symbol
  symbol_name: "load_agent_context"

Para sa dependency analysis:

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

Hindi lang ito mga grep replacement. Graph-aware sila, semantically indexed, at integrated sa parehong code intelligence na nagpapatakbo sa mga agent mismo.

Unified Search Sa Lahat ng Registry

Minsan, hindi mo alam kung aling registry ang may hawak ng sagot. Sinasaklaw ng unified search ang lahat:

$ orkestra search "database" --summary

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

254 na tugma sa limang registry. Sinasabi sa iyo ng summary kung saan mag-drill down. Alisin ang --summary para sa detalyadong resulta, o idagdag ang --limit 5 para panatilihing manageable ang output.

Bakit Mahalaga Ito

Hindi lang tungkol sa convenience ang progressive disclosure. Binabago nito kung paano ka nakikipag-interact sa mga komplikadong system.

Nagiging tractable ang debugging. Kapag gumawa ang isang agent ng hindi inaasahang desisyon, hindi ka nagge-grep sa mga log. Chine-check mo kung aling mga tool ang na-access nito (agents info), anong mga desisyon ang humuhubog sa behavior nito (decisions search), at sinusubaybayan ang implementation kung kailangan (intelligent_search).

Mas bilis ang onboarding. Hindi kailangang basahin ng mga bagong miyembro ng team ang buong codebase. Nagsisimula sila sa system status, nag-e-explore gamit ang agents list, at lumalalim lang kapag may nadatnan silang hindi nila maintindihan.

Nananatiling current ang documentation. Dahil binabasa ng CLI ang parehong mga registry na nag-configure sa mga agent, laging tumpak ang output. Walang drift sa pagitan ng sinasabi ng docs at ginagawa ng system.

Ang CLI Bilang Interface

Puwede kaming gumawa ng web dashboard. Puwede kaming sumulat ng masusing documentation. Sa halip, gumawa kami ng CLI na nagbabasa mula sa source of truth.

May mga bentahe ang CLI:

• Composable: I-pipe ang output sa pamamagitan ng jq, i-integrate sa mga script
• Scriptable: I-automate ang mga check, gumawa ng mga report
• Mabilis: Walang page loads, walang authentication flows
• Tumpak: Binabasa ang aktwal na configuration, hindi isang cached na representasyon

Para sa mga system kung saan mas mahalaga ang correctness kaysa aesthetics, panalo ang CLI.

Paggawa ng Sarili Mong Progressive Disclosure

Kung gumagawa ka ng agent systems, isaalang-alang kung paano sisiyasatin ito ng mga user:

1. Magsimula sa health checks. Isang command na nagsasabi sa iyo kung gumagana ang mga bagay.
2. Magbigay ng inventory views. Ilista kung ano ang umiiral bago ipaliwanag kung ano ang ginagawa nito.
3. Paganahin ang targeted na queries. Mas mahusay ang search kaysa sa pag-browse kapag malaking sukat.
4. Ibunyag ang provenance. Hayaan ang mga user na subaybayan ang mga desisyon pabalik sa pinagmulan nila.
5. Ikonekta sa code intelligence. Sa huli, kailangang makita ng mga user ang implementation.

Sinasagot ng bawat layer ang isang follow-up na tanong. Buuin ang mga ito ayon sa frequency—karamihan sa mga user, huminto sa layer 2 o 3. Mga power user lang ang umaabot sa layer 5.

Hindi ang punto, ibunyag ang lahat. Ang punto, ibunyag ang eksaktong kailangan, sa eksaktong sandaling kailangan ito. Iyon ang progressive disclosure na inilapat sa agent architecture.