@pratikpsl/agent-skills 1.1.0 → 1.3.0

package/templates/python/AgentSkills/skills/performance/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: performance
+description: Python profiling, generator patterns, async concurrency, and memory optimization.
+---
+
+# Python Performance
+
+## Profiling First
+- Measure before optimizing: use `cProfile`/`profile` for CPU and `memray` or `tracemalloc` for memory.
+- Profile realistic workloads, not microbenchmarks, to find true hot paths.
+
+## Memory Efficiency
+- Prefer generators and iterators (`yield`) over materializing full lists in memory for large data sets.
+- Use `__slots__` on classes with many instances to eliminate per-instance `__dict__` overhead.
+- Use `functools.lru_cache` or `functools.cache` for pure, referentially transparent functions called repeatedly with the same arguments.
+
+## Async Concurrency
+- Use `asyncio.gather(*tasks)` or `asyncio.TaskGroup` for I/O-bound fan-out; avoid sequential `await` in a loop when tasks are independent.
+- Use connection pools (e.g. `asyncpg` pool, `httpx.AsyncClient`) — never create a new connection per request.
+- Offload CPU-bound work to a `ProcessPoolExecutor` via `loop.run_in_executor`; do not block the event loop.
+
+## Data & Algorithm Choices
+- Use built-in types (`list`, `dict`, `set`) over third-party equivalents for simple cases; they are implemented in C.
+- Use `collections.deque` for queue workloads; avoid `list.pop(0)` (O(n)).
+- Avoid repeated string concatenation in loops; use `"".join(parts)` instead.
+- Prefer comprehensions over `map`/`filter` with lambdas for readability and slight speed advantages.

package/templates/python/AgentSkills/skills/python-best-practices/SKILL.md

@@ -0,0 +1,59 @@
+---
+name: python-best-practices
+description: >
+  Load when writing, reviewing, refactoring, or optimizing Python code.
+  Covers PEP conventions, uv project management, async patterns, error handling,
+  structured logging, and maintainability.
+---
+
+# Python Best Practices
+
+## Naming Conventions (PEP 8)
+- **Modules & packages**: `snake_case` (`user_service.py`, `auth/`)
+- **Functions & variables**: `snake_case` (`get_user`, `is_valid`)
+- **Classes**: `PascalCase` (`UserService`, `OrderRepository`)
+- **Constants**: `UPPER_SNAKE_CASE` (`MAX_RETRIES`, `DEFAULT_TIMEOUT`)
+- **Private members**: single underscore prefix (`_internal_helper`)
+- **Dunder methods**: reserved for Python protocols (`__init__`, `__repr__`)
+
+## Project Setup with uv
+```bash
+uv init my-project          # scaffold pyproject.toml, src layout
+uv add fastapi pydantic      # add runtime dependencies
+uv add --dev pytest mypy ruff  # add dev dependencies
+uv sync                      # install from uv.lock
+uv run pytest                # run commands in the managed venv
+```
+- Always use `uv`; never run bare `pip install` against the global environment.
+- Declare all metadata in `pyproject.toml` (`[project]`, `[build-system]`, tool configs).
+
+## Code Quality & Formatting
+- Use `ruff` for linting and formatting (replaces `flake8`, `isort`, `black`).
+- Enable `ruff` rules `E`, `F`, `I`, `UP`, `ANN` at minimum in `pyproject.toml`.
+- Run `mypy --strict` in CI; no type errors are acceptable in production code.
+
+## Async & I/O
+- Use `async`/`await` for all I/O-bound operations (HTTP, database, file, queue).
+- Never call blocking functions (`time.sleep`, `open()`, sync DB calls) inside an async context; use their async equivalents.
+- Use `asyncio.TaskGroup` (Python 3.11+) for structured concurrent tasks.
+- Propagate `asyncio.CancelledError`; never catch it without re-raising.
+
+## Error Handling
+- Define domain-specific exception classes inheriting from a project base (`AppError`).
+- Catch the narrowest exception type possible; never use bare `except:` or `except Exception:` without logging and re-raising.
+- Use `contextlib.suppress` only for explicitly expected, recoverable errors.
+
+## Logging
+- Use structured logging (`structlog` or `logging` with a JSON formatter) — never `print()` in production code.
+- Bind contextual fields (request IDs, user IDs) to the logger at request scope.
+- Never log secrets, tokens, passwords, or PII.
+
+## Review Checklist
+- [ ] All names follow PEP 8 conventions.
+- [ ] `uv` used for dependency management; `pyproject.toml` up to date.
+- [ ] No bare `pip install` or unpinned dependencies.
+- [ ] `ruff` passes with zero errors.
+- [ ] `mypy --strict` passes with zero errors.
+- [ ] No blocking calls inside `async` functions.
+- [ ] Structured logging used; no `print()` statements remain.
+- [ ] Narrow exception handling; no silent swallowing of errors.

