7b7d781a19
Exit code tables (README + AGENTS.md): - Add codes 14-16 (Ollama unavailable, model not found, embedding failed) - Add code 20 (Config not found, remapped from 2) - Clarify code 1 (now includes health check failed + not implemented) - Clarify code 2 (now exclusively usage/parsing errors from clap) New sections: - Configuration Precedence: CLI flags > env vars > config file > defaults - Shell Completions: bash, zsh, fish, powershell installation instructions Co-Authored-By: Claude (us.anthropic.claude-opus-4-5-20251101-v1:0) <noreply@anthropic.com>
133 lines
3.2 KiB
Markdown
133 lines
3.2 KiB
Markdown
# AGENTS.md
|
|
|
|
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
|
|
|
|
## TDD Requirements
|
|
|
|
Test-first development is mandatory:
|
|
1. **RED** - Write failing test first
|
|
2. **GREEN** - Minimal implementation to pass
|
|
3. **REFACTOR** - Clean up while green
|
|
|
|
## Key Patterns
|
|
|
|
Find the simplest solution that meets all acceptance criteria.
|
|
Use third party libraries whenever there's a well-maintained, active, and widely adopted solution (for example, date-fns for TS date math)
|
|
Build extensible pieces of logic that can easily be integrated with other pieces.
|
|
DRY principles should be loosely held.
|
|
Architecture MUST be clear and well thought-out. Ask the user for clarification whenever ambiguity is discovered around architecture, or you think a better approach than planned exists.
|
|
|
|
---
|
|
|
|
## Third-Party Library Usage
|
|
|
|
If you aren't 100% sure how to use a third-party library, **SEARCH ONLINE** to find the latest documentation and mid-2025 best practices.
|
|
|
|
---
|
|
|
|
## 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.
|
|
|
|
### Activation
|
|
|
|
```bash
|
|
# Explicit flag
|
|
lore --robot issues -n 10
|
|
|
|
# JSON shorthand (-J)
|
|
lore -J issues -n 10
|
|
|
|
# Auto-detection (when stdout is not a TTY)
|
|
lore issues | jq .
|
|
|
|
# Environment variable
|
|
LORE_ROBOT=1 lore issues
|
|
```
|
|
|
|
### Robot Mode Commands
|
|
|
|
```bash
|
|
# List issues/MRs with JSON output
|
|
lore --robot issues -n 10
|
|
lore --robot mrs -s opened
|
|
|
|
# Show detailed entity info
|
|
lore --robot issues 123
|
|
lore --robot mrs 456 -p group/repo
|
|
|
|
# Count entities
|
|
lore --robot count issues
|
|
lore --robot count discussions --for mr
|
|
|
|
# Search indexed documents
|
|
lore --robot search "authentication bug"
|
|
|
|
# Check sync status
|
|
lore --robot status
|
|
|
|
# Run full sync pipeline
|
|
lore --robot sync
|
|
|
|
# Run ingestion only
|
|
lore --robot ingest issues
|
|
|
|
# Check environment health
|
|
lore --robot doctor
|
|
|
|
# Document and index statistics
|
|
lore --robot stats
|
|
```
|
|
|
|
### Response Format
|
|
|
|
All commands return consistent JSON:
|
|
|
|
```json
|
|
{"ok":true,"data":{...},"meta":{...}}
|
|
```
|
|
|
|
Errors return structured JSON to stderr:
|
|
|
|
```json
|
|
{"error":{"code":"CONFIG_NOT_FOUND","message":"...","suggestion":"Run 'lore init'"}}
|
|
```
|
|
|
|
### Exit Codes
|
|
|
|
| Code | Meaning |
|
|
|------|---------|
|
|
| 0 | Success |
|
|
| 1 | Internal error / health check failed / not implemented |
|
|
| 2 | Usage error (invalid flags or arguments) |
|
|
| 3 | Config invalid |
|
|
| 4 | Token not set |
|
|
| 5 | GitLab auth failed |
|
|
| 6 | Resource not found |
|
|
| 7 | Rate limited |
|
|
| 8 | Network error |
|
|
| 9 | Database locked |
|
|
| 10 | Database error |
|
|
| 11 | Migration failed |
|
|
| 12 | I/O error |
|
|
| 13 | Transform error |
|
|
| 14 | Ollama unavailable |
|
|
| 15 | Ollama model not found |
|
|
| 16 | Embedding failed |
|
|
| 20 | Config not found |
|
|
|
|
### Configuration Precedence
|
|
|
|
1. CLI flags (highest priority)
|
|
2. Environment variables (`LORE_ROBOT`, `GITLAB_TOKEN`, `LORE_CONFIG_PATH`)
|
|
3. Config file (`~/.config/lore/config.json`)
|
|
4. Built-in defaults (lowest priority)
|
|
|
|
### Best Practices
|
|
|
|
- Use `lore --robot` or `lore -J` for all agent interactions
|
|
- Check exit codes for error handling
|
|
- Parse JSON errors from stderr
|
|
- Use `-n` / `--limit` to control response size
|
|
- TTY detection handles piped commands automatically
|