# AGENTS.md — Build guide for eqMac

## Project scope
Route audio through an explicitly installed virtual device, apply a bounded EQ/gain chain and offer immediate bypass to the physical output. Add a spectrum view only after stable processing and device switching.

Catalogue verdict: kinda. The DSP is the easy part: a cascade of biquad filters driven by sliders is textbook, and an agent will write it correctly on the first try. The hard part is getting system audio into your process at all, which on macOS means a virtual output device and a Core Audio server plugin, signed and notarized, plus graceful handling of sample rate changes, device hotplug and headphone unplug. You can dodge most of that by installing BlackHole and building a loopback app that pulls from it and pushes to your real output, which is a genuine weekend project and works fine on your own machine. What you will not match in one sitting is the invisible-ness: no driver install prompts, no latency you can hear, no manual switching every time you plug in AirPods. Good build, mediocre replacement for something you want to forget exists.
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
- A Mac with Xcode, an installed supported BlackHole virtual audio device, a physical output and any required audio-capture permissions. Document manual routing, compatible sample rates, a safe bypass/restore path and the added latency; the app does not ship its own driver.
- Implementation components: Swift/SwiftUI with an AppKit menu-bar interface and Core Audio device discovery. An explicitly installed BlackHole virtual device supplies the selected input; use a documented Core Audio/AVAudioEngine route and Audio Unit EQ/gain stages to the selected physical output. Codable preset and device-choice settings only; no audio recordings or captured-content history.
- Scope boundary: A bundled driver, universal low latency and seamless OS-version compatibility are not promised.

## Stack and architecture
- Swift/SwiftUI with an AppKit menu-bar interface and Core Audio device discovery.
- An explicitly installed BlackHole virtual device supplies the selected input; use a documented Core Audio/AVAudioEngine route and Audio Unit EQ/gain stages to the selected physical output.
- Codable preset and device-choice settings only; no audio recordings or captured-content history.
- Domain model: audio device IDs, sample-rate configurations, EQ bands, gain stages, bypass state and presets

## Security and data integrity
- Request capture permissions explicitly, show the selected input/output and reject a route that feeds its output back into its input. Bound gain, use a safe limiter/bypass strategy and keep audio ephemeral without recording or telemetry.
- Correctness boundary: The audio callback cannot allocate or block; feedback loops are rejected and device loss restores a safe audible route when possible.
- Preflight device availability and sample-rate compatibility, keep real-time callbacks allocation-free/nonblocking and ramp gain changes. On device loss, stop the processing route and offer the documented physical-output restore path rather than generating silence without explanation.
- Export/import EQ presets and device preferences only. Retain a known-safe bypass setting and document how to restore the OS output device independently if the app crashes; do not save or export captured audio.

## Agent implementation rules
- Project rule — data model: audio device IDs, sample-rate configurations, EQ bands, gain stages, bypass state and presets
- Project rule — preserve this invariant: The audio callback cannot allocate or block; feedback loops are rejected and device loss restores a safe audible route when possible.
- Project rule — acceptance evidence: Unplug the chosen output and display recovery controls; switching presets ramps gain without an abrupt spike and bypass restores the original signal.