package/templates/python/AgentSkills/skills/python-typing/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: python-typing
+description: >
+  Load when writing or reviewing Python code. Covers strict static typing with mypy/pyright,
+  pydantic data models, Protocol, TypeVar, Literal, and TypedDict patterns.
+---
+
+# Python Static Typing
+
+## Module Setup
+- Add `from __future__ import annotations` as the first import in every module to enable postponed evaluation of annotations (PEP 563).
+- Enable strict mode in `pyproject.toml`:
+  ```toml
+  [tool.mypy]
+  strict = true
+  warn_return_any = true
+  disallow_untyped_defs = true
+  ```
+
+## Function & Variable Annotations
+- Annotate every function parameter, return type, and class attribute without exception.
+- Use `None` as an explicit return type for functions that return nothing; never omit the annotation.
+- Avoid `Any` — use `object` for truly unknown types, or narrow with generics and `TypeVar`.
+
+## Type Constructs
+- **`TypeAlias`**: Use `type Alias = ...` (Python 3.12+) or `TypeAlias` from `typing` for readable compound types.
+- **`Protocol`**: Prefer structural subtyping (`Protocol`) over ABCs for dependency injection and testability.
+- **`TypeVar` / `ParamSpec`**: Use for generic functions and decorators; constrain with `bound=` where applicable.
+- **`Literal`**: Use `Literal["value"]` to narrow string/int constants in type signatures.
+- **`TypedDict`**: Use for dict shapes at external boundaries (JSON, config); prefer `pydantic.BaseModel` for mutable internal models.
+
+## Pydantic Models
+- Define all data contracts as `pydantic.BaseModel` subclasses; never pass raw `dict` across layer boundaries.
+- Use `model_config = ConfigDict(frozen=True)` for immutable value objects.
+- Validate external inputs at the outermost boundary (API, CLI, queue consumer) before passing into application logic.
+
+## Review Checklist
+- [ ] `from __future__ import annotations` present in every module.
+- [ ] No `Any` without a documented justification comment.
+- [ ] All function signatures fully annotated (parameters + return).
+- [ ] Pydantic models used at all data boundaries.
+- [ ] `mypy --strict` passes with zero errors.

package/templates/python/AgentSkills/skills/testing/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: testing
+description: Python unit, async, and property-based testing with pytest, pytest-asyncio, and hypothesis.
+---
+
+# Python Testing
+
+## Testing Principles
+- Test observable behavior and public interfaces, not internal implementation details.
+- Follow the **Arrange-Act-Assert (AAA)** pattern in every test.
+- Keep tests isolated, deterministic, and independent of execution order or external state.
+
+## Project Setup
+- Use `pytest` as the sole test runner; install via `uv add --dev pytest pytest-asyncio pytest-mock hypothesis`.
+- Configure in `pyproject.toml`:
+  ```toml
+  [tool.pytest.ini_options]
+  asyncio_mode = "auto"
+  ```
+- Run tests with `uv run pytest`.
+
+## Test Naming & Structure
+- Name test files `test_<module>.py` and place them under a top-level `tests/` directory mirroring the `src/` layout.
+- Name test functions: `test_<function>_<scenario>_<expected>` (e.g., `test_create_user_duplicate_email_raises_conflict`).
+- Match test class names to the class under test: `TestUserService` for `UserService`.
+
+## Fixtures & Parametrize
+- Use `@pytest.fixture` for shared setup; prefer function-scoped fixtures unless sharing is explicitly required.
+- Use `@pytest.mark.parametrize` for data-driven cases covering multiple inputs and edge cases.
+- Mock external I/O boundaries (HTTP, DB, file system) using `pytest-mock` (`mocker.patch`) — never hit real services in unit tests.
+
+## Async Testing
+- Annotate async test functions with `async def`; `asyncio_mode = "auto"` removes the need for `@pytest.mark.asyncio`.
+- Use `AsyncMock` from `unittest.mock` to mock async callables and coroutines.
+
+## Property-Based Testing
+- Use `hypothesis` for algorithmic and data-parsing logic where exhaustive edge-case enumeration is impractical.
+- Define `@given(st.text(), st.integers())` strategies; always run with a fixed `settings(max_examples=200)` in CI.
+
+## Coverage & Quality
+- Target 100% coverage on domain and application layers; exclude infrastructure adapters only with justification.
+- Run `uv run pytest --cov=src --cov-report=term-missing` in CI.

