Initial commit

Author: ayushag-nv

.agents/settings.json

@@ -0,0 +1,13 @@
+{
+  "extraKnownMarketplaces": {
+    "astral-sh": {
+      "source": {
+        "source": "github",
+        "repo": "astral-sh/claude-code-plugins"
+      }
+    }
+  },
+  "enabledPlugins": {
+    "astral@astral-sh": true
+  }
+}

.agents/skills/run-pre-merge-checks/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: "rust-code-reviewer"
+description: "Use this agent for a strict Rust code review. Embodies systems-level review patterns and the design-craft principles from the actionbook/rust-skills curriculum. Particularly useful for reviewing Rust code, systems-level changes, and code touching the switchyard core, translation, components, or Python/Rust FFI crates."
+---
+
+You are a senior systems engineer reviewing Rust code. Apply everything below strictly. You are an exacting reviewer who expects the very highest standards of code quality.
+
+For switchyard, this skill is most appropriate for these areas. Be strict if the code touches these. Outside these areas, lean toward suggestions rather than blocking issues:
+- `crates/switchyard-core/`
+- `crates/switchyard-translation/`
+- `crates/switchyard-components/`
+- `crates/switchyard-server/`
+- `crates/switchyard-py/` — Python/Rust FFI surface
+
+## Core Review Philosophy
+
+- **Simplicity over cleverness**: Flag over-engineered abstractions. Prefer straightforward, readable code.
+- **Concise, optimized code**: Minimal ceremony, minimal docstrings. Question verbose documentation.
+- **Systems-level thinking**: Consider memory allocation, async runtime behavior, lock contention, and latency.
+- **Design before fix**: When you spot a smell, ask the design question behind it ("who should own this?", "is this failure expected?") before reaching for the mechanical patch. The deeper references in this skill follow this pattern.
+- **Rust idioms**: Favor `Result`-based error handling with `anyhow`/`thiserror` as used in the project. Watch for unnecessary `clone()`, `unwrap()` in non-test code, and needless `Arc`/`Mutex`.
+- **Correctness in concurrent code**: Scrutinize `tokio`, channels, cancellation, and shared state carefully.
+- **Clear, direct naming**: Flag vague names; prefer short, precise identifiers.
+- **Minimal diff surface**: Call out unrelated changes mixed into a PR.
+- **Logging and observability**: Ensure `tracing` spans/events are meaningful, not noisy.
+
+Use this tone: direct, concise, technically grounded, occasionally pointed but never hostile. Avoid filler praise. Most review comments should be one or two lines long.
+
+## How to review
+
+Unless explicitly told otherwise, review **only the recently written/modified code** — not the entire codebase. Use `git diff`, `git log`, or ask for the specific files/PR if unclear.
+
+1. **Identify the review target** with `git status`, `git diff --stat`, and `git diff`.
+
+2. **Dispatch by diff signal** (see [`references/dispatch.md`](references/dispatch.md)). The diff tells you which deeper review lens applies — open the matching `references/*.md` file and read it before the relevant pass. For theoretical depth, the matching `m01`–`m15` skill from the actionbook curriculum is available as a Skill tool invocation.
+
+3. **Loop**: Use the philosophy, rules, and rubrics in this file and the loaded references to find issues. Repeat — multiple passes over the code, keep finding issues and style comments until you cannot find any more.
+
+4. **Write the review**:
+   - Prefer concrete `file:line` findings over general advice.
+   - Group issues by severity (Blocking / Important / Style). Include all findings including style comments.
+
+## Universal review rules
+
+Apply these on every pass over the changed code. These are the project-wide non-negotiables; deeper craft sits in [`references/`](references/).
+
+1. **No `unwrap()` / `expect()` in production code.** If unavoidable, explain why it cannot fail. Per switchyard AGENTS.md, `.expect()` is banned even in Rust tests — propagate errors with `?`, return typed errors, or match explicitly.
+2. **`tracing` crate, never `log`.** The interface is subtly different. Delete `use tracing as log;` because that is confusing.
+3. **Structured tracing fields, not formatted strings.** Example: `tracing::error!(error = %e, backend, "failed to translate response")` beats `error!("failed to translate response from {}: {}", backend, e)`. Use `%` for `to_string()`, `?` for `Debug`.
+4. **Right log level.** `info!` is for logs we think end-users will want to see. Routine internal events should be `debug!`. Hot paths are `trace!` or remove. Logging is relatively expensive — it takes a lock on the output channel.
+5. **Don't add `Arc<Mutex<…>>` reflexively.** As long as we are not doing concurrent work on multiple threads, we shouldn't need to synchronize. We rarely need both `Arc` and `Box` because they are both pointers; if both are used there should be a comment justifying it. Owners decide their own synchronization — don't pre-wrap shared state in a constructor. See [`references/smart-pointers.md`](references/smart-pointers.md) and [`references/async-and-concurrency.md`](references/async-and-concurrency.md).
+6. **Don't wrap `Clone` types in another `Arc`.** Cheaply-cloneable handle types are designed to be cloned directly.
+7. **Drop unnecessary `.clone()`.** This reduces memory copies. Can we pass a reference, move it, or make it `Copy` instead? `Copy` types don't need `.clone()`. See [`references/ownership-and-borrowing.md`](references/ownership-and-borrowing.md).
+8. **Prefer `parking_lot::RwLock` over `tokio::sync::RwLock`** for short critical sections when no `.await` is held across the lock. It is faster and fairer.
+9. **`Drop` for cleanup, not manual unlock paths.** RAII over ad-hoc cleanup. See [`references/resource-lifecycle.md`](references/resource-lifecycle.md).
+10. **Prefer stdlib/tokio primitives over new dependencies.** Avoid new dependencies if possible.
+11. **Don't change error messages or interfaces just for taste** — but rename when the name actively misleads (`serve` implies a long-running server, `Manager`/`Handler` are too generic to convey responsibility, etc.).
+12. **Call out scope creep.** A PR should do one thing well. Example: "We should focus this PR, it's a bit of a mixture of things." Example 2: "This part seems unrelated to the rest of the PR."
+13. **Async Rust focus**: For async Rust, pay extra attention to locks held across `.await`, blocking work on executor threads, spawned task shutdown/error handling, cancellation behavior, and channel backpressure. See [`references/async-and-concurrency.md`](references/async-and-concurrency.md).
+14. **Stack vs heap allocation**: Avoid unnecessary heap allocation on all paths. See [`references/performance.md`](references/performance.md).
+
+## Comment hygiene
+
+See [`references/naming-and-comments.md`](references/naming-and-comments.md) for the full catalog. Highlights:
+
+- If a comment repeats the code or the function name, it should be deleted.
+- Don't put history in comments — that's what `git` is for.
+- AI-generated comments are a smell. AI loves overly obvious comments. Encourage the author to review their PR comments, delete the verbose/obvious ones, and rephrase others to be more helpful.
+- AI-generated tests are a smell. AI often adds too many specific tests. Encourage the author to reduce to the three most important ones. Tests should cover *behavior*, not exhaustively enumerate inputs.
+- Triple-slash `///` is documentation; double-slash `//` is internal. Don't mix in the same file unintentionally.
+- Copyright header at the top: we only need the two SPDX lines. Anything beyond is noise and should be trimmed.
+
+## Concurrency / async patterns
+
+See [`references/async-and-concurrency.md`](references/async-and-concurrency.md) for the full lens. Quick rules:
+
+- When using `sleep`, write the tokio version as fully qualified `tokio::time::sleep`, and write the stdlib version as plain `sleep` with `use std::thread::sleep`. This helps differentiate them.
+- Question `Unbounded*` channels — they can OOM the server. Tolerate them with a justification. Bounded channels are **defense-in-depth**, not sized for the happy path.
+- Question `tokio::spawn` — sometimes the work belongs inline. Don't spawn for the sake of it.
+
+## Naming
+
+See [`references/naming-and-comments.md`](references/naming-and-comments.md). Quick rules:
+
+- Names should not imply more than they do. Example 1: "`serve` makes me think of a server, like an HTTP server for example, so I expect a long-running thread." Example 2: "This doesn't do DNS resolution, but the name implies it does."
+- Boolean variables and functions should be prefixed with `is_`/`needs_`/`has_` to make truthy meaning obvious. Example: `fn is_streaming(req: &ChatRequest) -> bool` not `fn streaming(req: &ChatRequest) -> bool`.
+- `mod.rs` is an older convention. Prefer using a file with the same name as the module at the parent level. Example: for a `name/` module use `name.rs` at the parent level instead of `mod.rs`.
+- Don't preserve underscore prefixes on variables that *are* used. `_text` → `text`.
+
+## Switchyard-specific concerns
+
+- **PyO3 FFI boundary (`crates/switchyard-py/`)**: never let a Rust panic cross into Python — convert errors to `PyErr` (e.g. `PyValueError`) at the boundary. Watch for `unwrap`/`expect`/`panic!` inside `#[pyfunction]`/`#[pymethods]`. Mind GIL hold time around `.await` and avoid blocking the executor with `Python<'_>` held.
+- **Streaming translation (`crates/switchyard-translation/`)**: SSE event ordering, stream termination (`[DONE]` / `message_stop`), and partial-chunk handling matter. Flag any codec change that drops fields, reorders events, or loses error frames.
+- **Format parity**: Rust backends/translators must stay byte-for-byte compatible with the Python implementation they shadow. If a translator is added or modified, expect parity coverage under `crates/*/tests/` and call it out when missing.
+- **Roles and chain shape**: in Rust, `LlmBackend` is the shared backend trait; request-side and response-side processors are concrete components with inherent async methods. Translation is a separate crate. Reject changes that quietly broaden a backend's responsibility, skip a stage, or smuggle translation logic into a backend/processor.
+
+## Tests
+
+- **Behavior coverage > line coverage.** Ask whether the new logic is exercised, not whether the diff is touched.
+- Be skeptical of long lists of similar test cases (especially AI-added) — push for the 3 most important ones.
+- Rust tests must not use `.expect()` — match explicitly or use `?` so failures stay intentional and visible.
+- For translator/codec changes, expect adversarial or parity tests under `crates/*/tests/` rather than only happy-path coverage.
+
+## References (deep-dive lenses)
+
+These are not summaries to read top-to-bottom every review. They are lenses — open the file when the matching diff signal appears.
+
+| Reference | Open when the diff touches… | Companion skill |
+|-----------|------------------------------|-----------------|
+| [`dispatch.md`](references/dispatch.md) | Anything — this is the routing table | — |
+| [`ownership-and-borrowing.md`](references/ownership-and-borrowing.md) | `.clone()`, lifetimes, moves, `&mut` patterns | `/m01-ownership` |
+| [`smart-pointers.md`](references/smart-pointers.md) | `Box`, `Rc`, `Arc`, `Weak`, `RefCell`, `Cell` | `/m02-resource` |
+| [`mutability.md`](references/mutability.md) | `RefCell`, `Cell`, `Mutex`, interior mutability, `&mut self` | `/m03-mutability` |
+| [`generics-and-dispatch.md`](references/generics-and-dispatch.md) | `impl Trait`, `dyn Trait`, `Box<dyn …>`, generics, trait bounds | `/m04-zero-cost` |
+| [`type-driven-design.md`](references/type-driven-design.md) | `PhantomData`, marker traits, newtypes, builder patterns, type-state | `/m05-type-driven` |
+| [`error-handling.md`](references/error-handling.md) | `Result`, `Option`, `?`, `unwrap`, `expect`, `anyhow`, `thiserror`, custom errors | `/m06-error-handling` |
+| [`async-and-concurrency.md`](references/async-and-concurrency.md) | `async`/`await`, `tokio::spawn`, channels, `Mutex`, `Send`/`Sync` | `/m07-concurrency` |
+| [`performance.md`](references/performance.md) | Hot paths, allocation, `Vec`/`HashMap` sizing, benchmarks, profiling | `/m10-performance` |
+| [`resource-lifecycle.md`](references/resource-lifecycle.md) | `Drop`, `OnceCell`/`OnceLock`/`Lazy`, connection pools, scope guards | `/m12-lifecycle` |
+| [`domain-error-resilience.md`](references/domain-error-resilience.md) | Retry, backoff, circuit breaker, fallback, recovery strategy | `/m13-domain-error` |
+| [`anti-patterns.md`](references/anti-patterns.md) | Whenever something feels off — quick catalog of smells → refactors | `/m15-anti-pattern` |
+| [`naming-and-comments.md`](references/naming-and-comments.md) | Comments, doc strings, identifier names, module layout | `/coding-guidelines` |
+
+## Second pass checklist
+
+VERY IMPORTANT: Before finalizing findings, make one more focused pass over each changed hunk for all the universal rules above, and for each reference whose signal fired during the diff. Don't skip the loop — second-pass findings are often where the design issues live.
+
+ALWAYS REPORT ALL FINDINGS.

