From cf9a671fb88ed51f9fe35f76674857c168c0dd6d Mon Sep 17 00:00:00 2001 From: alexion Date: Thu, 17 Sep 2026 09:56:58 -0400 Subject: [PATCH] feat(skills): add style review workflow --- .pi/prompts/review-nix.md | 31 -------------- .pi/prompts/review.md | 42 +++++++++++++++++++ .pi/skills/nix-style | 2 +- .pi/skills/rust-style | 1 + src/skills/AGENTS.md | 0 src/skills/README.md | 1 + src/skills/nix-style/SKILL.md | 34 --------------- .../{nix-style => style}/RULE-FORMAT.md | 0 src/skills/style/STYLE.md | 21 ++++++++++ src/skills/style/nix/SKILL.md | 18 ++++++++ .../{nix-style => style/nix}/rules/flake.md | 0 .../{nix-style => style/nix}/rules/let.md | 0 src/skills/style/rust/SKILL.md | 9 ++++ src/skills/style/rust/rules/build.md | 39 +++++++++++++++++ src/skills/style/rust/rules/files.md | 28 +++++++++++++ 15 files changed, 160 insertions(+), 66 deletions(-) delete mode 100644 .pi/prompts/review-nix.md create mode 100644 .pi/prompts/review.md create mode 120000 .pi/skills/rust-style delete mode 100644 src/skills/AGENTS.md delete mode 100644 src/skills/nix-style/SKILL.md rename src/skills/{nix-style => style}/RULE-FORMAT.md (100%) create mode 100644 src/skills/style/STYLE.md create mode 100644 src/skills/style/nix/SKILL.md rename src/skills/{nix-style => style/nix}/rules/flake.md (100%) rename src/skills/{nix-style => style/nix}/rules/let.md (100%) create mode 100644 src/skills/style/rust/SKILL.md create mode 100644 src/skills/style/rust/rules/build.md create mode 100644 src/skills/style/rust/rules/files.md diff --git a/.pi/prompts/review-nix.md b/.pi/prompts/review-nix.md deleted file mode 100644 index 7339187..0000000 --- a/.pi/prompts/review-nix.md +++ /dev/null @@ -1,31 +0,0 @@ ---- -description: Review Nix changes against repository Nix style rules -argument-hint: "[target]" ---- - -Use the `nix-style` skill. -Audit ${ARGUMENTS:-the staged diff} for violations of the repository Nix style rules. - -Report only actionable findings. -Order findings by severity. -Do not report preferences unless a loaded rule states them. - -Use this format for each finding: - -```text -`code-path:line` -> `smallest reviewed-code excerpt that shows the violation` - -`rule-file:line`: Finding title. -Summary: why the code breaks the rule -Fix: suggested fix -``` - -Keep the code excerpt to one to three lines when possible. -Use a longer excerpt only when the violation needs surrounding context. -Use `...` to omit unrelated lines from a multi-line excerpt. -Use a skill-relative rule citation, such as `let.md:7`. -Make the fix direct. -Do not include alternatives when one fix best follows the cited rule. - -It is acceptable to report no findings when the reviewed Nix already follows the loaded rules. diff --git a/.pi/prompts/review.md b/.pi/prompts/review.md new file mode 100644 index 0000000..d0e78c6 --- /dev/null +++ b/.pi/prompts/review.md @@ -0,0 +1,42 @@ +--- +description: Review changes against repository style rules +argument-hint: "[target]" +--- + +Review target: `${ARGUMENTS:-the staged diff}`. +Audit the target for violations of the repository style rules. + +Choose skills from the reviewed files: + +- Use the `nix-style` skill for `*.nix` files. +- Use the `rust-style` skill for `*.rs` files. +- Use the `rust-style` skill for `Cargo.toml` files. +- Use the `rust-style` skill for Bazel files that define Rust targets. + +If the target includes multiple matching file types, use all matching skills. +If the target is a diff, choose skills from the changed files. +Do not use a style skill when no reviewed file matches it. + +Report only actionable findings. +Order findings by severity. +Do not report preferences unless a loaded rule states them. + +Use this format for each finding: + +```text +`code-path:line` +> `smallest reviewed-code excerpt that shows the violation` + +`skill::rule-file:line`: Finding title. +Summary: why the code breaks the rule +Fix: suggested fix +``` + +Keep the code excerpt to one to three lines when possible. +Use a longer excerpt only when the violation needs surrounding context. +Use `...` to omit unrelated lines from a multi-line excerpt. +Use a style-skill rule citation, such as `rust::files.md:23` or `nix::let.md:7`. +Make the fix direct. +Do not include alternatives when one fix best follows the cited rule. + +It is acceptable to report no findings when the target follows the loaded rules. diff --git a/.pi/skills/nix-style b/.pi/skills/nix-style index 1622f88..cb71dea 120000 --- a/.pi/skills/nix-style +++ b/.pi/skills/nix-style @@ -1 +1 @@ -../../src/skills/nix-style \ No newline at end of file +../../src/skills/style/nix \ No newline at end of file diff --git a/.pi/skills/rust-style b/.pi/skills/rust-style new file mode 120000 index 0000000..b48fcfb --- /dev/null +++ b/.pi/skills/rust-style @@ -0,0 +1 @@ +../../src/skills/style/rust \ No newline at end of file diff --git a/src/skills/AGENTS.md b/src/skills/AGENTS.md deleted file mode 100644 index e69de29..0000000 diff --git a/src/skills/README.md b/src/skills/README.md index 75ed668..4c86489 100644 --- a/src/skills/README.md +++ b/src/skills/README.md @@ -6,6 +6,7 @@ This directory contains monorepo-owned agent skill sources. ```text src/skills/ Monorepo-owned skill sources +src/skills/// Grouped monorepo skill sources .pi/skills/ Monorepo-wide enabled Pi skill symlinks src//skills/ Project-owned skill sources src//.pi/skills/ Project-specific enabled Pi skill symlinks diff --git a/src/skills/nix-style/SKILL.md b/src/skills/nix-style/SKILL.md deleted file mode 100644 index e943686..0000000 --- a/src/skills/nix-style/SKILL.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -name: nix-style -description: Use when creating, editing, or reviewing Nix files in this repository. ---- - -# nix-style - -Use this skill as the source of truth for repository Nix conventions. - -## Load rules - -Read every Markdown file directly under [`rules/`](rules/) before applying this skill. -Resolve [`rules/`](rules/) relative to this `SKILL.md`. - -Finish when all discovered rule files have been read. - -## Apply rules - -Apply the loaded rules when editing or reviewing Nix files. -When loaded rules conflict, follow the most specific rule. - -After editing Nix files, run: - -```bash -nix run .#fix -``` - -Finish when `nix run .#fix` succeeds and the Nix change follows the loaded rules. -If the command fails, report the failure. - -## Maintain rules - -When adding or changing files under [`rules/`](rules/), read [`RULE-FORMAT.md`](RULE-FORMAT.md) first. -Finish when the changed rule files follow that format. diff --git a/src/skills/nix-style/RULE-FORMAT.md b/src/skills/style/RULE-FORMAT.md similarity index 100% rename from src/skills/nix-style/RULE-FORMAT.md rename to src/skills/style/RULE-FORMAT.md diff --git a/src/skills/style/STYLE.md b/src/skills/style/STYLE.md new file mode 100644 index 0000000..79a89d0 --- /dev/null +++ b/src/skills/style/STYLE.md @@ -0,0 +1,21 @@ +# Style skill instructions + +Use this document for skills that own repository style conventions. + +## Load rules + +Read every Markdown file directly under `rules/` before applying the skill. +Resolve `rules/` relative to the skill's `SKILL.md`. + +Finish when all discovered rule files have been read. + +## Apply rules + +Apply the loaded rules when editing or reviewing files covered by the skill. +When loaded rules conflict, follow the most specific rule. + + +## Maintain rules + +When adding or changing files under `rules/`, read `src/skills/style/RULE-FORMAT.md` first. +Finish when the changed rule files follow that format. diff --git a/src/skills/style/nix/SKILL.md b/src/skills/style/nix/SKILL.md new file mode 100644 index 0000000..cfcd9bd --- /dev/null +++ b/src/skills/style/nix/SKILL.md @@ -0,0 +1,18 @@ +--- +name: nix-style +description: Use when creating, editing, or reviewing Nix files in this repository. +--- + +# nix-style + +Use this skill as the source of truth for repository Nix conventions. +Follow the shared style skill instructions in `src/skills/style/STYLE.md`. + +After editing Nix files, run: + +```bash +nix run .#fix +``` + +Finish when `nix run .#fix` succeeds and the Nix change follows the loaded rules. +If the command fails, report the failure. diff --git a/src/skills/nix-style/rules/flake.md b/src/skills/style/nix/rules/flake.md similarity index 100% rename from src/skills/nix-style/rules/flake.md rename to src/skills/style/nix/rules/flake.md diff --git a/src/skills/nix-style/rules/let.md b/src/skills/style/nix/rules/let.md similarity index 100% rename from src/skills/nix-style/rules/let.md rename to src/skills/style/nix/rules/let.md diff --git a/src/skills/style/rust/SKILL.md b/src/skills/style/rust/SKILL.md new file mode 100644 index 0000000..f9dd09b --- /dev/null +++ b/src/skills/style/rust/SKILL.md @@ -0,0 +1,9 @@ +--- +name: rust-style +description: Use when creating, editing, or reviewing Rust files in this repository. +--- + +# rust-style + +Use this skill as the source of truth for repository Rust conventions. +Follow the shared style skill instructions in `src/skills/style/STYLE.md`. diff --git a/src/skills/style/rust/rules/build.md b/src/skills/style/rust/rules/build.md new file mode 100644 index 0000000..4ccf566 --- /dev/null +++ b/src/skills/style/rust/rules/build.md @@ -0,0 +1,39 @@ +# Build rules + +## Use workspace dependency versions + +### Rule + +Declare Rust dependency versions in the repository root `Cargo.toml` under `[workspace.dependencies]`. +Reference workspace dependencies from package `Cargo.toml` files with `workspace = true`. +Do not declare dependency versions in package `Cargo.toml` files unless the operator explicitly requests a package-local version. +Add package-local dependency features only when the feature set is specific to that package. + +### Rationale + +The repository has one Cargo workspace and one `Cargo.lock`. +Centralized dependency versions keep package manifests consistent with the workspace lockfile. + +## Declare Rust tests in Bazel + +### Rule + +Declare Rust test files in the nearest Bazel `BUILD` file with `rust_test`. +Do not add `[[test]]` entries to `Cargo.toml` unless the operator explicitly requests Cargo test declarations. + +### Rationale + +Bazel is the source of truth for Rust test targets in this repository. +Keeping test declarations in Bazel avoids duplicate test target lists. + +## Use one source input style per `rust_test` + +### Rule + +Do not set both `crate` and `srcs` on a `rust_test` target. +Use exactly one input style for each Rust test target. + +### Rationale + +`rules_rust` rejects `rust_test` targets that set both `crate` and `srcs`. +Keeping one input style per target makes the test declaration valid and unambiguous. diff --git a/src/skills/style/rust/rules/files.md b/src/skills/style/rust/rules/files.md new file mode 100644 index 0000000..283cd04 --- /dev/null +++ b/src/skills/style/rust/rules/files.md @@ -0,0 +1,28 @@ +# File rules + +## Avoid generic Rust file names + +### Rule + +Do not name Rust source files `lib.rs` or `main.rs`. +Name library crate root files after the crate they define. +Name binary crate root files after the binary they define, or use a `_main.rs` suffix. +Set explicit Cargo paths and Bazel `srcs` when needed. + +### Rationale + +Generic root names make file search results and review context less clear. +Descriptive file names show which crate or binary owns the code. + +## Keep Rust tests in separate files + +### Rule + +Put Rust tests in separate `*_test.rs` files. +Name each test file after the Rust source file or crate root that it tests. +Do not use generic test file names such as `lib_test.rs` or `main_test.rs`. +Do not add inline `#[cfg(test)]` modules. + +### Rationale + +Separate test files keep production modules focused and match the repository's Bazel test layout.