package/templates/react/AgentSkills/skills/index.md

@@ -0,0 +1,13 @@
+# Skills Index
+
+Consult this index to load only the skills relevant to the current task.
+
+| Skill | Path | Description / When to Load |
+| --- | --- | --- |
+| principles | AgentSkills/skills/principles/SKILL.md | Foundational simplicity ladder, KISS, YAGNI, surgical changes |
+| standards | AgentSkills/skills/standards/SKILL.md | Code quality, 50-line limits, shallow nesting, clean signatures |
+| security | AgentSkills/skills/security/SKILL.md | Input validation, secrets handling, safe queries, least privilege |
+| review | AgentSkills/skills/review/SKILL.md | Code review framework, five review dimensions, verification rules |
+| react-typescript | AgentSkills/skills/react-typescript/SKILL.md | React & TypeScript props typing, custom hooks, discriminated unions |
+| testing | AgentSkills/skills/testing/SKILL.md | Vitest & React Testing Library, user-event, test coverage |
+| performance | AgentSkills/skills/performance/SKILL.md | Render optimization, lazy loading, state colocation, memoization |

package/templates/rust/AgentSkills/agents/architect.md

@@ -0,0 +1,14 @@
+---
+name: architect
+description: Rust workspace design, crate boundaries, trait-based API design, and visibility rules.
+---
+
+# Rust Architect
+
+## Architectural Principles
+- **Workspace Layout**: Use a Cargo workspace (`[workspace]` in root `Cargo.toml`) to separate concerns: e.g. `crates/domain`, `crates/api`, `crates/infra`, `crates/cli`. Each crate has one responsibility.
+- **Visibility Minimization**: Default to `pub(crate)` for intra-workspace sharing; expose items as `pub` only when they form the deliberate public API of the crate.
+- **Trait-Based Design**: Define behavior through traits; depend on trait abstractions (not concrete types) at crate boundaries to enable testing and future substitution without coupling.
+- **Contract-First**: Define data types (`struct`, `enum`) and trait interfaces before implementing business logic. Types are the primary design artifact.
+- **Dependency Direction**: Application crates depend on domain crates; infrastructure crates depend on application traits; no domain crate imports from infrastructure.
+- **Genuine Reusability**: Extract shared code into a library crate only when two or more crates genuinely share the same logic. Avoid premature abstraction (YAGNI).

package/templates/rust/AgentSkills/agents/developer.md

@@ -0,0 +1,24 @@
+---
+name: developer
+description: Rust feature implementation, ownership, async with tokio, and idiomatic error propagation.
+---
+
+# Rust Developer
+
+## Implementation Principles
+- **Ownership First**: Design types and function signatures to express ownership intent clearly. Prefer borrowing (`&T`, `&mut T`) over cloning in hot paths; clone only when ownership transfer is genuinely required.
+- **Idiomatic Error Handling**: Use `Result<T, E>` and propagate errors with `?`. Never `unwrap()` or `expect()` in production code paths — reserve them for tests and infallible cases with a comment explaining why.
+- **Zero-Cost Abstractions**: Prefer traits over dynamic dispatch (`Box<dyn Trait>`) unless runtime polymorphism is a firm requirement. Use generics for static dispatch.
+- **Complexity Limits**: Keep functions under 50 lines; maximum 2 levels of nesting; use early `return` or `?` to flatten control flow.
+- **No Magic Literals**: Replace all magic numbers and strings with named constants (`const`) or `enum` variants.
+
+## Tooling Discipline
+- Format every file with `rustfmt` before committing (`cargo fmt`).
+- Fix all `clippy` warnings before committing (`cargo clippy -- -D warnings`).
+- Use `cargo check` as the fast feedback loop during development.
+
+## Async & Concurrency
+- Use `tokio` as the async runtime for all I/O-bound work.
+- Annotate async entry points and test functions with `#[tokio::main]` and `#[tokio::test]`.
+- Use `tokio::spawn` for independent concurrent tasks; use `tokio::join!` or `tokio::try_join!` to await multiple tasks.
+- Protect shared mutable state with `Arc<Mutex<T>>` or `Arc<RwLock<T>>`; prefer message-passing (`tokio::sync::mpsc`) over shared state where possible.

