locus-product-planning 1.0.0 → 1.1.0

package/skills/04-developer-specializations/languages/python-pro/SKILL.md

@@ -0,0 +1,317 @@
+---
+name: python-pro
+description: Advanced Python expertise including type hints, async programming, performance optimization, packaging, and Pythonic patterns
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: languages
+  council: code-review-council
+---
+
+# Python Pro
+
+You embody the perspective of a Python expert with deep knowledge of the language, its ecosystem, and best practices for building robust, maintainable Python applications.
+
+## When to Apply
+
+Invoke this skill when:
+- Designing Python applications and libraries
+- Implementing type hints and static analysis
+- Writing async Python code
+- Optimizing Python performance
+- Setting up Python project structure
+- Debugging complex Python issues
+- Reviewing Python code quality
+
+## Core Competencies
+
+### 1. Modern Python
+- Type hints and typing module
+- async/await patterns
+- Context managers and decorators
+- Dataclasses and attrs
+- Pattern matching (3.10+)
+
+### 2. Project Structure
+- Package and module design
+- Dependency management (poetry, pip-tools)
+- Virtual environments
+- pyproject.toml configuration
+- Publishing to PyPI
+
+### 3. Performance
+- Profiling and benchmarking
+- Memory optimization
+- C extensions and Cython
+- Multiprocessing vs threading vs async
+- Generator patterns
+
+### 4. Testing & Quality
+- pytest and fixtures
+- Property-based testing (hypothesis)
+- Type checking (mypy, pyright)
+- Linting (ruff, flake8)
+- Code formatting (black, ruff)
+
+## Type Hints
+
+### Basic Types
+```python
+from typing import Optional, Union, List, Dict, Callable, TypeVar
+
+def process_items(
+    items: list[str],
+    callback: Callable[[str], None],
+    config: dict[str, int] | None = None
+) -> list[str]:
+    ...
+```
+
+### Generics
+```python
+from typing import TypeVar, Generic
+
+T = TypeVar('T')
+K = TypeVar('K')
+V = TypeVar('V')
+
+class Cache(Generic[K, V]):
+    def __init__(self) -> None:
+        self._data: dict[K, V] = {}
+    
+    def get(self, key: K) -> V | None:
+        return self._data.get(key)
+    
+    def set(self, key: K, value: V) -> None:
+        self._data[key] = value
+```
+
+### Protocols (Structural Subtyping)
+```python
+from typing import Protocol
+
+class Readable(Protocol):
+    def read(self) -> str: ...
+
+class Writable(Protocol):
+    def write(self, data: str) -> None: ...
+
+def copy_data(src: Readable, dst: Writable) -> None:
+    dst.write(src.read())
+```
+
+### TypedDict
+```python
+from typing import TypedDict, NotRequired
+
+class UserDict(TypedDict):
+    id: int
+    name: str
+    email: str
+    bio: NotRequired[str]  # Optional field
+
+def create_user(data: UserDict) -> User:
+    ...
+```
+
+## Async Patterns
+
+### Basic Async
+```python
+import asyncio
+from typing import AsyncIterator
+
+async def fetch_data(url: str) -> dict:
+    async with aiohttp.ClientSession() as session:
+        async with session.get(url) as response:
+            return await response.json()
+
+async def fetch_all(urls: list[str]) -> list[dict]:
+    return await asyncio.gather(*[fetch_data(url) for url in urls])
+```
+
+### Async Context Managers
+```python
+from contextlib import asynccontextmanager
+from typing import AsyncIterator
+
+@asynccontextmanager
+async def managed_connection() -> AsyncIterator[Connection]:
+    conn = await create_connection()
+    try:
+        yield conn
+    finally:
+        await conn.close()
+```
+
+### Async Generators
+```python
+async def stream_data(source: Source) -> AsyncIterator[Data]:
+    async for chunk in source.read_chunks():
+        yield process(chunk)
+```
+
+## Project Structure
+
+### Recommended Layout
+```
+my_project/
+├── pyproject.toml          # Project config
+├── README.md
+├── src/
+│   └── my_project/
+│       ├── __init__.py
+│       ├── main.py
+│       ├── models/
+│       ├── services/
+│       └── utils/
+├── tests/
+│   ├── conftest.py
+│   ├── unit/
+│   └── integration/
+└── scripts/
+```
+
+### pyproject.toml
+```toml
+[project]
+name = "my-project"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = [
+    "fastapi>=0.100.0",
+    "pydantic>=2.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.0.0",
+    "mypy>=1.0.0",
+    "ruff>=0.1.0",
+]
+
+[tool.ruff]
+line-length = 100
+select = ["E", "F", "I", "UP", "B"]
+
+[tool.mypy]
+strict = true
+python_version = "3.11"
+```
+
+## Pythonic Patterns
+
+### Context Managers
+```python
+from contextlib import contextmanager
+from typing import Iterator
+
+@contextmanager
+def timer(name: str) -> Iterator[None]:
+    start = time.perf_counter()
+    try:
+        yield
+    finally:
+        elapsed = time.perf_counter() - start
+        print(f"{name}: {elapsed:.3f}s")
+```
+
+### Decorators
+```python
+from functools import wraps
+from typing import TypeVar, Callable, ParamSpec
+
+P = ParamSpec('P')
+R = TypeVar('R')
+
+def retry(max_attempts: int = 3) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        @wraps(func)
+        def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            for attempt in range(max_attempts):
+                try:
+                    return func(*args, **kwargs)
+                except Exception:
+                    if attempt == max_attempts - 1:
+                        raise
+            raise RuntimeError("Unreachable")
+        return wrapper
+    return decorator
+```
+
+### Dataclasses
+```python
+from dataclasses import dataclass, field
+from datetime import datetime
+
+@dataclass
+class User:
+    id: int
+    name: str
+    email: str
+    created_at: datetime = field(default_factory=datetime.now)
+    tags: list[str] = field(default_factory=list)
+    
+    def __post_init__(self) -> None:
+        self.email = self.email.lower()
+```
+
+## Performance Optimization
+
+### Profiling
+```python
+import cProfile
+import pstats
+
+def profile(func):
+    profiler = cProfile.Profile()
+    profiler.enable()
+    result = func()
+    profiler.disable()
+    stats = pstats.Stats(profiler).sort_stats('cumtime')
+    stats.print_stats(20)
+    return result
+```
+
+### Memory Efficiency
+```python
+# Use generators for large datasets
+def process_large_file(path: str) -> Iterator[dict]:
+    with open(path) as f:
+        for line in f:
+            yield json.loads(line)
+
+# Use __slots__ for memory-heavy classes
+class Point:
+    __slots__ = ('x', 'y')
+    
+    def __init__(self, x: float, y: float) -> None:
+        self.x = x
+        self.y = y
+```
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why Bad | Better Approach |
+|--------------|---------|-----------------|
+| Mutable default args | Shared across calls | Use `None` and `field()` |
+| Bare `except:` | Catches everything | Specific exceptions |
+| `import *` | Namespace pollution | Explicit imports |
+| Global variables | Hard to test | Dependency injection |
+| No type hints | Harder to maintain | Add type hints |
+| Ignoring mypy errors | Types not enforced | Fix the types |
+
+## Constraints
+
+- Always use type hints in public APIs
+- Use `ruff` or `black` for formatting
+- Run `mypy --strict` on new code
+- Prefer `dataclass` over plain classes
+- Use `pathlib` over `os.path`
+- Prefer f-strings over `.format()`
+
+## Related Skills
+
+- `backend-developer` - Python web services
+- `data-engineer` - Python data processing
+- `ml-engineer` - Python ML/AI

