initial draft of agent files

AGENTS.md

@@ -0,0 +1,81 @@
+# AGENTS.md — Mixxx Project Instructions
+
+Mixxx is a free, open-source DJ application. C++17/Qt 6, JavaScript for
+controller mappings, CMake build system. GPL v2+.
+
+## Build
+
+```bash
+cd cbuild
+cmake -DCMAKE_BUILD_TYPE=Debug -DDEBUG_ASSERTIONS_FATAL=ON -DCMAKE_EXPORT_COMPILE_COMMANDS=ON ..
+cmake --build . --parallel $(nproc)
+ctest  # run tests (Google Test)
+```
+
+## Code Style
+
+- **Formatting**: `.clang-format` (Google base, 4-space indent, 8-space continuation). Run `pre-commit` or `python tools/clang_format.py`. Only format new/modified code — never mass-reformat.
+- **Separate formatting commits** from logic commits.
+- **Pre-commit hooks** enforce clang-format, ESLint, codespell, markdownlint, gersemi, etc. Install with `pre-commit install && pre-commit install -t pre-push`.
+
+### C++ Conventions
+
+- 4 spaces, never tabs. 100-col hard limit, 80-col soft limit.
+- Classes: `CamelCase`. Methods: `camelBack()`. Members: `m_prefix`. Pointers: `pPrefix`. Constants: `kPascalCase`. Enums: `enum class CamelCase`.
+- CO/setting keys: `snake_case`.
+- K&R braces. Always braces on control flow bodies.
+- `#pragma once`, not include guards.
+- Include order: matching header → system → Qt → library deps → Mixxx local → forward decls. Alphabetical within groups.
+- No naked `new`/`delete` — use `std::make_unique`, `std::make_shared`, or `make_parented`.
+- `VERIFY_OR_DEBUG_ASSERT(cond) { recovery; }` for defensive checks.
+- `override` on all virtual overrides; omit redundant `virtual`.
+- `QStringLiteral("...")` for string literals.
+- tr("...") for strings that will need translation.
+- No `goto`. No `Q_UNUSED` (use unnamed params instead). No C-style enums.
+- `///` doc comments in headers. `// TODO(username)` or `// TODO(issue URL)` for TODOs.
+- Wrap new code in `namespace mixxx {}`. Anonymous namespace for file-local helpers in .cpp.
+- Non-const ref out-params: use pointers, not references (legacy convention).
+- Lambdas: use carefully — they get extra review scrutiny for lifetime/control-flow issues.
+
+### JavaScript (Controller Mappings)
+
+- Scripts in `res/controllers/`. ESLint enforced (`eslint.config.cjs`).
+- Use Components JS library and JSDoc comments.
+
+### QML
+
+- `res/qml/` and `src/qml/`. `qmlformat`/`qmllint` available via pre-commit.
+
+## Git & PR Workflow
+
+- One branch per feature/bugfix. Every commit must build.
+- Small commits. Imperative commit messages, 72-char wrap, describe what + why.
+- Bug fixes → stable branch (e.g. `2.5`). Features → `main`.
+- Don't rebase without reviewer agreement. Use `--fixup` commits, only squash before merge if requested.
+- Post before/after screenshots for GUI changes.
+- Keep PRs focused — no unrelated formatting, config, or refactoring changes mixed in.
+
+## Common Review Issues
+
+1. Pre-commit must pass before pushing.
+2. Use `std::chrono::duration` for time values.
+3. Use `Q_ENUM` + `QVariant::fromValue` instead of manual `static_cast<int>`.
+4. No `.DS_Store` or IDE files.
+5. Squash when asked; rebase onto the correct target branch.
+6. Document the "why" in commits and comments.
+7. SVG assets: full-size, borderless, matching existing conventions.
+
+## Key Architecture
+
+- **ControlObject/ControlProxy**: `[Group], key_name` inter-component communication.
+- **Engine thread**: Real-time audio — no allocations, no locks, no Qt signals.
+- **parented_ptr/make_parented**: Qt object-tree ownership. Object must get a parent before `parented_ptr` destructs.
+
+## Project Layout
+
+```text
+src/          C++ source (engine/, controllers/, library/, mixer/, effects/, qml/, preferences/, util/, test/)
+res/          Resources (controllers/ JS/XML, skins/, qml/)
+cmake/        CMake modules
+tools/        Python helper scripts
+```