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

meeting-session Specification

Purpose

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

Requirements

Requirement: Meeting Assistant creates a note before transcription

Meeting Assistant SHALL create an Obsidian markdown note for a meeting session before transcription starts.

The note SHALL be the durable anchor for meeting metadata, user notes, assistant-discovered context, transcript references, summaries, decisions, and next steps.

Scenario: Session starts

• WHEN the user starts a new meeting session
• THEN Meeting Assistant creates a markdown note in the configured meetings folder before starting transcription

Scenario: Recording starts from hotkey

• WHEN the user presses the recording hotkey while recording is inactive
• THEN Meeting Assistant creates the transcript file, creates the meeting note with links to the transcript, assistant context, and summary notes, and opens the meeting note through an obsidian:// system command

Scenario: User adds context before transcription

• WHEN the note exists before transcription starts
• THEN the user can add attendees, project context, and other notes to that file

Requirement: Vault locations are configurable

Meeting Assistant SHALL expose separate configuration settings for transcript files, meeting notes, assistant context, generated summaries, project knowledge, and dictation words.

The dictation words location SHALL point to a word-list artifact that speech recognition pipelines MAY use as vocabulary hints when supported.

Scenario: Transcript and note locations are configured separately

• WHEN Meeting Assistant starts with configured vault locations
• THEN transcripts, meeting notes, assistant context, generated summaries, project knowledge, and dictation words each have an independently configured path

Scenario: Provider supports dictation words

• WHEN the configured speech recognition pipeline supports vocabulary hints
• THEN Meeting Assistant can provide words from the configured dictation words path without changing the other vault locations

Scenario: Dictation words are unavailable

• WHEN Meeting Assistant starts recording and the configured dictation words path cannot be read within the configured timeout
• THEN Meeting Assistant logs the failure and starts recording without dictation-word hints

Requirement: Meeting note template is coded and round-trippable

Meeting Assistant SHALL link the note files generated for one meeting run through frontmatter.

The meeting note frontmatter SHALL link to the transcript, assistant context, and summary notes.

Generated artifact notes SHALL link only to the other notes from the same run and SHALL omit the frontmatter property that would reference themselves.

Meeting Assistant SHALL escape generated meeting-note frontmatter string values after metadata enrichment and workflow rules have been applied, immediately before writing the final markdown file.

Scenario: Meeting note links to generated artifacts

• WHEN Meeting Assistant creates a meeting note
• THEN the note frontmatter links to the configured transcript, assistant context, and summary note locations

Scenario: Scalar list frontmatter is normalized

• GIVEN a meeting note frontmatter field that Meeting Assistant expects as a list is stored as a scalar string
• WHEN Meeting Assistant reads the meeting note
• THEN it treats the scalar string as a one-item list
• AND continues processing the meeting note

Scenario: Generated artifacts do not self-reference

• WHEN Meeting Assistant writes transcript, assistant context, or summary artifact frontmatter
• THEN the artifact frontmatter links to the other run notes
• AND the artifact frontmatter omits the property for the artifact's own note type

Scenario: Generated frontmatter remains parseable after attendee transforms

• GIVEN meeting metadata or workflow rules produce an attendee name that contains a single quote
• WHEN Meeting Assistant writes the final meeting note
• THEN the attendee value is escaped in frontmatter
• AND the meeting note frontmatter remains parseable when read back

Requirement: Meeting notes preserve user-authored content

Meeting Assistant SHALL preserve user-authored meeting notes and include them as input when generating summaries, decisions, and next steps.

Scenario: User writes notes during the meeting

• WHEN the user updates the meeting note while the meeting is active
• THEN Meeting Assistant keeps that content and incorporates it into generated meeting outputs

Requirement: Meeting sessions are platform independent

Meeting Assistant SHALL support meeting sessions that do not originate from Teams, Zoom, or any other meeting software API.

Meeting software integrations MAY augment the meeting experience, but they SHALL NOT be required for the primary meeting capture, transcription, or summary flow.

Scenario: In-person meeting is captured

• WHEN the user starts transcription for an in-person meeting
• THEN Meeting Assistant captures and processes the meeting without requiring a meeting platform integration

