Skip to content

subagent-architecture.md

Latest commit

 

History

History
232 lines (178 loc) · 8.54 KB

subagent-architecture.md

File metadata and controls

232 lines (178 loc) · 8.54 KB

Subagent Architecture Guide

Overview

This repository uses a coordinator-worker delegation pattern for agent composition. Orchestrator agents (like accessibility-lead, web-accessibility-wizard, document-accessibility-wizard) coordinate specialized agents to deliver comprehensive accessibility audits.

Coordination Models

1. Explicit Coordinator Pattern (Recommended)

A single orchestrator agent maintains an allowlisted set of specialized agents it can delegate to.

Example: accessibility-lead

agents:
  - web-accessibility-wizard
  - cognitive-accessibility
  - design-system-auditor
  - aria-specialist
  - keyboard-navigator
  - forms-specialist
  - modal-specialist
  - contrast-master
  - live-region-controller
  - alt-text-headings
  - tables-data-specialist
  - link-checker
  - testing-coach
  - wcag-guide
  - text-quality-reviewer

Reward:

  • Clear delegation scope — no ambiguity about which agents a coordinator can call
  • Prevents cascading failures — specialist agents don't call other agents unpredictably
  • Faster development — agents are focused, don't coordinate with each other
  • Easier debugging — clear call graph
  • Better token efficiency — no redundant parallel discovery

Risk:

  • Coordinator must maintain accurate allowlist
  • Adding new specialists requires coordinator update
  • Single point of delegation — can become bottleneck if overloaded

2. Internal Helper Pattern

Some agents are not user-invocable and only exist to support orchestrators:

  • markdown-scanner — scans single markdown file (invoked by markdown-a11y-assistant)
  • document-inventory — builds document lists (invoked by document-accessibility-wizard)
  • cross-page-analyzer — aggregates findings (invoked by web-accessibility-wizard)

These agents:

  • Have user-invocable: false in frontmatter
  • Are called via the agent or Task tool by orchestrators
  • Are not exposed directly to users
  • Handle narrow, reusable functionality

3. Nested Subagent Pattern (VS Code 1.113+, Disabled by Default)

VS Code 1.113 supports nested subagent calls: a specialist agent calling another specialist agent.

Repo Policy:

  • Platform capability: Yes, technically supported
  • Repo recommendation: Disabled by default
  • When to enable: Only for intentionally designed orchestration flows (e.g., a coordinator agent that needs to spawn multiple parallel analysis subagents)
  • Config: chat.subagents.allowInvocationsFromSubagents (default: false)

Why disabled by default?

  1. Cascade risk — Wrong agent selection at any level propagates
  2. Token cost — Nested calls multiply latency and token consumption
  3. Debugging complexity — Deeper call stacks, harder to trace failures
  4. Ambiguous ownership — Who owns the final finding — specialist or coordinator?

When to enable (rare):

  • A coordinator orchestrates multiple parallel analysis agents that themselves delegate to focused specialists
  • Example: web-accessibility-wizard → spawn playwright-scanner AND axe-core-cli agents in parallel, each doing focused work

Delegation Rules

✅ Good Patterns

  1. Single Orchestrator Coordinates Specialists

    accessibility-lead
├── aria-specialist
├── keyboard-navigator
├── forms-specialist
└── contrast-master

  2. Orchestrator Spawns Internal Helpers

    document-accessibility-wizard
├── document-inventory
├── word-accessibility
├── excel-accessibility
├── powerpoint-accessibility
└── cross-document-analyzer

  3. Specialist Does NOT Delegate

    aria-specialist (focused, no subagents)
keyboard-navigator (focused, no subagents)
forms-specialist (focused, no subagents)

❌ Anti-Patterns

  1. Specialist Calls Another Specialist

    aria-specialist → calls keyboard-navigator
(Confusing: who does the user think is handling this?)

  2. Nested Delegation Without Clear Ownership

    accessibility-lead → web-accessibility-wizard → aria-specialist
(Three levels, unclear where issue lives if it fails)

  3. Multiple Coordinators Without Clear Scope

    accessibility-lead AND web-accessibility-wizard both claim ARIA
(Duplicate findings, conflicting guidance)

Allowlist Validation

All agents using the agent tool to invoke subagents must declare an agents: list in their frontmatter:

---
name: accessibility-lead
agents:
  - web-accessibility-wizard
  - cognitive-accessibility
  - design-system-auditor
  # ... full list of coordinable agents
---

Validator Rule: If an agent has tools: [..., 'agent', ...] but no agents: frontmatter, the CI validator (scripts/validate-agents.js) will reject it.

This ensures:

  • Explicit scope documentation
  • No surprise delegations
  • Easier code review (PR shows exactly which agents are coordinable)
  • Prevents accidental subagent calls

Framework Integration

Chat Customizations Editor (VS Code 1.113)

The Chat Customizations Editor displays agents with their allowlists:

  • Coordinator agents show their specialist agents in the UI
  • Users understand the delegation scope before invoking
  • Specialist agents (user-invocable: false) don't appear in user picker

Agent Debug Log (VS Code 1.113)

When debugging an agent orchestration:

  1. Open Agent Debug Log (chat.agentDebugLog.enabled)
  2. Trigger the coordinator agent
  3. Watch the call graph: which subagents were invoked, in what order, with what results
  4. If findings are duplicated, check the call graph for unexpected parallel calls

MCP and Subagents

MCP servers are orthogonal to subagent delegation:

  • MCP provides tools (accessibility scanning functions, GitHub API, etc.)
  • Agents invoke tools via MCP, not other agents
  • Both coordinators and specialists can invoke the same MCP tools
  • Example: Both aria-specialist and forms-specialist invoke the same MCP axe-core: scan tool

Repo Policy Summary

Aspect Decision Rationale
Coordinator pattern Explicit allowlist Clear scope, debugging simplicity
Specialist delegation No subagents Focused, less token cost
Internal helpers user-invocable: false Not in user picker, clear role
Nested subagents Disabled by default Cascade risk, token cost
Tool usage MCP preferred Platform-native, no cascades
Validation Require agents: frontmatter Prevent accidental delegation

Adding a New Specialist Agent

  1. Create the agent file with focused responsibility
  2. Set user-invocable: false if it's only for coordinators
  3. Do NOT include tools: [..., 'agent', ...] (specialists don't delegate)
  4. If a coordinator needs to call it, add to that coordinator's agents: list
  5. Document the agent's entry point in the coordinator's instructions
  6. Run scripts/validate-agents.js to verify

Adding a New Coordinator Agent

  1. Create the orchestrator agent
  2. Define the complete agents: list in frontmatter (all agents it can invoke)
  3. Include tools: [..., 'agent', ...] in the tools list
  4. Document the delegation flow in the agent's instructions
  5. Link to this architecture guide
  6. Run scripts/validate-agents.js to verify the agents: list is complete

Troubleshooting Orchestration

Symptom: Duplicate findings

Cause: Multiple coordinators are analyzing the same content Solution: Check the call graph — only one coordinator should be active per session

Symptom: Agent not invoked

Cause: Coordinator's agents: list doesn't include it, or agent has user-invocable: false Solution: Check coordinator's frontmatter agents: list; verify specialist is not marked user-invocable: false unless intentional

Symptom: Slow analysis

Cause: Nested subagents creating deep call stacks Solution: Flatten to single coordinator; move specialist work to MCP tools if possible

Symptom: Conflicting guidance

Cause: Different specialists giving different recommendations Solution: Ensure only one coordinator is active; have coordinator synthesize findings into one guidance set

References