How to Implement Subagent Delegation Patterns in Custom Agents for HVE Core

Subagent delegation patterns enable parent agents to orchestrate specialized subagents by declaring dependencies in front-matter and invoking them via runSubagent or task tools, creating modular, maintainable workflows.

Subagent delegation patterns form the architectural backbone of the microsoft/hve-core repository, allowing complex AI workflows to be decomposed into focused, reusable components. By implementing subagent delegation patterns, you can build parent orchestrators that coordinate specialized subagents for research, implementation, or validation without monolithic agent definitions.

Architecture of Subagent Delegation

Understanding the core components is essential before implementing subagent delegation patterns in your custom agents. The architecture separates concerns between orchestration and execution, using declarative front-matter and glob-based path resolution.

Parent Orchestrator Agents

The parent agent (orchestrator) declares its subagent dependencies in the agents: front-matter field and controls the overall workflow flow. According to the RPI Agent definition, pure orchestrators set disable-model-invocation: true to prevent the parent from invoking its own model when it only coordinates work. The parent defines the protocol for when and how each subagent runs, potentially launching independent subagents in parallel and aggregating their outputs before proceeding to the next phase.

Subagent Files

Subagent files contain focused logic for specific tasks and reside under <collection>/subagents/. Each subagent file sets user-invocable: false in its front-matter to prevent direct invocation from the UI, ensuring they can only be called by parent agents. As implemented in the Researcher Subagent, these files expose only the tools required for their specific task and define clear input/output contracts.

Invocation Protocol

The parent invokes subagents using the runSubagent or task tool with a glob path like .github/agents/**/researcher-subagent.agent.md. This glob pattern ensures the engine can resolve the subagent regardless of directory depth or collection layout changes. The orchestrator supplies required inputs through the inputs field, and the subagent returns artifact paths and status indicators for the parent to consume.

When to Use Subagent Delegation Patterns

Implement subagent delegation patterns when your workflow exhibits specific characteristics that benefit from modular separation.

• Distinct tool sets – When a step requires specialized tools (e.g., web search, file grep) that the parent does not need, encapsulate the logic in a subagent to maintain least-privilege tool access.
• Structured output requirements – When a step produces file-based artifacts (research logs, validation reports) that subsequent phases consume, subagents isolate that responsibility and output generation.
• Cross-flow reusability – When logic such as convention discovery or phase implementation recurs across multiple parent agents (RPI Agent, PR reviewer, design-thinking coach), subagents prevent duplication.

Conversely, keep simple, single-line actions inline to avoid unnecessary overhead. Delegation adds coordination complexity, so use it for substantial, self-contained subtasks.

Step-by-Step Implementation Guide

Follow these steps to implement subagent delegation patterns in your HVE Core custom agents.

1. Create the Subagent File

Place the subagent under <collection>/subagents/ with restricted permissions and focused tool grants.

---
name: Researcher Subagent
description: "Research subagent using search, read, fetch-web, and GitHub tools"
user-invocable: false
---

# Researcher Subagent

## Inputs

- `scope` – topic to investigate.
- `output` – file path where the research log will be stored.

## Protocol

1. Use `search` to find relevant docs.
2. `read` key instruction files.
3. `fetch_web` for external references.
4. Write findings to `{{output}}`.

## Response

Return the path to the research document and a status flag.

2. Declare Dependencies in Parent Front-Matter

Add the agents list and disable model invocation if the parent only orchestrates.

---
name: Simple Orchestrator
description: "Coordinates research and implementation subagents"
disable-model-invocation: true
agents:
  - Researcher Subagent
  - Phase Implementor
---

3. Reference Subagents with Glob Paths

Use glob patterns in the parent body to ensure path resolution remains stable across directory restructuring.

Run the researcher subagent at `.github/agents/**/researcher-subagent.agent.md`.

4. Invoke with runSubagent

Call the subagent with explicit inputs and output destinations.

