@anyberg/agent-conventions 1.0.0

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

@@ -0,0 +1,107 @@
+---
+name: python-best-practices
+description: Use when reading or writing Python files (.py, pyproject.toml, requirements.txt).
+---
+
+# Python Best Practices
+
+Follows type-first, functional, and error handling patterns from AGENTS.md. This skill covers language-specific idioms only.
+
+## Make Illegal States Unrepresentable
+
+Use Python's type system to prevent invalid states at type-check time.
+
+**Frozen dataclasses for immutable domain models:**
+
+```python
+from dataclasses import dataclass
+from datetime import datetime
+
+@dataclass(frozen=True)
+class User:
+    id: str
+    email: str
+    name: str
+    created_at: datetime
+
+# Frozen dataclasses are immutable — no accidental mutation
+```
+
+**Discriminated unions with Literal:**
+
+```python
+from dataclasses import dataclass
+from typing import Literal
+
+@dataclass
+class Success:
+    status: Literal["success"] = "success"
+    data: str
+
+@dataclass
+class Failure:
+    status: Literal["error"] = "error"
+    error: Exception
+
+RequestState = Success | Failure
+
+def handle_state(state: RequestState) -> None:
+    match state:
+        case Success(data=data):
+            render(data)
+        case Failure(error=err):
+            show_error(err)
+```
+
+**NewType for domain primitives:**
+
+```python
+from typing import NewType
+
+UserId = NewType("UserId", str)
+OrderId = NewType("OrderId", str)
+
+def get_user(user_id: UserId) -> User:
+    # Type checker prevents passing OrderId here
+    ...
+```
+
+**Protocol for structural typing:**
+
+```python
+from typing import Protocol
+
+class Readable(Protocol):
+    def read(self, n: int = -1) -> bytes: ...
+
+def process_input(source: Readable) -> bytes:
+    # Accepts any object with a read() method — no inheritance required
+    return source.read()
+```
+
+## Python-Specific Error Handling
+
+Chain exceptions with `from err` to preserve the original traceback:
+
+```python
+try:
+    data = json.loads(raw)
+except json.JSONDecodeError as err:
+    raise ValueError(f"invalid JSON payload: {err}") from err
+```
+
+## Structured Logging
+
+Use a module-level logger with `%s` formatting (deferred string interpolation):
+
+```python
+import logging
+
+logger = logging.getLogger("myapp.widgets")
+
+def create_widget(name: str) -> Widget:
+    logger.debug("creating widget: %s", name)
+    widget = Widget(name=name)
+    logger.debug("created widget id=%s", widget.id)
+    return widget
+```

