From c668850cb2e4aa4ce69f3c2b6d6e1696f1107ebe Mon Sep 17 00:00:00 2001 From: Herbert Wolverson Date: Sun, 14 Jun 2026 15:39:00 -0500 Subject: [PATCH] Update local workflow skills --- .agents/skills/libreqos-git-workflow/SKILL.md | 36 +++++++++++++++++++ .../skills/libreqos-rust-workflow/SKILL.md | 9 +++++ 2 files changed, 45 insertions(+) create mode 100644 .agents/skills/libreqos-git-workflow/SKILL.md diff --git a/.agents/skills/libreqos-git-workflow/SKILL.md b/.agents/skills/libreqos-git-workflow/SKILL.md new file mode 100644 index 00000000..d975118a --- /dev/null +++ b/.agents/skills/libreqos-git-workflow/SKILL.md @@ -0,0 +1,36 @@ +--- +name: libreqos-git-workflow +description: Shared LibreQoS git workflow. Use when committing, organizing commit history, preparing larger PRs, or deciding how to split changes for review. +--- + +# LibreQoS Git Workflow + +Use this skill when creating commits or preparing a PR in this repo. + +## Commit Strategy + +- For small changes, a single focused commit is fine. +- For larger PRs, prefer multiple focused commits that tell a clear narrative for the reviewer. +- Each commit should represent one understandable step: setup, mechanical move, behavior change, tests, docs, or cleanup. +- Write commit messages that explain why the step exists, not just which files changed. +- Avoid mixing unrelated fixes, formatting churn, generated artifacts, and behavior changes in the same commit. +- Keep commits reviewable on their own whenever practical, but do not add compatibility scaffolding only to make an intermediate commit independently shippable. + +## Before Committing + +- Inspect `git status`, `git diff`, and `git log --oneline -10`. +- Stage only intended files. Leave unrelated user or generated changes untouched. +- Run the targeted validation required by the changed area before the commit when practical. +- If validation was skipped or could not run, say that explicitly in the final user-facing summary. + +## Larger PR Narrative + +- Order commits so the reviewer can follow the work without jumping between concepts. +- Put broad mechanical changes before behavior changes when that reduces review noise. +- Put tests close to the behavior they validate unless the repo convention prefers a separate test commit. +- Use docs commits where they help operators or reviewers understand the visible behavior change. + +## Notes + +- Do not amend, squash, rebase, force-push, or rewrite history unless the user explicitly asks. +- Do not commit secrets, local runtime artifacts, screenshots, logs, or unrelated untracked files. diff --git a/.agents/skills/libreqos-rust-workflow/SKILL.md b/.agents/skills/libreqos-rust-workflow/SKILL.md index 6f489d2a..262bc6f6 100644 --- a/.agents/skills/libreqos-rust-workflow/SKILL.md +++ b/.agents/skills/libreqos-rust-workflow/SKILL.md @@ -70,6 +70,15 @@ Use this skill for Rust work in this repo. - Keep RustDoc current for changed public items and note side effects for non-pure functions. - Avoid allocation in hot paths. +## Async And Tokio + +- Treat async code as latency-sensitive shared execution. Do not add blocking work to a Tokio task without checking the impact on the runtime. +- Review every synchronous call made from an async context for blocking potential, including filesystem I/O, process spawning, DNS/network clients, compression, parsing of large inputs, CPU-heavy loops, mutex contention, and sleep/wait calls. +- Use async APIs when they exist and fit the surrounding code. +- Use `tokio::task::spawn_blocking` for unavoidable blocking or CPU-heavy work called from async code, and keep the closure narrow so ownership, cancellation behavior, and error handling stay obvious. +- Do not hold async locks, runtime handles, or request-scoped borrows across `spawn_blocking` boundaries unless the ownership and lifetime implications are explicit and safe. +- Prefer `tokio::sync` primitives inside async tasks. Use blocking locks only when there is a clear reason and no `.await` can occur while the guard is held. + ## Notes - Existing code does not fully match all preferred conventions yet. Treat these as direction for new and touched code, not as a reason to perform unrelated cleanup.