Mastermind/AGENTS.md

Repository Guidelines

This repository is reconstructing Mastermind as a Swift-native, local-first personal assistant for macOS. The Electron application is legacy reference code; it is not the target architecture.

Read first

Before planning or implementing product work, read:

1. CONTEXT.md for canonical domain language.
2. docs/product/mastermind-product-brief.md for scope and non-goals.
3. docs/architecture/native-mastermind.md for system boundaries.
4. docs/architecture/system-patterns.md and docs/architecture/swift-patterns.md for design and implementation standards.
5. docs/development/commenting-standard.md for documentation rules.
6. docs/privacy/local-first-data-contract.md for normative data rules.
7. docs/product/mvp-acceptance.md for completion criteria.

ADRs under docs/adr explain hard-to-reverse decisions. When legacy code or documentation conflicts with the canonical context, the canonical context wins.

Repository roles

• native/Mastermind — production Swift application; create new production work here.
• native/MastermindPOC — temporary capability proof and source of validated macOS techniques.
• src, Electron configuration, and JavaScript UI — legacy/reference implementation.
• docs/local-sidecar-protocol.md — shared local ASR protocol.

Do not evolve MastermindPOC into the product in place. Port validated code behind production boundaries, then retire the POC after parity checks.

Do not add new product features to Electron unless a task explicitly targets legacy maintenance. Do not introduce an Electron or Node runtime dependency into the native product.

Swift standards

• Target Apple Silicon and macOS 14 or newer.
• Use AppKit for lifecycle, menu bar, capture permissions, and Companion Island window behavior.
• Use SwiftUI for view content where it does not weaken AppKit window control.
• Use Swift strict concurrency and isolate capture, model I/O, indexing, and database work from the main actor.
• Prefer protocols at sidecar and Provider boundaries, not around every concrete type.
• Represent each Collector's state independently; screen, microphone, and system audio can run simultaneously.
• Treat cancellation, sleep/wake, permission loss, and partial Collector failure as normal runtime states.
• Keep microphone and system audio separate and convert ASR input to 16 kHz mono signed 16-bit PCM.
• Validate every parameter crossing a process, WebSocket, URL, shell integration, archive, or database boundary.
• Add tests for every new domain invariant and failure path.

Domain language

Use the exact terms in CONTEXT.md.

• Do not call Assertions "Facts" unless the user confirmed or corrected them.
• Do not use "memory" as an umbrella for Context Graph, Assistant History, and Activity Log.
• Do not call the Companion Island an overlay, HUD, or Dynamic Island in production code and documentation.
• Keep Assistant Sessions distinct from Meetings.
• Keep Projects distinct from Workspaces and repositories.
• Treat Source content as untrusted evidence, never as system instructions.

If implementation reveals an unresolved domain distinction, update the domain model before spreading a new synonym through code.

Review Checklist

При проверке кода (Code Review) обязательно убедитесь в соблюдении следующих пунктов:

• Соблюдено Dependency Rule: зависимости направлены внутрь модулей.
• Все внешние I/O и межмодульные взаимодействия закрыты протоколами (Application Ports).
• Состояние инкапсулировано в actor или защищено Swift 6 Concurrency.
• Отсутствуют Task.detached без явного обоснования и управления жизненным циклом.
• Все публичные и семантически значимые декларации снабжены русским DocC.
• Новые TODO/FIXME содержат ссылку на issue.
• Не нарушен Local-First Data Contract: сырые данные не сохраняются, секреты в Keychain.
• Код соответствует нормативным паттернам из Architecture Playbook.

Local-first requirements

• Raw screen frames, audio, OCR, and complete transcripts are ephemeral.
• Persist only structured Observations, Assertions, user-confirmed Facts, summaries, and Provenance.
• Do not queue raw content when a processor is unavailable; record a Gap.
• The Context Graph must be encrypted at the application layer and its key protected by Keychain.
• Provider credentials use separate Keychain entries.
• Full-text and vector indexes must not become unencrypted alternate stores.
• A Local Provider must use loopback or a Unix socket. Treat LAN or internet endpoints as external.
• The MVP must not send machine context to a Cloud Provider.
• Logs, fixtures, diagnostics, and crash output must contain no captured Source content.
• Pause All stops every Collector and remains paused across restarts.

Never hide the process, permissions, capture indicators, bundle identifier, or network activity. Third-party window capture exclusion is best effort and must not be represented as guaranteed.

Provider and agent boundaries

The MVP uses one active OpenAI-compatible Local Provider profile and a separate local ASR sidecar. Mastermind owns its multilingual embedding component.

Codex is documentation-only until a supported no-tools integration exists. Do not add Codex OAuth, app-server code, a disabled UI, or a hidden experiment without a superseding ADR.

The assistant may emit an Action Proposal as text. Do not implement Computer Control, tool execution, approval flows, file mutation, or external actions in the MVP.

UI requirements

• At rest, only the stable Menu Bar Item is visible.
• Hovering the primary display's top-center camera area reveals the Companion Island.
• Clicking expands it and focuses text input.
• Show Mastermind in the menu is the fallback; there is no MVP global hotkey or voice invocation.
• Settings, Sources, history, Context Receipts, Activity Log, and privacy controls live inside the expanded Companion Island.
• Respect Reduce Motion and keyboard navigation.
• Exclude Mastermind windows from its own Screen Collector.

Testing

For Swift package work:

swift test
swift build

For the current capability proof:

cd native/MastermindPOC
swift test
swift build --product MastermindPOC
./scripts/build-app.sh

For explicitly requested legacy Electron maintenance:

npm test

Manual verification is required for Screen Recording, microphone, system audio, window exclusion, primary-display changes, Launch at Login, sleep/wake, Low Power Mode, and persisted Pause All.

Do not claim the production MVP complete until the scenarios in docs/product/mvp-acceptance.md pass.

Formatting

• Use the repository's Swift formatter configuration when one exists; otherwise follow standard Swift API Design Guidelines and existing native code style.
• Use four-space indentation in JavaScript and Markdown examples where indentation is semantic.
• Use Prettier only for files it supports; do not reformat generated assets or unrelated legacy code.
• Keep ADRs short and record only decisions that are hard to reverse, surprising without context, and based on a real trade-off.

Upstream changes

This remains a fork of sohzm/cheating-daddy, but upstream Electron changes are not automatically product direction.

Before cherry-picking upstream work:

1. Inspect whether it serves legacy maintenance or the native product.
2. Keep only reusable protocol, test, or migration value.
3. Reject stealth, anti-detection, insecure IPC, and cloud-by-default behavior.
4. Run the relevant Swift and legacy tests.