meeting-assistant/openspec/specs/agent-project-tools/spec.md

agent-project-tools Specification

Purpose

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

Requirements

Requirement: Agents can use project context tools

Meeting Assistant SHALL expose tools that allow agents to look up project information, retrieve keyword-relevant context, and inspect meeting-derived knowledge.

Project tools SHALL treat each direct subfolder of the configured projects folder as one project. A meeting note binds projects by listing those subfolder names in the projects frontmatter field.

The summary agent SHALL expose these project tools:

• list_projects
• list_projectfiles
• read_projectfile
• write_projectfile
• list_past_project_meetings
• read_past_project_meeting_summary
• search

The search tool SHALL search the requested current-meeting project scope, or all projects assigned to the current meeting when no project scope is supplied.

The search tool SHALL search both configured project files for the scoped projects and past meeting summary notes in the configured summaries folder whose frontmatter projects intersect the scoped projects.

The search tool SHALL refuse requested project scopes that are not assigned to the current meeting.

Scenario: Agent looks up meeting project context

• WHEN a meeting note identifies a project
• THEN the agent can retrieve relevant project context through Meeting Assistant tools

Scenario: Agent lists projects bound to the meeting

• WHEN the meeting note frontmatter lists project folder names
• THEN list_projects returns the matching configured project subfolders

Scenario: Agent reads a clamped project file range

• WHEN the agent reads a project file with optional line bounds outside the file length
• THEN read_projectfile clamps the requested range to the available file lines without failing

Scenario: Agent searches project knowledge

• WHEN the agent calls search with ripgrep syntax keywords
• THEN Meeting Assistant runs the search against the requested projects or the meeting-bound projects and returns matches as filename:line text

Scenario: Agent searches past project meeting summaries

• GIVEN the current meeting note is assigned to Project X
• AND a prior summary note in the configured summaries folder is assigned to Project X
• WHEN the summary agent searches for a keyword
• THEN Meeting Assistant returns matches from both Project X project files and matching past summary notes

Scenario: Agent search rejects out-of-scope project

• GIVEN the current meeting note is assigned to Project X
• WHEN the summary agent searches with project scope Project Z
• THEN Meeting Assistant refuses the request because Project Z is not assigned to the current meeting

Requirement: Agents can write files in existing projects

Meeting Assistant SHALL expose a write_projectfile tool that can create or update files inside an existing project folder.

The target project SHALL be an existing direct subfolder of the configured projects folder. The target file path SHALL stay inside that project folder.

When no line edit arguments are supplied and replace_file is not true, write_projectfile SHALL append the supplied content to the file and SHALL create the file when it does not exist.

When replace_file is true, write_projectfile SHALL replace the whole file with the supplied content.

When both from and to are supplied, write_projectfile SHALL replace the inclusive 1-based line range with the supplied content.

When insert is supplied, write_projectfile SHALL insert the supplied content at that 1-based line position.

Meeting Assistant SHALL refuse ambiguous writes that combine replace_file with line edit arguments.

Scenario: Project file is appended or created

• WHEN the agent writes a project file without line edit arguments
• THEN Meeting Assistant appends the supplied content to an existing file
• AND creates the file with the supplied content when it does not exist

Scenario: Project file is explicitly replaced

• WHEN the agent writes a project file with replace_file set to true
• THEN Meeting Assistant writes the supplied content as the complete file content

Scenario: Project file line range is replaced

• WHEN the agent writes a project file with from and to line numbers
• THEN Meeting Assistant replaces the inclusive line range with the supplied content

Scenario: Project file content is inserted

• WHEN the agent writes a project file with an insert line number
• THEN Meeting Assistant inserts the supplied content at that line position

Scenario: Project file write target is invalid

• WHEN the target project is missing or the target path escapes the project folder
• THEN Meeting Assistant refuses the project file write

Scenario: Project file write mode is ambiguous

• WHEN the agent combines replace_file with from, to, or insert
• THEN Meeting Assistant refuses the project file write