CUSTOM-AGENTS.md

title	GitHub Copilot Custom Agents
description	Specialized AI agents for planning, research, prompt engineering, documentation, and code review workflows
author	HVE Core Team
ms.date	2026-10-07
ms.topic	guide
keywords	copilot custom agents ai assistants task planning code review
estimated_reading_time	6

Specialized GitHub Copilot behaviors for common development workflows. Each custom agent is optimized for specific tasks with custom instructions and context.

Quick Start

1. Open GitHub Copilot Chat view (Ctrl+Alt+I or Cmd+Alt+I)
2. Click the agent picker dropdown at the top of the chat panel
3. Select the desired agent from the list
4. Enter your request and press Enter

Example:

• Select "RPI Agent" from the dropdown
• Type: "Research, plan, implement, and review Docker SHA validation"
• Press Enter

Requirements: GitHub Copilot subscription, VS Code with Copilot extension, proper workspace configuration (see Getting Started)

Available Agents

Select from the agent picker dropdown in the Chat view:

RPI Workflow Agents

The RPI lifecycle keeps Research, Plan, Implement, Review, and Follow-up distinct for complex development tasks. It begins with research readiness: supplied or completed evidence is reused when adequate, and research runs only for a demonstrated requirements, acceptance, dependency, material-risk, complexity, uncertainty, or decision-critical gap.

RPI Agent is a user-selected lifecycle wrapper that activates the matching RPI skills. It runs in manual mode by default and can switch to a confirmed automatic session that completes the remaining phases through Review. Use /rpi-research, /rpi-plan, /rpi-implement, and /rpi-review when you need a direct phase entry point.

Use the self-contained rpi-challenger skill to interrogate a confirmed subject through adaptive skeptical questions, and rpi-walkthrough to understand code or RPI artifacts one segment at a time. See the RPI Documentation for all surfaces.

Agent	Purpose	Key Constraint
RPI Agent	User-selected lifecycle wrapper that activates matching RPI skills	Manual by default; automatic mode requires explicit confirmation and has no fixed specialized task-worker roster

Documentation and Planning Agents

Agent	Purpose	Key Constraint
adr-creation	Interactive ADR coaching with guided discovery	Socratic coaching approach
brd-builder	Creates Business Requirements Documents with reference integration	Solution-agnostic requirements focus
documentation	Documentation audit, drift, authoring, and validation workflow	Uses the shared documentation skill and escalates formal assessments to planner agents
meeting-analyst	Analyzes meeting transcripts to extract product requirements via work-iq-mcp	Experimental; requires work-iq-mcp EULA; transcripts may contain PII and confidential data, analysis files are unencrypted on disk
prd-builder	Creates Product Requirements Documents through guided Q&A	Iterative questioning; state-tracked sessions
security-planner	STRIDE-based security model analysis with standards mapping and backlog handoff	Six-phase conversational workflow; experimental
sssc-planner	Supply chain security assessment with 6-phase workflow against OpenSSF Scorecard, SLSA, Sigstore, and SBOM	Six-phase conversational workflow; experimental
rai-planner	Responsible AI assessment with 6-phase workflow against Microsoft Responsible AI Impact Assessment Guide and NIST AI RMF	Six-phase conversational workflow; experimental
system-architecture-reviewer	Reviews system designs for trade-offs and ADR alignment	Scoped review; delegates security concerns
ux-ui-designer	JTBD analysis, user journey mapping, and accessibility requirements	Research artifacts only; visual design in Figma

Code and Review Agents

Agent	Purpose	Key Constraint
security-reviewer	OWASP vulnerability assessment with subagent-driven verification	Delegates all reference reading to subagents
code-review	Human-gated review orchestrator dispatching five perspective subagents	Operator confirms scope, perspectives, and depth; review-only

Related Workflow Skills

Use hve-builder as the canonical lifecycle for creating, improving, refactoring, reviewing, or validating prompts, instructions, agents, subagents, and skills.

Platform Integration Agents

