spokesman

Imported from arhamhi/spokesman (AGENTS.md). Install upstream with npx skills add arhamhi/spokesman. Copyright stays with the author.

Spokesman - agent instructions

Spokesman is Arham's personal native macOS dictation app for his 16-inch 2021 M1 Pro MacBook Pro. Its daily-driver promise is simple: hold Control+Option, talk naturally, release, and get voice-preserving text in the focused app without opening a terminal or managing a background script.

Read first

1. PLAN.md - locked product direction, delivery phases, and success criteria.
2. docs/handoff/STATE.md - current factual code and verification state.
3. docs/handoff/NEXT_STEPS.md - the ordered execution queue. Work top to bottom.
4. docs/handoff/DECISIONS.md - durable decisions and rationale. Supersede decisions explicitly instead of silently reversing them.
5. docs/PRD.md - detailed behavior and product requirements.

Working agreement

• Preserve the existing working Windows pipeline as a reference while moving the active product through small, testable macOS slices.
• For macOS work, run DEVELOPER_DIR=/Applications/Xcode.app/Contents/Developer swift test --package-path macos and bash scripts/build-macos-app.sh. The build script selects that Xcode automatically. Keep the retained Windows baseline green with .venv\Scripts\python.exe -m pytest -q and .venv\Scripts\python.exe -m ruff check src tests when shared files change.
• Automated tests do not replace live M1 Pro verification for global shortcuts, focus-safe paste, menu-bar behavior, launch at login, Apple Dictation latency, or overlay placement.
• Update STATE.md, NEXT_STEPS.md, and DECISIONS.md in the same change as the code they describe.
• Keep STATE.md a compact present-tense snapshot. Put rationale in DECISIONS.md, future work in NEXT_STEPS.md, and stable scope in PLAN.md or PRD.md.
• Do not add a dependency or change the application shell without a measured need and a decision-log entry.
• Preserve unrelated local changes. Never use destructive Git commands unless Arham explicitly requests them.

Hard constraints

• One user, one 16-inch 2021 M1 Pro MacBook Pro with 16 GB unified memory.
• The native release targets macOS 26 and Xcode 26. Do not add an older-OS fallback unless the real Mac cannot run macOS 26.
• Audio is processed in memory and discarded. Never persist audio.
• Transcripts and derived analytics are local. No telemetry, crash reporting, or silent uploads.
• The core dictation path must work without an API key or paid service.
• Codex-backed coaching is an explicit, user-approved analysis path and must fail without breaking dictation.
• The macOS runtime is Swift/AppKit, SpeechAnalyzer plus DictationTranscriber, AVAudioEngine, Accessibility/Core Graphics, WKWebView, and SMAppService. No Python, Whisper, local LLM, Electron, or third-party runtime dependency belongs in the macOS dictation path.
• The Bauhaus bento visual direction stays. Information architecture may change to serve the product.

Source layout

• macos/ - native Swift package and app metadata.
• src/spokesman/ - application code.
• tests/ - automated tests mirroring application behavior.
• scripts/ - setup, launch, install, and verification helpers.
• data/ - ignored local settings, history, dictionary, snippets, and analytics.
• models/ - ignored local model files and caches.
• docs/handoff/ - current state, ordered work, and durable decisions.
• docs/verification/ - live platform exit checks that automation cannot prove.

Phase 1 stop condition

Phase 1 is complete only when the native source compiles and tests on macOS 26, the builder produces a verified signed .app, normal use starts no terminal or Python process, launch at login is silent, the menu-bar app implements Control+Option push-to-talk and hands-free interaction, the HUD remains focus-safe through recording and delivery, warmed release-to-paste latency passes the M1 Pro gate, no audio is persisted, and docs/verification/MACOS-PHASE1.md is fully checked.