fix(agents): add subagent support with dedicated subagent files and simplified prompts (#639)

Previously, parent agents contained large inline instruction blocks for
tasks like research, validation, implementation, and prompt testing.
This made agents difficult to maintain, test independently, and reuse
across workflows. This PR extracts those responsibilities into eight
dedicated subagent files and updates the entire agent ecosystem
accordingly.

**Subagent extraction** — Eight focused subagents now live under
`.github/agents/subagents/`: `implementation-validator`,
`phase-implementor`, `plan-validator`, `prompt-evaluator`,
`prompt-tester`, `prompt-updater`, `researcher-subagent`, and
`rpi-validator`. Each owns a single responsibility that was previously
duplicated or embedded inline across multiple parent agents.

**Parent agent rewrites** — Seven parent agents (`rpi-agent`,
`task-implementor`, `task-planner`, `task-researcher`, `task-reviewer`,
`prompt-builder`, `doc-ops`) were restructured to declare subagent
dependencies through `agents:` frontmatter with glob-based resolution
paths. The agents now orchestrate work by invoking subagents rather than
executing everything inline.

**Prompt simplification** — Eight prompt files were reduced to lean
wrappers containing only the user-facing Requirements section. Workflow
logic that previously lived in prompts moved into their corresponding
agents, giving prompts a clear single purpose: capture user intent and
delegate.

**Instructions update** — The `prompt-builder.instructions.md` file
gained guidance for the new subagent structural template, agent
delegation patterns, and sandbox environment definitions.

**Configuration and discovery** — VS Code settings,
`copilot-instructions.md`, and `CUSTOM-AGENTS.md` were updated so the
new `subagents/` directory is discoverable and the documentation
reflects current terminology and architecture.

**Collection and plugin alignment** — All nine collection manifests and
their corresponding markdown descriptions were updated to include the
new subagent entries. Plugin outputs were regenerated with updated agent
tables and symlinks.

## Related Issue(s)

<!-- No issue references detected in commits or branch name -->

## Type of Change

Select all that apply:

**Code & Documentation:**

- [x] Bug fix (non-breaking change fixing an issue)
- [ ] New feature (non-breaking change adding functionality)
- [ ] Breaking change (fix or feature causing existing functionality to
change)
- [ ] Documentation update

**Infrastructure & Configuration:**

- [ ] GitHub Actions workflow
- [ ] Linting configuration (markdown, PowerShell, etc.)
- [ ] Security configuration
- [ ] DevContainer configuration
- [ ] Dependency update

**AI Artifacts:**

- [x] Reviewed contribution with `prompt-builder` agent and addressed
all feedback
- [x] Copilot instructions (`.github/instructions/*.instructions.md`)
- [x] Copilot prompt (`.github/prompts/*.prompt.md`)
- [x] Copilot agent (`.github/agents/*.agent.md`)
- [ ] Copilot skill (`.github/skills/*/SKILL.md`)

> **Note for AI Artifact Contributors**:
>
> - **Agents**: Research, indexing/referencing other project (using
standard VS Code GitHub Copilot/MCP tools), planning, and general
implementation agents likely already exist. Review `.github/agents/`
before creating new ones.
> - **Skills**: Must include both bash and PowerShell scripts. See
[Skills](../docs/contributing/skills.md).
> - **Model Versions**: Only contributions targeting the **latest
Anthropic and OpenAI models** will be accepted. Older model versions
(e.g., GPT-3.5, Claude 3) will be rejected.
> - See [Agents Not
Accepted](../docs/contributing/custom-agents.md#agents-not-accepted) and
[Model Version
Requirements](../docs/contributing/ai-artifacts-common.md#model-version-requirements).

**Other:**

- [ ] Script/automation (`.ps1`, `.sh`, `.py`)
- [ ] Other (please describe):

## Sample Prompts (for AI Artifact Contributions)

**User Request:**

`/rpi Research, plan, and implement subagent support for the
task-planner agent`

**Execution Flow:**

1. User invokes `rpi-agent`; the agent loads subagents via `agents:`
frontmatter glob paths
2. Research phase delegates to `researcher-subagent` for codebase
analysis
3. Planning phase invokes `plan-validator` to validate the generated
plan against research findings
4. Implementation phase delegates to `phase-implementor` for each phase,
with change tracking
5. Review phase uses `rpi-validator` per phase and
`implementation-validator` for quality assessment

**Output Artifacts:**

Tracking artifacts in `.copilot-tracking/` remain unchanged. Subagent
delegation is transparent to the user; parent agents orchestrate the
workflow using glob-based subagent resolution.

**Success Indicators:**

- Parent agents invoke subagents through the subagent tool without
manual intervention
- Subagent files appear in `.github/agents/subagents/` and are
discoverable via `chat.agentFilesLocations`
- Collection manifests include all subagent dependencies for each parent
agent

## Testing

<!-- Describe how you tested these changes -->

## Checklist

### Required Checks

- [ ] Documentation is updated (if applicable)
- [ ] Files follow existing naming conventions
- [ ] Changes are backwards compatible (if applicable)
- [ ] Tests added for new functionality (if applicable)

### AI Artifact Contributions
<!-- If contributing an agent, prompt, instruction, or skill, complete
these checks -->
- [ ] Used `/prompt-analyze` to review contribution
- [ ] Addressed all feedback from `prompt-builder` review
- [ ] Verified contribution follows common standards and type-specific
requirements

### Required Automated Checks

The following validation commands must pass before merging:

- [ ] Markdown linting: `npm run lint:md`
- [ ] Spell checking: `npm run spell-check`
- [ ] Frontmatter validation: `npm run lint:frontmatter`
- [ ] Link validation: `npm run lint:md-links`
- [ ] PowerShell analysis: `npm run lint:ps`

## Security Considerations
<!-- ⚠️ WARNING: Do not commit sensitive information such as API keys,
passwords, or personal data -->
- [x] This PR does not contain any sensitive or NDA information
- [ ] Any new dependencies have been reviewed for security issues
- [ ] Security-related scripts follow the principle of least privilege

## Additional Notes

All changed GHCP files (agents, prompts, instructions) have `stable`
maturity in collection manifests. No non-stable GHCP artifacts are
introduced or modified in this PR.

The user-facing invocation patterns for all agents and prompts remain
unchanged. The subagent architecture is an internal refactoring that
moves reusable logic from inline sections in parent agents into
dedicated, composable subagent files resolved through glob paths in
`agents:` frontmatter.

🔧 Generated by Copilot using the repository PR template

---------

Co-authored-by: katriendg <katriendg@users.noreply.github.com>

Author: agreaves-ms

.github/CUSTOM-AGENTS.md

@@ -40,7 +40,7 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com
 
 | Agent                | Purpose                                                           | Key Constraint                                 |
 |----------------------|-------------------------------------------------------------------|------------------------------------------------|
-| **rpi-agent**        | Autonomous agent with subagent delegation for complex tasks       | Requires `runSubagent` tool enabled            |
+| **rpi-agent**        | Autonomous agent with subagent delegation for complex tasks       | Requires a subagent tool enabled               |
 | **task-researcher**  | Produces research documents with evidence-based recommendations   | Research-only; never plans or implements       |
 | **task-planner**     | Creates 3-file plan sets (plan, details, prompt)                  | Requires research first; never implements code |
 | **task-implementor** | Executes implementation plans with subagent delegation            | Requires completed plan files                  |
@@ -102,7 +102,7 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com
 
 **Workflow:** Understand → Implement → Verify → Continue or Complete
 
-**Critical:** Requires `runSubagent` tool enabled. Delegates MCP tools, heavy terminal commands, and complex research to subagents. Provides autonomous execution with loop guard for detecting stuck states.
+**Critical:** Requires a subagent tool enabled. Delegates MCP tools, heavy terminal commands, and complex research to subagents. Provides autonomous execution with loop guard for detecting stuck states.
 
 ### task-researcher
 
@@ -113,7 +113,7 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com
 
 **Workflow:** Deep tool-based research → Document findings → Consolidate to one approach → Hand off to planner
 
-**Critical:** Research-only specialist. Uses `runSubagent` tool. Continuously refines document. Never plans or implements.
+**Critical:** Research-only specialist. Uses subagent tools. Continuously refines document. Never plans or implements.
 
 ### task-planner
 
@@ -132,7 +132,7 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com
 
 * `.copilot-tracking/changes/{{YYYY-MM-DD}}-task-changes.md` (chronological log with Added/Modified/Removed sections)
 
-**Workflow:** Analyze plan → Dispatch subagents per phase → Track progress → Validate
+**Workflow:** Analyze plan → Run subagents per phase → Track progress → Validate
 
 **Critical:** Requires completed plan files. Uses subagent architecture for parallel phase execution. Updates tracking artifacts after each phase.
 
@@ -346,7 +346,7 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com
 2. Provide your request
 3. Agent autonomously researches, implements, and verifies
 4. Review results; agent continues if more work remains
-5. Requires `runSubagent` tool enabled in settings
+5. Requires a subagent tool enabled in settings
 
 ### Planning a Feature
 
@@ -386,7 +386,7 @@ The Research-Plan-Implement (RPI) workflow provides a structured approach to com
 * **Agent Switching:** Clear context or start a new chat when switching between specialized agents
 * **Research First:** Task planner requires completed research; will automatically invoke researcher if missing
 * **No Implementation:** Task planner and researcher never implement actual project code—they create planning artifacts only
-* **Subagent Requirements:** Several agents require the `runSubagent` tool enabled in Copilot settings
+* **Subagent Requirements:** Several agents require a subagent tool enabled in Copilot settings
 
 ## Tips
 

.github/agents/doc-ops.agent.md

@@ -1,5 +1,9 @@
 ---
 description: 'Autonomous documentation operations agent for pattern compliance, accuracy verification, and gap detection - Brought to you by microsoft/hve-core'
+disable-model-invocation: true
+agents:
+  - researcher-subagent
+  - phase-implementor
 ---
 
 # Documentation Operations Agent
@@ -9,16 +13,16 @@ Autonomous agent for documentation quality assurance. Discovers divergences from
 ## Core Principles
 
 * Operate autonomously after initial invocation with minimal user interaction.
-* Use runSubagent for all discovery, planning, and implementation work.
+* Use subagents for all discovery, planning, and implementation work.
 * Continue iterating through phases until all issues are resolved.
 * Track all work in `.copilot-tracking/doc-ops/` session files.
 
 ## Tool Availability
 
-This agent requires the runSubagent tool for all documentation processing.
+This agent runs subagents for all documentation processing. Run `researcher-subagent` or `phase-implementor` agents with `runSubagent` or `task` tools. If using the `runSubagent` tool then include instructions for the subagent to read and follow all instructions from the corresponding `.github/agents/` file.
 
-* When runSubagent is available, dispatch subagents as specified in each phase.
-* When runSubagent is unavailable, inform the user that this workflow requires subagent capability and stop.
+* When a `runSubagent` or `task` tool is available, run subagents as specified in each phase.
+* When neither `runSubagent` nor `task` tools are available, inform the user that one of these tools is required and should be enabled.
 
 The main agent executes directly only for:
 
@@ -61,8 +65,8 @@ Apply scope filtering before any discovery or processing. Subagents receive only
 
 Detect divergences from documentation conventions:
 
-* Compare files against [writing-style.instructions.md](../instructions/writing-style.instructions.md) patterns.
-* Validate structure against [markdown.instructions.md](../instructions/markdown.instructions.md) requirements.
+* Compare files against writing-style instructions patterns.
+* Validate structure against markdown instructions requirements.
 * Check frontmatter fields match schema requirements.
 * Identify prohibited patterns (em dashes, bolded-prefix lists, hedging phrases).
 
@@ -135,23 +139,21 @@ Update the session file after each phase with discoveries, plan items, and compl
 
 ### Phase 1: Discovery
 
-Dispatch three subagents to discover issues across all capabilities.
-
-Use the runSubagent tool to dispatch each discovery subagent. Each subagent focuses on one capability and reports all findings.
+Run three `researcher-subagent` agents in parallel with `runSubagent` or `task` tools to discover issues across all capabilities. If using the `runSubagent` tool then include instructions for each to read and follow all instructions from `.github/agents/**/researcher-subagent.agent.md`.
 
 #### Pattern Compliance Discovery
 
-Dispatch a subagent with:
+Run a `researcher-subagent` agent with:
 
 * Task: Scan all in-scope files for divergences from writing-style.instructions.md and markdown.instructions.md.
-* Instructions to read: [writing-style.instructions.md](../instructions/writing-style.instructions.md), [markdown.instructions.md](../instructions/markdown.instructions.md).
+* Instructions to read: [writing-style.instructions.md](.github/instructions/writing-style.instructions.md), [markdown.instructions.md](.github/instructions/markdown.instructions.md).
 * File scope: All files matching Included Files patterns, excluding Excluded Files patterns.
 * Response format: List each issue with file path, line number, violation type, and suggested fix.
 * Requirement: Indicate whether additional passes are needed and report total issue count.
 
 #### Accuracy Checking Discovery
 
-Dispatch a subagent with:
+Run a `researcher-subagent` agent with:
 
 * Task: Compare documentation claims against actual implementation.
 * Focus areas: Script parameter documentation in scripts/, file structure descriptions in docs/, example commands and their expected behavior.
@@ -160,7 +162,7 @@ Dispatch a subagent with:
 
 #### Missing Documentation Discovery
 
-Dispatch a subagent with:
+Run a `researcher-subagent` agent with:
 
 * Task: Identify undocumented functionality.
 * Scan locations: scripts/ (scripts without README or usage docs), extension/ (undocumented features), .github/skills/ (skills without adequate documentation).
@@ -175,9 +177,9 @@ After all discovery subagents complete:
 
 ### Phase 2: Planning
 
-Dispatch a planning subagent to create a prioritized work plan.
+Run a planning subagent to create a prioritized work plan.
 
-Use the runSubagent tool with:
+Run a `researcher-subagent` agent with `runSubagent` or `task` tools with inline instructions. If using the `runSubagent` tool then include instructions to read and follow all instructions from `.github/agents/**/researcher-subagent.agent.md`:
 
 * Task: Create a work plan from discovered issues.
 * Input: Read the session file Discovered Issues section.
@@ -196,17 +198,17 @@ After planning completes:
 
 ### Phase 3: Implementation
 
-Dispatch implementation subagents to execute fixes from the work plan.
+Run `phase-implementor` agents with `runSubagent` or `task` tools to execute fixes from the work plan.
 
-Use the runSubagent tool to dispatch subagents based on work plan size:
+If using the `runSubagent` tool then include instructions for each to read and follow all instructions from `.github/agents/**/phase-implementor.agent.md`. Run based on work plan size:
 
-* For small plans (fewer than 10 items): One subagent processes all items.
-* For larger plans: Dispatch subagents by capability category (pattern compliance, accuracy, documentation creation).
+* For small plans (fewer than 10 items): One `phase-implementor` agent processes all items.
+* For larger plans: Run `phase-implementor` agents by capability category (pattern compliance, accuracy, documentation creation).
 
-Each implementation subagent receives:
+Each `phase-implementor` agent receives:
 
 * Task: Execute assigned work items from the plan.
-* Instructions to follow: [writing-style.instructions.md](../instructions/writing-style.instructions.md), [markdown.instructions.md](../instructions/markdown.instructions.md).
+* Instructions to follow: [writing-style.instructions.md](.github/instructions/writing-style.instructions.md), [markdown.instructions.md](.github/instructions/markdown.instructions.md).
 * Work items: Specific numbered items from the plan.
 * Response format: Report each change with file path, change description, and completion status.
 * Requirement: Report any new issues discovered during implementation and whether additional passes are needed.
@@ -245,7 +247,7 @@ Report final status and close the session.
 
 ## Subagent Specifications
 
-All subagents dispatched via runSubagent follow these specifications.
+All subagents follow these specifications.
 
 ### Discovery Subagent Template
 
@@ -407,4 +409,4 @@ When all phases complete, provide:
 | Validation Status | Passed, Failed with count, or Partial       |
 | Followup Items    | Count requiring manual intervention         |
 
-Suggest a commit message following [commit-message.instructions.md](../instructions/commit-message.instructions.md). Exclude `.copilot-tracking/` files from the commit.
+Suggest a commit message following [commit-message.instructions.md](.github/instructions/commit-message.instructions.md). Exclude `.copilot-tracking/` files from the commit.