Requirement: Windows Outlook enrichment is optional

Meeting Assistant SHALL gate Outlook Classic COM enrichment behind the Windows compilation target.

When the Windows build starts a meeting and Outlook Classic has exactly one current Teams appointment, Meeting Assistant SHALL copy the appointment title to the meeting note and copy the appointment agenda and scheduled end time to the assistant-context frontmatter.

Meeting Assistant SHALL exclude canceled Outlook appointments from current Teams appointment metadata lookup.

Meeting Assistant SHALL copy the appointment attendees to the meeting note only when the raw appointment attendee count is less than or equal to the configured Recording:MaxMetadataAttendeeImportCount. The default maximum SHALL be 30 attendees.

The agenda SHALL be extracted from the appointment body content before the Teams join separator or Teams join text.

Scenario: Current Teams appointment enriches meeting artifacts

• WHEN a Windows build starts a meeting while Outlook Classic exposes exactly one current Teams appointment
• THEN Meeting Assistant uses the appointment subject as the meeting title
• AND writes the appointment attendees into meeting note frontmatter when the raw attendee count is within the configured import limit
• AND writes the appointment agenda into assistant-context frontmatter
• AND writes the appointment end time as scheduled_end into assistant-context frontmatter

Scenario: Canceled appointment is ignored during metadata lookup

• GIVEN Outlook Classic exposes one canceled current Teams appointment
• AND Outlook Classic exposes one active current Teams appointment at the same time
• WHEN a Windows build starts a meeting
• THEN Meeting Assistant selects the active appointment metadata

Scenario: Oversized attendee list is not imported

• GIVEN the configured metadata attendee import limit is 30
• WHEN a Windows build starts a meeting while Outlook Classic exposes exactly one current Teams appointment with 31 attendees
• THEN Meeting Assistant uses the appointment subject as the meeting title
• AND does not write the appointment attendees into meeting note frontmatter
• AND writes the appointment agenda into assistant-context frontmatter
• AND writes the appointment end time as scheduled_end into assistant-context frontmatter

Scenario: Outlook is unavailable or ambiguous

• WHEN Outlook Classic is unavailable or more than one current Teams appointment is found
• THEN Meeting Assistant starts the recording with the default generated meeting title and empty agenda
• AND omits scheduled_end from assistant-context frontmatter

Requirement: Outlook Teams meetings can prompt recording start

Meeting Assistant SHALL enable scheduled Outlook Classic calendar checks for recording-start prompts by default.

When scheduled recording prompts are enabled on Windows, Meeting Assistant SHALL periodically read the user's Outlook Classic calendar appointments for the current local day through COM into an in-memory cache.

Meeting Assistant SHALL default the Outlook calendar sync interval to 30 minutes when scheduled recording prompts are enabled.

Meeting Assistant SHALL schedule recording-start prompts from the cached calendar appointments rather than querying Outlook for each prompt.

Meeting Assistant SHALL consider Teams appointments from Outlook calendar data as initial prompt candidates. The detection MAY be extended later for other meeting providers.

Meeting Assistant SHALL exclude canceled Outlook appointments from recording-start prompt candidates.

When a Teams appointment reaches its scheduled start window, Meeting Assistant SHALL show a native Windows app notification asking whether to record the meeting, with affirmative and negative actions.

On Windows, the recording-start notification SHALL request reminder-style toast behavior and remain actionable for 5 minutes.

Meeting Assistant SHALL prompt at most once per calendar appointment during a local day, regardless of whether the user accepts, declines, or ignores the notification.

If the user accepts the recording prompt while no recording is active, Meeting Assistant SHALL start a new recording normally.

If the user accepts the recording prompt while another recording is active, Meeting Assistant SHALL stop the active recording normally and then start the prompted meeting recording.

When stopping an active recording for an accepted prompt, Meeting Assistant SHALL use the normal stop path so empty or too-short recordings are removed according to existing settings and other completed recordings continue normal transcription, speaker recognition, and summary processing.