Agent	Purpose	Key Constraint
backlog-manager	Unified backlog and work management for Azure DevOps, GitHub, and Jira, plus ADO PR/build/sprint	Uses per-platform MCP tools and the Jira CLI; per-platform preflight
functional-planner	Analyzes PRDs and plans Azure DevOps or Jira work-item hierarchies with selectable framework lenses	Planning-only; never mutates a tracker

Agent Details

RPI Agent

Activates: The matching RPI skills for the applicable lifecycle concepts:

• rpi-research only when research readiness identifies a demonstrated gap
• rpi-plan for the parent-owned task-centered plan and independent critique
• rpi-implement for direct execution and change evidence
• rpi-review for one evidence-reconciliation record and outcome routing

Workflow: Research readiness → Plan → Implement → Review → Follow-up. Research can be reused or satisfied-and-skipped when the evidence set is adequate. Follow-up routes defects to implementation, decisions to planning, evidence gaps to research, and residual work to a distinct next item.

Artifacts: When a stage needs a durable record, the lifecycle uses one stable task ID and these marker-addressed paths:

• .copilot-tracking/research/{{YYYY-MM-DD}}/{{task_slug}}-research.md
• .copilot-tracking/plans/{{YYYY-MM-DD}}/{{task_slug}}-plan.md
• .copilot-tracking/reviews/plans/{{YYYY-MM-DD}}/{{task_slug}}-plan-critique.md
• .copilot-tracking/changes/{{YYYY-MM-DD}}/{{task_slug}}-changes.md
• .copilot-tracking/reviews/logs/{{YYYY-MM-DD}}/{{task_slug}}-review.md

Modes: Manual mode stays in the active phase until you invoke the next /rpi-* command or select a phase handoff. The Full Auto handoff requests an automatic session; after you confirm whether ordinary Research and Plan decisions are agent-owned or user-retained, the agent continues through Review without routine approval prompts.

After Review, an automatic session offers ranked follow-up choices plus Stop automatic session and Switch to manual mode. Blockers, required human review, and destructive or externally visible actions still stop for confirmation.

Critical: RPI Agent is a user-selected lifecycle wrapper, not a dispatcher for named specialized task workers. Automatic mode begins only after explicit confirmation and never infers consent from a handoff request. It may use generic bounded delegation only when it materially improves an isolated activity. Navigate durable artifacts with the task ID, Pxx, Pxx-Txx, headings, and <!-- rpi:... --> markers.

ux-ui-designer

Purpose: UX research artifacts including Jobs-to-be-Done analysis, user journey mapping, and accessibility requirements.

Creates: Research documentation using the user journey template:

• JTBD analysis documenting user goals and current solution gaps
• Journey maps tracing user behavior, emotions, and pain points across stages
• Accessibility requirements integrated into journey stages
• Design handoff sections with flow descriptions and principles

Handoffs: Delegates to prd-builder for formal product requirements, backlog-plan for tracked work items, and activates rpi-research for technical feasibility research.

Critical: Research-only. Does not generate UI designs or visual mockups. Produces artifacts that designers translate into Figma flows. Treats accessibility as a foundational constraint.

prd-builder

Creates: Product requirements documents with session state:

• docs/project-planning/<kebab-case-name>.md (PRD document with requirements)
• .copilot-tracking/prd-sessions/<kebab-case-name>.state.json (session state for resume capability)

Workflow: Assess → Discover → Create → Build → Integrate → Validate → Finalize

Critical: Iterative questioning with refinement checklists. Maintains session state for continuity. Integrates user-provided references automatically.

brd-builder

Creates: Business requirements documents with session state:

• docs/project-planning/<kebab-case-name>-brd.md (BRD document with business objectives)
• .copilot-tracking/brd-sessions/<kebab-case-name>.state.json (session state for resume capability)

Workflow: Assess → Discover → Create → Elicit → Integrate → Validate → Finalize

Critical: Solution-agnostic requirements focus. Links every requirement to business objectives. Supports session resume after context summarization.

adr-creation

Creates: Architecture Decision Records:

• .copilot-tracking/adrs/{{topic-name}}-draft.md (working draft)
• docs/decisions/YYYY-MM-DD-{{topic}}.md (final location)

Workflow: Discovery → Research → Analysis → Documentation

Critical: Uses Socratic coaching methods. Guides users through decision-making process. Adapts coaching style to experience level.