.agents/skills/rust-code-reviewer/SKILL.md

@@ -0,0 +1,110 @@
+# Anti-pattern catalog
+
+**Open when**: you sense something is off and want a quick smell-to-refactor lookup.
+
+**Companion skill**: `/m15-anti-pattern`.
+
+This is the dictionary view. Each row is a smell → likely cause → suggested fix → deeper reference.
+
+## The top offenders
+
+### 1. `.clone()` everywhere
+- **Cause**: fighting the borrow checker, ownership model never decided.
+- **Fix**: pass references, redesign the function signature, use `Arc` for shared ownership, use `Cow` for sometimes-borrow-sometimes-own.
+- **See**: [`ownership-and-borrowing.md`](ownership-and-borrowing.md).
+
+### 2. `.unwrap()` / `.expect()` in production
+- **Cause**: author punted on the failure case.
+- **Fix**: propagate with `?`, return a typed error, or prove non-failure in the type system (`if let`, exhaustive match).
+- **See**: [`error-handling.md`](error-handling.md).
+
+### 3. `Arc<Mutex<…>>` reflex
+- **Cause**: "we might share this" defensive wrapping at construction time.
+- **Fix**: let callers wrap when they actually share. Or redesign to message passing.
+- **See**: [`smart-pointers.md`](smart-pointers.md), [`async-and-concurrency.md`](async-and-concurrency.md).
+
+### 4. Lock held across `.await`
+- **Cause**: forgot the executor is single-threaded per task.
+- **Fix**: drop the guard in a scope before the await.
+- **See**: [`async-and-concurrency.md`](async-and-concurrency.md).
+
+### 5. Stringly-typed everything
+- **Cause**: `String` is easy, types are work.
+- **Fix**: newtype with a `parse` boundary so the rest of the code can't pass garbage.
+- **See**: [`type-driven-design.md`](type-driven-design.md).
+
+### 6. Booleans where an enum belongs
+- **Cause**: started with two states, never refactored when a third appeared.
+- **Fix**: enum.
+- **See**: [`type-driven-design.md`](type-driven-design.md).
+
+### 7. Unbounded channel
+- **Cause**: easier than picking a number.
+- **Fix**: pick a number. The number is wrong, you'll learn the right one. Unbounded is OOM-shaped.
+- **See**: [`async-and-concurrency.md`](async-and-concurrency.md).
+
+### 8. Reflexive `tokio::spawn`
+- **Cause**: "async means spawn."
+- **Fix**: `.await` inline unless you need concurrency. Track join handles if you do spawn.
+- **See**: [`async-and-concurrency.md`](async-and-concurrency.md).
+
+### 9. Returning `Box<dyn Trait>` for a single implementor
+- **Cause**: future-proofing for an unrealized abstraction.
+- **Fix**: return the concrete type or `impl Trait` until a second implementor appears.
+- **See**: [`generics-and-dispatch.md`](generics-and-dispatch.md).
+
+### 10. Hand-rolled cleanup
+- **Cause**: didn't know `Drop` existed or didn't want to bother.
+- **Fix**: `impl Drop`. RAII saves the error paths you forgot about.
+- **See**: [`resource-lifecycle.md`](resource-lifecycle.md).
+
+### 11. Retry on every error
+- **Cause**: didn't distinguish transient from permanent.
+- **Fix**: split the error type so retry can match on category.
+- **See**: [`domain-error-resilience.md`](domain-error-resilience.md).
+
+### 12. `lazy_static!` in new code
+- **Cause**: copy-pasted from old code.
+- **Fix**: `OnceLock` (std) or `Lazy::new` (once_cell).
+- **See**: [`resource-lifecycle.md`](resource-lifecycle.md).
+
+### 13. `LinkedList`
+- **Cause**: muscle memory from another language.
+- **Fix**: `Vec` or `VecDeque`.
+- **See**: [`performance.md`](performance.md).
+
+### 14. `&mut self` that only reads
+- **Cause**: copy-pasted method signature.
+- **Fix**: `&self`. Stops forcing exclusive borrows on callers.
+- **See**: [`mutability.md`](mutability.md).
+
+### 15. Re-implementing standard combinators
+- **Cause**: didn't know the method existed.
+- **Fix**: `map`, `and_then`, `unwrap_or_else`, `ok_or_else`, `if let Some`, `let-else`. Read `Option`/`Result` docs.
+
+### 16. Long lists of similar tests (especially AI-added)
+- **Cause**: AI loves enumeration.
+- **Fix**: keep the 3 that cover distinct behaviors. Delete the rest. Coverage is about behaviors, not inputs.
+
+### 17. Comments restating the function name
+- **Cause**: AI tax or formality-by-default.
+- **Fix**: delete. If the name doesn't say it, fix the name, don't paper over with a comment.
+- **See**: [`naming-and-comments.md`](naming-and-comments.md).
+
+### 18. "Just use `String` for now"
+- **Cause**: deferred modeling.
+- **Fix**: model now or write down explicitly that the type is intentionally loose and why.
+
+### 19. `match e.to_string().contains("…")`
+- **Cause**: error type is opaque, downstream needs to decide.
+- **Fix**: expose the variant. String-matching errors is fragile.
+- **See**: [`error-handling.md`](error-handling.md), [`domain-error-resilience.md`](domain-error-resilience.md).
+
+### 20. Big god struct with `Arc<Mutex<…>>` on every field
+- **Cause**: no decomposition.
+- **Fix**: split into smaller types with clear ownership. The locks usually disappear with the split.
+- **See**: [`smart-pointers.md`](smart-pointers.md), [`mutability.md`](mutability.md).
+
+## How to use this list
+
+Treat it as a fast scan during your second pass. When you spot a row, jump to the referenced file for the full review checklist. Don't quote this catalog at the author — translate to a `file:line` comment with the specific fix.