When the user accepts a recording prompt, Meeting Assistant SHALL start the recording with the accepted cached appointment's metadata and SHALL NOT perform a separate current-meeting metadata lookup for that prompted start.

Prompted-start metadata SHALL include the accepted appointment title, attendees, agenda, and scheduled end when those values are available from the cached appointment.

Prompted starts SHALL run the normal meeting workflow created rules before applying the accepted appointment metadata.

After created rules run, prompted starts SHALL apply the accepted appointment metadata and then run the normal collecting metadata to transcribing state-transition workflow rules with that metadata available in the meeting note.

Scenario: Teams meeting start prompts the user

• GIVEN scheduled Outlook recording prompts are enabled
• AND Meeting Assistant has synced Outlook Classic Teams appointments for today
• WHEN the appointment reaches its scheduled start window
• THEN Meeting Assistant shows a native Windows app notification asking whether to record the meeting
• AND the notification remains actionable for 5 minutes
• AND marks that appointment as prompted for the day

Scenario: Canceled Teams meeting does not prompt recording

• GIVEN scheduled Outlook recording prompts are enabled
• AND Meeting Assistant has synced a canceled Outlook Classic Teams appointment for today
• WHEN the canceled appointment reaches its scheduled start window
• THEN Meeting Assistant does not show a recording prompt for that appointment

Scenario: Back-to-back cached Teams meetings prompt without another Outlook sync

• GIVEN scheduled Outlook recording prompts are enabled
• AND Meeting Assistant has synced two Teams appointments for today that start ten minutes apart
• WHEN each appointment reaches its scheduled start window
• THEN Meeting Assistant shows a recording prompt for each appointment
• AND does not require another Outlook calendar sync between the prompts

Scenario: User accepts prompt while idle

• GIVEN scheduled Outlook recording prompts are enabled
• AND no meeting recording is active
• WHEN the user accepts a Teams meeting recording prompt
• THEN Meeting Assistant starts recording normally

Scenario: User accepts prompt while already recording

• GIVEN scheduled Outlook recording prompts are enabled
• AND a meeting recording is active
• WHEN the user accepts a Teams meeting recording prompt
• THEN Meeting Assistant stops the active recording normally
• AND starts a new recording normally after the stop request

Scenario: Accepted prompt supplies meeting metadata

• GIVEN scheduled Outlook recording prompts are enabled
• AND Meeting Assistant has cached two current Teams appointments with different metadata
• WHEN the user accepts the recording prompt for one appointment
• THEN Meeting Assistant starts the recording with the accepted appointment's metadata
• AND does not perform a standalone current-meeting metadata lookup for that recording
• AND runs created workflow rules before writing the cached appointment metadata
• AND runs collecting metadata to transcribing workflow rules after writing the cached appointment metadata

Scenario: Prompt is disabled

• GIVEN scheduled Outlook recording prompts are disabled
• WHEN a Teams appointment reaches its scheduled start
• THEN Meeting Assistant does not query Outlook for recording prompt candidates
• AND does not show a recording prompt

Requirement: Meeting automation rules are configurable

Meeting Assistant SHALL allow an optional local YAML rules file path to be configured.

When the configured rules file is missing or blank, Meeting Assistant SHALL continue without applying automation rules.

The local rules file SHALL be ignored by source control.

Rules SHALL be evaluated against the latest meeting note data read from disk for each event.

Meeting Assistant SHALL expose a diagnostic endpoint that reloads application configuration so workflow automation configuration changes can be picked up without restarting the application.

Scenario: Missing rules file is ignored

• WHEN Meeting Assistant handles a meeting event and no configured rules file exists
• THEN it leaves the meeting note and assistant context unchanged

Scenario: Created rule adds default attendee

• GIVEN a configured rule that triggers on meeting creation when meeting.attendees.count = 0
• WHEN Meeting Assistant creates a meeting note without attendees
• THEN it adds the configured attendee to the meeting note

Scenario: Workflow configuration is reloaded diagnostically

• GIVEN the workflow automation configuration has changed on disk
• WHEN the diagnostic workflow reload endpoint is called
• THEN Meeting Assistant reloads application configuration without restarting
• AND future workflow events use the reloaded workflow automation configuration