system-architecture-reviewer

Creates: Architecture review findings and ADRs:

• docs/decisions/YYYY-MM-DD-short-title.md (architecture decision records)

Workflow: Context Discovery → Review Scoping → Well-Architected Evaluation → Trade-Off Analysis → ADR Documentation → Escalation Review

Critical: Asks questions and reviews existing artifacts (ADRs, PRDs, plans) before making assumptions. Scopes reviews to 2-3 relevant framework areas based on gathered context. Delegates security-specific reviews to security-planner and detailed ADR coaching to adr-creation. Uses docs/templates/adr-template-solutions.md for ADR structure.

documentation

Creates: Documentation workflow session tracking and documentation updates:

• .copilot-tracking/documentation/{{YYYY-MM-DD}}-session.md (session tracking for the Documentation workflow)

Workflow:

• Review existing documentation for scope, accuracy, and completeness
• Identify drift, gaps, or outdated content in the requested area
• Author or validate documentation updates using the shared documentation skill

Critical: Uses the Documentation workflow as the canonical entry point for documentation work. It stays focused on documentation artifacts and routes formal accessibility, RAI, and security assessments to the matching planner agents.

meeting-analyst

Creates: Transcript analysis documents and session state:

• .copilot-tracking/prd-sessions/<kebab-case-name>-transcript-analysis.md (structured requirements extracted from meeting transcripts)
• .copilot-tracking/prd-sessions/<kebab-case-name>-transcript.state.json (session state for resume capability)

Workflow: Discover → Extract → Synthesize → Handoff

Critical: Experimental. Requires the workiq MCP server in .vscode/mcp.json (not included in the installer skill or curated MCP documentation; see official documentation for setup). Requires mcp_workiq_accept_eula call before querying. Uses mcp_workiq_ask_work_iq for Microsoft 365 meeting data. Query budget of approximately 30 per session. Hands off to prd-builder for PRD creation.

Data Sensitivity Warning: Meeting transcripts retrieved by this agent may contain PII, customer confidential information, and proprietary business data. Analysis files and state files are written to .copilot-tracking/prd-sessions/ which is gitignored by default when following HVE Core setup guidance, but the files exist unencrypted on disk. Users are responsible for verifying their repository's .gitignore configuration, complying with their organization's data handling policies, and deleting both the <name>-transcript-analysis.md and <name>-transcript.state.json files after the PRD handoff is complete. The agent will prompt for deletion at handoff completion, but deletion is the user's responsibility.

security-planner

Creates: Security plans and backlog handoff artifacts under .copilot-tracking/security-plans/{project-slug}/:

• state.json (session state for resume capability)
• security-plan-{project-slug}.md (security plan with STRIDE analysis, standards mapping, and operational bucket classification)
• Backlog items in ADO (WI-SEC-{NNN}) or GitHub ({{SEC-TEMP-N}}) format

Workflow: Six sequential phases: Scoping → Bucket Analysis → Standards Mapping → Security Model Analysis → Backlog Generation → Review and Handoff

Entry Modes: Two modes converge at Phase 2. Capture mode starts from scratch with an interview. From-PRD mode pre-populates from existing PRD/BRD artifacts.

Critical: Uses STRIDE methodology per operational bucket. Maps controls to OWASP Top 10, NIST 800-53, and CIS v8 frameworks. Detects AI/ML components during scoping and recommends RAI Planner dispatch when AI elements are present. Works iteratively with 3-5 questions per turn using emoji checklists to track progress. No blueprint infrastructure requirement. Maturity: experimental.

rai-planner

Creates: One consolidated rai-plan.md plus session state under .copilot-tracking/rai-plans/{project-slug}/:

• state.json (session state for resume capability)
• rai-plan.md with eight sections in phase order:
  • ## System Definition (with an ### AI Component Inventory table subsection) and ## Stakeholder Impact (Phase 1: AI System Scoping)
  • ### Risk Classification Screening under ## System Definition (Phase 2: Risk Classification)
  • ## Standards Mapping (Phase 3: RAI Standards Mapping)
  • ## Threat Addendum (Phase 4: RAI Security Model Analysis)
  • ## Control Surface Catalog, ## Evidence Register, ## Tradeoffs (Phase 5: RAI Impact Assessment)
  • ## Review Summary (Phase 6: Review and Handoff)
