meeting-assistant/openspec/specs/meeting-summary/spec.md

meeting-summary Specification

Purpose

TBD - created by archiving change define-meeting-assistant-v1. Update Purpose after archive.

Requirements

Requirement: Meeting Assistant generates meeting outputs

Meeting Assistant SHALL generate a summary, decisions, and next steps from the meeting transcript, metadata, user notes, and assistant-discovered context.

Meeting Assistant SHALL use a Microsoft Agent Framework pipeline for the first summary implementation. The pipeline SHALL use a configurable OpenAI-compatible endpoint, model, and API key source, including support for a direct key or an environment variable name.

The summary pipeline SHALL retry transient model endpoint failures according to configurable reconnection attempts and delay settings.

The summary pipeline SHALL track context-window usage for the configured model using response usage when available and request-size estimates otherwise. The context-window limit, maximum output reserve, compaction enablement, compaction threshold, and Responses compact endpoint path SHALL be configurable.

When only the configured remaining context ratio is available, the summary pipeline SHALL try to compact the conversation through the configured OpenAI-compatible POST /v1/responses/compact endpoint. If that endpoint is unavailable or returns invalid data, the pipeline SHALL fall back to Microsoft Agent Framework compaction.

Fallback compaction SHALL become increasingly aggressive: collapse old tool results, summarize older conversation spans, keep only the last four user turns, and drop oldest groups if still over budget.

When summary generation fails after retries, Meeting Assistant SHALL write a markdown failure report to the configured summary note path. The failure report SHALL include a clickable retry link, error details, and the meeting artifact paths needed to diagnose or retry the run.

After transcript processing finishes for a recording, Meeting Assistant SHALL automatically invoke the summary pipeline for that meeting.

Meeting Assistant SHALL expose an API operation to retry summary generation for a given summary note path. The retry operation SHALL resolve the linked meeting artifacts from the meeting note frontmatter and SHALL overwrite the existing summary note with either the new summary or a new failure report.

The summary pipeline SHALL expose tools scoped to the current meeting:

• read_meetingnote
• read_transcript
• read_context
• read_usernotes
• read_glossary
• write_summary
• write_context
• list_projects
• list_projectfiles
• read_projectfile
• write_projectfile
• search

All summary-agent read tools that return file-like content SHALL support either reading the whole file or reading a clamped inclusive 1-based line range when from and to are supplied.

The summary pipeline SHALL write the summary note as a markdown artifact linked to the meeting note, transcript, and assistant context.

The summary agent SHALL be able to read the meeting note, transcript, assistant context, glossary, and bound project files through tools.

The summary agent SHALL be able to write the summary and assistant context files as its owned artifacts.

For summary-agent writes to any file other than the summary file and assistant context file, Meeting Assistant SHALL record an in-memory diff containing removed and added lines.

Meeting Assistant SHALL use a diff implementation that can reduce whole-file rewrites to changed lines instead of treating every rewrite as a full replacement.

When the summary agent finishes, Meeting Assistant SHALL append the collected external write diffs to the assistant context file.

After writing the meeting summary, the summary agent SHALL update existing project files when the meeting produced project-relevant knowledge.

The assistant context note SHALL keep title, start_time, end_time, meeting, transcript, summary, state, and agenda in frontmatter. Meeting Assistant SHALL write title and start_time when the assistant context note is created, update title when later meeting metadata is discovered, and write end_time when transcript processing stops. When a Teams appointment is detected at recording start, the assistant context note SHALL also keep scheduled_end in frontmatter. The state value SHALL be one of collecting metadata, transcribing, speaker recognition, summarizing, finished, or error.

The summary note SHALL keep frontmatter links to meeting artifacts and SHALL copy title, start_time, and end_time from the meeting note when available. If the meeting note has no title, the summary agent SHALL be able to provide a title when writing the summary.

The summary agent SHALL be able to read and write the assistant context body as its own notebook using overwrite, replace, and insert line modes.

Scenario: Assistant context note is initialized

• WHEN Meeting Assistant starts a meeting session
• THEN it creates the assistant context note with frontmatter links to the meeting note, transcript note, and summary note
• AND the assistant context frontmatter state is collecting metadata
• AND the assistant context frontmatter includes agenda, empty when no agenda is known
• AND the assistant context frontmatter includes scheduled_end when Teams metadata supplied a scheduled end time

Scenario: Assistant context state follows meeting processing

• WHEN transcription, final speaker recognition, and summary generation progress
• THEN Meeting Assistant updates assistant context frontmatter state to collecting metadata, transcribing, speaker recognition, summarizing, finished, or error as appropriate
• AND preserves existing agenda and scheduled_end frontmatter values

Scenario: External project write is audited

• WHEN the summary agent writes a bound project file
• THEN Meeting Assistant records the changed removed and added lines for that project file
• AND appends that diff to the assistant context after the agent finishes

Scenario: Dictionary write is audited

• WHEN the summary agent adds a dictation word and the dictionary file changes
• THEN Meeting Assistant records the changed removed and added lines for the dictionary file
• AND appends that diff to the assistant context after the agent finishes

Scenario: Owned artifact writes are not audited

• WHEN the summary agent writes the summary or assistant context file
• THEN Meeting Assistant does not include those writes in the external write diff audit

Requirement: Summary agent instructions are configurable

Meeting Assistant SHALL allow the summary agent initial prompt to be configured through application settings.

When no configured initial prompt is supplied, Meeting Assistant SHALL use the built-in default prompt.

Scenario: Configured initial prompt is used

• WHEN MeetingAssistant:Agent:InitialPrompt is configured with non-empty content
• THEN the summary agent uses that configured prompt as its base instructions

Scenario: Empty initial prompt falls back to built-in default

• WHEN MeetingAssistant:Agent:InitialPrompt is missing or blank
• THEN the summary agent uses the built-in default instructions

Requirement: Summary agent receives bound project instructions

Meeting Assistant SHALL append project instructions to the summary agent instructions for projects bound to the meeting note frontmatter.

For each bound project folder under the configured projects folder, when an AGENTS.md file exists directly in that project folder, Meeting Assistant SHALL append the project name and the AGENTS.md content under a project instructions section.

When no bound projects have AGENTS.md, Meeting Assistant SHALL not append the project instructions section.

Scenario: Project AGENTS files are appended

• GIVEN the meeting note frontmatter lists projects Alpha and Beta
• AND both configured project folders contain AGENTS.md
• WHEN the summary agent is created
• THEN its instructions include ---, projects:, # Alpha, Alpha's AGENTS.md, # Beta, and Beta's AGENTS.md

Scenario: Projects without AGENTS files are skipped

• GIVEN the meeting note frontmatter lists project Alpha
• AND the configured project folder does not contain AGENTS.md
• WHEN the summary agent is created
• THEN no empty project instruction entry is appended for Alpha