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.

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

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, and transcript_line.

A state_transition trigger MAY filter by from, to, or both state values.

A speaker_identified trigger MAY filter by speaker name.

A transcript_line trigger MAY filter by speaker name.

Workflow rule execution SHALL log each triggered rule with its rule name and event type.

Workflow rule execution SHALL log rule failures with the rule name and event type.

Scenario: State transition rule matches from and to

• GIVEN a configured rule that triggers on a state transition from collecting metadata to transcribing
• WHEN Meeting Assistant transitions that meeting from collecting metadata to transcribing
• THEN it applies the rule steps

Scenario: Speaker identified rule filters by name

• GIVEN a configured rule that triggers when speaker Ada is identified
• WHEN Meeting Assistant identifies speaker Grace
• THEN it does not apply the rule
• WHEN Meeting Assistant identifies speaker Ada
• THEN it applies the rule steps

Scenario: Transcript line rule rewrites masked profanity after durable append

• GIVEN a configured rule that triggers on transcript line writes and sets transcript.line by replacing ***** with [redacted]
• WHEN Meeting Assistant writes a transcript line for speaker Guest-1 containing *****
• THEN Meeting Assistant first appends the original formatted line to the transcript file
• AND rewrites that written line to contain [redacted]
• AND the final written transcript line does not contain *****

Scenario: Transcript line workflow failure keeps transcript writing

• GIVEN a configured transcript line workflow rule fails while processing a transcript line
• WHEN Meeting Assistant receives that live transcript segment
• THEN Meeting Assistant keeps the original formatted line in the transcript file
• AND logs the workflow rule failure
• AND continues processing later transcript segments

Requirement: Meeting automation rules support conditions and steps

Meeting Assistant SHALL support rule conditions using an expression engine.

Rules SHALL support nested and, or, and not condition groups.

Step values SHALL support Razor syntax against the current meeting event model.

Rendered step values SHALL be treated as plain UTF-8 text for markdown artifacts and SHALL NOT persist Razor HTML entity encoding.

Step values SHALL treat @ characters inside valid email address tokens as literal text rather than Razor transitions.

Meeting Assistant SHALL expose the formatted transcript line and transcript speaker to transcript_line rule conditions and Razor step templates.

Meeting Assistant SHALL support these initial rule steps:

• add_attendee
• remove_attendee
• set_property
• add_context
• add_project

The set_property step SHALL support setting transcript.line during transcript_line events.

Scenario: Nested conditions choose a matching rule

• GIVEN a configured rule with nested and, or, and not conditions over meeting title, attendees, and event data
• WHEN the condition evaluates to true
• THEN Meeting Assistant applies the rule
• WHEN the condition evaluates to false
• THEN Meeting Assistant skips the rule

Scenario: Templated context mentions identified speaker

• GIVEN a configured speaker_identified rule with an add_context step using Razor syntax
• WHEN Meeting Assistant identifies matching speaker Ada
• THEN it appends rendered context text containing Ada to the assistant context note

Scenario: Email addresses do not trigger Razor templating

• GIVEN a configured rule step value containing Support@contoso.com
• WHEN the rule runs
• THEN Meeting Assistant preserves the email address as literal text

Scenario: Email addresses can appear beside Razor templating

• GIVEN a configured rule step value containing both Support@contoso.com and a Razor expression
• WHEN the rule runs
• THEN Meeting Assistant renders the Razor expression and preserves the email address as literal text

Scenario: Razor-rendered transcript line preserves UTF-8 text

• GIVEN a configured transcript_line rule uses Razor to replace part of a transcript line containing heißt, Schimpfwörter, and nächstes
• WHEN the rule changes transcript.line
• THEN the resulting transcript line contains the original UTF-8 characters
• AND does not contain HTML entities such as ß, ö, or ä

Scenario: Rule can clean a meeting title

• GIVEN a configured state-transition rule that matches a title containing a configured marker
• WHEN the rule runs
• THEN Meeting Assistant can update the meeting title through set_property

Scenario: Transcript line conditions can use the written line and speaker

• GIVEN a configured transcript_line rule with conditions over transcript.line and transcript.speaker
• WHEN Meeting Assistant writes a transcript line that matches both conditions
• THEN Meeting Assistant applies the rule steps after the original formatted line is durably appended
• AND rewrites the written line if a rule changes transcript.line

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