repovine AGENTS.md

repovine -- quick reference

This managed block is intentionally short for Claude Code and Codex. Detailed workflows live in the generated skills, agent files, and hooks so this always-on file does not compete with project instructions.

Start

Before non-trivial work, call the repovine MCP server first. Use search_context when the task wording is fuzzy, map_context when a domain/package/module is named, then inspect_node after narrowing. Skip this only for trivial single-file tasks.

If the MCP call fails with a connection error, the server is not running. Ask the user to check the MCP config. Do not fall back to blind file reading -- without the graph you lack structure and dependency info.

If a tool returns result.status:"building", call get_build_status({ "waitSec": 45 }) once instead of polling. stageEtaSec estimates only the current stage; use stage and remainingStages to report progress. If the long-poll still returns building, continue with direct file reads only when the task can proceed without graph structure. To abandon a cold build, call get_build_status({ "cancel": true }); it stops Stage 1 workers and returns cancelled (no graph) or keeps a prior ready graph.

Context Session Quality scores repovine MCP responses, not agent prose. Pass contextSessionId on MCP calls and inspect with get_context_session_quality; harnesses recompute via repovine delivery compliance. The score and its thresholds are advisory until the labelled-corpus return bar in docs/context-quality.md is met; evidence-backed annotation checks remain enforceable.

Working loop

• Orient/map/inspect: search_context, map_context, inspect_node.
• Follow the task axis: runtime/user flow -> get_entrypoints + trace_flow; shared contracts -> analyze_dependencies; env/resources -> get_config_surface; architecture/review candidates -> analyze_architecture; annotation health -> get_annotation_status.
• After code edits, call refresh_context({}). After changing repovine.config.json, call refresh_context({ "reloadConfig": true }) so the running MCP process re-reads config and rebuilds the graph. Changing repovine.domains.json is picked up by a normal refresh; using reloadConfig: true is harmless when both files changed.
• Never hand-edit repovine.annots.json. Change it through write_annotation, merge_annotations, or refresh_context({ "cleanupOrphans": true }); validate_annotations reads it and reports, and writes nothing.