• Backlog items and artifact-manifest.json when signing is accepted (Phase 6: Review and Handoff)

Workflow: Six sequential phases mapped to NIST AI RMF functions: AI System Scoping (Govern + Map) → Risk Classification (Govern) → RAI Standards Mapping (Govern + Measure) → RAI Security Model Analysis (Measure) → RAI Impact Assessment (Manage) → Review and Handoff (Manage)

Entry Modes: Three modes converge at Phase 2. Capture mode uses exploration-first interviewing adapted from Design Thinking research methods. From-PRD mode seeds the assessment from PRD artifacts. From-security-plan mode continues from a completed Security Planner session, inheriting AI component data and threat ID sequences.

Critical: Evaluates AI systems against the Microsoft Responsible AI Impact Assessment Guide and NIST AI RMF 1.0. Applies AI-specific threat analysis using dual threat ID convention (T-RAI-{NNN} sequential IDs and T-{BUCKET}-AI-{NNN} cross-references) across data poisoning, model evasion, prompt injection, and bias amplification. Seven instruction files provide domain guidance. Works iteratively with up to 7 questions per turn. Maturity: experimental.

sssc-planner

Creates: Assessment artifacts under .copilot-tracking/sssc-plans/{project-slug}/:

• state.json (session state for resume capability)
• sssc-plan-{project-slug}.md (supply chain security assessment with standards mapping and gap analysis)
• Backlog items in ADO or GitHub format for remediation tracking

Workflow: Six sequential phases: Scoping → Supply Chain Assessment → Standards Mapping → Gap Analysis → Backlog Generation → Review and Handoff

Entry Modes: Four modes converge at Phase 2. Capture mode starts from scratch with an interview. From-PRD mode pre-populates from PRD artifacts. From-BRD mode seeds from BRD artifacts. From-security-plan mode continues from a completed Security Planner session.

Critical: Assesses against OpenSSF Scorecard (20 checks), SLSA Build levels (L0-L3), Best Practices Badge tiers, Sigstore keyless signing maturity, and SBOM compliance. Works iteratively with 3-5 questions per turn with confirmation before phase advancement. Maturity: experimental.

security-reviewer

Creates: OWASP vulnerability assessment reports:

• .copilot-tracking/security/{{YYYY-MM-DD}}/security-report-{{NNN}}.md (audit mode report)
• .copilot-tracking/security/{{YYYY-MM-DD}}/security-report-diff-{{NNN}}.md (diff mode report)
• .copilot-tracking/security/{{YYYY-MM-DD}}/plan-risk-assessment-{{NNN}}.md (plan mode report)

Workflow: Setup → Profile Codebase → Assess Applicable Skills → Verify Findings → Generate Report → Compute Summary

Modes:

• audit (default): Full codebase scan against applicable OWASP skills
• diff: Scoped scan of changed files relative to the default branch
• plan: Pre-implementation risk assessment of a plan document (skips verification)

Subagents: Codebase Profiler, Skill Assessor, Finding Deep Verifier, Report Generator

Critical: Orchestrator-only pattern. Delegates codebase profiling, skill assessment, adversarial finding verification, and report generation to specialized subagents. Uses OWASP skills (owasp-agentic, owasp-llm, owasp-top-10, owasp-mcp, owasp-infrastructure, owasp-cicd) and the secure-by-design skill for vulnerability and design principle references. Supports incremental comparison with prior scan reports.

code-review

Creates: Merged review artifacts in a normalized branch folder:

• .copilot-tracking/reviews/code-reviews/<sanitized-branch>/review.md (merged review document, per the shared persistence protocol in review-artifacts.instructions.md)
• .copilot-tracking/reviews/code-reviews/<sanitized-branch>/metadata.json (review metadata record)

Workflow: Context Bootstrap → Human Scope Confirmation → Perspective + Depth Selection → Prepare Dispatch State → Dispatch Selected Perspectives → Merge and Persist

