arrowhead: Instructions file for Codex

Arrowhead Coding Agent Playbook

Mission

• Deliver the Arrowhead Rust rewrite according to the consolidated spec in README.md.
• Preserve repository cleanliness and avoid ambiguous states; never leave todo!() panics in committed code.
• Prioritise maintainability, clear error handling, and strong test coverage using the provided fixture vault.

Ground Rules

1. Toolchain: Build against Rust 1.86 (2024 edition). Update rust-toolchain.toml if a later MSRV is required; call it out in reviews.
2. Features: Semantic search ships by default using sqlite-vec; keep embeddings healthy and avoid regressing the always-on pipeline.
3. Style: Follow idiomatic Rust (clippy clean, cargo fmt). Prefer explicit structs/enums over loose maps; document non-obvious flows with concise comments.
4. Error Handling: Use anyhow/thiserror as scoped in the spec. Return actionable errors instead of panicking.
5. Testing: Add unit tests alongside code (#[cfg(test)]). Integration tests under tests/integration/ will land later; plan your APIs so those paths stay testable. Use tests/fixtures/test-vault as read-only input; write indexes to temp dirs.
6. Docs: Update specs/design docs when behaviour or architecture shifts so the expectations stay current.

Workflow Expectations

• Start complex tasks with a brief plan (2–5 steps max) and keep it up to date.
• For MCP tooling, call mcp.discovery.get_vault_conventions right after initialize and before any note creation, update, or deletion so agents respect vault naming rules.
• Stage work incrementally; validate with cargo fmt, cargo check, cargo clippy --all-targets -- -D warnings, and relevant tests before surfacing results or pushing.
• Treat those commands as the “pre-flight” checklist before every push/PR. Run cargo fmt --all (not just --check), rebuild, and rerun tests after the final file edit so CI never redlines on formatting or missing coverage.
• Summaries must highlight behavioural changes, tests executed, and next steps. Flag known gaps or follow-up items.
• If external dependencies require network or MSRV bumps, pause and confirm with the designer before proceeding.