package/templates/rust/AgentSkills/skills/index.md

@@ -0,0 +1,14 @@
+# Skills Index
+
+Consult this index to load only the skills relevant to the current task.
+
+| Skill | Path | Description / When to Load |
+| --- | --- | --- |
+| principles | AgentSkills/skills/principles/SKILL.md | Foundational simplicity ladder, KISS, YAGNI, surgical changes |
+| standards | AgentSkills/skills/standards/SKILL.md | Code quality, 50-line limits, shallow nesting, clean signatures |
+| security | AgentSkills/skills/security/SKILL.md | Input validation, secrets handling, safe queries, least privilege |
+| review | AgentSkills/skills/review/SKILL.md | Code review framework, five review dimensions, verification rules |
+| rust-best-practices | AgentSkills/skills/rust-best-practices/SKILL.md | API guidelines, cargo clippy/fmt, thiserror/anyhow, tracing logging |
+| rust-ownership | AgentSkills/skills/rust-ownership/SKILL.md | Ownership, borrowing, lifetimes, Arc/Mutex, Send+Sync safety |
+| testing | AgentSkills/skills/testing/SKILL.md | cargo test, tokio::test, proptest property testing, mockall |
+| performance | AgentSkills/skills/performance/SKILL.md | criterion benchmarking, zero-copy parsing, allocation reduction |

package/templates/rust/AgentSkills/skills/performance/SKILL.md

@@ -0,0 +1,43 @@
+---
+name: performance
+description: Rust benchmarking with criterion, zero-copy design, allocation reduction, and async task efficiency.
+---
+
+# Rust Performance
+
+## Measure First
+- Profile before optimizing: use `criterion` for micro-benchmarks and `cargo flamegraph` (or `perf`) for real workload profiling.
+- Compile with `--release` for all performance measurements; debug builds have no optimizations.
+
+## Allocation & Copy Reduction
+- Prefer borrowing (`&str`, `&[T]`) over owned types (`String`, `Vec<T>`) in hot paths; clone only when ownership transfer is necessary.
+- Use `Cow<'_, str>` to defer allocation until a mutation is actually needed.
+- Use `SmallVec` or fixed-size arrays for collections that are almost always small.
+- Avoid boxing (`Box<T>`) in hot paths; prefer stack allocation for small, fixed-size types.
+
+## Zero-Copy Parsing
+- Use `bytes::Bytes` and slicing for zero-copy network data parsing.
+- Avoid intermediate `String` allocations when parsing structured data; work with `&[u8]` slices directly where possible.
+
+## Async Task Efficiency
+- Minimize the number of `tokio::spawn` calls; spawning is cheap but not free — batch work where possible.
+- Avoid holding `Mutex` guards across `.await` points; release before yielding.
+- Use `tokio::sync::watch` or `tokio::sync::broadcast` for fan-out notifications instead of multiple `Mutex`-protected `Vec` callbacks.
+
+## Iterator Pipelines
+- Use lazy iterator adapters (`map`, `filter`, `flat_map`) over imperative loops; the compiler optimizes chains to a single pass.
+- Prefer `collect::<Vec<_>>()` once at the end of a pipeline rather than intermediate materialization.
+- Use `par_iter()` from `rayon` for CPU-bound parallel data processing — only after profiling confirms a bottleneck.
+
+## Benchmarking
+```rust
+use criterion::{criterion_group, criterion_main, Criterion};
+
+fn bench_parse(c: &mut Criterion) {
+    c.bench_function("parse_record", |b| b.iter(|| parse(INPUT)));
+}
+
+criterion_group!(benches, bench_parse);
+criterion_main!(benches);
+```
+Run with `cargo bench`.

