Scaffold C++20 screencast project with Meson, agent workflow, and phase plan

.agents/skills/cpp-meson-build/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: cpp-meson-build
+description: |
+  Guidelines for C++20 development and Meson build management in the
+  screen_cast project. Read before changing source files, build files,
+  dependencies, or toolchain configuration.
+disable-model-invocation: false
+---
+
+# cpp-meson-build
+
+Guidelines for C++20 development and Meson build management in the `screen_cast`
+project.
+
+## Scope
+
+Use this skill for:
+
+- Adding or changing C++ source files, headers, or namespaces.
+- Modifying `meson.build` files, compiler flags, or targets.
+- Adding or updating dependencies (system libraries, pkg-config, subprojects).
+- Toolchain, sanitizer, static-analysis, or formatter configuration.
+
+## Meson conventions
+
+- Keep `meson.build` files declarative and readable.
+- Prefer `dependency()` with `pkg-config` names over manual `-l` flags.
+- Pin required C++ standard: `cpp_std = 'c++20'`.
+- Put one target per `meson.build` file where practical.
+- Use `include_directories('include')` for the public API headers.
+- Declare unit tests with `test()` and keep them deterministic.
+
+## Dependency verification
+
+Before adding a new dependency:
+
+- verify the pkg-config file exists on the target system (e.g.
+  `pkg-config --exists libavcodec`);
+- check that the required headers compile;
+- update `meson.build` and this skill's `references/` if needed.
+
+## Error handling
+
+- Prefer `std::expected<T,E>`, `std::optional<T>`, or `std::error_code` over
+  exceptions for recoverable failures.
+- Use RAII wrappers; avoid raw owning pointers.
+- Keep headers minimal and forward-declare where possible.
+
+## Modern C++ guidelines
+
+All project code must use C++20 idioms:
+
+- **Ownership**: use `std::unique_ptr` and `std::shared_ptr`; no raw `new`/`delete`
+  or raw owning pointers.
+- **Optional values**: use `std::optional<T>` instead of sentinel values or
+  out-parameters.
+- **Fallible operations**: use `std::expected<T,E>` or `std::error_code` for
+  recoverable errors; avoid exceptions for control flow.
+- **Views**: use `std::span<T>` for non-owning buffers and `std::string_view`
+  for read-only strings.
+- **Compile-time**: prefer `constexpr`/`consteval` where possible.
+- **Type safety**: prefer `enum class`, `std::variant`, and `std::optional`
+  over bare integers or bool flags.
+- **Concurrency**: prefer `std::jthread`, `std::stop_token`, and standard
+  synchronization primitives.
+- **Containers**: use standard containers; avoid C arrays and raw buffers.
+- **Formatting/time**: use `<format>` / `std::format` and `<chrono>`.
+- **Algorithms**: prefer `std::ranges` over hand-rolled loops where it
+  improves clarity.
+- **Callables**: avoid `std::function` unless type erasure is required.
+- **Concepts**: use `requires` clauses to express interface contracts where
+  beneficial.
+
+Reject C-style patterns (`printf`, `sprintf`, manual memory management with
+`malloc`/`free`, raw arrays) when a standard-library equivalent exists.
+
+## Useful commands
+
+```sh
+meson setup build
+meson compile -C build
+meson test -C build --print-errorlogs
+meson configure build
+```
+
+## References
+
+- `meson.build` (project root)
+- `meson_options.txt` (if present)
+- `docs/ARCHITECTURE.md`
+- `docs/PHASES.md`