Skip to content

ekala-project/corepkgs / .agents/skills/best-practices

best-practices

Verified

Review a package expression for best-practices compliance. Use when reviewing PRs or auditing existing packages — checks meta completeness, build-system idioms (cmakeEntries, mesonEntries, pyproject), dependency placement, and packaging conventions.

Best Practices Review

Review a Nix package expression and report violations. Read the package file(s), then check every rule below. Report each finding with the line number and a short explanation.

Meta Attributes

Required Fields

Every package must have all three:

FieldWhat to check
meta.descriptionPresent, non-empty, does not repeat the package name verbatim
meta.licensePresent, uses lib.licenses.* (not a raw string)
meta.platformsPresent, uses lib.platforms.*

Recommended Fields

Flag as "recommended" (not error) if missing:

  • meta.homepage — upstream project URL
  • meta.mainProgram — for packages that install a binary

Forbidden Fields

Flag as error if present:

  • meta.maintainers or meta.teams — not a recognised key; fails check-meta

Build-System Idioms

CMake

  • If cmakeEntries, cmakeFlags, or cmakeBuildType are used, cmake.configurePhaseHook must be in nativeBuildInputs. (Some builds use cmake as a dependency without the configure phase hook — that is fine.)
  • Prefer cmakeEntries (attrset) over cmakeFlags (string list) for -D flags. Flag cmakeFlags with -D entries as "prefer cmakeEntries".

Meson

  • If mesonEntries, mesonFlags, or mesonFeatures are used, meson.configurePhaseHook must be in nativeBuildInputs.
  • ninja must be in nativeBuildInputs when meson.configurePhaseHook is present.
  • Prefer mesonEntries over mesonFlags for -D options. Flag mesonFlags with -D entries as "prefer mesonEntries".
  • Prefer mesonFeatures for feature-type options (enabled/disabled/auto).

Python

When using buildPythonPackage:

  • pyproject = true should be set (flag legacy format = as "prefer pyproject")
  • build-system should be present when pyproject = true
  • pythonImportsCheck is recommended

Rust

When using buildRustPackage:

  • cargoHash must be present
  • meta.mainProgram is recommended for binary crates

Go

When using buildGoModule:

  • vendorHash must be present
  • meta.mainProgram is recommended for CLI tools

Packaging Conventions

Structural

  • Use finalAttrs pattern — flag rec { as "prefer finalAttrs"
  • Do not set __structuredAttrs = true — it is the default
  • Do not set doCheck = false or doInstallCheck = false — they are defaults
  • Do not set meta.maintainers or meta.teams
  • Avoid placeholder if possible — prefer shell output references for better content-addressed derivation support. E.g. "PREFIX=${placeholder "out"}" → "PREFIX=$(out)"

Formatting

  • Attributes inside a derivation block (e.g. mkDerivation) should be separated by an empty line between each attribute
  • Exception: pname, version, extensions, pyproject, and disabled may be grouped together without blank lines

Dependencies

  • Build tools (compilers, code generators, pkg-config) belong in nativeBuildInputs, not buildInputs
  • Libraries belong in buildInputs, not nativeBuildInputs
  • Test-only deps belong in checkInputs or nativeCheckInputs
  • strictDeps = true should be set when depsBuildBuild is used
  • In top-level scope, prefer referencing the interpreter's package set over the top-level alias — e.g. python3.pkgs over python3Packages

Sources

  • Prefer forge-specific fetchers (fetchFromGitHub, fetchFromGitLab, fetchFromBitbucket, etc.) for source checkouts — flag fetchzip/fetchurl pointing at a forge source tarball as "prefer fetchFrom*". Fetching uploaded release artifacts (e.g. pre-built binaries, vendored bundles) with fetchzip/fetchurl is acceptable.
  • fetchFromGitHub/fetchFromGitLab should use tag, not rev with a tag value
  • Hash should be SRI format (sha256-...), not bare hex

Commits

  • Each commit should be one logical change
  • Fixup commits (fixup!, squash!, or small corrections to a previous commit in the same PR) should be squashed into the commit they fix before merge
  • Standalone fixup commits are only acceptable when they address an existing issue in an already-merged commit

Testing

  • Prefer passthru.tests over in-build doCheck = true
  • Python packages: prefer testPaths over manual test phase

Output Format

Group findings by severity:

## Errors
- line 12: missing `cmake.configurePhaseHook` in nativeBuildInputs
- line 30: `meta.maintainers` is forbidden — remove it

## Warnings
- line 8: `cmakeFlags` with -D entries — prefer `cmakeEntries` attrset
- line 25: `doCheck = false` is the default — remove redundant line

## Recommendations
- missing `meta.homepage`
- missing `meta.mainProgram` for binary package

If there are no findings in a severity group, omit that group. If the package is clean, say so.

rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 466kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 192kUpdated Claude CodeCodexVerifiedInstall