feat(agents): add meeting analyst agent for transcript analysis using work-iq

[agreaves-ms]

feat(agents): add meeting analyst agent for transcript analysis

Description

#501

Added a new experimental meeting analyst agent that retrieves meeting transcripts from Microsoft 365 via work-iq-mcp, extracts product requirements and decisions, and produces structured handoff documents for the PRD builder agent. Registered the agent in the custom agents catalog and configured the workiq MCP server.

• feat(agents): added meeting-analyst.agent.md with a four-phase workflow (Discover, Extract, Synthesize, Handoff) for analyzing meeting transcripts and extracting product requirements, decisions, action items, and open questions
  • Defined session state tracking and resume capability via JSON state files in .copilot-tracking/prd-sessions/
  • Included query budget management (approximately 30 queries per session with user warnings at thresholds)
  • Documented error handling for common work-iq-mcp failure modes
  • Specified structured handoff format for downstream PRD builder consumption
• docs(agents): registered meeting-analyst in the custom agents catalog with description, workflow summary, and critical usage notes
• config(mcp): added workiq MCP server entry to .vscode/mcp.json using npx -y @microsoft/workiq mcp

Additional Changes — Collection Folder Decoupling & Code Consolidation

Three related change sets were applied to decouple collection-folder placement, consolidate duplicate PowerShell functions, and address review findings:

1. Collection Folder Decoupling (13 files)

Relaxed {collection-id} subfolder placement from a hard requirement to an organizational convention. Research confirmed that no script, validation rule, CI workflow, or build tool enforced folder-to-collection-ID matching — the constraint existed only in documentation. Multiple collections (e.g., rpi, data-science, hve-core-all) already referenced artifacts outside their matching folder.

What changed:

• Updated 10 documentation files (.github/copilot-instructions.md, .github/CUSTOM-AGENTS.md, contributing guides, architecture docs) to use convention-based language ("by convention" / "typically organized under") instead of prescriptive language ("must live under").
• Added NOTE blocks and YAML comments clarifying that collections can reference artifacts from any subfolder via path: entries.
• Moved Get-CollectionArtifactKey from Prepare-Extension.ps1 into PluginHelpers.psm1 as a shared function, removing the script-local copy.
• Added duplicate artifact key detection to Validate-Collections.ps1 — fails CI when two artifacts of the same kind share a basename key but have different paths, preventing silent overwrites in extension packaging.
• Added extension/PACKAGING.md YAML comments documenting path flexibility.

Why: With the folder constraint relaxed, a safety net was needed to catch conflicting artifact filenames. The duplicate detection reuses the same key extraction logic as extension packaging (Get-CollectionArtifactKey), running in CI via the existing npm run lint:collections-metadata pipeline.

2. Get-CollectionManifest Deduplication (3 files)

Consolidated duplicate Get-CollectionManifest implementations. The PluginHelpers.psm1 version supported YAML only, while the Prepare-Extension.ps1 version supported YAML+JSON with path validation. The script-local definition in Prepare-Extension.ps1 shadowed the module export.

What changed:

• Upgraded Get-CollectionManifest in PluginHelpers.psm1 to support YAML+JSON formats with [ValidateNotNullOrEmpty()] and Test-Path guard.
• Removed the duplicate 36-line Get-CollectionManifest and 17-line Get-CollectionArtifactMaturity from Prepare-Extension.ps1. Updated 2 call sites to use Resolve-CollectionItemMaturity.
• Added Mock Out-File {} to 10 PSScriptAnalyzer test contexts to prevent mock data from overwriting logs/ output files.

Why: Eliminated function shadowing and DRY violations flagged during review (IV-002). Centralizing manifest parsing in the shared module ensures all callers (Validate-Collections.ps1, Generate-Plugins.ps1, Prepare-Extension.ps1) use identical parsing logic.

3. ConvertFrom-Yaml Consistency (1 file)

Replaced 3 remaining direct ConvertFrom-Yaml calls in Prepare-Extension.ps1 with the consolidated Get-CollectionManifest function, addressing review findings IV-001 and IV-002.

Why: Ensures all collection manifest loading flows through a single function with consistent error handling and format support.

Validation

