Lumos

Why it exists

Ask an AI agent to change a large, unfamiliar Laravel app and it burns context blindly grepping files — and still misses the routes, model relations, and call chains that matter. Lumos pre-computes that structure once and hands an agent a precise context bundle per task, so it implements changes grounded in how the program actually fits together. It’s my personal answer to “how do I make AI agents genuinely competent on real production code?”

The retrieval, done properly

• AST symbol-level chunking. A chunk is a whole function / method / type — carrying its fully-qualified name, params, return type, docstring, side-effects, and real call-graph edges — not a fixed-size text window. This is the difference between RAG over blobs and RAG over a program’s semantics.
• Deterministic retrieval, measured against the alternative. An earlier iteration ran hybrid pgvector + BM25 with Reciprocal Rank Fusion. I built an eval harness — hand-authored golden queries scored on Recall@k and MRR against a real production codebase — and a deterministic vocabulary-and-call-graph walk beat it. So I deleted the embedding lane entirely and wrote down why. Retrieval today is BM25 in ParadeDB plus a bounded graph expansion through callers and callees. One Postgres, no vector store, no separate Elastic or Qdrant.
• Framework-aware. A Laravel enrichment pass models routes → controllers → models → tables, jobs, events, policies, and tags side-effects (db read/write, http, mail, queue) — so queries like “trace this endpoint” actually work.

The agentic layer

A spec becomes a task DAG; agents claim tasks from a leased queue with heartbeats, each calling get_task_context to assemble the bundle (spec requirements, dependency artifacts, repo-map signatures, semantic hits, target-file state, stale-code warnings). Exposed as MCP tools. The LLM lane is kept out of the trust path: fact types structurally cannot carry source text, generated documents are rejected unless they cite the rows they are based on, and claims are re-checked for staleness as the code moves.

Built on a plugin kernel with enforced invariants — exclusive schema ownership, no cross-plugin imports, ≤500 LOC/file — a codebase deliberately architected so an agent can understand any feature by reading one folder. Personal, local-only; a study in building systems for AI agents.