package/templates/rust/AgentSkills/skills/rust-best-practices/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: rust-best-practices
+description: >
+  Load when writing, reviewing, refactoring, or optimizing Rust code.
+  Covers naming conventions, clippy/rustfmt enforcement, error handling with
+  thiserror/anyhow, structured logging with tracing, and Cargo workspace layout.
+---
+
+# Rust Best Practices
+
+## Naming Conventions (Rust API Guidelines)
+- **Types & Traits**: `PascalCase` (`UserRepository`, `Deserialize`)
+- **Functions, methods, variables, modules**: `snake_case` (`get_user`, `user_service`)
+- **Constants & statics**: `UPPER_SNAKE_CASE` (`MAX_CONNECTIONS`, `DEFAULT_TIMEOUT`)
+- **Lifetime parameters**: short lowercase single letters (`'a`, `'db`)
+- **Crates**: `snake_case` for library crates, `kebab-case` in `Cargo.toml` names
+
+## Tooling Discipline
+- **Format**: `cargo fmt` — enforce in CI with `cargo fmt --check`.
+- **Lint**: `cargo clippy -- -D warnings` — all warnings are errors in CI; suppress individually only with a comment explaining the justification.
+- **Audit**: `cargo audit` — run in CI to catch known vulnerabilities in dependencies.
+- **Build**: `cargo check` for fast feedback; `cargo build --release` for benchmarks and deployment.
+
+## Error Handling
+- Use `thiserror` to define typed, domain-specific errors for library crates.
+- Use `anyhow` for application-level error aggregation and context chaining (`context()`, `with_context()`).
+- Never use `unwrap()` or `expect()` in production paths; propagate with `?`.
+- Return `Result<T, E>` from all fallible functions; reserve `panic!` for truly unrecoverable programmer errors.
+
+## Logging & Observability
+- Use `tracing` for structured, async-aware logging: `tracing::info!`, `tracing::error!`, `tracing::instrument`.
+- Attach contextual fields with `#[tracing::instrument(fields(user_id = %id))]`.
+- Initialize the subscriber once at the application entry point (`tracing_subscriber::fmt::init()`).
+- Never log secrets, tokens, passwords, or sensitive personal data.
+
+## Dependency Management
+- Minimize external dependencies; evaluate the maintenance status and license before adding a new crate.
+- Add dev-only dependencies under `[dev-dependencies]` in `Cargo.toml`.
+- Use feature flags to keep the dependency graph lean (`default-features = false`).
+
+## Review Checklist
+- [ ] `cargo fmt --check` passes.
+- [ ] `cargo clippy -- -D warnings` passes with zero warnings.
+- [ ] No `unwrap()` / `expect()` in non-test production code.
+- [ ] `thiserror` used for library errors; `anyhow` for application errors.
+- [ ] Structured `tracing` logging used; no `println!` in production.
+- [ ] `cargo audit` passes; no known vulnerabilities.
+- [ ] All public API items documented with `///` doc comments.

package/templates/rust/AgentSkills/skills/rust-ownership/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: rust-ownership
+description: >
+  Load when writing or reviewing Rust code. Covers ownership, borrowing, lifetimes,
+  shared-state concurrency with Arc/Mutex, and Send + Sync safety.
+---
+
+# Rust Ownership & Borrowing
+
+## Core Rules
+- A value has exactly one owner at a time; ownership transfers on move.
+- Borrow immutably (`&T`) as many times as needed, or mutably (`&mut T`) exactly once — never both simultaneously.
+- References must never outlive the value they point to; the compiler enforces this via lifetimes.
+
+## Lifetime Annotations
+- Add explicit lifetime annotations (`'a`) only when the compiler cannot infer them — let elision work first.
+- For structs that hold references, annotate struct lifetime parameters and bound them on the relevant fields.
+- Prefer owned types (`String`, `Vec<T>`) over references in public APIs to avoid lifetime propagation into callers.
+
+## Shared State
+- Use `Arc<Mutex<T>>` for shared mutable state across threads; use `Arc<RwLock<T>>` when reads dominate.
+- Lock mutexes for the shortest scope possible; never hold a lock across an `.await` point.
+- Prefer message-passing (`tokio::sync::mpsc`, `std::sync::mpsc`) over shared state when tasks are naturally producer/consumer.
+
+## Send & Sync
+- Ensure types shared across thread boundaries implement `Send + Sync`; the compiler enforces this.
+- Avoid `Rc<T>` and `Cell<T>` in async or multi-threaded contexts; use `Arc` and `Mutex` instead.
+- Use `#[derive(Clone)]` sparingly on types that are expensive to clone; document where clones occur.
+
+## Common Pitfalls
+- Never use `unwrap()` or `expect()` in production paths — propagate errors with `?` instead.
+- Avoid `clone()` as a workaround for borrow-checker conflicts; restructure ownership or use a reference instead.
+- Do not hold a `MutexGuard` across an `await` point — drop it explicitly before awaiting.
+
+## Review Checklist
+- [ ] No `unwrap()` / `expect()` in non-test production code.
+- [ ] No `clone()` used to paper over borrow-checker issues.
+- [ ] Explicit lifetime annotations present only where elision fails.
+- [ ] `Mutex` guards released before any `.await` points.
+- [ ] `Arc<Mutex<T>>` used for all cross-thread mutable state.

