Avoma

Build me a focused meeting transcription and AI notes workflow for the personal core of Avoma. Requirements:

- Use Python 3.12, FastAPI, SQLite, whisper.cpp, and a minimal HTMX interface. Model source documents, editable pages or notes, internal links, revisions, and exports; retain source IDs and timestamps.
- Paid product context: Transcribe calls and maintain a lightweight coaching notebook from user-owned recordings. Build only this DIY scope: Record or import a meeting, transcribe it locally, identify speakers with manual correction, generate structured notes, and maintain a lightweight coaching notebook from user-owned recordings.
- Add explicit start, pause, resume, and stop controls with a visible recording indicator.
- Support importing WAV, MP3, M4A, and MP4 files through ffmpeg.
- Run transcription locally and display timestamped editable segments. Generate decisions, action items, questions, and a concise summary from approved text. Export Markdown, plain text, and WebVTT beside the original recording.
- Use a local web page with input, progress, review, and export views. Required input or access: desktop microphone access; whisper.cpp model files. Keep credentials in .env.
- Recovery: If optional OpenAI or Anthropic API key is unavailable, keep the source record and show a recoverable error instead of a fabricated result.
- Acceptance: with one labelled sample, show the input, saved intermediate state, and exported result; verify this invariant: When transcription fails, keep the recording; every quoted note must reference a segment that exists in the saved transcript.
- Out of scope: conversation intelligence, CRM data, forecasting, coaching, and enterprise integrations; calendar auto-join. Keep this a personal, inspectable workflow.
- Include a README with setup, a sample input, required keys or permissions, data location, and the supported scope.

# AGENTS.md — Build guide for Avoma

## Project scope
Record or import a meeting, transcribe it locally, identify speakers with manual correction, generate structured notes, and maintain a lightweight coaching notebook from user-owned recordings.

Catalogue verdict: no. A consolation build is possible, but the paid product's decisive value sits outside a solo rebuild. For Avoma, transcribe calls and maintain a lightweight coaching notebook from user-owned recordings. The hard boundary is conversation intelligence, crm data, forecasting, coaching, and enterprise integrations, plus capture reliability, integrations, and collaboration.
Use the implementation prompt below to define the deliverable. Complete each phase's acceptance checks before extending the scope.

## Working agreement
- Inspect the repository and its existing instructions before choosing paths, dependencies or commands. Keep one coherent stack and explain changes to the proposed architecture.
- Plan a vertical slice that accepts a real input and produces the useful output described below. Persist only the state the prompt calls for; respect memory-only and upstream-managed workflows. Use fixtures only when they are clearly labelled.
- After scaffolding, document the actual install, development, check and build commands in README and keep them synchronized with the package or project manifest. Do not report commands as successful unless they ran.
- Work in small steps. At handoff, list implemented flows, checks actually performed, remaining blockers, and any credentials or provider setup the owner must supply.
- Do not publish, spend money, contact customers, delete source data or run irreversible migrations without the project owner's authorization.

## Prerequisites
- desktop microphone access
- whisper.cpp model files
- optional OpenAI or Anthropic API key
- local storage

## Stack and architecture
- Use Python 3.12, FastAPI, SQLite, whisper.cpp, and a minimal HTMX interface.
- Model source documents, editable pages or notes, internal links, revisions, and exports; retain source IDs and timestamps.
- Interface for this meeting transcription and AI notes workflow: a local web page with input, progress, review, and export views.

## Security and data integrity
- If optional OpenAI or Anthropic API key is unavailable, keep the source record and show a recoverable error instead of a fabricated result.
- Keep API keys and OAuth secrets in .env; redact them from logs, generated files, and error responses.
- State the practical limit: conversation intelligence, CRM data, forecasting, coaching, and enterprise integrations.

## Agent implementation rules
- Project rule, data: Model source documents, editable pages or notes, internal links, revisions, and exports; retain source IDs and timestamps.
- Project rule, behavior: Add explicit start, pause, resume, and stop controls with a visible recording indicator.
- Project rule, recovery: If optional OpenAI or Anthropic API key is unavailable, keep the source record and show a recoverable error instead of a fabricated result.

