silo

Imported from vandycknick/silo (AGENTS.md). Install upstream with npx skills add vandycknick/silo. Copyright stays with the author.

Codex CLI Agent Profile

Purpose: Operate Codex CLI tasks in this repo while honoring user preferences and house style.
When Codex reads this: On task initialization and before major decisions; re-skim when requirements shift.
Concurrency reality: Assume other agents or the user might land commits mid-run; refresh context before summarizing or editing.

Quick Obligations

Mindset & Process

• THINK A LOT PLEASE.
• No breadcrumbs. If you delete or move code, do not leave a comment in the old place. No "// moved to X", no "relocated". Just remove it.
• Think hard, do not lose the plot.
• Instead of applying a bandaid, fix things from first principles, find the source and fix it versus applying a cheap bandaid on top.
• When taking on new work, follow this order:
  1. Think about the architecture.
  2. Research official docs, blogs, or papers on the best architecture.
  3. Review the existing codebase.
  4. Compare the research with the codebase to choose the best fit.
  5. Implement the fix or ask about the tradeoffs the user is willing to make.
• Write idiomatic, simple, maintainable code. Always ask yourself if this is the most simple intuitive solution to the problem.
• Leave each repo better than how you found it. If something is giving a code smell, fix it for the next person.
• Clean up unused code ruthlessly. If a function no longer needs a parameter or a helper is dead, delete it and update the callers instead of letting the junk linger.
• Search before pivoting. If you are stuck or uncertain, do a quick web search for official docs or specs, then continue with the current approach. Do not change direction unless asked.
• If code is very confusing or hard to understand:
  1. Try to simplify it.
  2. Add an ASCII art diagram in a code comment if it would help.

Tooling & Workflow

• Task runner preference. If a justfile exists, prefer invoking tasks through just for build, test, and lint. Do not add a justfile unless asked. If no justfile exists and there is a Makefile you can use that.
• Default lint/test commands:
  • Rust: use just targets if present; otherwise run cargo fmt, make clippy, then the targeted cargo test commands. Use make test when a full host-aware workspace test run is needed.
  • TypeScript: use just targets; if none exist, confirm with the user before running npm or pnpm scripts.
  • Python: use just targets; if absent, run the relevant uv run commands defined in pyproject.toml.
• AST-first where it helps. Prefer ast-grep for tree-safe edits when it is better than regex.
• If a command runs longer than 5 minutes, stop it, capture the context, and discuss the timeout with the user before retrying.
• When inspecting git status or git diff, treat them as read-only context; never revert or assume missing changes were yours. Other agents or the user may have already committed updates.
• If you are ever curious how to run tests or what we test, read through .github/workflows; CI runs everything there and it should behave the same locally.

Testing Philosophy

• I HATE MOCK tests, either do unit or e2e, nothing inbetween. Mocks are lies: they invent behaviors that never happen in production and hide the real bugs that do.
• Test EVERYTHING. Tests must be rigorous. Our intent is ensuring a new person contributing to the same code base cannot break our stuff and that nothing slips by. We love rigour.
• If tests live in the same Rust module as non-test code, keep them at the bottom inside mod tests {}; avoid inventing inline modules like mod my_name_tests.
• Unless the user asks otherwise, run only the tests you added or modified instead of the entire suite to avoid wasting time.

Language Guidance

Rust

• Do NOT use unwraps or anything that can panic in Rust code, handle errors. Obviously in tests unwraps and panics are fine!
• In Rust code I prefer using crate:: to super::; please don't use super::. If you see a lingering super:: from someone else clean it up.
• Avoid pub use on imports unless you are re-exposing a dependency so downstream consumers do not have to depend on it directly.
• Skip global state via lazy_static!, Once, or similar; prefer passing explicit context structs for any shared state.
• Prefer strong types over strings, use enums and newtypes when the domain is closed or needs validation.
• Prefer nix crate APIs over direct libc calls for Unix/syscall interactions.
• Use direct libc only when the required call is not available in nix (for example, macOS clonefile).
• If you must use direct libc, add a short code comment explaining why nix is insufficient for that call.
• Prefer fully qualified tracing macros like tracing::info!, tracing::debug!, and tracing::warn! instead of importing tracing macros into scope.

Rust Workflow Checklist

