# AGENTS.md — Build guide for Wispr Flow

## Project scope
Start/stop local dictation from a shortcut, review the result and insert only into the originally selected app with a copy-only fallback.

Catalogue verdict: yes. Hotkey → record → Whisper → paste at cursor. One of the most-cloned apps of the trend for a reason.
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
- Runtime and tools: Swift, SwiftUI/AppKit and SQLite on macOS, with secrets in Keychain where needed.
- Before starting: A Mac, the current Xcode toolchain and a documented permission checklist; distribution signing is a separate delivery task.

## Stack and architecture
- Swift, SwiftUI/AppKit and SQLite on macOS, with secrets in Keychain where needed
- Data design: Store SessionState, CapturedAppIdentity, AudioTempPath and PasteboardRevision; cancellation terminates work and late results cannot change a cancelled session or paste into a different app.
- Setup: A Mac, the current Xcode toolchain and a documented permission checklist; distribution signing is a separate delivery task

## Security and data integrity
- Ask for each operating-system permission when its feature is used. Handle denial and revocation without a loop; show permission status and keep local history deletable.
- Retain the pinned whisper.cpp local path and no-cloud initial scope. Permission denial, five-minute stop, temp-file cleanup and manual insertion are required; no guarantee that every destination accepts simulated paste.
- Keep secrets outside client bundles and exported projects; document what leaves the device and make retention/deletion controls visible.

## Agent implementation rules
- Project rule — domain: Store SessionState, CapturedAppIdentity, AudioTempPath and PasteboardRevision; cancellation terminates work and late results cannot change a cancelled session or paste into a different app.
- Project rule — scope and recovery: Retain the pinned whisper.cpp local path and no-cloud initial scope. Permission denial, five-minute stop, temp-file cleanup and manual insertion are required; no guarantee that every destination accepts simulated paste.
- Project rule — acceptance: Switch apps while recognition runs and copy new clipboard text before insertion; keep the transcript ready for manual action and preserve the new clipboard value.
- Project rule — delivery: document real setup commands and permissions; do not claim a build, accuracy level, performance result or security certification that has not been demonstrated.

