roborev: Instructions file for Codex

AGENTS.md

Purpose

This repo hosts roborev, a local daemon + CLI for AI-assisted code review. Use this guide to navigate the codebase quickly, understand subsystem boundaries, and avoid missing adjacent changes when working in a growing Go project.

Start Here

• Product behavior and user-facing workflows: README.md
• CLI entry point and command registration: cmd/roborev/main.go
• Command discovery: rg '^func .*Cmd\(' cmd/roborev
• Daemon HTTP API and route wiring: internal/daemon/server.go
• Worker pool and job execution: internal/daemon/worker.go
• SQLite schema migrations: internal/storage/migrations.go
• Config loading and resolution: internal/config/config.go
• Prompt construction: internal/prompt/prompt.go
• TUI entry point: cmd/roborev/tui/tui.go
• Release documentation workflow: docs/README.md

Documentation Style

• Write documentation for humans and agents in plain language: name who does what, use short sentences, and explain unfamiliar terms. Prefer bullets for independent facts, numbered steps for sequences, and paragraphs for rationale.
• Living architecture describes the system, not the history of implementing it. Separate implemented behavior, approved-but-unbuilt work, proposals, and historical decisions. Do not turn every document into a mandatory template.
• Organize around reader questions: purpose, what works today, responsibilities, how it works, rules and failure behavior, and open decisions. Use only the sections the topic needs. Keep detailed protocol definitions below the overview or in focused linked documents.
• Make the opening useful on its own. State the purpose briefly and list current capabilities and gaps separately; do not pack status, ownership, restrictions, and future work into one paragraph.
• Give each bullet one main idea. Use a small table for repeated comparisons and a diagram when it clarifies a relationship or sequence. Neither is required decoration, and a long paragraph does not become readable by adding a bullet.
• State rules directly, then explain non-obvious reasons. Preserve exact field names, authorization checks, failure conditions, and protocol requirements; simpler wording must not weaken the contract.
• Update the relevant section instead of appending a narration of the latest change. Give each fact one owning document and link to it elsewhere. Indexes should route readers, not duplicate detailed implementation status.
• Keep superseded designs outside the normal reading path in clearly marked historical sections or linked documents. Preserve decision rationale, approvals, and active exceptions, including their removal conditions.