voleeo-api: Instructions file for Codex

AGENTS.md

Guidance for AI coding agents working in this repository.

File-size rule: this document must stay under 300 lines. When you add a new rule or section, tighten or remove existing content first — never just append. A bloated guide is read less, not more. Keep prose terse, examples one-line, and prefer references to inline duplication.

Product vision

Voleeo is an AI-native local toolkit with MCP bridge. Every feature serves one goal: an AI agent (via MCP) and a developer share the same view of the system. UI, data models, and IPC are designed for both human and machine consumers.

Model routing (delegated sub-work only)

Applies to subagents/workflows spawned via the Agent/Workflow tools — pick model per task. The main session model is user-controlled (/model) and never auto-switches; this table only routes delegated work. When unsure, step up a tier.

• Haiku — mechanical, fully-specified: keyword/file searches, fan-out reads (Explore), renames, formatting, log/grep scans, applying a known edit across files. Also commit messages and PR descriptions (use the cheapest tier).
• Sonnet — default for real work: feature implementation, code review, writing tests, focused single-file/single-bug debugging, doc edits.
• Opus — hard reasoning: architecture/design, cross-crate refactors, render-loop/concurrency/IPC-shape bugs (see numbered rules), security review, ambiguous multi-step tasks, adversarial verification of findings.

Tool discipline

• Locate before reading. Use grep/find to confirm a file holds what you need before Read; never read whole directories.
• Budget the work. Aim to finish a task in under 20 tool calls. After ~10 calls with no visible progress, stop and explain the blocker rather than pushing on.

Code quality

KISS · DRY · YAGNI. When planning and writing code, default to the simplest thing that works: stdlib or an already-installed dep before new code, one line before fifty, a native/CSS/DB feature before app code. Build nothing for a need that isn't here yet. Factor real duplication — never abstract speculatively (no interface with one impl, no config for a constant). Shortest working diff wins; if you can't name why a piece of code must exist, cut it.