From 859923f86be9c2b235f5608619d207e3aecf7285 Mon Sep 17 00:00:00 2001 From: Taylor Eernisse Date: Sat, 7 Feb 2026 21:35:32 -0500 Subject: [PATCH] docs: update AGENTS.md robot mode section for --fields, actions, exit codes Sync the agent instructions with the current robot mode implementation: - Add RUST_CLI_TOOLS_BEST_PRACTICES.md reference for Rust coding guidance - Expand robot mode description to cover all new capabilities - Add --fields examples (minimal preset, custom field lists) - Document error actions array for automated recovery workflows - Update response format to show elapsed_ms and actions in error envelope - Add field selection section with usage examples - Separate health check to exit code 19 (was overloaded on exit code 1) - Add robot-docs recommendation for response schema discovery - Update best practices with --fields minimal for token efficiency Co-Authored-By: Claude Opus 4.6 --- AGENTS.md | 38 +++++++++++++++++++++++++++++--------- 1 file changed, 29 insertions(+), 9 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index a239495..e797214 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,6 +35,8 @@ We only use **Cargo** in this project, NEVER any other package manager. - **Configuration:** Cargo.toml only - **Unsafe code:** Forbidden (`#![forbid(unsafe_code)]`) +When writing Rust code, reference RUST_CLI_TOOLS_BEST_PRACTICES.md + ### Release Profile Use the release profile defined in `Cargo.toml`. If you need to change it, justify the @@ -591,7 +593,7 @@ If you aren't 100% sure how to use a third-party library, **SEARCH ONLINE** to f ## Gitlore Robot Mode -The `lore` CLI has a robot mode optimized for AI agent consumption with structured JSON output, meaningful exit codes, and TTY auto-detection. +The `lore` CLI has a robot mode optimized for AI agent consumption with compact JSON output, structured errors with machine-actionable recovery steps, meaningful exit codes, response timing metadata, field selection for token efficiency, and TTY auto-detection. ### Activation @@ -616,6 +618,10 @@ LORE_ROBOT=1 lore issues lore --robot issues -n 10 lore --robot mrs -s opened +# List with field selection (reduces token usage ~60%) +lore --robot issues --fields minimal +lore --robot mrs --fields iid,title,state,draft + # Show detailed entity info lore --robot issues 123 lore --robot mrs 456 -p group/repo @@ -645,7 +651,7 @@ lore --robot doctor # Document and index statistics lore --robot stats -# Quick health pre-flight check (exit 0 = healthy, 1 = unhealthy) +# Quick health pre-flight check (exit 0 = healthy, 19 = unhealthy) lore --robot health # Generate searchable documents from ingested data @@ -654,7 +660,7 @@ lore --robot generate-docs # Generate vector embeddings via Ollama lore --robot embed -# Agent self-discovery manifest (all commands, flags, exit codes) +# Agent self-discovery manifest (all commands, flags, exit codes, response schemas) lore robot-docs # Version information @@ -663,16 +669,27 @@ lore --robot version ### Response Format -All commands return consistent JSON: +All commands return compact JSON with a uniform envelope and timing metadata: ```json -{"ok":true,"data":{...},"meta":{...}} +{"ok":true,"data":{...},"meta":{"elapsed_ms":42}} ``` -Errors return structured JSON to stderr: +Errors return structured JSON to stderr with machine-actionable recovery steps: ```json -{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'lore init'"}} +{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'lore init'","actions":["lore init"]}} +``` + +The `actions` array contains executable shell commands for automated recovery. It is omitted when empty. + +### Field Selection + +The `--fields` flag on `issues` and `mrs` list commands controls which fields appear in the JSON response: + +```bash +lore -J issues --fields minimal # Preset: iid, title, state, updated_at_iso +lore -J mrs --fields iid,title,state,draft,labels # Custom field list ``` ### Exit Codes @@ -680,7 +697,7 @@ Errors return structured JSON to stderr: | Code | Meaning | |------|---------| | 0 | Success | -| 1 | Internal error / health check failed / not implemented | +| 1 | Internal error / not implemented | | 2 | Usage error (invalid flags or arguments) | | 3 | Config invalid | | 4 | Token not set | @@ -698,6 +715,7 @@ Errors return structured JSON to stderr: | 16 | Embedding failed | | 17 | Not found (entity does not exist) | | 18 | Ambiguous match (use `-p` to specify project) | +| 19 | Health check failed | | 20 | Config not found | ### Configuration Precedence @@ -711,7 +729,8 @@ Errors return structured JSON to stderr: - Use `lore --robot` or `lore -J` for all agent interactions - Check exit codes for error handling -- Parse JSON errors from stderr +- Parse JSON errors from stderr; use `actions` array for automated recovery +- Use `--fields minimal` to reduce token usage (~60% fewer tokens) - Use `-n` / `--limit` to control response size - Use `-q` / `--quiet` to suppress progress bars and non-essential output - Use `--color never` in non-TTY automation for ANSI-free output @@ -719,4 +738,5 @@ Errors return structured JSON to stderr: - Use `--log-format json` for machine-readable log output to stderr - TTY detection handles piped commands automatically - Use `lore --robot health` as a fast pre-flight check before queries +- Use `lore robot-docs` for response schema discovery - The `-p` flag supports fuzzy project matching (suffix and substring)