# AGENTS.md

## Project intent

Build a Windows-native, diagnostics-first recording application MVP with a high-performance C++ engine and a Qt 6 + Qt Widgets user interface.

## Canonical product decisions

Product decisions (defaults, navigation, audio/video model, container/codec rules) are **not
duplicated here** to avoid the two drifting apart. `CLAUDE.md` and `docs/product-spec.md` are the
single authoritative source for user-visible product behavior — read them before any change that
could be visible to a user. This file only adds constraints on *how* agents implement that
behavior, not *what* the behavior is:

- UI must not duplicate track resolution logic. It submits editable source rows; the engine
  returns resolved tracks.
- When switching containers, the selected audio codec must be reconciled to a valid codec for the
  new container; reconciliation is engine logic, never duplicated in the UI.
- If a hotkey starts recording while the app window is visible, activate the Record view. If
  minimized, do not restore the window.

## Architectural rules

- Keep the recording engine independent from UI concerns.
- Keep capture, encode, mux, diagnostics, telemetry, and UI responsibilities separate.
- Use structured data models rather than ad hoc UI-bound state.
- Prefer explicit state machines for recording session lifecycle.
- Every live metric must have:
  - source
  - meaning
  - update cadence
  - UI consumer
  - log consumer
- Prefer isolated capability probes before production integration.
- Do not optimize speculatively; add profiling hooks and measure.

## Documentation rules

- Update specs when product behavior changes.
- Add an ADR for any cross-cutting architectural decision.
- Each milestone must end with:
  - implementation notes
  - tests
  - doc updates
  - explicit unresolved issues, if any

## Agent workflow

- Opus owns architecture, product decisions, cross-cutting reviews, and final approval.
- Sonnet implements substantial bounded features from approved specs.
- Codex handles repo bootstrap, mechanical work, tests, refactors, build fixes, and explicit task lists.
- No agent should silently expand MVP scope.

## Fast Iteration Policy

This policy applies to all future ExoSnap agent sessions.

### Scope

- Normal feature slices target 30-60 minutes.
- Keep each slice to one subsystem.
- Do not broaden scope without a blocking technical need.
- Record minor P2/polish findings for consolidated review instead of fixing everything immediately.

### Agent use

- Do not launch multiple Explore agents when direct repository inspection is sufficient.
- Use at most one architecture/exploration pass for normal slices.
- Use workers only for meaningful, clearly separated packages.
- Run independent workers in parallel worktrees only when their file ownership is disjoint.
- Never let workers concurrently edit high-churn files such as:
  - `MainWindow.cpp`
  - `RecordPage.cpp`
  - `ConfigPage.cpp`
  - shared stores/view models
  - shared CMake files

### Development validation

During implementation, workers should use the smallest sufficient validation:

1. Build only the affected target.
2. Run focused tests for the changed subsystem.
3. Do not run full Debug builds, full CTest, quality suite, and Release build after every worker or edit cycle.

Canonical principle: `Minimal validation during development; complete validation once at the final gate.`

### Running tests

`scripts/run-tests.ps1` is the standard entry point for running the suite — use
it instead of invoking `ctest` directly. It sets the required environment (a
throwaway `EXOSNAP_CONFIG_DIR`, `QT_QPA_PLATFORM=offscreen`, `QT_PLUGIN_PATH`, Qt
on `PATH`), writes the full log to `<BuildDir>/Testing/last-run.log`, and prints
only a compact summary plus the exact failing gtest cases.

- Whole suite: `pwsh scripts/run-tests.ps1`
- Focused: `pwsh scripts/run-tests.ps1 -Filter <regex>` (matches test **binary**
  names, e.g. `recorder_core.` — each CTest entry is one binary, not one gtest
  case; gtest_main runs all cases in-process and still prints the exact failing
  `Suite.Case`).
- No-GPU host: `pwsh scripts/run-tests.ps1 -ExcludeLabel live` skips binaries
  that issue real hardware queries (DXGI adapter enumeration, GPU capability
  probes).
- Build first: add `-Build` to do a full build before testing.

### Final validation

Run once after the integrated branch is complete:

- format check
- `git diff --check`
- full Debug build
- focused tests if still useful
- full CTest
- quality/static checks once
- Release build only at the final gate or when Release-specific behavior is in scope

Do not invoke `check-quality.ps1` after already running the same complete configure/build/test sequence unless the script provides additional required checks that cannot be invoked separately. Prefer invoking only the missing static-analysis step when possible.

### Test and visual budgets

For a normal feature slice:

- approximately 5-15 targeted new tests
- approximately 2-4 Visual Harness scenarios
- no exhaustive matrix unless the feature is inherently high-risk
- no fragile physical-device or multi-step external automation

### Acceptance

- Green automated tests and clean deterministic visual scenarios are sufficient for implementation waves.
- Physical hardware checks and broad visual/product review are deferred to consolidated final review rounds.
- One or two documented minor limitations do not block merge when core behavior is correct.