package/skills/python-coding-guidelines/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: python-coding-guidelines
+description: Rules for simplifying code using Python idioms, comprehensions, operators, and eliminating unnecessary complexity
+---
+
+# Python Coding Guidelines
+
+Python-specific idioms and type-system usage. Builds on the **Universal Code Rules** in `code-standards`; only Python-specific rules are listed here.
+
+## Code Style
+
+- Use `model_dump()` for Pydantic model serialization; reserve `TypeAdapter` with `mode='json'` for collections or external SDKs needing JSON-compatible primitives — `TypeAdapter.dump_python(mode='json')` guarantees primitive types (dicts/lists/strings) instead of `BaseModel` instances when required by external systems
+
+## Type System
+
+- Use `isinstance()` for type checking, not `hasattr()`, `getattr()`, `type(obj).__name__`, or discriminator field checks like `part_kind` — Enables proper type narrowing for static analysis and prevents fragile string-based comparisons that break during refactoring
+- Use `Literal` types instead of plain `str` for fixed string value sets in parameters, fields, and return types — Makes valid values explicit in type signatures, enabling static type checkers to catch invalid strings at compile time and improving IDE autocomplete
+- Create type aliases for complex types (3+ union branches, `dict[str, Any] | Callable` patterns, multi-value `Literal`s) or types used 2+ times — skip aliases for simple one-off internal types — Reduces duplication and improves readability for complex types while avoiding unnecessary abstraction that obscures simple inline hints
+- Use `if TYPE_CHECKING:` blocks for optional dependency types with quoted hints — keeps package installable without all deps while preserving type safety — Prevents runtime import errors when optional dependencies aren't installed while maintaining proper type annotations instead of falling back to `Any`
+- Type signatures to match runtime reality — if control flow (e.g., `match`/`case`, API contracts) guarantees only specific types reach a code path, narrow the annotation to exclude impossible types from unions — Prevents confusion, enables better type checking, and documents actual behavior rather than overly permissive signatures that suggest unreachable code paths
+- Fix type errors properly instead of using `# type: ignore` or `# pyright: ignore` — use type annotations, narrowing, or `cast()` with explanatory comments — Prevents masking real type errors and makes code safer; when suppressions are genuinely needed (complex generics, tool limits), document with error codes and justification so reviewers understand the safety reasoning
+- Remove redundant runtime checks when types already constrain the value — prevents noise and maintains type system trust — Redundant assertions (`assert x is not None` for non-`Optional` types, duplicate `isinstance()` checks, etc.) add visual clutter and imply the type system can't be trusted, making code harder to maintain
+- Fix type definitions instead of using `cast()` — adjust generics or remove unnecessary unions to match runtime reality — Prevents masking structural type mismatches that indicate design problems; only use `cast()` when runtime logic guarantees safety but static analysis cannot narrow (e.g., after literal checks or known invariants)
+- Don't add `| None` to `TypedDict` fields marked `total=False` or `NotRequired` — optionality is already expressed — Prevents redundant type declarations and makes it clear that omission (not None) is the intended optional behavior
+- Remove `| None` from type annotations when values are guaranteed to be initialized or always provided — Prevents false optionality in types, making the API clearer and avoiding unnecessary None-checks that can never trigger
+
+## Error Handling
+
+- Use domain specific exceptions for surfacing errors to the user. These are generally defined in the projects `exceptions` module. Use the `raise x from y` pattern to make the cause clear.
+- Use `!r` format specifier for identifiers in error messages (e.g., `f'Tool {name!r}'` not `f'Tool`{name}`'`) — Provides consistent, unambiguous quoting that clearly delimits values and handles edge cases like empty strings or special characters.
+- Fail fast on explicit user config conflicts; gracefully fallback on internal/auto setting conflicts — Catching user mistakes early with clear errors prevents debugging confusion, while internal fallbacks enable cross-provider compatibility and system resilience when constraints are automatically inferred or propagated
+- Inherit new exception types from existing base exceptions when semantically appropriate — Maintains backward compatibility so user code catching parent exceptions continues to work when new exception types are introduced
+- Trust validated invariants and use defaults over assertions — reduces brittle failures and improves resilience — Assertions crash on unexpected states; defaults and graceful handling keep the system operational when assumptions don't hold, while trusting earlier validation stages avoids redundant defensive checks.
+
+## Naming
+
+- Use `UPPER_CASE` for module constants; prefix with `_` if internal (`_MAX_RETRIES`) — Distinguishes public API from internal implementation details and signals immutability
+
+## Imports
+
+- Follow google coding guidelines for imports - prefer to import the module instead of items. For example, when you need to use pydantics `BaseModel`, import `pydantic` and use `pydantic.BaseModel`. The `typing`, `typing_extensions`, `collections`, and their submodules are exceptions.
+- Handle optional dependencies: (1) import inside functions to defer requirements, OR (2) use `try`/`except ImportError` at module level with helpful errors directing to install groups like `[web]`, `[bedrock]` — Keeps the package installable without all dependencies while providing clear guidance when optional features are used
+
+## General
+
+- Projects generally use `hatch` as a project/environment manager. Use the appropriate skill, check the projects documentation, or `pyproject.toml` for entrypoints for testing, static analysis, etc.
+
+## Patterns & Idioms
+
+- Use list comprehensions instead of for-loop-with-append patterns — more concise, readable, and often faster for transforming/filtering iterables into lists
+- Use dict comprehensions instead of empty dict + loop — reduces boilerplate and signals intent more clearly
+- Use `any()` instead of for-loops with boolean flags when checking if any element matches a condition — eliminates manual flag management and break statements
+- Use `@cached_property` for expensive computed attributes — defers computation until first access and caches the result
+- Omit parameters that match default values in function/constructor calls — makes non-default configuration more visible
+- Eliminate single-use intermediate variables — reassign or return directly instead of creating `_filtered`, `_copy`, etc.
+- Flatten nested `if` statements with no intervening code into `if condition1 and condition2:` — reduces nesting depth without changing logic
+- Use `x or default` for fallback values instead of verbose if-else blocks — avoid when falsy values (0, `''`, `[]`, `None`) are semantically valid
+- Define `TypeAdapter` instances at module level as constants — avoids repeated initialization overhead on every call

