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

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: 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 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: 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: 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, and speaker_identified.

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

A speaker_identified trigger MAY filter by speaker name.

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

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.

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

Meeting Assistant SHALL support these initial rule steps:

• add_attendee
• remove_attendee
• set_property
• add_context
• add_project

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