## Optional agent skills and references
- Optional external skill: [swiftui-expert-skill](https://github.com/AvdLee/SwiftUI-Agent-Skill/blob/main/skills/swiftui-expert-skill/SKILL.md) — Build and review native SwiftUI views, state management, navigation, accessibility and rendering performance. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
- Optional external skill: [swift-concurrency](https://github.com/AvdLee/Swift-Concurrency-Agent-Skill/blob/main/skills/swift-concurrency/SKILL.md) — Design Swift async tasks, actors, isolation, cancellation and safe data sharing, including Swift 6 migration. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
- Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.

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 the actual eqMac-inspired workflow with owned or clearly labeled sample data: Route audio through an explicitly installed virtual device, apply a bounded EQ/gain chain and offer immediate bypass to the physical output. Add a spectrum view only after stable processing and device switching.
- Publish a reproducible walkthrough with this observable result: Unplug the chosen output and display recovery controls; switching presets ramps gain without an abrupt spike and bypass restores the original signal.
- Explain who can operate this scoped tool, its setup and ongoing costs, and these remaining product gaps: A bundled driver, universal low latency and seamless OS-version compatibility are not promised. Avoid guaranteed savings, performance scores or implied endorsement.

## Engineering roadmap
1. Phase 1 — Scope and fixtures. Implement this bounded workflow: Route audio through an explicitly installed virtual device, apply a bounded EQ/gain chain and offer immediate bypass to the physical output. Add a spectrum view only after stable processing and device switching. Record prerequisites, select representative user-owned fixtures and document the unsupported features: A bundled driver, universal low latency and seamless OS-version compatibility are not promised.
2. Phase 2 — Configure routing and preset state. Model device identifiers, sample-rate compatibility, band/gain values and bypass state. Persist only bounded presets and selected-device preferences; audio buffers remain ephemeral. Do not create a recorded-audio database or reimplement a virtual driver.
3. Phase 3 — Complete the first useful path. Implement the workflow's input, review and output interface, with clear controls and explicit empty/error states. Preflight device availability and sample-rate compatibility, keep real-time callbacks allocation-free/nonblocking and ramp gain changes. On device loss, stop the processing route and offer the documented physical-output restore path rather than generating silence without explanation.
4. Phase 4 — Permissions and integration failure. Request capture permissions explicitly, show the selected input/output and reject a route that feeds its output back into its input. Bound gain, use a safe limiter/bypass strategy and keep audio ephemeral without recording or telemetry. Request integration credentials and permissions only for the enabled feature; show a disconnected state instead of mock results.
5. Phase 5 — Portable handoff. Export/import EQ presets and device preferences only. Retain a known-safe bypass setting and document how to restore the OS output device independently if the app crashes; do not save or export captured audio. Include setup, operating limits, fixture walkthrough and shutdown/restart instructions in the README.
6. Phase 6 — Acceptance scenarios. Unplug the chosen output and display recovery controls; switching presets ramps gain without an abrupt spike and bypass restores the original signal. Repeat the workflow after restart and with a denied permission or unavailable dependency; show recoverable failure rather than a success placeholder.

## Paid-product capabilities outside this build
- A first-party, notarized audio driver: you are borrowing someone else's virtual device instead
- Automatic output-device following, so plugging in headphones means switching things by hand
- Very low latency and rock-solid handling of sample rate mismatches and hotplug events
- Extras like per-device presets, balance control, and a curated preset library
- Updates, crash fixes, and someone else's problem when a macOS point release breaks audio

## Implementation prompt
WORKING SLICE
Route audio through an explicitly installed virtual device, apply a bounded EQ/gain chain and offer immediate bypass to the physical output. Add a spectrum view only after stable processing and device switching.

Build this scoped eqMac-inspired workflow with a documented data model and visible failure states.

Architecture
- Swift/SwiftUI with an AppKit menu-bar interface and Core Audio device discovery.
- An explicitly installed BlackHole virtual device supplies the selected input; use a documented Core Audio/AVAudioEngine route and Audio Unit EQ/gain stages to the selected physical output.
- Codable preset and device-choice settings only; no audio recordings or captured-content history.

Prerequisites and limits
A Mac with Xcode, an installed supported BlackHole virtual audio device, a physical output and any required audio-capture permissions. Document manual routing, compatible sample rates, a safe bypass/restore path and the added latency; the app does not ship its own driver.
Outside this release: A bundled driver, universal low latency and seamless OS-version compatibility are not promised.

Data model and correctness
audio device IDs, sample-rate configurations, EQ bands, gain stages, bypass state and presets
Invariant: The audio callback cannot allocate or block; feedback loops are rejected and device loss restores a safe audible route when possible.
Preflight device availability and sample-rate compatibility, keep real-time callbacks allocation-free/nonblocking and ramp gain changes. On device loss, stop the processing route and offer the documented physical-output restore path rather than generating silence without explanation.

Security and privacy
Request capture permissions explicitly, show the selected input/output and reject a route that feeds its output back into its input. Bound gain, use a safe limiter/bypass strategy and keep audio ephemeral without recording or telemetry.

Recovery and export
Export/import EQ presets and device preferences only. Retain a known-safe bypass setting and document how to restore the OS output device independently if the app crashes; do not save or export captured audio.

Implementation order
1. Phase 1 — Scope and fixtures. Implement this bounded workflow: Route audio through an explicitly installed virtual device, apply a bounded EQ/gain chain and offer immediate bypass to the physical output. Add a spectrum view only after stable processing and device switching. Record prerequisites, select representative user-owned fixtures and document the unsupported features: A bundled driver, universal low latency and seamless OS-version compatibility are not promised.
2. Phase 2 — Configure routing and preset state. Model device identifiers, sample-rate compatibility, band/gain values and bypass state. Persist only bounded presets and selected-device preferences; audio buffers remain ephemeral. Do not create a recorded-audio database or reimplement a virtual driver.
3. Phase 3 — Complete the first useful path. Implement the workflow's input, review and output interface, with clear controls and explicit empty/error states. Preflight device availability and sample-rate compatibility, keep real-time callbacks allocation-free/nonblocking and ramp gain changes. On device loss, stop the processing route and offer the documented physical-output restore path rather than generating silence without explanation.
4. Phase 4 — Permissions and integration failure. Request capture permissions explicitly, show the selected input/output and reject a route that feeds its output back into its input. Bound gain, use a safe limiter/bypass strategy and keep audio ephemeral without recording or telemetry. Request integration credentials and permissions only for the enabled feature; show a disconnected state instead of mock results.
5. Phase 5 — Portable handoff. Export/import EQ presets and device preferences only. Retain a known-safe bypass setting and document how to restore the OS output device independently if the app crashes; do not save or export captured audio. Include setup, operating limits, fixture walkthrough and shutdown/restart instructions in the README.
6. Phase 6 — Acceptance scenarios. Unplug the chosen output and display recovery controls; switching presets ramps gain without an abrupt spike and bypass restores the original signal. Repeat the workflow after restart and with a denied permission or unavailable dependency; show recoverable failure rather than a success placeholder.

Acceptance
Unplug the chosen output and display recovery controls; switching presets ramps gain without an abrupt spike and bypass restores the original signal.
Use real source data or clearly labeled fixtures. Explain unsupported input and provider failures; do not fabricate analytics, delivery receipts, accuracy claims or security guarantees.

Optional agent guidance
Optional external skill: [swiftui-expert-skill](https://github.com/AvdLee/SwiftUI-Agent-Skill/blob/main/skills/swiftui-expert-skill/SKILL.md) — Build and review native SwiftUI views, state management, navigation, accessibility and rendering performance. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Optional external skill: [swift-concurrency](https://github.com/AvdLee/Swift-Concurrency-Agent-Skill/blob/main/skills/swift-concurrency/SKILL.md) — Design Swift async tasks, actors, isolation, cancellation and safe data sharing, including Swift 6 migration. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Optional external skill: [sharp-edges](https://github.com/trailofbits/skills/blob/main/plugins/sharp-edges/skills/sharp-edges/SKILL.md) — Review security-sensitive APIs and configuration for dangerous defaults and easy-to-misuse interfaces. Review its instructions and compatibility before use; it does not grant deployment, data-access or publication permission.
Project rule — data model: audio device IDs, sample-rate configurations, EQ bands, gain stages, bypass state and presets
Project rule — preserve this invariant: The audio callback cannot allocate or block; feedback loops are rejected and device loss restores a safe audible route when possible.
Project rule — acceptance evidence: Unplug the chosen output and display recovery controls; switching presets ramps gain without an abrupt spike and bypass restores the original signal.

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