All 1290 Pester tests pass (0 failures, 1 skipped). All lint checks pass (npm run lint:all — 0 errors across 175 markdown files, PowerShell, YAML, frontmatter, links, collections metadata, version consistency, and skills validation). Plugin validation passes (npm run plugin:validate — 10 collections, 0 errors).

Warning

This PR includes experimental GHCP artifacts that may have breaking changes.

• .github/agents/meeting-analyst.agent.md

GHCP Artifact Maturity

File	Type	Maturity	Notes
.github/agents/meeting-analyst.agent.md	Agent	⚠️ experimental	Pre-release only

GHCP Maturity Acknowledgment

• I acknowledge this PR includes non-stable GHCP artifacts
• Non-stable artifacts are intentional for this change

Related Issue(s)

Closes #501

Type of Change

Select all that apply:

Code & Documentation:

• 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:

• Reviewed contribution with prompt-builder agent and addressed all feedback
• Copilot instructions (.github/instructions/*.instructions.md)
• Copilot prompt (.github/prompts/*.prompt.md)
• 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.
• 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 and Model Version Requirements.

Other:

• Script/automation (.ps1, .sh, .py)
• Other (please describe):

Sample Prompts (for AI Artifact Contributions)

User Request:

meeting-analyst selected

I want to extract product requirements from the customer portal redesign meetings over the past two weeks. Key participants were Alice Chen and Bob Martinez.

Execution Flow:

1. Agent calls mcp_workiq_accept_eula with https://github.com/microsoft/work-iq-mcp.
2. Agent asks clarifying questions about topic, date range, and participants (if not provided).
3. Discover: Queries mcp_workiq_ask_work_iq to find matching meetings. Presents a numbered list of discovered meetings with name, date, and participants. Waits for user confirmation.
4. Extract: For each confirmed meeting, queries transcripts (one to two queries per meeting) focusing on requirements, decisions, action items, and pain points. Tracks query budget and warns at 20 and 25.
5. Synthesize: Organizes extracted content into structured categories with requirement IDs (TR-001, TR-002, ...). Flags contradictions and asks user to resolve ambiguities.
6. Handoff: Creates the transcript analysis markdown file and state JSON. Presents summary and guides user to start a prd-builder session.

Output Artifacts:

• .copilot-tracking/prd-sessions/customer-portal-redesign-transcript-analysis.md
• .copilot-tracking/prd-sessions/customer-portal-redesign-transcript.state.json

---
title: "Transcript Analysis: Customer Portal Redesign"
description: "Meeting transcript analysis handoff for PRD creation"
source-agent: meeting-analyst
target-agent: prd-builder
---

## Product/Initiative
Customer Portal Redesign - modernize the self-service portal...

## Problem Statement

### Current Situation
Summary of the current state identified from discussions.

### Key Challenges
Specific problems and pain points raised in meetings.

## Requirements Extracted
| Req ID | Requirement          | Source Meeting          | Date       | Speaker     |
| ------ | -------------------- | ---------------------- | ---------- | ----------- |
| TR-001 | Single sign-on login | Portal Review - Week 1 | 2026-02-03 | Alice Chen  |
| TR-002 | Dashboard widgets    | Portal Review - Week 2 | 2026-02-10 | Bob Martinez |

Success Indicators:

• The agent announces each phase transition (Discover, Extract, Synthesize, Handoff) during the conversation.
• A numbered meeting list is presented for confirmation before extraction begins.
• The query budget count is visible and stays within the approximately 30 query limit.
• The transcript analysis file contains populated tables for requirements, decisions, action items, and open questions with source meeting attribution.
• The state JSON file reflects the completed phase and final query count.
• The agent provides a handoff summary with counts (e.g., "Found 8 requirements, 3 decisions, 5 action items, 2 open questions") and directs the user to prd-builder.

For detailed contribution requirements, see:

• Common Standards: docs/contributing/ai-artifacts-common.md - Shared standards for XML blocks, markdown quality, RFC 2119, validation, and testing
• Agents: docs/contributing/custom-agents.md - Agent configurations with tools and behavior patterns
• Prompts: docs/contributing/prompts.md - Workflow-specific guidance with template variables
• Instructions: docs/contributing/instructions.md - Technology-specific standards with glob patterns
• Skills: docs/contributing/skills.md - Task execution utilities with cross-platform scripts

Testing

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

• 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

• 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

The meeting-analyst agent is marked as experimental (maturity: experimental in frontmatter). It requires the work-iq-mcp EULA acceptance before querying and has a query budget of approximately 30 per session. The agent hands off to the prd-builder agent for PRD creation or update.

🔍 - Generated by Copilot

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

Scanned Files

None

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 86.01%. Comparing base (5e8306f) to head (8d648a9).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main     #502   +/-   ##
=======================================
  Coverage   86.01%   86.01%           
=======================================
  Files          28       28           
  Lines        5270     5270           
=======================================
  Hits         4533     4533           
  Misses        737      737           

Flag	Coverage Δ
pester	86.01% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

Adds a new experimental meeting-analyst custom agent to analyze Microsoft 365 meeting transcripts via work-iq MCP tooling and generate structured handoff artifacts for prd-builder.

Changes:

• Added a new .github/agents/meeting-analyst.agent.md agent with a 4-phase workflow (Discover, Extract, Synthesize, Handoff) and session-state guidance.
• Registered meeting-analyst in the custom agents catalog documentation.
• Added a workiq MCP server entry in .vscode/mcp.json to enable the required MCP tools.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
.vscode/mcp.json	Adds workiq MCP server configuration to support transcript retrieval.
.github/agents/meeting-analyst.agent.md	New agent definition and workflow for transcript analysis + PRD handoff.
.github/CUSTOM-AGENTS.md	Documents and registers the new agent in the agent catalog.

[WilliamBerryiii]

Approving as experimental - but I do think that we should ultimately move this to a Copilot Studio prompt/instruction set .. since ideally this kinda stuff should be processed as soon as a meeting recording and transcript are available.

[katriendg]

Super nice work. I do believe this is the first agent and MCP addition that impacts our security posture for the solution, and we should take a moment to reflect if we are taking the required warnings and RAI notes.

This new agent is very useful to non-technical users, the more reason for ensuring we have some warnings or at least documented potential risks, especially with accidentally committing content to git repos.

1. the agent should understand its sensitivity
2. enhance the threat-model doc
3. document warnings

I've added a few comments around these hopefully they are easy to add for you.

[WilliamBerryiii]

Reverting this back to a draft state in accordance with our policies for PR staleness.

[WilliamBerryiii]

PR Compliance Update — Added Closes #501 to the Related Issue(s) section, which was previously empty (the issue was referenced in the Description but not in the designated section). This ensures GitHub will automatically close #501 when this PR merges.

No other content was changed. The PR body was already well-structured. 👍

[raymond-nassar]

Review questions from the perspective of someone who would use meeting-analyst to turn meeting transcript insights into backlog refinement inputs:

1. Since this PR adds workiq as a new MCP dependency in .vscode/mcp.json, should the MCP guidance also document it more explicitly — including trust, authentication, and troubleshooting expectations for users of this workflow?

2. Should the transcript analysis output include a brief Backlog Implications section so the results are easier to translate into follow-up planning work?

3. Since HVE-Core already has downstream backlog/work-item agents like ado-prd-to-wit and github-backlog-manager, should meeting-analyst make that handoff more explicit so the flow is clearer from transcript analysis to backlog updates?

4. Should the final handoff make confidence or confirmation status more explicit for extracted findings (for example: confirmed, inferred, or needs follow-up validation)?

5. Should the workflow ask earlier whether the goal is to create new planning artifacts or update existing ones?

6. Should the transcript analysis output start with a short executive summary for backlog refinement?

7. Should the discovery phase ask for existing PRD, epic, feature, or work item references up front so the analysis can be anchored to work already in progress?

8. Should the Action Items output indicate when the owner or due date is unknown or unconfirmed?

[katriendg]

@raymond-nassar thanks a lot for your input, we've tried addressing most of your comments. I believe for the automated MCP setup guidance we have left it to a note because of the experimental status of this agent, we do not yet want to add it to the installer skill. But will be done once we move to stable.
Some testing is out just to ensure the changes work as expected, but it's pretty much ready for review and initial merge.