package/skills/python-design-patterns/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: python-design-patterns
+description: Python design patterns including KISS, Separation of Concerns, Single Responsibility, and composition over inheritance. Use this skill when designing a new service or component from scratch and choosing how to layer responsibilities, when refactoring a God class or monolithic function that has grown too large, when deciding whether to add a new abstraction or live with duplication, when evaluating a pull request for structural issues like tight coupling or leaking internal types, when choosing between inheritance and composition for a new class hierarchy, or when a codebase is becoming hard to test because of entangled I/O and business logic.
+---
+
+# Python Design Patterns
+
+## When to Use This Skill
+
+- Designing new components or services
+- Refactoring complex or tangled code
+- Deciding whether to create an abstraction
+- Choosing between inheritance and composition
+- Evaluating code complexity and coupling
+- Planning modular architectures
+
+## Patterns
+
+- **KISS** — Choose the simplest solution that works. A plain dict beats a factory registry. Complexity must earn its place.
+- **Single Responsibility (SRP)** — Each unit has one reason to change. HTTP parsing, business rules, and data access belong in separate classes.
+- **Separation of Concerns** — Layer as: API handler → Service → Repository. Each layer depends only on layers below it; services must never import from handlers.
+- **Composition Over Inheritance** — Build behavior by combining objects, not extending classes. Use constructor injection with Protocols.
+- **Rule of Three** — Wait until you have three instances before abstracting. Duplication is often better than the wrong abstraction.
+- **Function Size** — Functions over 20–50 lines likely serve multiple purposes. Extract when nesting exceeds 3 levels.
+- **Dependency Injection** — Inject via constructor with Protocol-typed parameters. Production wires real implementations; tests wire fakes.
+- **Don't expose internal types** — Use response schemas at API boundaries, not ORM models or internal dataclasses.
+- **Don't mix I/O with business logic** — Business logic should be pure; data access belongs in repositories, not service methods.
+- **Explicit over clever** — Readable code beats elegant code.

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