Requirement: Meeting automation rules support lifecycle triggers

Meeting Assistant SHALL support rule triggers for created, state_transition, speaker_identified, transcript_line, and attendee_added.

An attendee_added trigger MAY filter by equals, contains, or regex against the attendee value being added. equals and contains filters SHALL match case-insensitively.

Meeting Assistant SHALL apply attendee-added transformations before storing attendees added from meeting metadata, accepted recording-prompt metadata, workflow add_attendee steps, screenshot OCR, speaker identity updates, and summarizer add-attendee tools.

Scenario: Attendee added rule filters and transforms a metadata attendee

• GIVEN a configured rule that triggers on added attendees containing @contoso.com
• AND the rule sets attendee.name to a display name derived from the added attendee
• WHEN Meeting Assistant adds attendee Ada Lovelace <ada@contoso.com> from meeting metadata
• THEN the stored meeting attendee is the transformed attendee name
• AND the original attendee string is not stored

Requirement: Meeting automation rules support conditions and steps

Meeting Assistant SHALL expose the added attendee name to attendee_added rule conditions and Razor step templates as attendee.name.

The set_property step SHALL support setting attendee.name during attendee_added events.

Rules with an attendee_added trigger SHALL be limited to transforming attendee.name with set_property.

Direct meeting note file writes SHALL NOT emit attendee_added or transform attendee values.

Scenario: Attendee added rules can use regex and Razor

• GIVEN a configured attendee_added rule with a regex filter over the added attendee
• WHEN Meeting Assistant adds an attendee matching the regex
• THEN the rule can set attendee.name with a Razor template using Model.Attendee.Name

Requirement: Workflow rules and speaker identities can be edited through a tray-launched assistant

Meeting Assistant SHALL expose an Open agent item from the tray icon menu.

The tray icon SHALL be implemented through the Uno notification icon stack.

The tray icon menu SHALL show every configured launch profile when recording can be started and SHALL include each profile's configured toggle hotkey in the corresponding start or switch menu item.

When the user selects Open agent, Meeting Assistant SHALL open a basic MewUI chat window for editing the configured workflow rules file and speaker identities.

The chat window SHALL be titled Meeting Summary Agent, SHALL display user and assistant messages as visually distinct cards, SHALL display basic markdown emphasis, inline code, fenced code blocks, pipe tables rendered as grid views, and line breaks in agent responses, SHALL display lightweight visible reasoning summary lines and tool-call lines that include only the called tool name while the agent is working, SHALL display a plain Thinking... line as the bottom activity line while the agent is working, MAY replace that bottom line with Reconnecting... while retrying a transient agent request, SHALL replace per-turn activity after completion with a collapsible Worked for <duration> expander between the user and assistant cards, SHALL show visible reasoning summary lines, tool-call lines, and status lines in order inside the expander when expanded, SHALL collapse those details again when the expander is closed, SHALL provide a multiline text input at the bottom with placeholder text for asking to make a rule or list identities, SHALL send on Enter, SHALL insert a newline on Shift+Enter, and SHALL provide an explicit Send button.

When a new chat message or thinking state is appended, the chat window SHALL scroll to the bottom of the newly rendered content if the conversation was already near the bottom or did not need scrolling before the append.

The Windows executable and rules-and-identities editor window SHALL use the Meeting Assistant application icon so the editor has a taskbar icon.

The rules editor agent SHALL be configured from the summarizer agent settings by default, while allowing workflow-rules-editor-specific endpoint, key, model, reasoning, reconnection, output, and compaction settings to override those defaults.

The rules and identities editor agent SHALL include the workflow engine documentation in its system prompt and SHALL receive read, write, and search tools scoped to the configured workflow rules file.

The rules editor write_rules tool SHALL append to the configured workflow rules file by default and SHALL validate the complete resulting YAML document before writing it.

The rules editor write_rules tool SHALL replace the whole configured workflow rules file only when replace_file is true.

The rules editor write_rules tool SHALL refuse invalid YAML without changing the configured workflow rules file.

