# Repository Guidelines
## Project Structure & Module Organization
- `src/`: Single Rust crate (`openvcs-core`) providing shared types/traits for the OpenVCS client and plugins.
- Feature-gated modules: `plugin_protocol`, `plugin_stdio`, `plugin_runtime`, `events`, `host`.
- VCS surface area lives behind the `vcs` feature (see `src/lib.rs`).
- `.github/workflows/`: CI, CodeQL, nightly packaging/release automation.
- `target/`: Cargo build artifacts (do not commit).
## Build, Test, and Development Commands
- `cargo check --all-targets --all-features`: Fast compile check matching CI’s broadest configuration.
- `cargo test`: Run default-feature unit tests.
- `cargo test --no-default-features --features plugin-protocol,vcs,backend-registry`: Validate feature combinations used in CI.
- `cargo package`: Ensure the crate packages cleanly (used by nightly automation).
## Coding Style & Naming Conventions
- Format with Rustfmt: `cargo fmt`.
- Prefer Clippy-clean code: `cargo clippy --all-targets --all-features -D warnings`.
- Naming: `snake_case` (functions/modules), `CamelCase` (types), `SCREAMING_SNAKE_CASE` (constants).
- Preserve feature gates (`#[cfg(feature = "...")]`) when adding new APIs; keep the default feature set lightweight.
## Testing Guidelines
- Uses Rust’s built-in test harness (`#[test]`) with unit tests colocated in modules (e.g., `src/models.rs`).
- Add tests next to the code they cover; keep tests deterministic and free of network/file-system assumptions unless required.
## Commit & Pull Request Guidelines
- Before committing, run `cargo fmt` (CI enforces `cargo fmt --all -- --check`).
- Commit messages in this repo are short and imperative (e.g., “Update lib.rs”, “Fix compile issues”). Follow that pattern and mention the touched area.
- Commit message format: agents must format commit messages with a short
title of at most 72 characters, followed by a blank line and any
additional explanatory text in the body.
- Open PRs against the `Dev` branch; include a clear description, rationale, and any relevant issue links.
- Ensure CI passes locally where possible (at minimum `cargo test`, ideally the full-feature test command above).
- After making changes, run `just fix` to automatically apply formatting and simple fixes before committing.
- Commit changes locally with a clear, conventional message, but do NOT push to remotes or create PRs—leave pushing and PR creation to a human maintainer.
**Sandbox note**: Running `just fix` and some `cargo` commands (for example `cargo build` or commands that fetch dependencies or build native binaries) may require network access or host-level tooling and therefore should be run outside a restricted sandbox or container. If operating with sandboxing or restricted network access, request approval before executing these commands or run them on the host machine.