Imported from flyingsquirrel0419/context-compiler (AGENTS.md). Install upstream with npx skills add flyingsquirrel0419/context-compiler. Copyright stays with the author.

Context Compiler agent guide

Architecture

crates/core owns all reusable analysis. crates/cli owns argument parsing and terminal presentation only. Keep the data flow scan → symbols/imports → rank → budget/slice → render deterministic. See docs/architecture.md and record material choices using the repository Decision Log format.

Invariants

• Never execute analyzed repository code or read environment values.
• Never include likely secret files by default; render-time redaction is defense in depth.
• Stable input and configuration must produce stable ordering and content.
• A requested token budget is a hard selection constraint; do not generate then truncate.
• Unsupported/malformed files degrade to file-level analysis without panics.
• Core analysis must not move into the CLI.

Commands

cargo fmt --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --workspace
cargo build --release

Add unit tests for algorithms, integration tests for public APIs, and CLI tests for user-visible behavior. Avoid fixture-specific scoring rules.

Common pitfalls

Do not follow symlinks, rely on Unix-only paths, serialize unversioned cache internals, print arbitrary filenames without considering terminal escapes, or claim exact tokenizer/parser behavior. Ranking components must remain visible through ctx explain.

Release

Update CHANGELOG.md, run all commands above, smoke-test every CLI command from a clean directory, audit TODO/FIXME/unwrap/debug prints, tag vMAJOR.MINOR.PATCH, and verify archives plus checksums from the release workflow.