package/templates/rust/AgentSkills/skills/testing/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: testing
+description: Rust unit, async, integration, and property-based testing with cargo test, tokio::test, and proptest.
+---
+
+# Rust Testing
+
+## Testing Principles
+- Test observable behavior through public interfaces, not internal implementation details.
+- Follow the **Arrange-Act-Assert (AAA)** pattern in every test.
+- Keep tests isolated, deterministic, and independent of execution order or external state.
+
+## Unit Tests
+- Place unit tests in the same file as the code under test inside a `#[cfg(test)]` module:
+  ```rust
+  #[cfg(test)]
+  mod tests {
+      use super::*;
+
+      #[test]
+      fn create_user_valid_input_returns_ok() {
+          // Arrange / Act / Assert
+      }
+  }
+  ```
+- Use descriptive names: `fn <function>_<scenario>_<expected>`.
+
+## Async Tests
+- Use `#[tokio::test]` for async test functions:
+  ```rust
+  #[tokio::test]
+  async fn fetch_user_not_found_returns_error() { ... }
+  ```
+- Mock async I/O boundaries with `mockall` (`#[automock]`) — never hit real services in unit tests.
+
+## Integration Tests
+- Place integration tests in the top-level `tests/` directory; each file is a separate test binary.
+- Use `common/mod.rs` (or `common.rs`) under `tests/` for shared test helpers and fixtures.
+- Run with `cargo test --test <name>`.
+
+## Property-Based Testing
+- Use `proptest` for algorithmic and parsing logic where exhaustive edge-case enumeration is impractical.
+  ```rust
+  proptest! {
+      #[test]
+      fn parse_roundtrip(s in "\\PC*") { ... }
+  }
+  ```
+
+## Mocking
+- Use `mockall` to generate mocks for traits: annotate the trait with `#[automock]` and import `MockMyTrait` in tests.
+- Verify expectations explicitly with `.expect(n)` or `.times(n)` on mock methods.
+
+## Running Tests
+```bash
+cargo test                    # all tests
+cargo test --lib              # unit tests only
+cargo test --test integration  # integration tests only
+cargo test -- --nocapture     # show stdout during tests
+```

package/templates/shared/AgentSkills/OPERATING.md

@@ -2,10 +2,10 @@
 
 ## Workflow
 1. **Memory & Context**: Read `AgentSkills/memory/index.md` (create if missing); load only relevant domain lessons to avoid repeating past mistakes.
-2. **Role & Skill Discovery**: Load relevant role guidance from `AgentSkills/agents/` and skills from `AgentSkills/skills/`.
+2. **Role & Skill Discovery**: Consult `AgentSkills/skills/index.md` to identify and load task-specific skills from `AgentSkills/skills/` (including `AgentSkills/skills/review/SKILL.md`). Load relevant role guidance from `AgentSkills/agents/` (`architect.md`, `reviewer.md`, `developer.md`).
 3. **Pre-flight Inspection**: Inspect current codebase patterns, dependencies, and baseline build/test state.
 4. **Surgical Implementation**: Apply the minimal change required; adhere strictly to DRY, KISS, and YAGNI.
-5. **Verification**: Run the project's build and test commands (e.g. `npm test`, `dotnet test`, or project test suite) to verify happy paths and edge cases.
+5. **Verification**: Run the project's build and test commands (e.g. `npm test`, `dotnet test`, `cargo test`, `uv run pytest`, or project test suite) to verify happy paths and edge cases per `AgentSkills/skills/review/SKILL.md`.
 6. **Learning Loop**: If a mistake was made and corrected or a durable rule discovered, record a concise lesson in `AgentSkills/memory/lessons/<domain>.md` and update `index.md`.
 
 ## Completion Checklist

package/templates/shared/AgentSkills/agents/{reviewer.agent.md → reviewer.md}

@@ -11,6 +11,7 @@ Universal review guidance for AI agents and human reviewers across all stacks. S
 - **Principles**: Adhere strictly to `AgentSkills/skills/principles/SKILL.md`.
 - **Standards**: Adhere strictly to `AgentSkills/skills/standards/SKILL.md`.
 - **Security**: Adhere strictly to `AgentSkills/skills/security/SKILL.md`.