## Optional agent skills and references
- Recommended skill: [swiftui-expert-skill](https://github.com/AvdLee/SwiftUI-Agent-Skill/blob/main/skills/swiftui-expert-skill/SKILL.md) — design native SwiftUI state, accessible controls and permission/error views for the proposed Apple-platform interface. Follow the maintainer's installation instructions and match its requirements to the chosen runtime.
- Recommended skill: [swift-concurrency](https://github.com/AvdLee/Swift-Concurrency-Agent-Skill/blob/main/skills/swift-concurrency/SKILL.md) — isolate capture, background work and UI updates, and make cancellation invalidate late callbacks. Follow the maintainer's installation instructions and match its requirements to the chosen runtime.

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 working slice using synthetic or explicitly authorized non-sensitive examples: Start/stop local dictation from a shortcut, review the result and insert only into the originally selected app with a copy-only fallback.
- Share a synthetic example export and the acceptance walkthrough; keep real customer, health, financial and source data private: Switch apps while recognition runs and copy new clipboard text before insertion; keep the transcript ready for manual action and preserve the new clipboard value.
- State the limits before asking someone to replace their existing tool: Retain the pinned whisper.cpp local path and no-cloud initial scope. Permission denial, five-minute stop, temp-file cleanup and manual insertion are required; no guarantee that every destination accepts simulated paste.

## Engineering roadmap
1. Phase 1 — Pin the working slice and create its example input: Start/stop local dictation from a shortcut, review the result and insert only into the originally selected app with a copy-only fallback. Confirm setup: A Mac, the current Xcode toolchain and a documented permission checklist; distribution signing is a separate delivery task.
2. Phase 2 — Implement persistence and write-time invariants before decorating the UI: Store SessionState, CapturedAppIdentity, AudioTempPath and PasteboardRevision; cancellation terminates work and late results cannot change a cancelled session or paste into a different app.
3. Phase 3 — Connect the working view to real saved state. Ask for each operating-system permission when its feature is used. Handle denial and revocation without a loop; show permission status and keep local history deletable.
4. Phase 4 — Expose the app-specific limits and recovery path in context: Retain the pinned whisper.cpp local path and no-cloud initial scope. Permission denial, five-minute stop, temp-file cleanup and manual insertion are required; no guarantee that every destination accepts simulated paste.
5. Phase 5 — Walk through this concrete acceptance case and preserve its exported evidence: Switch apps while recognition runs and copy new clipboard text before insertion; keep the transcript ready for manual action and preserve the new clipboard value. Finish the README and backup/restore instructions; report unfinished capabilities explicitly.

## Paid-product capabilities outside this build
- their tuned auto-editing voice model
- per-app tone formatting
- the mobile keyboard
- polish on edge cases (accents, noise)

## Implementation prompt
Build me a macOS menu-bar dictation tool with local transcription like Wispr Flow. Requirements:

- Use Swift, AppKit, AVFoundation, and a pinned whisper.cpp command-line build. Store settings under Application Support/LocalDictation and keep the downloaded model at a configured local path. No cloud provider or API key is needed for the initial version.
- Implement states idle, recording, transcribing, ready, cancelled, and error. A configurable global shortcut starts/stops recording; an optional hold-to-talk mode stops on release. Show a recording indicator with elapsed time and auto-stop after five minutes.
- Capture microphone audio with AVAudioEngine and convert to the mono sample format expected by the pinned transcription binary. Write a unique temporary audio file, spawn the binary with an argument array, and capture bounded stdout/stderr. Never invoke a shell with dictated text or filenames.
- Escape cancels recording or transcription. Cancellation terminates the child process, deletes its temporary audio, and marks the session cancelled so a late callback cannot paste text. Denied microphone or Accessibility permission must show an actionable state with no recording underway.
- Capture the frontmost app identity when recording starts. After transcription, display editable text and an Insert button; optional auto-insert is allowed only if the same app remains frontmost. Otherwise keep the result for manual insertion. Do not inspect or store unrelated screen content.
- Insert via the pasteboard and a simulated Cmd-V when Accessibility permission allows it. Offer copy-only fallback. If restoring the previous clipboard is enabled, restore only if the pasteboard change count still matches this app write, so a new user copy is not overwritten.
- Keep audio only until transcription or cancellation completes; transcript history is off by default. Apply only deterministic whitespace/punctuation cleanup in v1, retaining the raw transcript for review. No accounts or telemetry. Out of scope: mobile keyboard, per-app AI tone changes, and guaranteed insertion into every app.
- Acceptance: start/stop, five-minute stop, denied permission, Escape during recognition, focus change before completion, and clipboard change during insertion all produce safe states. README covers Xcode build, model download/checksum, microphone/Accessibility permissions, privacy behavior, and manual fallback.

EDITORIAL IMPLEMENTATION CONTRACT
Working slice: Start/stop local dictation from a shortcut, review the result and insert only into the originally selected app with a copy-only fallback.
Data and invariants: Store SessionState, CapturedAppIdentity, AudioTempPath and PasteboardRevision; cancellation terminates work and late results cannot change a cancelled session or paste into a different app.
Boundary and recovery: Retain the pinned whisper.cpp local path and no-cloud initial scope. Permission denial, five-minute stop, temp-file cleanup and manual insertion are required; no guarantee that every destination accepts simulated paste.
Acceptance walkthrough: Switch apps while recognition runs and copy new clipboard text before insertion; keep the transcript ready for manual action and preserve the new clipboard value.
Record actual dependency versions, permissions and provider access in setup instructions. Preserve originals, expose partial failures and document backup/restore. These are acceptance requirements, not a claim of a completed or production-certified build. Add the domain, recovery and acceptance rules to AGENTS.md so future edits preserve them.

## 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.