oo: Instructions file for Codex

AGENTS.md — oo Project

Agent guidelines for the oo codebase (Rust, Edition 2024).

---

1. Context7 Protocol

Before writing any Rust code, resolve current documentation via Context7:

context7_resolve-library-id → context7_query-docs

Use this for crate APIs (tokio, clap, rusqlite, thiserror, assert_cmd, etc.). Training data may be outdated — Context7 has authoritative current docs.

---

2. Minimalist Engineering Philosophy

Every line of code is a liability. Before creating anything:

• LESS IS MORE: Question necessity before creation
• Challenge Everything: Ask "Is this truly needed?" before implementing
• Minimal Viable Solution: Build the simplest thing that fully solves the problem
• No Speculative Features: Don't build for "future needs" - solve today's problem
• Prefer Existing: Reuse existing code/tools before creating new ones
• One Purpose Per Component: Each function/module should do one thing well

Pre-Creation Challenge (MANDATORY)

Before creating ANY code, ask:

1. Is this explicitly required by the GitHub issue?
2. Can existing code/tools solve this instead?
3. What's the SIMPLEST way to meet the requirement?
4. Will removing this break core functionality?
5. Am I building for hypothetical future needs?

If you cannot justify the necessity, DO NOT CREATE IT.

---

3. Pre-Push Quality Gates

All checks must pass locally before any push. CI is for verification, not discovery.

cargo fmt --check          # formatting
cargo clippy -- -D warnings  # lint (warnings are errors)
cargo test                 # all tests pass
cargo tarpaulin --fail-under 70  # coverage gate (70% interim, 80% target after VCR cassettes)
cargo build --release      # release build succeeds

Fix failures locally. Never push to "see if CI catches anything."

---

4. Testing Standards

• TDD preferred — write tests before implementation
• 80% line coverage minimum for new code — enforced via cargo tarpaulin
• Unit tests in-module (#[cfg(test)]) for pure logic
• Integration tests in tests/ for CLI behaviour — use assert_cmd
• Integration tests are the primary coverage driver — they test real CLI invocations
• Every new pattern in src/pattern/ must have a corresponding test
• Tests must provide real value — no trivial assertions like assert!(true) or assert_eq!(1, 1)
• Every test must exercise a real code path and assert meaningful behaviour
• Network-dependent tests must be marked #[ignore] with a comment explaining why
• ~197 tests currently; do not reduce this count