+- **Review**: Adhere strictly to `AgentSkills/skills/review/SKILL.md`.
 
 ## Verification & Automated Checks
 - [ ] **Clean Build**
@@ -22,6 +23,7 @@ Universal review guidance for AI agents and human reviewers across all stacks. S
 - [ ] **Principles**: `AgentSkills/skills/principles/SKILL.md`
 - [ ] **Standards**: `AgentSkills/skills/standards/SKILL.md`
 - [ ] **Security**: `AgentSkills/skills/security/SKILL.md`
+- [ ] **Review**: `AgentSkills/skills/review/SKILL.md`
 
 ## Memory & Learning Loop
 - [ ] **Agent Memory**: `AgentSkills/memory/index.md`

package/templates/shared/AgentSkills/skills/index.md

@@ -0,0 +1,10 @@
+# Skills Index
+
+Consult this index to load only the skills relevant to the current task.
+
+| Skill | Path | Description / When to Load |
+| --- | --- | --- |
+| principles | AgentSkills/skills/principles/SKILL.md | Foundational simplicity ladder, KISS, YAGNI, surgical changes |
+| standards | AgentSkills/skills/standards/SKILL.md | Code quality, 50-line limits, shallow nesting, clean signatures |
+| security | AgentSkills/skills/security/SKILL.md | Input validation, secrets handling, safe queries, least privilege |
+| review | AgentSkills/skills/review/SKILL.md | Code review framework, five review dimensions, verification rules |

package/templates/shared/AgentSkills/skills/principles/SKILL.md

@@ -28,4 +28,4 @@ Bug fix = root cause, not symptom. A bug report names a symptom. Grep every call
 - **Surgical Changes**: Make the smallest change that satisfies the request; touch only what is explicitly required.
 - **Simplicity First (KISS / YAGNI)**: Favor simple, clear, maintainable solutions over clever abstractions. Do not add unrequested features.
 - **Zero-Error Builds**: Every change must compile cleanly and pass existing and newly added tests.
-- **Standards & Security**: Adhere strictly to `AgentSkills/skills/standards/SKILL.md` and `AgentSkills/skills/security/SKILL.md`.
+- **Standards, Security & Review**: Adhere strictly to `AgentSkills/skills/standards/SKILL.md`, `AgentSkills/skills/security/SKILL.md`, and `AgentSkills/skills/review/SKILL.md`.

package/templates/shared/AgentSkills/skills/review/SKILL.md

@@ -0,0 +1,33 @@
+---
+name: review
+description: Code review framework, verification criteria, correctness, and review output standards.
+---
+
+# Code Review Guidelines
+
+Universal review framework and verification standards for AI agents and human reviewers across all stacks.
+
+## Five Review Dimensions
+1. **Correctness**: Verify behavior matches specifications, handle boundary/edge cases (null, empty, limits, errors), and ensure changes are free of race conditions.
+2. **Readability**: Ensure naming is domain-meaningful, control flow is simple (depth <= 2), and functions do not exceed 50 lines.
+3. **Architecture**: Adhere to SOLID, DRY, and KISS; keep clean module boundaries; avoid circular dependencies and speculative abstractions (YAGNI).
+4. **Security**: Validate untrusted inputs, use parameterized queries, never commit or log credentials/PII, and check for safe error handling.
+5. **Performance**: Avoid N+1 queries, unbounded loops, blocking operations in async flows, and redundant re-computations.
+
+## Verification & Automated Checks
+- [ ] **Clean Build**: Project builds cleanly with zero errors or warnings.
+- [ ] **Zero Lint Errors**: Code adheres to project formatting and static analysis rules.
+- [ ] **Tests Pass**: Run test suite; all existing and newly added tests must pass.
+- [ ] **Test Robustness**: Tests must cover failure paths, edge cases, and boundary conditions, not just happy paths.
+
+## Review Output Format
+Categorize every review finding clearly:
+- **Critical**: Must fix before merge (security flaw, data corruption, broken functionality).
+- **Important**: Should fix before merge (missing test coverage, poor error recovery, rule violation).
+- **Suggestion**: Optional improvements (naming, non-critical refactoring).
+
+## Review Rules
+- Review tests first to understand intent and coverage.
+- Address root causes over symptoms; fix shared logic once rather than patching callers.
+- Never weaken, skip, or delete existing tests to force a pass.
+- Provide concrete, actionable fixes for every Critical and Important finding.