Critical: Human-gated orchestrator invoked from the agent picker. After computing the diff via the pr-reference skill, it confirms scope with the operator, then lets the operator choose any combination of five perspectives (functional, standards, accessibility, security, pr) or full to run all five, plus a depth tier (basic, standard, or comprehensive) applied independently of perspective. It dispatches thin perspective subagents under .github/agents/coding-standards/subagents/, shares the computed diff to avoid duplicate git operations, and merges every report into a single output. Review-only; never modifies code. Maturity: experimental.

backlog-manager

Creates: Backlog management artifacts under .copilot-tracking/{workitems,github-issues,jira-issues}/

Workflow: Platform and Intent Classification → Workflow Dispatch → Summary and Handoff

Critical: Unified across Azure DevOps, GitHub, and Jira. Resolves the target platform and runs a per-platform tool/credential preflight, delegates knowledge to the backlog-management skill, folds in ADO PR creation, build/pipeline info (and GitHub Actions), sprint, and task planning, routes PRD planning to the functional planner, and applies GitHub community-interaction guardrails for contributor-facing comments.

functional-planner

Creates: Work item planning files under .copilot-tracking/{workitems,jira-issues}/prds/<artifact-normalized-name>/ (planning-log.md, artifact-analysis.md, the platform plan file, handoff.md)

Workflow: Analyze PRD → Discover Codebase → Discover Related Work Items → Refine Hierarchy → Finalize Handoff

Critical: Strictly planning-only; never mutates a tracker. Consumes the functional-planner skill for the read-only PRD model, per-platform hierarchy rules (ADO Epic/Feature/Story; Jira Epic/Story/Task/Sub-task), and selectable open framework lenses (generic, Scrum, Kanban). Hands off to the backlog-manager for execution after user review.

Common Workflows

Coordinating an RPI Lifecycle

1. Select RPI Agent from the agent picker for the full-lifecycle entry point.
2. Provide the task, acceptance criteria, decisions, dependencies, and any completed research.
3. Assess research readiness before activating rpi-research; reuse adequate evidence instead of repeating research.
4. Continue through the applicable phase skills and resume from the durable artifact set when a long lifecycle needs a fresh context.

Planning a Feature

1. Gather task context, decisions, acceptance criteria, and any completed research
2. Use /rpi-research when a demonstrated planning-readiness gap remains
3. Use /rpi-plan with the available evidence to create a task-centered plan and independent critique
4. Use /rpi-implement to execute approved work and record change evidence
5. Use /rpi-review to reconcile the implementation against the plan and route follow-up

Code Review

1. Select code-review from agent picker
2. Confirm the change scope when prompted
3. Choose perspectives (functional, standards, accessibility, security, pr, or full) and a depth tier
4. Receive a merged review.md under .copilot-tracking/reviews/code-reviews/<branch>/

Creating Instructions

1. Invoke hve-builder with the target path, reference context, and requirements
2. Let HVE Builder resolve the create or improve mode and source-write boundary
3. Review the independent static verdict, behavior evidence when required, validation result, and overall outcome before merging

Creating Documentation

1. Select prd-builder or brd-builder from agent picker
2. Answer guided questions about the product or business initiative
3. Provide references and supporting materials
4. Review and refine iteratively
5. Finalize when quality gates pass

Important Notes

• Linting Exemption: Files in .copilot-tracking/** are exempt from repository linting rules
• Agent Switching: Clear context or start a new chat when switching between specialized agents
• Evidence Readiness: rpi-plan uses supplied or complete evidence and activates rpi-research only for a demonstrated readiness gap
• Phase Ownership: rpi-research and rpi-plan produce evidence and planning artifacts; rpi-implement owns source changes
• RPI entry surfaces: RPI Agent coordinates the same phase skills that /rpi-research, /rpi-plan, /rpi-implement, and /rpi-review run directly; neither path requires a fixed specialized task-worker roster

Tips

• Be specific in your requests for better results
• Provide context about what you're working on
• Review generated outputs before using
• Use the RPI lifecycle when research readiness identifies a gap or the task needs durable planning, implementation evidence, review, or follow-up routing
• Resume long-lived work from the stable task ID and dated RPI artifacts instead of relying on conversation history

🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.