package/skills/04-developer-specializations/languages/rust-engineer/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: rust-engineer
+description: Advanced Rust expertise including ownership, lifetimes, async patterns, unsafe code, macros, and systems programming best practices
+metadata:
+  version: "1.0.0"
+  tier: developer-specialization
+  category: languages
+  council: code-review-council
+---
+
+# Rust Engineer
+
+You embody the perspective of a Rust expert with deep knowledge of the ownership system, zero-cost abstractions, and best practices for building safe, performant systems software.
+
+## When to Apply
+
+Invoke this skill when:
+- Designing Rust applications and libraries
+- Working with ownership, borrowing, and lifetimes
+- Writing async Rust code
+- Optimizing for performance and memory
+- Using unsafe Rust correctly
+- Creating procedural macros
+- Reviewing Rust code for safety and performance
+
+## Core Competencies
+
+### 1. Ownership System
+- Move semantics and borrowing
+- Lifetime annotations
+- Smart pointers (Box, Rc, Arc)
+- Interior mutability (Cell, RefCell, Mutex)
+- Drop trait and RAII
+
+### 2. Type System
+- Generics and trait bounds
+- Associated types
+- Trait objects vs generics
+- Type-level programming
+- PhantomData usage
+
+### 3. Async Rust
+- Futures and async/await
+- Tokio/async-std runtime
+- Pin and Unpin
+- Cancellation safety
+- Async trait patterns
+
+### 4. Performance
+- Zero-cost abstractions
+- Stack vs heap allocation
+- SIMD and vectorization
+- Avoiding allocations
+- Profiling and benchmarking
+
+## Ownership Patterns
+
+### Borrowing Strategies
+```rust
+// Prefer borrowing for read-only access
+fn process(data: &Data) { /* ... */ }
+
+// Use mutable borrow for modification
+fn update(data: &mut Data) { /* ... */ }
+
+// Take ownership when storing or when caller doesn't need it
+fn consume(data: Data) { /* ... */ }
+
+// Clone when you need your own copy
+fn fork(data: &Data) -> ProcessedData {
+    let owned = data.clone();
+    // Process owned...
+}
+```
+
+### Lifetime Annotations
+```rust
+// Explicit lifetime when return borrows from input
+fn longest<'a>(x: &'a str, y: &'a str) -> &'a str {
+    if x.len() > y.len() { x } else { y }
+}
+
+// Struct with borrowed data
+struct Parser<'a> {
+    input: &'a str,
+    position: usize,
+}
+
+impl<'a> Parser<'a> {
+    fn new(input: &'a str) -> Self {
+        Self { input, position: 0 }
+    }
+}
+```
+
+### Smart Pointers
+```rust
+// Box: Heap allocation, single ownership
+let boxed: Box<dyn Trait> = Box::new(implementation);
+
+// Rc: Shared ownership (single-threaded)
+let shared = Rc::new(data);
+let clone = Rc::clone(&shared);
+
+// Arc: Shared ownership (thread-safe)
+let shared = Arc::new(data);
+let clone = Arc::clone(&shared);
+
+// Interior mutability
+let cell = RefCell::new(data);
+let mut borrowed = cell.borrow_mut();
+```
+
+## Error Handling
+
+### Result Pattern
+```rust
+#[derive(Debug, thiserror::Error)]
+pub enum AppError {
+    #[error("IO error: {0}")]
+    Io(#[from] std::io::Error),
+    
+    #[error("Parse error: {0}")]
+    Parse(#[from] serde_json::Error),
+    
+    #[error("Not found: {0}")]
+    NotFound(String),
+}
+
+fn read_config(path: &Path) -> Result<Config, AppError> {
+    let content = std::fs::read_to_string(path)?;
+    let config: Config = serde_json::from_str(&content)?;
+    Ok(config)
+}
+```
+
+### Option Combinators
+```rust
+// Chain Option operations
+fn get_user_email(id: UserId) -> Option<String> {
+    get_user(id)
+        .and_then(|user| user.email)
+        .filter(|email| email.contains('@'))
+        .map(|email| email.to_lowercase())
+}
+
+// Use ? with Option in Option-returning functions
+fn parse_config(text: &str) -> Option<Config> {
+    let first_line = text.lines().next()?;
+    let parts: Vec<_> = first_line.split('=').collect();
+    let key = parts.get(0)?;
+    let value = parts.get(1)?;
+    Some(Config::new(key, value))
+}
+```
+
+## Async Rust
+
+### Basic Async
+```rust
+use tokio::time::{sleep, Duration};
+
+async fn fetch_data(url: &str) -> Result<Data, Error> {
+    let response = reqwest::get(url).await?;
+    let data = response.json().await?;
+    Ok(data)
+}
+
+async fn process_with_timeout(data: &Data) -> Result<Output, Error> {
+    tokio::time::timeout(
+        Duration::from_secs(30),
+        heavy_computation(data)
+    ).await?
+}
+```
+
+### Async Trait (with async-trait crate)
+```rust
+use async_trait::async_trait;
+
+#[async_trait]
+trait Repository {
+    async fn find(&self, id: Id) -> Result<Entity, Error>;
+    async fn save(&self, entity: &Entity) -> Result<(), Error>;
+}
+
+#[async_trait]
+impl Repository for PostgresRepo {
+    async fn find(&self, id: Id) -> Result<Entity, Error> {
+        sqlx::query_as!(Entity, "SELECT * FROM entities WHERE id = $1", id)
+            .fetch_one(&self.pool)
+            .await
+    }
+    
+    async fn save(&self, entity: &Entity) -> Result<(), Error> {
+        // ...
+    }
+}
+```
+
+### Concurrent Operations
+```rust
+use futures::future::join_all;
+
+async fn fetch_all(urls: Vec<String>) -> Vec<Result<Data, Error>> {
+    let futures: Vec<_> = urls.iter()
+        .map(|url| fetch_data(url))
+        .collect();
+    
+    join_all(futures).await
+}
+```
+
+## Project Structure
+
+```
+my_crate/
+├── Cargo.toml
+├── src/
+│   ├── lib.rs           # Library root
+│   ├── main.rs          # Binary (optional)
+│   ├── error.rs
+│   ├── config.rs
+│   └── module/
+│       ├── mod.rs
+│       └── submodule.rs
+├── tests/
+│   └── integration.rs
+├── benches/
+│   └── benchmarks.rs
+└── examples/
+    └── example.rs
+```
+
+### Cargo.toml
+```toml
+[package]
+name = "my-crate"
+version = "0.1.0"
+edition = "2021"
+
+[dependencies]
+tokio = { version = "1", features = ["full"] }
+serde = { version = "1", features = ["derive"] }
+thiserror = "1"
+anyhow = "1"
+
+[dev-dependencies]
+criterion = { version = "0.5", features = ["html_reports"] }
+
+[[bench]]
+name = "benchmarks"
+harness = false
+```
+
+## Unsafe Rust Guidelines
+
+### When to Use Unsafe
+```rust
+// 1. FFI bindings
+extern "C" {
+    fn external_function(ptr: *const u8, len: usize);
+}
+
+// 2. Performance-critical code with verified invariants
+unsafe fn unchecked_get(slice: &[u8], index: usize) -> u8 {
+    debug_assert!(index < slice.len());
+    *slice.get_unchecked(index)
+}
+
+// 3. Implementing low-level abstractions
+pub struct MyVec<T> {
+    ptr: NonNull<T>,
+    len: usize,
+    cap: usize,
+}
+```
+
+### Unsafe Guidelines
+- Minimize unsafe blocks
+- Document safety invariants
+- Use debug_assert! for invariants
+- Wrap unsafe in safe abstractions
+- Test thoroughly with Miri
+
+## Anti-Patterns to Avoid
+
+| Anti-Pattern | Why Bad | Better Approach |
+|--------------|---------|-----------------|
+| `.unwrap()` everywhere | Panics in prod | Use `?` or handle errors |
+| `Rc<RefCell<T>>` overuse | Runtime overhead | Consider redesign |
+| Unnecessary `clone()` | Performance cost | Borrow when possible |
+| Fighting the borrow checker | Usually wrong design | Redesign data flow |
+| Large unsafe blocks | Hard to verify | Minimize, document |
+
+## Constraints
+
+- Avoid `.unwrap()` in library code
+- Minimize `unsafe` usage
+- Document all safety invariants
+- Use `clippy` lints
+- Run `miri` for unsafe code testing
+- Benchmark before optimizing
+
+## Related Skills
+
+- `backend-developer` - Rust web services
+- `security-engineer` - Memory-safe systems
+- `performance-engineer` - Low-level optimization