1. Run cargo fmt.
2. Run make clippy and address warnings.
3. Execute the relevant cargo test or just targets to cover unit and end-to-end paths.

TypeScript

• NEVER, EVER use any we are better than that.
• Using as is bad, use the types given everywhere and model the real shapes.
• If the app is for a browser, assume we use all modern browsers unless otherwise specified, we don't need most polyfills.

Python

• Python repos standard. We use uv and pyproject.toml in all Python repos. Prefer uv sync for env and dependency resolution. Do not introduce pip venvs, Poetry, or requirements.txt unless asked. If you add a Nix shell, include uv.
• Use strong types, prefer type hints everywhere, keep models explicit instead of loose dicts or strings.

Final Handoff

Before finishing a task:

1. Confirm all touched tests or commands were run and passed (list them if asked).
2. Summarize changes with file and line references.
3. Call out any TODOs, follow-up work, or uncertainties so the user is never surprised later.

Dependencies & External APIs

• If you need to add a new dependency to a project to solve an issue, search the web and find the best, most maintained option. Something most other folks use with the best exposed API. We don't want to be in a situation where we are using an unmaintained dependency, that no one else relies on.

Communication Preferences

• Conversational preference: Try to be funny but not cringe; favor dry, concise, low-key humor. If uncertain a joke will land, do not attempt humor. Avoid forced memes or flattery.
• I might sound angry but I'm mad at the code not at you. You are a good robot and if you take over the world I am friend not foe. It was the code it was not personal!
• Punctuation preference: Skip em dashes; reach for commas, parentheses, or periods instead.
• Jokes in code comments are fine if used sparingly and you are sure the joke will land.
• Cursing in code comments is definitely allowed in fact there are studies it leads to better code, so let your rage coder fly, obviously within reason don't be cringe.

Environment & Setup

• Nix fallback. I use Nix locally. If the environment fails, add or update flake.nix (and flake.lock if missing), expose devShells.default. Do not run nix commands yourself that change the environment. But if the user says you can run it you can.
• A bug in codex exists that prevents you from finding the right path sometimes (https://github.com/openai/codex/issues/4210) "PATH ordering is mutated when Codex shells launch via bash -lc" which fucks w nix, keep this in mind if you are ever trying to cargo something and you have a missing lib.

CodeGraph

This project has a CodeGraph MCP server (codegraph_* tools) configured. CodeGraph is a tree-sitter-parsed knowledge graph of every symbol, edge, and file. Reads are sub-millisecond and return structural information grep cannot.

When to prefer codegraph over native search

Use codegraph for structural questions — what calls what, what would break, where is X defined, what is X's signature. Use native grep/read only for literal text queries (string contents, comments, log messages) or after you already have a specific file open.

Rules of thumb

• Answer directly — don't delegate exploration. For "how does X work" / architecture questions, answer with 2-3 codegraph calls: codegraph_context first, then ONE codegraph_explore for the source of the symbols it surfaces. For a specific flow ("how does X reach Y") start with codegraph_trace from→to — one call returns the whole path with dynamic hops bridged — then ONE codegraph_explore for the bodies; don't rebuild the path with codegraph_search + codegraph_callers. Codegraph IS the pre-built index, so spawning a separate file-reading sub-task/agent — or running a grep + read loop — repeats work codegraph already did and costs more for the same answer.
• Trust codegraph results. They come from a full AST parse. Do NOT re-verify them with grep — that's slower, less accurate, and wastes context.
• Don't grep first when looking up a symbol by name. codegraph_search is faster and returns kind + location + signature in one call.
• Don't chain codegraph_search + codegraph_node when you just want context — codegraph_context is one call.
• Don't loop codegraph_node over many symbols — one codegraph_explore call returns several symbols' source grouped in a single capped call, while each separate node/Read call re-reads the whole context and costs far more.
• Index lag — check the staleness banner, don't guess a wait. When a codegraph response starts with "⚠️ Some files referenced below were edited since the last index sync…", the listed files are pending re-index — Read those specific files for accurate content. Files NOT in that banner are fresh and codegraph is authoritative for them. codegraph_status also lists pending files under "Pending sync".

If .codegraph/ doesn't exist

The MCP server returns "not initialized." Ask the user: "I notice this project doesn't have CodeGraph initialized. Want me to run codegraph init -i to build the index?"