The rules and identities editor agent SHALL receive speaker identity tools to search/list, read, update, delete, and merge identities in the local speaker identity database, and a create tool that refuses sampleless identity creation with an actionable response.

The rules and identities editor agent SHALL receive speaker sample tools to list, read, delete, and queue playback of samples linked to identities. The delete sample tool SHALL refuse to delete the last remaining sample for an identity.

The first model request caused by each user-submitted chat turn SHALL send the X-Initiator: user header, while follow-up model requests within that same turn, such as tool-call continuations, SHALL send X-Initiator: agent.

Meeting Assistant SHALL provide a diagnostic endpoint that opens the workflow rules editor through the same window service used by the tray menu.

Scenario: Tray menu opens the editor

• WHEN the user opens the tray icon menu
• THEN the menu includes Open agent
• WHEN the user selects Open agent
• THEN Meeting Assistant opens the workflow rules and identities editor chat window

Scenario: Tray menu shows configured profile hotkeys

• GIVEN the default launch profile uses Ctrl+Alt+M
• AND the english launch profile uses Ctrl+Alt+L
• WHEN the user opens the tray icon menu while Meeting Assistant is idle
• THEN the menu includes a start item for default showing Ctrl+Alt+M
• AND the menu includes a start item for english showing Ctrl+Alt+L

Scenario: Rules editor can be opened diagnostically

• WHEN a diagnostic caller requests the workflow rules editor to open
• THEN Meeting Assistant invokes the workflow rules editor window service

Scenario: Rules editor is scoped to the configured rules file

• GIVEN a configured workflow rules file
• WHEN the rules editor agent runs
• THEN its read, write, and search tools can access only that configured workflow rules file
• AND its system prompt includes the workflow engine documentation

Scenario: Rules editor appends by default

• GIVEN a configured workflow rules file with existing valid rules
• WHEN the rules editor writes an additional valid rule without replace_file
• THEN Meeting Assistant appends the new rule
• AND preserves the existing rules

Scenario: Rules editor replaces only when requested

• GIVEN a configured workflow rules file with existing rules
• WHEN the rules editor writes valid YAML with replace_file set to true
• THEN Meeting Assistant replaces the complete rules file with the supplied YAML

Scenario: Rules editor refuses invalid YAML

• GIVEN a configured workflow rules file with valid existing rules
• WHEN the rules editor writes YAML that would make the file invalid
• THEN Meeting Assistant refuses the write
• AND keeps the existing rules file unchanged

Scenario: Rules editor can manage speaker identities

• GIVEN the speaker identity database contains speaker identities and samples
• WHEN the rules editor agent runs
• THEN it can search, read, update, delete, and merge speaker identities
• AND sampleless identity creation is refused with an actionable response
• AND it can list, read, delete, and queue playback of identity samples
• AND deleting the last sample for an identity is refused

Scenario: User sends a rules-editing chat turn

• GIVEN the rules editor chat window is open
• WHEN the user types a prompt and presses Enter
• THEN the user message appears in the conversation
• AND a plain Thinking... line appears at the bottom while the agent is running
• WHEN the agent emits visible reasoning summaries or calls tools
• THEN lightweight activity lines appear above the bottom activity line with the visible reasoning summary text or only the called tool names
• WHEN the agent turn completes
• THEN the activity is represented between the user and assistant cards as a collapsed Worked for <duration> expander
• AND expanding it shows the visible reasoning summary, status, and tool-call lines in order
• AND collapsing it hides those details again
• AND if no visible reasoning summary was emitted, the expander includes the fallback Thinking... line
• AND the first model request for that turn is marked as user-initiated
• AND the final assistant response replaces the live activity lines

Scenario: Rules editor displays agent request failures

• GIVEN the rules editor chat window is open
• WHEN the agent request fails or times out without caller cancellation
• THEN the user message remains in the conversation
• AND the thinking line is replaced by a visible assistant error message

Scenario: Chat auto-scrolls after appended content

• GIVEN the rules editor chat window content fits without scrolling or is already near the bottom
• WHEN a new user or assistant message is appended
• THEN the conversation scrolls to the bottom of the newly rendered message content