Scaffold C++20 screencast project with Meson, agent workflow, and phase plan
This commit is contained in:
@@ -0,0 +1,264 @@
|
||||
# AGENTS.md — Screencast (Linux) Agent Workflow
|
||||
|
||||
This document governs how Zed agents work in the `screen_cast` project. It is mandatory reading before any non-trivial implementation task.
|
||||
|
||||
## Agent memory
|
||||
|
||||
Before starting work in a new agent conversation:
|
||||
|
||||
- read this `AGENTS.md`;
|
||||
- read the `agent-memory/SKILL.md` skill;
|
||||
- read `.agents/MEMORY.md` for the current project handoff;
|
||||
- read `docs/PHASES.md` to understand the current phase and milestones;
|
||||
- read any domain-specific `RUNBOOK.md` relevant to the task (e.g.
|
||||
`docs/RUNBOOK.md` or `docs/multimedia/RUNBOOK.md`).
|
||||
|
||||
Update `.agents/MEMORY.md` when the task produces significant state, blockers,
|
||||
or decisions. Update the relevant `RUNBOOK.md` when the task reveals reusable
|
||||
operational observations. Update `docs/PHASES.md` when a phase is completed or
|
||||
its plan changes.
|
||||
|
||||
## Skills
|
||||
|
||||
Skills are task-specific instructions and must be read before planning work.
|
||||
|
||||
Before producing a plan, identify all skills applicable to the task and read
|
||||
their `SKILL.md` files.
|
||||
|
||||
Skills are self-contained directories under `.agents/skills/`.
|
||||
|
||||
When a skill is selected, read its `SKILL.md` and consult any relevant
|
||||
documentation under that skill's `references/` directory.
|
||||
|
||||
Skills are task-specific guidance, not a replacement for the mandatory project
|
||||
workflow in this file. The agent must follow `AGENTS.md` even when no skill
|
||||
applies.
|
||||
|
||||
### Skill selection
|
||||
|
||||
- C++ project, Meson build, dependencies, or toolchain issues:
|
||||
`cpp-meson-build/SKILL.md`
|
||||
- Linux screen/audio capture, PipeWire, xdg-desktop-portal, FFmpeg, VAAPI, or
|
||||
codec work:
|
||||
`linux-multimedia-capture/SKILL.md`
|
||||
- RTP/UDP networking, transport, signaling, NAT traversal, or encryption:
|
||||
`rtp-networking/SKILL.md`
|
||||
- Overall screencast application architecture, sender/receiver modes,
|
||||
protocol negotiation, or integration decisions:
|
||||
`screencast-app/SKILL.md`
|
||||
|
||||
Multiple skills may apply. Read all applicable ones.
|
||||
|
||||
For example, implementing sender-side capture + encode will normally require:
|
||||
|
||||
1. `cpp-meson-build/SKILL.md`
|
||||
2. `linux-multimedia-capture/SKILL.md`
|
||||
3. `screencast-app/SKILL.md`
|
||||
|
||||
A networking change will normally require:
|
||||
|
||||
1. `cpp-meson-build/SKILL.md`
|
||||
2. `rtp-networking/SKILL.md`
|
||||
3. `screencast-app/SKILL.md`
|
||||
|
||||
Do not assume that a skill is applicable merely because its subject is mentioned
|
||||
incidentally. Use the task's actual scope to determine applicability.
|
||||
|
||||
## Mandatory development workflow
|
||||
|
||||
All non-trivial implementation tasks follow this workflow:
|
||||
|
||||
### 1. Understand
|
||||
|
||||
Before changing anything:
|
||||
|
||||
- read `AGENTS.md`;
|
||||
- read all applicable skills;
|
||||
- inspect the existing implementation and directory structure;
|
||||
- search the project for related symbols, build rules, and tests;
|
||||
- identify system dependencies (pkg-config names, headers, runtime packages);
|
||||
- identify dependencies and integration points.
|
||||
|
||||
Do not modify files during this phase.
|
||||
|
||||
### Plan against the phase roadmap
|
||||
|
||||
- `docs/PHASES.md` defines the project milestones and the current active phase.
|
||||
- **Do not start implementation that belongs to a later phase** unless the user
|
||||
explicitly asks for it or the current phase is already complete and
|
||||
validated.
|
||||
- When planning work, identify which phase(s) the task touches and include that
|
||||
in the implementation plan.
|
||||
- Update `docs/PHASES.md` when a phase is finished, blocked, or its scope
|
||||
changes; update `.agents/MEMORY.md` at the same time.
|
||||
|
||||
### 2. Plan
|
||||
|
||||
Produce a concise implementation plan containing:
|
||||
|
||||
- understanding of the requirement;
|
||||
- relevant existing project functionality;
|
||||
- files/components likely to change;
|
||||
- proposed implementation;
|
||||
- build/dependency implications;
|
||||
- tests to add or modify;
|
||||
- multimedia/networking/security considerations;
|
||||
- potential risks or unresolved questions.
|
||||
|
||||
### 3. Wait for approval
|
||||
|
||||
**STOP after presenting the plan.**
|
||||
|
||||
Do not create, modify, delete, or rename files until the user explicitly
|
||||
approves the plan.
|
||||
|
||||
Questions and clarification are allowed during this phase.
|
||||
|
||||
### 4. Implement
|
||||
|
||||
After approval:
|
||||
|
||||
- implement the approved plan;
|
||||
- prefer existing project modules and standard library functionality;
|
||||
- keep the change as small and focused as practical;
|
||||
- do not introduce unrelated refactoring;
|
||||
- follow the C++ and project conventions described in this file and in skills.
|
||||
|
||||
If implementation reveals that the approved plan is materially wrong or
|
||||
incomplete, stop and explain the discrepancy rather than silently expanding
|
||||
scope.
|
||||
|
||||
### 5. Validate
|
||||
|
||||
Run appropriate tests and checks.
|
||||
|
||||
At minimum:
|
||||
|
||||
- the project must still configure with Meson (`meson setup build`);
|
||||
- the project must still compile (`ninja -C build`);
|
||||
- unit/integration tests pass (`meson test -C build --print-errorlogs`);
|
||||
- static analysis or formatting checks configured in the project;
|
||||
- manual smoke test of the affected component where automated tests are
|
||||
insufficient.
|
||||
|
||||
For multimedia or networking changes, validate runtime behavior on an actual
|
||||
Linux desktop session (Wayland or X11) when feasible.
|
||||
|
||||
### 6. Review
|
||||
|
||||
Before considering the task complete, review the resulting changes for:
|
||||
|
||||
- correctness;
|
||||
- integration with existing modules;
|
||||
- reuse of existing functionality;
|
||||
- maintainability (small headers, clear ownership, RAII);
|
||||
- security (buffer handling, bounds checks, no secrets committed);
|
||||
- thread safety and async I/O correctness;
|
||||
- regression risk;
|
||||
- build/dependency impact.
|
||||
|
||||
## Verify before assuming
|
||||
|
||||
Never invent or assume the existence of an API.
|
||||
|
||||
Before using a:
|
||||
|
||||
- system library or package;
|
||||
- header file or symbol;
|
||||
- class, function, or macro;
|
||||
- build option or pkg-config name;
|
||||
- external protocol or service;
|
||||
|
||||
verify that it exists in the current environment, project dependencies, or a
|
||||
reliable source (distribution package index, upstream API docs, local header).
|
||||
|
||||
Do not infer existence from naming conventions, training knowledge, or
|
||||
similarly named components. If existence cannot be verified, stop and report the
|
||||
uncertainty.
|
||||
|
||||
In particular, never add a dependency merely because it would be a plausible
|
||||
package name.
|
||||
|
||||
## Prefer framework and standard functionality
|
||||
|
||||
Before implementing custom functionality, search the project and the C++
|
||||
standard library for an existing mechanism.
|
||||
|
||||
Prefer, in order:
|
||||
|
||||
1. existing project functionality that already satisfies the requirement;
|
||||
2. C++ standard library facilities (`std::`, `<format>`, `<chrono>`, etc.);
|
||||
3. widely adopted third-party libraries already used by the project;
|
||||
4. a small project-specific implementation only when the above are insufficient.
|
||||
|
||||
Do not duplicate functionality merely because implementing it locally appears
|
||||
simpler.
|
||||
|
||||
When choosing a custom implementation over an existing mechanism, explain the
|
||||
reason in the plan.
|
||||
|
||||
## Git
|
||||
|
||||
- Keep commits focused and logically coherent.
|
||||
- Prefer one component or one phase per commit where practical.
|
||||
- Do not mix unrelated changes.
|
||||
- Review the staged diff before committing.
|
||||
- Never commit secrets, credentials, local configuration, or generated build
|
||||
artifacts.
|
||||
- Do not create a commit unless the user explicitly asks for one or the task
|
||||
explicitly requires it.
|
||||
- When committing, write concise, descriptive messages in imperative mood.
|
||||
|
||||
## Coding conventions
|
||||
|
||||
### Language baseline
|
||||
|
||||
- C++20 is mandatory. The project must compile with `-std=c++20` and all
|
||||
source must use C++20 idioms.
|
||||
- Prefer standard library facilities over hand-written alternatives.
|
||||
- No C-style constructs when a modern C++ equivalent exists.
|
||||
|
||||
### Modern C++ guidelines
|
||||
|
||||
- **Ownership**: use `std::unique_ptr` and `std::shared_ptr`; never use 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.
|
||||
- **References and views**: use `std::span<T>` for non-owning contiguous data
|
||||
and `std::string_view` for read-only strings.
|
||||
- **Compile-time computation**: prefer `constexpr`, `consteval`, and
|
||||
`std::integral_constant` where applicable.
|
||||
- **Type safety**: use `enum class`, `std::variant`, and `std::optional`
|
||||
instead of bare integers or bool flags.
|
||||
- **Concurrency**: prefer `std::jthread`, `std::stop_token`, and standard
|
||||
synchronization primitives. Avoid manual thread lifecycle management.
|
||||
- **Containers**: use `std::vector`, `std::array`, `std::deque`, and standard
|
||||
containers; avoid C arrays and raw buffers.
|
||||
- **Formatting and time**: use `<format>` / `std::format` and `<chrono>` instead
|
||||
of `printf`, `sprintf`, or manual time math.
|
||||
- **Algorithms**: prefer `std::ranges` algorithms over hand-rolled loops
|
||||
where clarity improves.
|
||||
- **Lambdas and callable abstractions**: use `std::function` sparingly; prefer
|
||||
function pointers, templates, or `auto` parameters for simple callbacks.
|
||||
- **Concepts and constraints**: use `requires` clauses or `std::concepts` to
|
||||
express interface contracts where beneficial.
|
||||
|
||||
### Style
|
||||
|
||||
- Use `namespace sc` for all project code.
|
||||
- Prefer `snake_case` for functions and variables, `PascalCase` for types,
|
||||
`SCREAMING_SNAKE_CASE` for constants.
|
||||
- Keep headers minimal and free of unnecessary includes; forward-declare where
|
||||
possible.
|
||||
- Format code with the configured formatter (`clang-format` if available).
|
||||
|
||||
### Error handling
|
||||
|
||||
- Use explicit error handling. Prefer `std::expected`, `std::optional`, or
|
||||
`std::error_code` over exceptions for recoverable errors.
|
||||
- Use RAII for resource cleanup; do not leave resources unreleased on error
|
||||
paths.
|
||||
- Avoid `assert` for user-facing error conditions; use real error returns or
|
||||
logging.
|
||||
Reference in New Issue
Block a user