# AGENTS.md

## Project

stygian — Additional adapters and infrastructure implementations for Stygian's hexagonal
architecture. Fills production gaps in caching, storage, streaming, discovery,
and distributed execution by implementing existing port traits with real backends.

## Setup commands

- Build: `cargo build --workspace --all-features`
- Test: `cargo test --workspace --all-features`
- Lint: `cargo clippy --workspace --all-features -- -D warnings`

## Architecture: Hexagonal

- Domain layer must have zero I/O dependencies
- All external interactions go through port traits
- Adapters implement port traits and live in `adapters/`
- New capabilities require a new port trait before an adapter
- Depend inward: adapters → ports ← domain

## Code style

- Language: rust

## Rules

- Rust edition 2024, stable toolchain (1.94.0).

- Hexagonal Architecture (Ports & Adapters): Domain core is isolated from infrastructure concerns.

- Workspace structure: domain (business logic), ports (trait definitions), adapters (implementations), application (orchestration).

- Domain layer NEVER imports from adapters; use dependency inversion via ports.

- Use Rust 1.94.0 features: async closures, trait upcasting, LazyCell/LazyLock, let chains.

- Use native 'async fn' in traits for the plugin interface (Rust 2024).

- All error types must use 'thiserror'; 'anyhow' is reserved for CLI entry points only.

- No .unwrap() or .expect() in library code; use exhaustive error handling.

- Library versions: tokio 1.49, reqwest 0.13, serde 1.0, sqlx 0.8.

- Feature-gate optional dependencies: redis behind 'redis', object storage behind 'object-storage', etc.

- Idempotence: All operations must be safely retryable with idempotency keys.

- Security-first: Authorization checks at repository level, fail-secure by default.

- Documentation: every public trait and method must have a doc comment with an example.

- Every new adapter MUST implement the corresponding port trait AND ScrapingService where appropriate.

- Cross-platform: handle path separators, case sensitivity, and encoding differences across OS targets.

## Testing instructions

- Run `cargo test --workspace --all-features` before committing
- Every new public function needs at least one test
- Fix all test failures before marking a task complete

## Commit conventions

- Use conventional commits: `feat:`, `fix:`, `refactor:`, `test:`, `docs:`
- Focus commit messages on user impact, not file counts or line numbers

---

_Generated by [wiggum](https://github.com/greysquirr3l/wiggum)._