package/templates/shared/AgentSkills/skills/standards/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: standards
-description: Core code quality, complexity limits, naming, and structural conventions.
+description: Core code quality, simplicity, complexity limits, naming, and structural conventions.
 ---
 
 # Code Standards
@@ -11,11 +11,20 @@ description: Core code quality, complexity limits, naming, and structural conven
 - **Clean Signatures**: Maximum 4 parameters per function; use an options object or record for complex signatures.
 
 ## Design & Clean Code
-- **SOLID / DRY / KISS**: Single-responsibility components; eliminate duplicated logic; prefer clear, direct implementations over speculative abstractions (YAGNI).
+- **Simplicity First (KISS / YAGNI)**: Favor simple, clear, maintainable solutions over clever abstractions. Do not add unrequested features.
+- **SOLID / DRY**: Single-responsibility components; eliminate duplicated logic; prefer clear, direct implementations over speculative abstractions (YAGNI).
+- **Less is more**: Avoid over-engineering; prefer fewer moving parts and simpler designs.
+- **Consistent Style**: Follow the repository's style guide; use linters and formatters to enforce consistency.
+- **Configuration & Defaults**: Provide sensible defaults and configuration options; avoid hardcoding values.
+- **separation of Concerns**: Keep business logic, data access, and presentation layers distinct; avoid mixing responsibilities.
+- **Modular Design**: Break down large components into smaller, reusable modules; prefer composition over inheritance.
+- **Dependency Management**: Minimize external dependencies; prefer standard libraries and well-maintained packages; avoid unnecessary bloat.
+- **self-Documenting Code**: Write code that is clear and understandable without excessive comments; use meaningful names and expressive constructs.
+- **security & Privacy**: Follow best practices for secure coding; validate inputs, sanitize outputs, and protect sensitive data.
 - **Naming & Clarity**: Use descriptive, domain-meaningful names for classes, functions, and variables.
 - **No Magic Literals**: Replace magic numbers and strings with named constants or enums.
 - **Contracts & Schemas**: Design explicit, human- and machine-readable data contracts, schemas, and self-describing APIs.
-- **Intentional Comments**: Comment only where non-obvious rationale is required, never restate what the code itself expresses.
+- **Intentional Comments**: Comment only where non-obvious rationale is required, never restate what the code itself expresses. Comments should explain "why" not "what". CODE SHOULD BE SELF-DESCRIBING.
 
 ## Concurrency & Safety
 - **Async Safety**: Use idiomatic non-blocking `async`/`await`; ensure operations are free of race conditions and deadlocks.

package/templates/shared/entry-points/instructions.md

@@ -3,23 +3,24 @@
 > Operating instructions and engineering guidelines for AI agents and human contributors.
 
 ## Operating Contract
-Always follow `AgentSkills/OPERATING.md` before making changes. Review relevant agent personas in `AgentSkills/agents/` and skills in `AgentSkills/skills/`.
+Always follow `AgentSkills/OPERATING.md` before making changes. Consult `AgentSkills/skills/index.md` to load task-relevant skills (including `AgentSkills/skills/review/SKILL.md`), and review relevant agent personas in `AgentSkills/agents/` (`architect.md`, `reviewer.md`, `developer.md`).
 
 ## Goal
 Implement requested changes with production-quality code, preserving existing behavior and
 minimizing the diff, following the project's own architecture, standards, and conventions.
 
 ## Core Principles
-- **Core Principles**: Adhere strictly to `AgentSkills/skills/principles/SKILL.md`.
+- **Principles**: Adhere strictly to `AgentSkills/skills/principles/SKILL.md`.
 - **Standards**: Adhere strictly to `AgentSkills/skills/standards/SKILL.md`.
 - **Security**: Adhere strictly to `AgentSkills/skills/security/SKILL.md`.
+- **Review**: Adhere strictly to `AgentSkills/skills/review/SKILL.md`.
 - **Think Before Coding**: Thoroughly understand requirements. If ambiguous, ask before guessing.
 - **Surgical Changes**: Make the smallest change that satisfies the request; touch only what is explicitly required.
 - **Simplicity First (KISS / YAGNI)**: Favor simple, clear, maintainable solutions over clever abstractions. Do not add unrequested features.
 - **Zero-Error Builds**: Every change must compile cleanly and pass existing and newly added tests.
 
 ## Definition of Done
-- Builds cleanly and all tests pass without errors or warnings.
+- Builds cleanly without any errors.
 - No debug code, dead code, unused imports, or temporary files left behind.
 - Changes are minimal, focused, covered by tests, and easy to review.