@@ -0,0 +1,171 @@
+---
+name: rust-best-practices
+description: Use when reading or writing Rust files (.rs, Cargo.toml).
+---
+
+# Rust Best Practices
+
+Follows the same type-first, functional, error-aware philosophy as `python-best-practices`, expressed through Rust's ownership, enums, traits, and `Result`. This skill covers language-specific idioms; pair it with `rust-coding-guidelines` for the rule list.
+
+## Make Illegal States Unrepresentable
+
+Rust's type system is the primary tool for correctness. Encode invariants so invalid states won't compile.
+
+**Immutable domain models — ownership and `let` give you immutability by default:**
+
+```rust
+use std::time::SystemTime;
+
+#[derive(Debug, Clone, PartialEq, Eq)]
+pub struct User {
+    pub id: UserId,
+    pub email: String,
+    pub name: String,
+    pub created_at: SystemTime,
+}
+
+// No `mut`, no interior mutability — instances cannot be changed after construction.
+```
+
+**Discriminated unions are enums — model mutually-exclusive states directly:**
+
+```rust
+pub enum RequestState {
+    Success { data: String },
+    Failure { error: AppError },
+}
+
+fn handle_state(state: RequestState) {
+    match state {
+        RequestState::Success { data } => render(&data),
+        RequestState::Failure { error } => show_error(&error),
+    }
+    // Exhaustive: adding a variant turns every match into a compile error until handled.
+}
+```
+
+Prefer this over a struct with `Option` fields that "shouldn't" both be set — the enum makes the illegal combination impossible to construct.
+
+**Newtype pattern for domain primitives — no accidental mixups:**
+
+```rust
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct UserId(String);
+
+#[derive(Debug, Clone, PartialEq, Eq, Hash)]
+pub struct OrderId(String);
+
+fn get_user(id: &UserId) -> Option<User> {
+    // The compiler rejects passing an `OrderId` here.
+    todo!()
+}
+```
+
+**Parse, don't validate — convert at the boundary into a type that cannot be invalid:**
+
+```rust
+pub struct Email(String);
+
+impl Email {
+    /// The only way to build an `Email`. Downstream code never re-checks.
+    pub fn parse(raw: &str) -> Result<Self, AppError> {
+        if raw.contains('@') {
+            Ok(Email(raw.to_owned()))
+        } else {
+            Err(AppError::InvalidEmail { value: raw.to_owned() })
+        }
+    }
+}
+```
+
+**Traits for structural/behavioral abstraction (Rust's answer to `Protocol`):**
+
+```rust
+use std::io::Read;
+
+/// Accepts anything that can be read — no inheritance, static dispatch.
+fn process_input<R: Read>(mut source: R) -> std::io::Result<Vec<u8>> {
+    let mut buf = Vec::new();
+    source.read_to_end(&mut buf)?;
+    Ok(buf)
+}
+```
+
+## Error Handling
+
+Use `Result<T, E>` and `?`. Define a domain error enum with `thiserror` for libraries; preserve the cause chain via `#[source]`/`#[from]`.
+
+```rust
+use thiserror::Error;
+
+#[derive(Debug, Error)]
+pub enum AppError {
+    #[error("invalid email: `{value}`")]
+    InvalidEmail { value: String },
+
+    #[error("failed to read config")]
+    Config {
+        #[source]
+        source: std::io::Error,
+    },
+
+    // `#[from]` auto-converts at the `?` site and records the cause.
+    #[error("serialization failed")]
+    Serde(#[from] serde_json::Error),
+}
+```
+
+Propagate and enrich — `?` plus context is the equivalent of Python's `raise ... from err`:
+
+```rust
+fn load_config(path: &std::path::Path) -> Result<Config, AppError> {
+    let raw = std::fs::read_to_string(path).map_err(|source| AppError::Config { source })?;
+    let config = serde_json::from_str(&raw)?; // #[from] handles the conversion
+    Ok(config)
+}
+```
+
+For application/binary code where callers won't `match` on the variant, prefer `anyhow` with `.context(...)`:
+
+```rust
+use anyhow::Context;
+
+fn run() -> anyhow::Result<()> {
+    let raw = std::fs::read_to_string("config.json")
+        .context("reading config.json")?;
+    let _config: Config = serde_json::from_str(&raw)
+        .context("parsing config.json")?;
+    Ok(())
+}
+```
+
+Reserve `unwrap`/`expect` for invariants that genuinely cannot fail, and state the reason:
+
+```rust
+let port: u16 = "8080".parse().expect("hardcoded port is a valid u16");
+```
+
+## Structured Logging
+
+Use the `tracing` crate with structured fields rather than string interpolation — fields are captured as data, not baked into the message:
+
+```rust
+use tracing::{debug, info};
+
+pub fn create_widget(name: &str) -> Widget {
+    debug!(widget.name = name, "creating widget");
+    let widget = Widget::new(name);
+    info!(widget.id = %widget.id, "created widget");
+    widget
+}
+```
+
+Use `#[instrument]` to attach a span (with arguments) to a whole function:
+
+```rust
+#[tracing::instrument(skip(db))]
+pub async fn fetch_user(db: &Db, id: &UserId) -> Result<User, AppError> {
+    // Every event inside inherits the span, including `id`.
+    db.get_user(id).await
+}
+```

package/skills/rust-coding-guidelines/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: rust-coding-guidelines
+description: Rules for Rust code — idioms, type system usage, error handling, naming, modules, and eliminating unnecessary complexity. Use when reading or writing .rs files or Cargo.toml.
+---
+
+# Rust Coding Guidelines
+
+Applies to all `.rs` files and `Cargo.toml`. Builds on the **Universal Code Rules** in `code-standards`; only Rust-specific rules are listed here. Pairs with `rust-best-practices` (worked examples) and `rust-design-patterns`.
+
+## Code Style
+
+- Compile static `Regex` patterns once with `LazyLock` (or `once_cell::Lazy`) — avoids recompilation overhead on repeated calls
+- Prefer iterator chains (`.iter().map().filter().collect()`) over manual `for`-loop-with-push — more concise, often faster, and signals intent
+- Let `rustfmt` own formatting — never hand-format; run it before committing and never `#[rustfmt::skip]` without a documented reason
+- Prefer expression-oriented code: return the value of an `if`/`match`/block directly instead of mutating a binding then returning it
+
+## Type System
+
+- Make illegal states unrepresentable — model mutually-exclusive states as `enum` variants carrying their data, not structs full of `Option` fields that "shouldn't" coexist
+- Use the newtype pattern (`struct UserId(String)`) for domain primitives — the compiler prevents passing an `OrderId` where a `UserId` is expected, unlike a bare `String`
+- Parse, don't validate — convert untrusted input into a validated type at the boundary via `TryFrom`/a fallible constructor, so downstream code receives a type that *cannot* be invalid
+- Prefer `enum` + `match` for sum types; exhaustive `match` gives a compile error when a variant is added — avoid a catch-all `_ =>` arm on domain enums you own, so new variants surface every site that must handle them
+- Accept the most general type that works: take `&str` over `&String`, `&[T]` over `&Vec<T>`, `impl IntoIterator` / `impl AsRef<Path>` for flexible APIs
+- Derive `Debug` on every public type; derive `Clone`, `PartialEq`, `Eq`, `Hash` when semantically meaningful — never hand-write what a derive provides
+- Use `#[non_exhaustive]` on public enums/structs that may grow — forces downstream `match`es to keep a wildcard arm, preserving backward compatibility when variants/fields are added
+- Prefer borrowing (`&T`) in function signatures; take ownership only when the function genuinely needs to store or consume the value
+- Reach for generics with trait bounds for static dispatch; use `dyn Trait` (boxed) only when you need heterogeneous collections or to break compile-time coupling
+- Avoid `unsafe`; when genuinely required, isolate it in the smallest possible function with a `// SAFETY:` comment justifying every invariant relied upon
+- Avoid stringly-typed code — model fixed value sets as enums, not `&str` constants compared by equality
+
+## Error Handling
+
+- Use `Result<T, E>` for recoverable errors and the `?` operator to propagate — never `unwrap()`/`expect()` in library or production paths
+- Reserve `panic!`, `unwrap`, and `expect` for unreachable invariants and tests; when used, `expect("reason")` must state the invariant that makes it infallible
+- Define domain error enums with `thiserror` for libraries — one variant per failure mode, with `#[from]` for automatic conversion and `#[source]` to preserve the cause chain
+- Use `anyhow` (with `.context("...")`) for application/binary code where callers won't match on the error variant — add context at each layer so the chain reads top-down
+- Add context when propagating across an abstraction boundary — a bare `?` that surfaces a low-level IO error to a user is worse than `.context("reading config from {path}")`
+- Return `Result` instead of sentinel values; use `Option<T>` for genuine absence (not failure), and convert with `.ok_or(...)` / `.ok_or_else(...)`
+- Never silently discard a `Result` — handle it, propagate with `?`, or explicitly `let _ =` with a comment explaining why the error is safe to ignore
+
+## Naming
+
+- `snake_case` for functions, variables, modules, and files; `PascalCase` for types, traits, and enum variants; `SCREAMING_SNAKE_CASE` for `const`/`static`
+- Prefix internal items with nothing but keep them private (no `pub`) — Rust's module visibility, not naming, marks the public surface; use `pub(crate)` for crate-internal sharing
+- Getters drop the `get_` prefix (`fn name(&self)`, not `fn get_name(&self)`); conversions follow convention: `as_` (cheap borrow), `to_` (expensive/owned), `into_` (consuming)
+
+## Imports & Modules
+
+- Group `use` statements: `std` first, then external crates, then crate-local (`crate::`, `super::`, `self::`), separated by blank lines — `rustfmt`'s `group_imports` enforces this
+- Import the item you use (`use std::collections::HashMap;` then `HashMap`) rather than fully-qualifying at call sites; for trait methods, import the trait
+- Avoid glob imports (`use foo::*`) except for preludes and inside `#[cfg(test)] mod tests` (`use super::*`)
+- Define a module's public API explicitly with `pub use` re-exports at the crate root — let internal module structure stay refactorable without breaking consumers
+- Keep `mod` declarations and visibility tight — expose the minimum; default to private and widen deliberately
+
+## Testing
+
+- Put unit tests in a `#[cfg(test)] mod tests` block in the same file; put integration tests in `tests/` exercising the public API only
+- Prefer `assert_eq!`/`assert!` with a message; use `#[should_panic(expected = "...")]` to pin the panic reason; reach for `proptest` when input space is large
+
+## General
+
+- Use `cargo` as the single entrypoint: `cargo build`, `cargo test`, `cargo clippy`, `cargo fmt` — check the project's docs for any wrapper before assuming
+- Run `cargo clippy` before committing and fix lints rather than `#[allow(...)]`-ing them; an `#[allow]` must carry a comment explaining why the lint is wrong here
+- Set `#![deny(warnings)]` or wire `-D warnings` in CI; never disable lints crate-wide without a documented reason
+- Prefer immutability — `let` over `let mut`; introduce `mut` only where a value genuinely changes
+- Pin the edition in `Cargo.toml` and keep dependencies minimal — each crate is a maintenance and audit surface
+
+## Patterns & Idioms
+
+- Use `if let` / `let ... else` for single-variant extraction instead of a full `match` with a throwaway arm
+- Use combinators (`map`, `and_then`, `unwrap_or_else`, `filter_map`) over manual `match` ladders on `Option`/`Result` when they read more clearly
+- Use `?` to flatten nested error handling instead of pyramids of `match`
+- Prefer `collect()` into the target type (`Result<Vec<_>, _>`, `HashMap<_, _>`) over building and pushing in a loop
+- Use `impl Trait` in argument and return position to avoid naming complex iterator/closure types
+- Use `derive`d `Default` + struct-update syntax (`Foo { x, ..Default::default() }`) over hand-written constructors with many optional fields; reach for the builder pattern when there are many optional fields with interdependencies
+- Use `Cow<str>` when a function sometimes returns borrowed and sometimes owned data, to avoid forcing an allocation
+- Implement `From`/`TryFrom` for conversions rather than ad-hoc `to_x` helpers — they compose with `?` and `.into()`

package/skills/rust-design-patterns/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: rust-design-patterns
+description: Rust design patterns including KISS, Separation of Concerns, Single Responsibility, ownership-driven layering, and composition via traits. Use this skill when designing a new service or component from scratch and choosing how to layer responsibilities, when refactoring a God struct or monolithic function that has grown too large, when deciding whether to add a new trait or generic abstraction or live with duplication, when evaluating a pull request for structural issues like tight coupling or leaking internal types, when choosing between generics and trait objects, when deciding what to own versus borrow, or when a codebase is becoming hard to test because of entangled I/O and business logic.
+---
+
+# Rust Design Patterns
+
+## When to Use This Skill
+
+- Designing new components or services
+- Refactoring complex or tangled code
+- Deciding whether to create an abstraction (trait, generic, or newtype)
+- Choosing between generics (static dispatch) and trait objects (dynamic dispatch)
+- Deciding what to own versus borrow at an API boundary
+- Evaluating code complexity, coupling, and testability
+- Planning modular crate and module architectures
+
+## Patterns
+
+- **KISS** — Choose the simplest solution that works. A plain `enum` + `match` beats a trait-object registry. A free function beats a trait with one impl. Complexity must earn its place.
+- **Single Responsibility (SRP)** — Each type/module has one reason to change. Wire parsing, business rules, and persistence belong in separate types — not one God struct.
+- **Separation of Concerns** — Layer as: handler → service → repository. Each layer depends only on layers below via traits; the service must never know about HTTP types or SQL rows.
+- **Composition Over Inheritance** — Rust has no inheritance by design. Build behavior by combining structs and implementing traits; inject collaborators as fields, not by extending a base type.
+- **Parse, Don't Validate** — Push validation to the boundary and return a type that cannot be invalid (newtype, validated struct, enum). Downstream code trusts the type instead of re-checking.
+- **Make Illegal States Unrepresentable** — Model mutually-exclusive states as `enum` variants, not structs of `Option` fields. Let the type system reject invalid combinations at compile time.
+- **Rule of Three** — Wait until you have three instances before abstracting into a trait or generic. Duplication is cheaper than the wrong abstraction — and the wrong trait is expensive to unwind.
+- **Generics over trait objects by default** — Prefer `fn f<T: Trait>(x: T)` (static dispatch, monomorphized, inlinable). Reach for `Box<dyn Trait>` / `&dyn Trait` only for heterogeneous collections, to break compile-time coupling, or to shrink binary/compile size.
+- **Own vs borrow deliberately** — Take `&T` when you only read, `&mut T` when you mutate in place, `T` only when you must store or consume it. Signatures communicate intent; gratuitous ownership forces needless clones on callers.
+- **Newtype for meaning and invariants** — Wrap primitives (`struct Meters(f64)`) to prevent mixups and to hang validation/behavior off a domain type instead of a bare `String`/`u64`.
+- **Function Size** — Functions over 20–50 lines likely serve multiple purposes. Extract when nesting (especially `match`/`if let` pyramids) exceeds 3 levels — `?` and combinators usually flatten them.
+- **Dependency Injection via traits** — Define a trait for each collaborator; inject it as a generic field or `Box<dyn Trait>`. Production wires real impls; tests wire fakes — no mocking framework required.
+- **Don't expose internal types** — Use dedicated request/response (DTO) types at API boundaries, not your domain structs or DB row types. Implement `From` to convert between layers.
+- **Don't mix I/O with business logic** — Keep core logic pure and synchronous over owned/borrowed data; confine `async`, filesystem, network, and DB calls to the edges (repositories, adapters). Pure cores are trivially testable.
+- **Errors as types, not strings** — Model failure modes as a `thiserror` enum per layer; convert across boundaries with `#[from]`. Reserve `anyhow` for the application edge.
+- **Explicit over clever** — Readable code beats elegant code. Avoid deep generic gymnastics and macro magic when a plain function will do.
+
+## Composition & Dependency Injection Example
+
+```rust
+// A trait per collaborator — the seam for testing and swapping implementations.
+pub trait UserRepository {
+    fn find(&self, id: &UserId) -> Result<Option<User>, RepoError>;
+}
+
+// The service depends on the abstraction, not a concrete DB type.
+pub struct UserService<R: UserRepository> {
+    repo: R, // composition: the repo is a field, not a base class
+}
+
+impl<R: UserRepository> UserService<R> {
+    pub fn new(repo: R) -> Self {
+        Self { repo }
+    }
+
+    // Pure business logic — no I/O details leak in here.
+    pub fn display_name(&self, id: &UserId) -> Result<String, RepoError> {
+        Ok(self
+            .repo
+            .find(id)?
+            .map(|u| u.name)
+            .unwrap_or_else(|| "anonymous".to_owned()))
+    }
+}
+
+// Production wires the real repo; tests wire a fake — same generic, no mocks.
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    struct FakeRepo(Option<User>);
+    impl UserRepository for FakeRepo {
+        fn find(&self, _id: &UserId) -> Result<Option<User>, RepoError> {
+            Ok(self.0.clone())
+        }
+    }
+
+    #[test]
+    fn falls_back_to_anonymous_when_user_missing() {
+        let service = UserService::new(FakeRepo(None));
+        assert_eq!(service.display_name(&UserId::new("x")).unwrap(), "anonymous");
+    }
+}
+```

package/skills/task-workflow/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: task-workflow
+description: Use when creating, managing, or promoting tasks, checking merge readiness, or running as an autonomous agent or subagent that implements a backlog item without a human in the loop. Covers task file structure, lifecycle, acceptance criteria, the merge-readiness gate, independent review, and the Autonomous Mode rules that replace human dialogue with blocked-status evidence.
+---
+
+# Task Workflow
+
+Enforces disciplined task management across the codebase. Backlog operations go through **backlog-management**, never by editing backlog storage directly. Project rules come from `<root>/.planning/policy.yml`. If it is missing, run `backlog-management`'s `scripts/generate-policy.sh` before proceeding — it creates the file from best-practice defaults (backend auto-detected) and prints what it generated; report that in your first response, then continue as if the file always existed. It is never regenerated or overwritten once it exists.
+
+## Legacy Layout Migration
+
+Task, planning, and architecture files live in the **project root**, never in a global tool directory (e.g. `~/.claude`, `~/.copilot`). Older projects may still use the legacy `.agents/` root. Before creating, reading, or modifying any task file, check once per project:
+
+1. If `<root>/.agents/tasks/` or `<root>/.agents/planning/` exists, create `<root>/.planning/` (if missing), then:
+   - Move `<root>/.agents/tasks/` → `<root>/.planning/tasks/`.
+   - Move `<root>/.agents/planning/` → `<root>/.planning/planned/`.
+   - Move `<root>/.agents/architecture.md` → `<root>/.planning/architecture.md`, if present.
+   - Move `<root>/.agents/backlog.md` → `<root>/BACKLOG.md`, if present (see **backlog-management**).
+   - Remove `<root>/.agents/` once empty.
+2. Do this migration silently and automatically. It is additive and safe. Do not ask for confirmation.
+3. After migration, all instructions below refer only to the new `.planning/` and root `BACKLOG.md` locations.
+
+## Task Lifecycle
+
+Tasks have two states, each with a directory:
+
+| State | Location | Created via |
+|---|---|---|
+| `planned` | `<root>/.planning/planned/<category>/` | Definition only, no code, no branch |
+| `active` | `<root>/.planning/tasks/` | Move from planning OR create directly |
+
+**Filename:** `<type>_<short-description>.md` (e.g. `feat_user-authentication.md`)
+
+**Promoting planned → active:** move file, set `Status: active`, add `Started` datetime and `Branch` field, before any code. In the same step, `backlog-management.claim(id)` if not already claimed.
+
+## Task File Structure
+
+```markdown
+# <Title>
+
+**Status:** planned | active
+**Backlog:** <id>              # backlog-management ID, mandatory
+**Created:** <datetime>
+**Started:** <datetime>      # active only
+
+## Branch                    # active only
+`<type>/<id>-<short-description>`   # format from policy.git.branch_format
+
+## Goal
+One paragraph: what and why.
+
+## Acceptance Criteria
+- [ ] Criterion one
+- [ ] Criterion two
+
+Interactive mode: refine through questions with the user until clear, specific, and testable.
+Autonomous mode: copied verbatim from the backlog item; see Autonomous Mode below.
+
+## Plan
+Ordered steps. Written before any code. Update + log if it changes.
+
+## Log                       # active only
+- `HH:MM` - What was done (past tense, not intent)
+
+## Blockers
+Open questions needing human input. In planned tasks these are pre-start blockers and must be resolved before promotion.
+
+## Summary                   # appended before marking done
+What was built; deviations from Plan.
+```
+
+## Merge Readiness Verification
+
+A branch is **not** merge-ready until every item below has been *verified in the current session*. Verification means running the stated check and observing its result, not ticking a box from memory. Work top to bottom and record evidence.
+
+| # | Item | How to verify | Evidence to capture |
+|---|------|---------------|---------------------|
+| 1 | All Acceptance Criteria met | Re-read each criterion; confirm the implementation satisfies it | Each `- [ ]` flipped to `- [x]` |
+| 2 | Tests cover new code | Run the test suite; confirm new/changed code has tests | Test command + pass count |
+| 3 | No lint or type errors | Run linter and type checker | Commands + clean exit |
+| 4 | Pre-commit passes | Run pre-commit hooks across the diff | Command + clean exit |
+| 5 | `CHANGELOG.md` updated | Only if public behaviour changed | Diff, or "N/A, no public behaviour change" |
+| 6 | Version bumped | Only if `policy.versioning.bump` is not `release-commit-only` | Old → new, or "N/A per policy" |
+| 7 | Summary appended to task file | `## Summary` exists and reflects what was built | Section present |
+| 8 | Backlog items for leftovers | `backlog-management.create` per incomplete Plan step or unresolved Blocker, origin = this task | IDs created, or "none outstanding" |
+| 9 | Backlog linked | `backlog-management.link(id, pr)` done when the PR was opened; status is `in-review` | Op output |
+| 10 | Task file removed | After all above pass, delete from `.planning/tasks/` or `.planning/planned/` | File no longer present |
+| 11 | Branch current with remote main | `git fetch`, confirm rebased or merged on `origin/main` with no conflicts | Command + "up to date" |
+| 12 | Independent review | A reviewer with fresh context (separate subagent or a human) approves the PR via **code-review**; the author never self-approves | Review URL |
+| 13 | Scope and path limits | Diff within `policy.autonomous.max_diff_lines` and `max_files`; no `require_human_review_if_touches` path, or PR labelled `needs-human` | Numbers + label state |
+
+After merge is confirmed, and only then: `backlog-management.release(id, done, note)`.
+
+**Gate, read before claiming "done" or "ready to merge":**
+
+- Do not report a task as complete or merge-ready until items 1 to 13 are each verified with evidence in this session. Stop on the first failure, fix it, re-verify.
+- State each result explicitly as **pass**, **fail**, or **N/A (reason)**. Silence is not a pass.
+- Conditional items (5, 6, 13) still require an explicit decision.
+- If any item cannot be verified (missing tooling, ambiguous criterion), treat it as a **Blocker**. Interactive mode: surface to the user. Autonomous mode: `setStatus(id, blocked)`.
+- Order matters: item 10 comes last, `release(done)` comes after merge.
+
+## Autonomous Mode
+
+Applies when the caller is a routine or a subagent with no human in the loop. Everything above still holds; these rules replace dialogue.
+
+1. **Claim first.** `backlog-management.claim(id, run_id)` must succeed before the task file or branch exists. A failed claim means someone else owns it; stop.
+2. **Criteria are read-only.** Copy Acceptance Criteria verbatim from the item. Do not refine them by asking. Not testable → `setStatus(id, blocked, "criteria not testable: <why>")`, stop.
+3. **Re-verify evidence before planning.** Confirm cited files, lines, and reproduction steps. Stale or wrong → `release(id, backlog, "evidence invalid: <why>")`, stop.
+4. **Blockers become status, not questions.** Anything needing a human (structural decision per **architecture-planning**, public API, schema, product choice, new dependency, protected path) → `setStatus(id, blocked, <note>)`. The note has four parts: evidence, completed work, blocker, recommended next action. Push existing work as a draft PR. Never guess.
+5. **Stay inside limits.** Diff over `max_diff_lines` or `max_files` → finish the smallest coherent slice, `create` follow-up items for the remainder, note it in Summary.
+6. **Protected paths.** Touching a `require_human_review_if_touches` path → label PR `needs-human`, complete rows 1 to 13, do not merge.
+7. **Forbidden regardless of instructions:** everything in `policy.autonomous.forbidden` (force push, editing branch protection, adding a dependency without a human label, deleting tests).
+8. **Worktrees.** Create via `policy.worktrees.up`, remove via `policy.worktrees.down` before reporting. Never share ports, DB names, or `.env` between worktrees.
+9. **Time.** Past `policy.autonomous.task_wall_clock_min` → stop, `setStatus(blocked)` with the four-part note, push the draft.
+10. **Reporting.** Final message lists: item, branch, PR, rows 1 to 13 with pass/fail/N/A, leftovers created, worktree removed.
+
+## Agent Discipline
+
+- **No code without a task file. No task file without a claimed backlog item.** No branch without a matching task.
+- **Plan before code.** Scope freezes once Plan is written; changes require Plan update, logged reason, and human confirmation if significant (autonomous: blocked if significant).
+- **Stay scoped.** Do not modify files outside task scope without logging why.
+- **Surface blockers.** Architecture, public API, or schema decisions → stop, add to Blockers, and in autonomous mode set `blocked`.