lilbee: Instructions file for Codex

lilbee — Development Guide

Before You Write Code (read this every time)

This file is long and the operational rules sit far down. These are the misses that have cost the most review cycles. Apply them BEFORE writing, not after:

1. Type external objects precisely. Never getattr(obj, "field", default) on a field the object's type guarantees. Annotate the parameter with the real type and read the attribute directly. getattr-with-default is only for attributes that genuinely may not exist (dynamic reflection).
2. Don't inherit the surrounding code's pattern without checking it against these rules. Nearby code may predate a rule. Copying an adjacent getattr / isinstance(self.app, ...) / : str shape just propagates the smell into your diff.
3. One-line docstrings by default. Describe what the code IS, not how it got there. No "previously", "now also", "some versions", "kept for".
4. The smell gate runs in make lint. scripts/check_style_rules.py fails on any NEW Code-Smell Trigger (see that section) on lines your diff adds vs main. Run make lint before committing; a genuinely dynamic case opts out inline with # style-check: allow-smell plus a written reason.

The full rules follow; this block is the part that gets skipped under time pressure, so it leads.

Project

The whole local AI stack in one executable: a model manager plus a search engine you can talk to. Python 3.11+, pluggable LLM providers (a managed local llama-server fleet by default, Ollama/OpenAI through the provider SDK), LanceDB for vectors. Managed with uv. Task tracking with beads (bd).

Framing: Lead with "the whole local AI stack in one executable". Two pillars, always both: it runs and manages the models (its own model manager, no Ollama or LM Studio needed, works with both), and it is a search engine you can talk to (cited answers). "RAG" and "local-first" are properties, not the identity. lilbee is both a standalone multipurpose tool AND an AI agent backend.