110 lines
2.7 KiB
Markdown
110 lines
2.7 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 list issues
|
|
|
|
# Auto-detection (when stdout is not a TTY)
|
|
lore list issues | jq .
|
|
|
|
# Environment variable
|
|
LORE_ROBOT=true lore list issues
|
|
```
|
|
|
|
### Robot Mode Commands
|
|
|
|
```bash
|
|
# List issues/MRs with JSON output
|
|
lore --robot list issues --limit=10
|
|
lore --robot list mrs --state=opened
|
|
|
|
# Count entities
|
|
lore --robot count issues
|
|
lore --robot count discussions --type=mr
|
|
|
|
# Show detailed entity info
|
|
lore --robot show issue 123
|
|
lore --robot show mr 456 --project=group/repo
|
|
|
|
# Check sync status
|
|
lore --robot sync-status
|
|
|
|
# Run ingestion (quiet, JSON summary)
|
|
lore --robot ingest --type=issues
|
|
|
|
# Check environment health
|
|
lore --robot doctor
|
|
```
|
|
|
|
### 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` for all agent interactions
|
|
- Check exit codes for error handling
|
|
- Parse JSON errors from stderr
|
|
- Use `--limit` to control response size
|
|
- TTY detection handles piped commands automatically
|