@ketecode/loom 0.0.0-stage → 0.1.0

package/skills/ruby-testing/SKILL.md

@@ -0,0 +1,113 @@
+---
+name: ruby-testing
+description: Writes and stabilises Ruby test suites in whichever framework the project already runs, RSpec or Minitest, with FactoryBot or fixtures, verifying doubles and stubs, frozen or travelled time, WebMock and VCR to keep tests off the network, and a seed-and-bisect routine for order-dependent or flaky specs. Use when adding RSpec examples or Minitest tests to a Ruby or Rails codebase, stubbing an HTTP client or the clock in Ruby, or tracking down a spec that fails only in CI or only with some seeds.
+license: MIT
+compatibility: Any Agent Skills host. Needs ruby, bundler and the project's test framework (rspec or minitest); webmock, vcr, factory_bot and timecop only if the project uses them.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: testing
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "ruby, bundle"
+  kete-loom/owner: "Kete-org"
+---
+
+# Ruby testing with RSpec or Minitest
+
+Fast, isolated tests that fail for one clear reason.
+
+## 0. Find the setup
+
+1. Detect the framework: `spec/` + `.rspec` + `rspec` in `Gemfile.lock` means RSpec; `test/` + `minitest` (or Rails `test_helper.rb`) means Minitest. Use that one. Never add the other framework.
+2. Find the command: `bin/rspec`, `bundle exec rspec`, `bin/rails test`, `bundle exec rake test`, or what CI runs. Always go through Bundler.
+3. Read `spec/spec_helper.rb` / `rails_helper.rb` / `spec/support/**` or `test/test_helper.rb`. Reuse existing helpers, shared contexts, factories and fixtures.
+4. Run the suite (or the relevant directory) once. If it already fails, **stop and tell the user** which tests fail before you change anything.
+5. Note what is installed: `factory_bot`, `webmock`, `vcr`, `timecop`, `database_cleaner`, `shoulda-matchers`, `rspec-rails`. Use them; ask before adding a gem.
+
+## 1. Writing a test
+
+**RSpec**
+
+```ruby
+RSpec.describe Invoice do
+  describe "#total" do
+    it "rejects a negative quantity" do
+      invoice = described_class.new(lines: [{ price: 5, quantity: -1 }])
+      expect { invoice.total }.to raise_error(Invoice::InvalidLine, /quantity/)
+    end
+  end
+end
+```
+
+- `describe` the unit or method (`"#instance_method"`, `".class_method"`), `context "when ..."` for a condition, `it` for one behaviour.
+- `let` for lazy values, `let!` only when the record must exist before the example. Don't nest `let` overrides more than two levels deep.
+- Floats: `be_within(0.001).of(0.3)`. Collections: `contain_exactly`, `match_array`, `include`.
+
+**Minitest**
+
+```ruby
+class InvoiceTest < Minitest::Test   # ActiveSupport::TestCase in Rails
+  def test_total_rejects_negative_quantity
+    invoice = Invoice.new(lines: [{ price: 5, quantity: -1 }])
+    error = assert_raises(Invoice::InvalidLine) { invoice.total }
+    assert_match(/quantity/, error.message)
+  end
+end
+```
+
+- `assert_equal expected, actual` (expected first). `assert_in_delta` for floats.
+- Spec-style Minitest: wrap the value, `_(total).must_equal 5`. minitest 6 removed the expectation methods from `Object`, so a bare `total.must_equal 5` raises `NoMethodError`.
+
+Both: test through the public interface, one behaviour per test, arrange-act-assert. Keep the `raise_error` / `assert_raises` block to the single call that should raise.
+
+## 2. Test data
+
+- **FactoryBot:** factories hold the minimum valid attributes; add `trait`s for variants. Prefer `build` or `build_stubbed` (no DB) over `create`; use `create` only when the test reads back from the database. Use `sequence` for unique fields.
+- Avoid deep association chains in factories; they make every `create` insert many rows.
+- **Rails fixtures** (`test/fixtures/*.yml`): fine for stable reference data; reference them by name (`users(:alice)`). Don't mutate shared fixtures in a way later tests rely on.
+- Each test builds its own data. Never depend on records created by another test.
+
+## 3. Doubles and stubs
+
+- Stub only boundaries: HTTP clients, payment gateways, mailers, the clock, randomness. Never stub the object under test.
+- **RSpec:** prefer verifying doubles so stubs break when the real API changes: `instance_double(PaymentGateway, charge: result)`, `class_double`, `object_double`. Also set `config.mock_with(:rspec) { |m| m.verify_partial_doubles = true }`.
+  - `allow(x).to receive(:y).and_return(z)` to stub; `expect(x).to receive(:y).with(args)` only when the call itself is the behaviour.
+  - Spies: `allow(...)` then `expect(x).to have_received(:y)` after acting.
+  - Avoid `allow_any_instance_of`; inject the collaborator instead.
+- **Minitest:** `Object#stub` and `Minitest::Mock` come from `require "minitest/mock"`. From minitest 6 they live in the separate `minitest-mock` gem; add it to the Gemfile if the require fails. Call `mock.verify` at the end.
+
+## 4. Time, randomness and the network
+
+- **Time:** in Rails use `ActiveSupport::Testing::TimeHelpers` (`travel_to Time.zone.local(2025, 1, 31) { ... }`, `freeze_time`); include it in RSpec via `config.include ActiveSupport::Testing::TimeHelpers`. Outside Rails use `Timecop.freeze` with `Timecop.return` in an `after` hook, or inject a clock. Test month ends, leap days and DST boundaries explicitly.
+- **Randomness:** RSpec: `config.order = :random` and `Kernel.srand config.seed` so a seed reproduces everything. Minitest randomises order by default; reuse with `--seed N`.
+- **Network:** `require "webmock/rspec"` (or `webmock/minitest`) and `WebMock.disable_net_connect!(allow_localhost: true)` in the helper. Stub with `stub_request(:post, "https://api.example.com/charges").with(body: hash_including(amount: 500)).to_return(status: 200, body: json)`.
+- **VCR** for recorded responses: `filter_sensitive_data("<API_KEY>") { ENV["API_KEY"] }` so secrets never land in cassettes; use `record: :once` and re-record deliberately. Check every new cassette for tokens and personal data before committing.
+- **Filesystem:** `Dir.mktmpdir` with a block, never the repo tree or `/tmp` paths shared between tests.
+
+## 5. Fixing a flaky test
+
+1. Reproduce with the CI seed: `bundle exec rspec --seed 12345` or `bin/rails test --seed 12345`.
+2. Order-dependent? RSpec: `bundle exec rspec --bisect --seed 12345` finds the minimal pair. Minitest: the `minitest-bisect` gem, if installed.
+3. Run the single test repeatedly to separate timing flakiness from order: loop it 20 times in the shell.
+4. Common causes and fixes:
+   - Leaked state: class-level caches, `ENV`, globals, `Rails.cache`, `Current` attributes. Reset in `after`, or avoid the global.
+   - Time: `Date.today` vs `Time.zone.today`, tests near midnight or month end. Freeze time.
+   - Ordering: queries without `order` compared with `eq`. Use `contain_exactly` or add `order`.
+   - Database: data committed outside the transaction (threads, `after_commit` in system tests). Use the project's cleaning strategy.
+   - Async: `sleep` in tests. Wait on a condition (Capybara's waiting matchers) or run jobs inline (`perform_enqueued_jobs`).
+5. Fix the cause. Do not add `retry` gems, sleeps, or skips to hide it.
+
+## 6. Speed
+
+- Profile: `bundle exec rspec --profile 10`. Look for `create` where `build_stubbed` would do, and `before(:all)` / `let!` creating unused data.
+- Parallelise only with the project's tool (`parallelize` in Rails, `parallel_tests`), after tests are isolated.
+
+## Rules
+
+- Never delete, skip (`skip`, `xit`, `pending`) or loosen an existing test to make the suite pass. If a test is wrong, explain why and get agreement first.
+- No real network, no real clock, no sleeps.
+- Don't assert on private methods or `instance_variable_get`.
+- After three focused attempts without green, stop and report what you tried.
+
+## Report back
+
+End with: tests added or changed (file and description), the exact command and seed you ran, final pass/fail counts, and anything left untested.

package/skills/ruby-testing/evals/triggers.json

@@ -0,0 +1,18 @@
+{
+  "should_trigger": [
+    "Add RSpec tests for the PaymentGateway wrapper, stubbing the HTTP calls",
+    "This Minitest test passes locally but fails in CI with some seeds, help me find why",
+    "How do I freeze time in an RSpec spec that checks subscription renewal dates?",
+    "Our FactoryBot factories make the suite crawl, can you speed up the specs?",
+    "Replace allow_any_instance_of in these specs with something less brittle",
+    "Write Minitest tests for this Ruby class and keep them off the network with WebMock"
+  ],
+  "should_not_trigger": [
+    "Refactor this Ruby class to use Enumerable instead of manual loops",
+    "Review the changed .rb files on my branch for nil errors before merging",
+    "bundle exec rspec says cannot load such file -- csv after upgrading Ruby",
+    "Write pytest fixtures for the payment client",
+    "Set up Playwright end-to-end tests for the checkout flow",
+    "Raise the test coverage of this repo to 80 percent"
+  ]
+}

package/skills/runbook-writing/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: runbook-writing
+description: Operational runbook and playbook authoring for on-call engineers, built around the alert or symptom that sends someone to the page, ordered read-only diagnosis checks with expected output, copy-paste remediation commands that each carry a rollback and a stop condition, escalation paths with contacts and time limits, verification that service has recovered, and a schedule for testing the runbook in drills. Use when writing or fixing a runbook for an alert, a recurring operational task such as failover or certificate rotation, or a service handover to an on-call rotation.
+license: MIT
+compatibility: Any Agent Skills host. Reads the codebase, alert rules and deploy config; runs only read-only commands to check that documented commands exist.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: docs
+  kete-loom/risk: runs-commands
+  kete-loom/owner: "Kete-org"
+---
+
+# Runbook writing
+
+A runbook is read at 3 a.m. by someone tired who may not know the service. Every step must be executable as written, in order, without needing the author.
+
+## 0. Scope the runbook
+
+1. One runbook per alert or per task. If the user wants "the runbook for service X", propose one short page per alert plus an index.
+2. Collect: the alert rule (query, threshold, duration), service ownership, dashboards, deploy method, config locations, dependencies, and past incidents for this alert. Search the repo for alert definitions and existing runbooks; reuse their location and format.
+3. Find who the reader is (any on-call engineer, a specialist team, support) and what access they have. Do not write steps that need access the reader lacks.
+4. If you cannot find how the service is deployed or restarted, **stop and ask the user**. Do not guess commands.
+
+## 1. Header
+
+```
+# Runbook: <alert name or task>
+Service: <name>   Owner: <team>   Last tested: <date, or "never">   Severity: <SEV level the alert pages at>
+Alert: <exact alert name as it appears in the pager>  Link: <alert rule>
+Dashboards: <links>
+```
+
+## 2. Trigger and symptoms
+
+- What fired: the exact condition in plain words ("5xx rate on checkout-api above 2% for 5 minutes").
+- What users see when this is real.
+- Known false positives and how to recognise them in under a minute.
+- Impact if ignored, so the reader can judge urgency.
+
+## 3. Diagnosis
+
+Ordered checks, most likely and cheapest first. Diagnosis steps must be **read-only**.
+
+```
+1. Is it a recent deploy?
+   Run: <command to list recent deploys>
+   Expect: last deploy older than 1 hour.
+   If a deploy landed in the last hour: go to Remediation A (roll back).
+2. Is the database reachable?
+   Run: <read-only check>
+   Expect: <exact healthy output>
+   If not: go to Remediation B, or escalate to the database team.
+```
+
+Rules for each check: the exact command or dashboard panel, the expected healthy output, and a branch for each abnormal result. Use placeholders like `<pod-name>` in angle brackets and say how to find the value.
+
+## 4. Remediation
+
+Each remediation is a separate, labelled procedure:
+
+- **When to use it**: which diagnosis result leads here.
+- **Risk**: what it affects (drops connections, loses in-flight jobs, customer-visible).
+- **Steps**: numbered, copy-paste commands, one action each. Destructive or customer-visible steps are marked `CAUTION` and say who must approve them.
+- **Rollback**: how to undo this remediation if it makes things worse.
+- **Stop condition**: when to stop trying and escalate ("if error rate is not falling 10 minutes after step 3").
+
+Prefer the safest effective action first: roll back, fail over, scale out, or disable a feature flag before restarting stateful systems, editing data or deleting anything. Never put a data-deleting command in a runbook without a backup or snapshot step immediately before it.
+
+## 5. Escalation
+
+- Who to page next, how (rotation name, not a person's phone number in plain text), and after how long.
+- Which dependency teams own what, with their rotation names.
+- When to declare an incident and who communicates to customers.
+
+## 6. Verification
+
+How to confirm recovery: the metric and the value it must return to, for how long, plus one user-level check (a synthetic request, a test login). Say when it is safe to resolve the alert.
+
+## 7. Afterwards
+
+- Record what was done in the incident ticket.
+- If this was a real incident, link the postmortem (the `incident-postmortem` skill covers writing it).
+- Update the runbook if any step was wrong or missing, and bump "Last tested".
+
+## Keeping runbooks tested
+
+- Check every command against the current code and config: search for the service names, namespaces, flags and script paths you reference. Run read-only commands (`--help`, list or describe commands) if the user allows; never run remediation commands to "test" them on production.
+- Recommend a drill in staging or a game day each quarter, or after any change to the service's deploy or infra, and record the date in the header.
+- Flag a runbook as stale when "Last tested" is over six months old or references removed resources.
+- Keep runbooks in the repo next to the service or in the team's known runbook location, and link each from its alert's annotation so the pager opens it directly.
+
+## Reviewing an existing runbook
+
+Report, most serious first: commands that no longer match the code, destructive steps without approval or rollback, diagnosis steps that change state, missing expected outputs, missing escalation or stop conditions, no verification, and a stale or missing "Last tested" date.
+
+## Never
+
+- Never include secrets, passwords or tokens. Point to where the reader gets them (the secrets manager path).
+- Never write "investigate the issue" or "fix the config" as a step; say exactly what to look at and what to change.
+- Never run remediation steps yourself while writing the runbook.
+- Never reference one engineer's laptop, alias or personal script.

package/skills/runbook-writing/evals/triggers.json

@@ -0,0 +1,14 @@
+{
+  "should_trigger": [
+    "Write a runbook for the HighReplicationLag alert on our Postgres cluster so on-call knows what to check and do",
+    "Our on-call playbook for the queue backlog alert just says 'restart things'. Rewrite it with diagnosis, rollback and escalation",
+    "Document the step-by-step procedure for rotating the TLS certificates on the ingress, with verification",
+    "We're handing the billing service to the SRE rotation. Create runbooks for each of its alerts"
+  ],
+  "should_not_trigger": [
+    "Write up the postmortem for last night's replication lag outage with action items",
+    "Set up a GitHub Actions workflow that deploys the ingress config on merge",
+    "Design a blue-green deployment so we can roll back the billing service instantly",
+    "Write a how-to guide for developers on running the billing service locally"
+  ]
+}

package/skills/rust-patterns/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: rust-patterns
+description: Idiomatic Rust design guide covering ownership and borrowing choices, Result-based errors with thiserror in libraries and anyhow in binaries, traits and generics, iterator chains, async with tokio, rules for unsafe, cargo workspaces and clippy settings. Use when writing new Rust code, shaping a crate's public API, choosing between owned and borrowed types, or setting up a Cargo workspace and lint policy.
+license: MIT
+compatibility: Any Agent Skills host. Needs a Rust toolchain (cargo, rustc, clippy, rustfmt) to check the code it writes.
+metadata:
+  kete-loom/version: "0.1.0"
+  kete-loom/category: coding
+  kete-loom/risk: runs-commands
+  kete-loom/requires: "cargo"
+  kete-loom/owner: "Kete-org"
+---
+
+# Rust patterns
+
+Write Rust that compiles on the first honest try, says what it owns, and fails with typed errors instead of panics.
+
+## 0. Before you write
+
+1. Read `Cargo.toml` (and the workspace root's, if any): edition, `rust-version`, features, existing error crate, async runtime. Match them; never add a second error crate or runtime.
+2. Read `clippy.toml`, `rustfmt.toml` and any `[lints]` table. They are the house rules.
+3. Find a neighbouring module that does something similar and copy its shape (error type, constructor style, module layout).
+4. If the task needs a new dependency, **stop and ask the user** before adding it, and name the crate and why.
+
+## 1. Ownership and borrowing
+
+Decide per parameter, in this order:
+
+| Need | Take |
+|---|---|
+| Only read it | `&T`, `&str`, `&[T]`, `&Path` (not `&String`, `&Vec<T>`, `&PathBuf`) |
+| Mutate the caller's value | `&mut T` |
+| Store it or move it to another thread | `T` by value (`String`, `Vec<T>`) |
+| Accept owned or borrowed, store it | `impl Into<String>` / `impl Into<PathBuf>` |
+| Return borrowed-or-owned | `Cow<'_, str>` |
+
+- Return owned values from constructors and builders; return references only from accessors (`fn name(&self) -> &str`).
+- When the borrow checker objects, restructure first: shorten the borrow with a block, split the struct into fields borrowed separately, or collect indices before mutating. Use `.clone()` only when the data is small or the copy is the real intent, never just to silence an error.
+- Shared ownership: `Rc<T>` single-threaded, `Arc<T>` across threads. Interior mutability: `Cell`/`RefCell` single-threaded, `Mutex`/`RwLock` or atomics across threads. Reaching for `Rc<RefCell<T>>` everywhere usually means the ownership tree needs redesign; say so.
+- Add explicit lifetimes only when elision can't express the relationship. A struct holding references (`struct Parser<'a>`) is fine for short-lived views; long-lived structs should own their data.
+
+## 2. Errors
+
+- Library crates: one error enum per crate or module with `thiserror`. Wrap sources with `#[from]` or `#[source]` so the chain survives.
+- Binaries and app glue: `anyhow::Result<T>`, adding context at each boundary with `.context("reading config")` / `.with_context(|| format!("opening {path:?}"))`.
+- Propagate with `?`. Convert at module boundaries, not at every call.
+- `unwrap()` and `expect()` belong in tests, examples and provably-impossible cases. For the last, use `expect("reason this cannot fail")`, never bare `unwrap()`.
+- Never return `Result<T, String>` or `Box<dyn Error>` from a public library API; callers can't match on them.
+- `panic!` is for broken invariants (bugs), not for bad input, missing files or network failures.
+
+Patterns and full examples: `references/errors-and-traits.md`.
+
+## 3. Traits and generics
+
+- Prefer generics (`fn f<R: Read>(r: R)` or `impl Read`) for hot paths and when the caller picks one type. Use `dyn Trait` for heterogeneous collections, plugin points and to cut compile time or binary size.
+- Keep trait bounds on `impl` blocks and functions, not on struct definitions.
+- Implement standard traits instead of ad hoc methods: `From`/`TryFrom` for conversions, `Display` for user-facing text, `Default`, `FromStr`, `Iterator`, `AsRef`.
+- Derive `Debug` on every public type. Derive `Clone`, `PartialEq`, `Eq`, `Hash` only when they make sense for the type.
+- Newtypes (`struct UserId(u64)`) for values that must not be mixed up. Enums instead of boolean flags or stringly-typed states.
+- Don't implement `Deref` to fake inheritance.
+
+## 4. Iterators and collections
+
+- Chain `iter()`, `map`, `filter`, `filter_map`, `flat_map`, then `collect()`; collect into `Result<Vec<_>, _>` to stop at the first error.
+- Use a plain `for` loop when the body has side effects, early `return`, or `?` that would make the chain unreadable.
+- Pre-size with `Vec::with_capacity` when the length is known. Use the `entry` API on maps instead of a lookup followed by an insert.
+- Don't `collect()` just to iterate again; pass the iterator on (`impl Iterator<Item = T>`).
+
+## 5. Async with tokio
+
+1. One runtime, created once with `#[tokio::main]` in the binary. Libraries take no runtime dependency they can avoid and never create their own runtime.
+2. Never block inside async code: no `std::thread::sleep`, `std::fs` on hot paths, blocking HTTP clients, or long CPU loops. Use `tokio::time::sleep`, `tokio::fs`, or move the work into `tokio::task::spawn_blocking`.
+3. Never hold a `std::sync::Mutex` guard across `.await`. Drop it before awaiting, or use `tokio::sync::Mutex` when the lock must span an await.
+4. Every `tokio::spawn` gets an owner: keep the `JoinHandle` (or use a `JoinSet`) and handle its result, or the task's panic and error vanish.
+5. Bound concurrency and channels: `tokio::sync::Semaphore`, bounded `mpsc::channel(n)`. Unbounded channels need a written reason.
+6. Add timeouts to network I/O with `tokio::time::timeout`, and support shutdown with a cancellation signal checked in `tokio::select!`.
+7. Spawned futures must be `Send + 'static`: move owned data (or an `Arc`) into them, don't borrow.
+
+## 6. Unsafe
+
+- Don't write `unsafe` unless the task cannot be done in safe Rust (FFI, a measured hot path, a primitive the standard library lacks). If you think you need it, **stop and tell the user why** before writing it.
+- Every `unsafe` block gets a `// SAFETY:` comment naming the invariant that makes it sound, and every `unsafe fn` gets a `# Safety` doc section stating what callers must uphold.
+- Keep the block as small as possible and wrap it in a safe API that enforces the invariant.
+- Run the tests under Miri (`cargo +nightly miri test`) when unsafe code touches pointers or memory layout, if Miri is available.
+
+## 7. Cargo workspaces
+
+- Root `Cargo.toml` with `[workspace]`, `members`, and shared versions in `[workspace.dependencies]`; members use `serde = { workspace = true }`.
+- Put shared lint settings in `[workspace.lints]` and `[lints] workspace = true` in each member.
+- Features are additive: a feature must never remove an API or change behaviour incompatibly. Gate optional dependencies with `dep:name`.
+- Commit `Cargo.lock`. Cargo's current guidance is to commit it for libraries too; follow the project if it has a documented reason not to.
+- Layout and a starter manifest: `references/cargo-and-clippy.md`.
+
+## 8. Finish: format, lint, test
+
+Run, and fix everything before you report:
+
+```sh
+cargo fmt --all
+cargo clippy --all-targets --all-features -- -D warnings
+cargo test --all-features
+```
+
+If the project has mutually exclusive features, `--all-features` fails by design: use the feature flags CI uses instead.
+
+- Fix clippy warnings in the code. Suppress only on the smallest item, with a reason: `#[expect(clippy::lint_name, reason = "...")]` when the project's `rust-version` is 1.81 or newer (it warns once the lint stops firing), otherwise `#[allow(clippy::lint_name)]` plus a comment.
+- If a check fails for reasons outside your change, report it instead of fixing unrelated code.
+
+## Never
+
+- Never add `unwrap()` on user input, I/O, parsing or network results in non-test code.
+- Never silence the borrow checker with `clone()`, `Rc<RefCell<_>>` or `unsafe` without saying why.
+- Never use `std::mem::transmute` to convert between types that have safe conversions.
+- Never add a dependency, a feature flag or `#![allow(...)]` at crate level without asking.
+
+## Report back
+
+End with: files changed, the three commands above and their results, any `unsafe`, `allow` or new dependency introduced and why, and anything left undone.

package/skills/rust-patterns/evals/triggers.json

@@ -0,0 +1,16 @@
+{
+  "should_trigger": [
+    "Should this Rust function take a String or a &str? It just looks up a key in a map",
+    "Set up a thiserror error enum for my parser crate and use anyhow in the CLI binary",
+    "Split my Rust project into a cargo workspace with a core library and a cli crate",
+    "Write an async tokio worker that pulls jobs from a channel and processes them with bounded concurrency",
+    "What's the idiomatic way to design a trait for pluggable storage backends in Rust?"
+  ],
+  "should_not_trigger": [
+    "Add proptest property tests for my Rust base64 encoder",
+    "Review this Rust pull request for unwraps and unsafe blocks before I merge it",
+    "cargo build fails with E0502 cannot borrow as mutable because it is also borrowed as immutable",
+    "Write idiomatic Go error handling with wrapped errors for this HTTP handler",
+    "Design a REST API for the orders service with pagination and versioning"
+  ]
+}

package/skills/rust-patterns/references/cargo-and-clippy.md

@@ -0,0 +1,105 @@
+# Cargo workspaces and clippy policy
+
+Read this when creating or restructuring a workspace, or setting lint policy.
+
+## Layout
+
+```
+my-project/
+├── Cargo.toml          # workspace root, no [package] unless it is also a crate
+├── Cargo.lock
+├── crates/
+│   ├── app-core/       # domain types and logic, no I/O
+│   ├── store/          # persistence, depends on app-core
+│   └── cli/            # binary, depends on app-core and store
+└── clippy.toml         # optional
+```
+
+Keep the dependency graph acyclic and pointing inwards: binaries depend on libraries, never the reverse.
+
+## Root manifest
+
+```toml
+[workspace]
+resolver = "3"          # edition 2024 default; use "2" on edition 2021
+members = ["crates/*"]
+
+[workspace.package]
+edition = "2024"
+license = "MIT"
+
+[workspace.dependencies]
+anyhow = "1"
+thiserror = "2"
+serde = { version = "1", features = ["derive"] }
+tokio = { version = "1", features = ["macros", "rt-multi-thread"] }
+
+[workspace.lints.rust]
+unsafe_code = "forbid"
+
+[workspace.lints.clippy]
+unwrap_used = "warn"
+expect_used = "warn"
+dbg_macro = "warn"
+todo = "warn"
+```
+
+Match the edition, resolver and dependency major versions already used by the project rather than copying the numbers above; they are placeholders.
+
+`unsafe_code = "forbid"` is a sensible default for crates with no FFI. Relax it per crate (`deny`, then `#[allow(unsafe_code)]` on the one module) only where unsafe is justified.
+
+## Member manifest
+
+```toml
+[package]
+name = "store"
+version = "0.1.0"
+edition.workspace = true
+license.workspace = true
+
+[dependencies]
+app-core = { path = "../app-core" }   # don't name a crate `core` or `std`: it shadows the built-in crate
+serde = { workspace = true }
+thiserror = { workspace = true }
+sqlx = { version = "0.8", optional = true }
+
+[features]
+default = []
+postgres = ["dep:sqlx"]
+
+[lints]
+workspace = true
+```
+
+## Useful cargo commands
+
+| Task | Command |
+|---|---|
+| Check fast without codegen | `cargo check --workspace --all-targets` |
+| Build one member | `cargo build -p store` |
+| Why is this crate here? | `cargo tree -i <crate>` |
+| Duplicate versions in the graph | `cargo tree -d` |
+| Features enabled on a crate | `cargo tree -e features -i <crate>` |
+| Update one dependency | `cargo update -p <crate>` |
+| Check every feature combination | `cargo hack check --feature-powerset` (needs `cargo-hack`) |
+
+## Clippy
+
+Baseline for CI:
+
+```sh
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+```
+
+- `clippy::all` (the default groups) is on already. `clippy::pedantic` is opt-in and noisy; enable it only if the project already does, or the user asks.
+- `unwrap_used` and `expect_used` are restriction lints. Allow them in tests with `#[cfg_attr(test, allow(clippy::unwrap_used, clippy::expect_used))]` at the crate root, or in `clippy.toml` with `allow-unwrap-in-tests = true` and `allow-expect-in-tests = true`.
+- Suppress a lint on the smallest item, with a reason:
+
+```rust
+#[expect(clippy::too_many_arguments, reason = "mirrors the C API one-to-one")] // Rust 1.81+
+fn ffi_call(/* ... */) {}
+```
+
+On an older `rust-version`, use `#[allow(...)]` with a trailing comment instead.
+
+- Don't use `cargo clippy --fix` on a dirty tree without reviewing the diff it produces.

package/skills/rust-patterns/references/errors-and-traits.md

@@ -0,0 +1,97 @@
+# Errors and traits: worked patterns
+
+Read this when designing a crate's error type or a public trait.
+
+## Library error with thiserror
+
+```rust
+use std::path::PathBuf;
+
+#[derive(Debug, thiserror::Error)]
+pub enum ConfigError {
+    #[error("could not read config file {path:?}")]
+    Read {
+        path: PathBuf,
+        #[source]
+        source: std::io::Error,
+    },
+    #[error("invalid config")]
+    Parse(#[from] toml::de::Error),
+    #[error("missing required key `{0}`")]
+    MissingKey(&'static str),
+}
+
+pub fn load(path: &std::path::Path) -> Result<Config, ConfigError> {
+    let text = std::fs::read_to_string(path).map_err(|source| ConfigError::Read {
+        path: path.to_owned(),
+        source,
+    })?;
+    let config: Config = toml::from_str(&text)?; // From<toml::de::Error>
+    Ok(config)
+}
+```
+
+Rules:
+
+- The `#[error]` message describes this layer only. Don't repeat the source's message in it; reporters walk `source()` and print the chain.
+- Use `#[from]` only when the conversion is unambiguous. If two call sites produce the same source type with different meaning, use explicit variants with `#[source]` and `map_err`.
+- Mark public error enums `#[non_exhaustive]` if you expect to add variants without a major version bump.
+
+## Application errors with anyhow
+
+```rust
+use anyhow::{bail, Context, Result};
+
+fn main() -> Result<()> {
+    let path = std::env::args().nth(1).context("usage: tool <config>")?;
+    let config = mylib::load(path.as_ref())
+        .with_context(|| format!("loading config from {path}"))?;
+    if config.workers == 0 {
+        bail!("workers must be at least 1");
+    }
+    Ok(())
+}
+```
+
+- Returning `anyhow::Result<()>` from `main` prints the error chain on failure and exits non-zero.
+- Use `anyhow::Error::downcast_ref::<T>()` only at the top level, when you must branch on a specific cause.
+
+## Option and Result helpers
+
+| Want | Use |
+|---|---|
+| Option to Result | `opt.ok_or(Error::Missing)?` / `opt.ok_or_else(\|\| ...)?` |
+| Default on None | `opt.unwrap_or_default()` / `unwrap_or_else(\|\| ...)` |
+| Transform the success value | `res.map(...)` |
+| Chain fallible steps | `res.and_then(...)` |
+| Log and drop an error deliberately | `if let Err(e) = res { tracing::warn!(error = %e, "..."); }` |
+
+Never use `let _ = fallible();` for a `Result` whose failure matters; handle or log it.
+
+## Trait design
+
+```rust
+pub trait Store {
+    fn get(&self, key: &str) -> Result<Option<Vec<u8>>, StoreError>;
+    fn put(&self, key: &str, value: &[u8]) -> Result<(), StoreError>;
+}
+
+pub struct Cache<S: Store> { inner: S }      // avoid: bound on the struct
+pub struct Cache<S> { inner: S }             // prefer
+impl<S: Store> Cache<S> { /* ... */ }        // bound where it is needed
+```
+
+- Take `&self` in trait methods unless mutation is the point; implementations can use interior mutability.
+- Keep traits small and focused. A trait with ten methods usually wants splitting.
+- To make a trait usable as `dyn Trait`, avoid generic methods and `Self` return types (or gate them with `where Self: Sized`).
+- Sealed traits (a private supertrait) stop downstream crates from implementing a trait you need to extend later.
+
+## Async traits
+
+`async fn` in traits works on stable Rust for static dispatch. For `dyn` use, or when callers need the returned future to be `Send`, check the project's current approach (the `async-trait` crate, or a method returning `Pin<Box<dyn Future<Output = T> + Send + '_>>`) and follow it rather than mixing styles.
+
+## Conversions
+
+- `impl From<A> for B` gives you `Into` for free. Never implement `Into` directly.
+- `TryFrom` for conversions that can fail; its `Error` type should be a real error, not `()` or `String`.
+- `AsRef<str>` / `AsRef<Path>` for functions that only need to look at the data.