# Repository Guidelines

## Project Structure & Module Organization
- `src/` holds the Rust library and CLI entry points (`src/lib.rs`, `src/main.rs`) plus app modules (`src/config/`, `src/core`, etc.).
- `tests/` contains integration and end-to-end tests (`tests/integration_tests.rs`, `tests/e2e_tests.rs`).
- `benches/` has Criterion benchmarks (`benches/benches.rs`).
- `docs/` includes design notes, plans, and the Rustdoc style guide (`docs/spec.md`, `docs/plan.md`, `docs/rustdoc_style.md`).
- `Cargo.toml` and `Cargo.lock` define dependencies and lock versions.

## Build, Test, and Development Commands
This repo standardizes workflows via `just`:
- `just init` installs required toolchain components, git hooks, and helper binaries.
- `just run` builds and runs the CLI (`cargo run ...`).
- `just test` runs the full test suite with `cargo nextest`.
- `just fmt` applies Rust formatting (nightly `cargo fmt`).
- `just check -- -D warnings` runs Clippy across all targets and features.
- `just pre-commit` runs formatting, linting, tests, docs, audits, and spellcheck.
- `just ci` is the non-interactive equivalent for CI.
- `just list` shows all available recipes.

## Coding Style & Naming Conventions
- Formatting is enforced by `rustfmt` with import grouping (`group_imports = "StdExternalCrate"`) and module-level import granularity.
- Use Rust standard naming: `snake_case` for functions/modules, `CamelCase` for types/traits, `SCREAMING_SNAKE_CASE` for constants.
- Keep modules focused; prefer explicit `mod` boundaries when adding new components.

## Testing Guidelines
- Integration and E2E tests live in `tests/` and are run via `just test` (uses `cargo nextest`).
- Benchmarks live in `benches/` and run with `just benchmark`.
- For coverage reports: `just coverage` (uses `cargo llvm-cov`).

## Commit & Pull Request Guidelines
- Current history uses short, plain-English summaries (e.g., “Updated readme, added docs”); follow that style unless the project adopts a stricter convention.
- PRs should include: a concise summary, the tests run (e.g., `just test`), and any relevant docs or behavior changes.
- If a change affects CLI behavior or config formats, update `docs/` and `CHANGELOG.md`.

## Security & Configuration Tips
- Run `just pre-commit` before submitting; it includes dependency audits (`cargo audit`) and unused dependency checks.
- `just init` installs recommended tooling and pre-commit hooks; run it once per machine.

<!-- BACKLOG.MD MCP GUIDELINES START -->

<CRITICAL_INSTRUCTION>

## BACKLOG WORKFLOW INSTRUCTIONS

This project uses Backlog.md MCP for all task and project management activities.

**CRITICAL GUIDANCE**

- If your client supports MCP resources, read `backlog://workflow/overview` to understand when and how to use Backlog for this project.
- If your client only supports tools or the above request fails, call `backlog.get_workflow_overview()` tool to load the tool-oriented overview (it lists the matching guide tools).

- **First time working here?** Read the overview resource IMMEDIATELY to learn the workflow
- **Already familiar?** You should have the overview cached ("## Backlog.md Overview (MCP)")
- **When to read it**: BEFORE creating tasks, or when you're unsure whether to track work

These guides cover:
- Decision framework for when to create tasks
- Search-first workflow to avoid duplicates
- Links to detailed guides for task creation, execution, and finalization
- MCP tools reference

You MUST read the overview resource to understand the complete workflow. The information is NOT summarized here.

</CRITICAL_INSTRUCTION>

<!-- BACKLOG.MD MCP GUIDELINES END -->