- name: Conduct conventions discovery
  runSubagent:
    agent: researcher-subagent
    path: .github/agents/**/researcher-subagent.agent.md
    inputs:
      scope: "workspace conventions"
      output: ".copilot-tracking/research/{{date}}/conventions.md"

5. Collect and Consume Output

After the subagent finishes, the parent reads the generated artifact using the read tool and incorporates findings into subsequent phases.

- name: Load research findings
  read:
    path: ".copilot-tracking/research/{{date}}/conventions.md"

6. Parallelize Independent Subagents

When subagents have no inter-dependencies, launch them simultaneously to reduce total execution time. The parent waits for all completions before aggregating results and proceeding to the next phase.

Common Subagent Delegation Patterns

The HVE Core ecosystem relies on several canonical patterns implemented in the RPI Agent and supporting subagents.

Pattern	Parent Agent	Subagent(s)	Goal
Research delegation	RPI Agent, PR reviewer	researcher-subagent	Gather codebase conventions, external documentation, or user-provided topics.
Phase execution	RPI Agent (Phase 3)	phase-implementor	Execute concrete implementation steps defined in the planning phase.
Validation	RPI Agent (Phase 4)	plan-validator, implementation-validator	Verify implementation matches the plan and quality standards.
Prompt updating	Prompt-builder agent	prompt-updater, prompt-tester	Refresh generated prompt files after code changes.

All patterns follow the same declarative flow: declare dependencies in front-matter, invoke via runSubagent, read output artifacts, and decide the next step.

Best Practices for Subagent Delegation

Follow these guidelines to maintain clean, maintainable subagent hierarchies.

• Prevent nested delegation – Never allow a subagent to call another subagent; only the parent coordinates delegation to avoid circular dependencies and complexity.
• Maintain single responsibility – Split subagents that handle both research and validation into separate, focused units.
• Version control together – Store subagents under the same .github/agents/ tree as their parents to ensure version consistency across the collection.
• Document contracts explicitly – Define inputs, outputs, and response formats in the subagent's Markdown body to help parent authors understand what files to read and what parameters to supply.

Summary

• Subagent delegation patterns in HVE Core use parent agents to declare dependencies via the agents: front-matter field and invoke subagents using runSubagent with glob paths.
• Subagents must set user-invocable: false and live under <collection>/subagents/ to prevent direct UI access while allowing parent orchestration.
• Parent orchestrators should set disable-model-invocation: true when they only coordinate work, preventing unnecessary model calls.
• Glob paths like .github/agents/**/researcher-subagent.agent.md ensure subagent resolution remains robust against directory restructuring.
• Parallel execution of independent subagents reduces workflow latency, while the parent aggregates outputs before proceeding.

Frequently Asked Questions

What is the difference between runSubagent and task for invoking subagents?

Both runSubagent and task tools initiate subagent execution, but runSubagent is the primary mechanism for structured delegation with explicit input/output contracts. According to the RPI Agent source, runSubagent accepts an agent name, path (glob), and inputs object, making it ideal for declarative workflows where the parent expects specific artifact outputs.

Can subagents invoke other subagents in HVE Core?

No, subagents should never invoke other subagents. Only the parent agent coordinates delegation to prevent circular dependencies and maintain clear separation of concerns. As documented in the agents customization guide, the parent maintains sole responsibility for workflow orchestration while subagents remain leaf nodes focused on single responsibilities.

How do I pass data between a parent agent and its subagent?

Pass data through the inputs field in the runSubagent configuration, where the parent supplies parameters like file paths or search scopes. The subagent then writes results to the specified output location (typically under .copilot-tracking/), and the parent uses the read tool to consume these artifacts in subsequent phases.

Why must subagent paths use glob patterns instead of relative paths?

Glob patterns like .github/agents/**/researcher-subagent.agent.md allow the HVE Core engine to resolve subagents regardless of directory depth or collection layout changes. This abstraction ensures that refactoring the directory structure under .github/agents/ does not break existing parent agent invocations, providing stability across repository versions and submodule inclusions.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}