@agentyx/core 0.8.0 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentyx/core",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "Shared domain foundations for Agentyx: configuration model, pack resolution and skills.",
   "type": "module",
   "license": "MIT",
@@ -43,7 +43,7 @@
     "access": "public"
   },
   "dependencies": {
-    "zod": "^4.0.17"
+    "zod": "^4.6.5"
   },
   "scripts": {
     "build": "tsdown src/index.ts --dts --clean",

package/skills/cargo-project-verification/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: cargo-project-verification
+description: Verify Rust work in a single crate or Cargo workspace before handoff, and keep manifests, lockfile, features and public API consistent. Use before declaring Rust work done and when editing Cargo.toml, Cargo.lock, features or public items.
+---
+
+# Cargo project verification
+
+Complements the generic `verification` Skill: that covers the discipline of proving a change; this
+covers Cargo specifics.
+
+## Find the real gate
+
+Read the repository's CI workflows, Makefile/justfile and contributor docs first. Repository policy
+wins over any default below, including flags, feature sets and toolchain.
+
+Typical baseline (drop `--workspace` for a single crate, adjust features to what the repo supports):
+
+```sh
+cargo fmt --all -- --check
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo test --workspace --locked
+cargo build --workspace --locked
+```
+
+- `--locked` assumes `Cargo.lock` is committed. Libraries sometimes ignore it; do not invent or
+  commit one against repository convention. If a lockfile is tracked and changed, say why.
+- `--all-features` is not valid everywhere (mutually exclusive or platform-specific features). Use
+  the combinations CI uses.
+- Fix clippy findings rather than adding `#[allow]`; if an allow is justified, scope it to the item
+  with a reason.
+
+## Manifests
+
+- In a workspace, shared versions and metadata belong in `[workspace.package]` and
+  `[workspace.dependencies]`; members inherit with `.workspace = true`. Do not re-pin them.
+- Add a dependency only with a reason; check `default-features` and the features it enables.
+- `rust-version` is a contract: avoid newer APIs and do not raise it casually.
+- Features should be additive. After adding or changing one, build with `--no-default-features`
+  and the repository's full feature set.
+
+## Public API and release
+
+- Public changes (items, CLI flags, output formats, schemas) need tests and docs. Run
+  `cargo doc --no-deps` when docs link to changed items, and call the change out in the summary.
+- For publishable crates, `cargo package --list` or `cargo publish --dry-run` shows what ships. Never
+  edit release versions by hand if release tooling owns them.
+
+Report the exact commands run and their outcome; name any you could not run and why.

package/skills/rust-filesystem-safety/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: rust-filesystem-safety
+description: Handle untrusted paths, symlinks and output directories safely in Rust. Use only when Rust code reads, walks, scans, generates, scaffolds or writes files whose names or locations come from users or repository contents; skip for code that never touches paths.
+---
+
+# Rust filesystem safety
+
+Treat names and locations from users, repositories, manifests and links as untrusted. A file inside
+the project can still point outside it.
+
+## Paths
+
+- Use `Path`/`PathBuf` and `components()` for path logic, never string slicing or `split('/')`.
+  Convert to `/`-joined strings only for URLs or IDs, handling `\` explicitly.
+- Accept a user-supplied relative path only if every component is `Component::Normal`; reject `..`,
+  root, drive/UNC prefixes and empty paths. Absolute inputs need an explicit decision.
+- Containment: canonicalize root and target, then `Path::starts_with` (component-wise, not a string
+  prefix). Do it before reading content, and again for resolved link targets. Canonicalizing needs an
+  existing path; for a new file, canonicalize the parent.
+- `to_str()` is `Option`: non-UTF-8 names are normal, so handle them without panicking.
+
+## Symlinks and races
+
+- Decide symlink behavior per feature; default to refusing. Walk without following links and inspect
+  with `symlink_metadata`. Never write through a symlinked directory. Treat Windows junctions the
+  same way.
+- Checks and use are separate syscalls, so a check cannot guarantee safety. Prefer an operation that
+  fails safely (`create_new`) over check-then-act, and expect files to vanish mid-run.
+
+## Collisions
+
+On case-insensitive filesystems two names differing only by case collide. Detect collisions on a
+normalized key before writing. On Windows also watch trailing dots/spaces and reserved device names.
+
+## Writing
+
+- Never overwrite or delete what you did not create. Use `OpenOptions::create_new(true)` for new
+  files and report `AlreadyExists`. Delete only paths you recorded or can prove are yours (for
+  example via a marker file).
+- For generated output directories, write into a staging directory on the same filesystem and rename
+  into place, keeping the last good output on failure.
+
+## Bounds and errors
+
+Bound traversal (depth, entry count, file size). Skip an unreadable or non-UTF-8 file with a
+diagnostic naming the path instead of failing the whole run, unless the caller needs completeness.

package/skills/rust-idiomatic-development/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: rust-idiomatic-development
+description: Write and review idiomatic Rust with clear ownership, expressive types, honest errors and a small public API. Use when adding or changing Rust types, functions, error handling or public items.
+---
+
+# Idiomatic Rust
+
+## Ownership
+
+- Borrow before cloning. Accept `&str`, `&Path` and `&[T]`; return owned data only when the caller
+  needs it. A `.clone()` added only to satisfy the borrow checker signals a design problem:
+  restructure the borrow or scope, or justify the clone in a comment.
+- Use `impl AsRef<Path>` or `impl Into<String>` at API edges where callers benefit; keep internals
+  concrete.
+- Avoid allocation in hot loops: reuse buffers, stream with iterators, use `Cow` when most inputs
+  pass through unchanged. Measure before contorting readable code.
+
+## Types
+
+- Make invalid states hard to represent: an `enum` per distinct case instead of a `String` plus
+  flags; newtypes whose constructor validates identifiers and similar values.
+- Match exhaustively on enums you own. Avoid `_ =>` there so a new variant breaks the build rather
+  than silently changing behavior.
+- Use an iterator chain when it reads as a pipeline; use a `for` loop for side effects or early
+  exits.
+
+## Errors
+
+- Code that handles user input, files or the network returns `Result`. Do not `unwrap`, `expect` or
+  index data that originates outside the process; reserve `expect` for true invariants and state the
+  invariant in the message.
+- Add context where an error crosses a boundary (which path, which key). Diagnostics are user-facing
+  output.
+
+## API surface
+
+- Keep `pub` minimal and prefer `pub(crate)`; every public item is a promise.
+- Keep serialized/wire types separate from domain types and convert at the boundary. Do not derive
+  `Deserialize` on a domain type if that bypasses its constructor validation.
+- Document public items with `///`, including failure modes. Comments explain intent, not syntax.
+
+## `unsafe`
+
+`unsafe` is repository policy, not a universal rule. Check `Cargo.toml`, `[workspace.lints]`, existing
+`unsafe` blocks and `SAFETY:` comments first. If the repository forbids it, respect that. If it
+allows it, keep blocks minimal and document the invariant in a `SAFETY:` comment.

package/skills/rust-testing-portability/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: rust-testing-portability
+description: Write deterministic, portable Rust tests that cover regressions and user-visible behavior. Use when adding or fixing Rust tests, fixing a bug, or touching code that must run on Linux, macOS and Windows.
+---
+
+# Rust testing and portability
+
+## Level
+
+- Unit tests (`#[cfg(test)]`) for pure logic and edge cases inside one module.
+- Integration tests (`tests/*.rs`) for the public API or the real binary, including exit codes and
+  the stdout/stderr text users see.
+- Every fixed bug gets a regression test that fails without the fix. Name it for the behavior, not
+  the issue number.
+
+## Deterministic
+
+- Use `tempfile` for filesystem fixtures; never write into the source tree or depend on the current
+  directory. Build fixtures in code or from small checked-in directories.
+- Do not sleep for arbitrary durations. Poll a condition with a bounded timeout, or inject the clock
+  or dependency. Bind port `0` instead of assuming a free port.
+- Sort anything from directory walks or hash maps before comparing.
+- Isolate the environment: set the variables a child process needs and clear those it must not
+  inherit.
+- To diagnose flakiness, repeat the single test (a shell loop around `cargo test <name>`) before
+  claiming it is stable.
+
+## Portable
+
+- Build paths with `join`; compare `/`-normalized strings only where the code promises them. Add a
+  Windows-separator case for any path or ID normalization.
+- Gate platform behavior with `#[cfg(unix)]` (symlinks, permissions) and `#[cfg(windows)]`. Do not
+  assume executable names or `.exe` suffixes; use `env!("CARGO_BIN_EXE_<name>")`.
+- Normalize `\r\n` before comparing generated text.
+- Do not create two fixtures differing only by case in one directory; case-insensitive filesystems
+  will merge them.
+
+## Snapshots
+
+Keep goldens small, reviewed and regenerated only through the project's documented command. Strip
+absolute paths, timestamps and versions so they pass on every platform.