## Optional agent skills and references
No installable skill is listed for this guide; use the project rules and the stack documentation.

Read the linked SKILL.md and its dependencies before adding a skill. Select only the skills matching this project's runtime and task; their documentation does not supply API access, credentials or approval to perform external actions. Pin the reviewed revision where the tool supports it. Follow the chosen agent's documented project-level installation mechanism.

## Distribution ideas
These are optional planning notes. Obtain the owner's approval before publishing or contacting anyone.
- Demonstrate this meeting transcription and AI notes operation with sample or user-owned data: Add explicit start, pause, resume, and stop controls with a visible recording indicator.
- Show a concrete result or export: Export Markdown, plain text, and WebVTT beside the original recording.
- State the practical limit: conversation intelligence, CRM data, forecasting, coaching, and enterprise integrations.

## Engineering roadmap
1. Phase 1, architecture and data: Use Python 3.12, FastAPI, SQLite, whisper.cpp, and a minimal HTMX interface. Model source documents, editable pages or notes, internal links, revisions, and exports; retain source IDs and timestamps.
2. Phase 2, implement: Add explicit start, pause, resume, and stop controls with a visible recording indicator.
3. Phase 3, implement: Support importing WAV, MP3, M4A, and MP4 files through ffmpeg.
4. Phase 4, review and output: Run transcription locally and display timestamped editable segments. Export Markdown, plain text, and WebVTT beside the original recording.
5. Phase 5, recovery and acceptance: If optional OpenAI or Anthropic API key is unavailable, keep the source record and show a recoverable error instead of a fabricated result. Verify this invariant with a saved fixture: When transcription fails, keep the recording; every quoted note must reference a segment that exists in the saved transcript. State the practical limit: conversation intelligence, CRM data, forecasting, coaching, and enterprise integrations.

## Paid-product capabilities outside this build
- conversation intelligence, CRM data, forecasting, coaching, and enterprise integrations
- calendar auto-join
- reliable speaker diarization
- mobile capture
- team search and sharing

## Implementation prompt
Build me a focused meeting transcription and AI notes workflow for the personal core of Avoma. Requirements:

- Use Python 3.12, FastAPI, SQLite, whisper.cpp, and a minimal HTMX interface. Model source documents, editable pages or notes, internal links, revisions, and exports; retain source IDs and timestamps.
- Paid product context: Transcribe calls and maintain a lightweight coaching notebook from user-owned recordings. Build only this DIY scope: Record or import a meeting, transcribe it locally, identify speakers with manual correction, generate structured notes, and maintain a lightweight coaching notebook from user-owned recordings.
- Add explicit start, pause, resume, and stop controls with a visible recording indicator.
- Support importing WAV, MP3, M4A, and MP4 files through ffmpeg.
- Run transcription locally and display timestamped editable segments. Generate decisions, action items, questions, and a concise summary from approved text. Export Markdown, plain text, and WebVTT beside the original recording.
- Use a local web page with input, progress, review, and export views. Required input or access: desktop microphone access; whisper.cpp model files. Keep credentials in .env.
- Recovery: If optional OpenAI or Anthropic API key is unavailable, keep the source record and show a recoverable error instead of a fabricated result.
- Acceptance: with one labelled sample, show the input, saved intermediate state, and exported result; verify this invariant: When transcription fails, keep the recording; every quoted note must reference a segment that exists in the saved transcript.
- Out of scope: conversation intelligence, CRM data, forecasting, coaching, and enterprise integrations; calendar auto-join. Keep this a personal, inspectable workflow.
- Include a README with setup, a sample input, required keys or permissions, data location, and the supported scope.

## Completion evidence
Demonstrate the prompt's acceptance scenarios against the scoped workflow. Include setup from a clean checkout and failure recovery. Check persistence across restart and export/restore only for the state the prompt says to store; for memory-only tools, confirm that temporary content is discarded as specified. Record actual results and remaining limitations. A detailed plan alone does not establish a working replacement.