9b63671df9
- README.md: Add hybrid search and robot mode to feature list. Update quick start to use new noun-first CLI syntax (lore issues, lore mrs, lore search). Add embedding configuration section. Update command examples throughout. - AGENTS.md: Update robot mode examples to new CLI syntax. Add search, sync, stats, and generate-docs commands to the robot mode reference. Update flag conventions (-n for limit, -s for state, -J for JSON). - docs/prd/checkpoint-3.md: Major expansion with gated milestone structure (Gate A: lexical, Gate B: hybrid, Gate C: sync). Add prerequisite rename note, code sample conventions, chunking strategy details, and sqlite-vec rowid encoding scheme. Clarify that Gate A requires only SQLite + FTS5 with no sqlite-vec dependency. - docs/phase-a-spec.md: New detailed specification for Gate A (lexical search MVP) covering document schema, FTS5 configuration, dirty queue mechanics, CLI interface, and acceptance criteria. - docs/api-efficiency-findings.md: Analysis of GitLab API pagination behavior and efficiency observations from production sync runs. Documents the missing x-next-page header issue and heuristic fix. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
122 lines
2.8 KiB
Markdown
122 lines
2.8 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 |
|
|
| 2 | Config not found |
|
|
| 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 |
|
|
|
|
### 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
|