Begin planning phase 3-5 implementation
This commit is contained in:
teernisse
File diff suppressed because one or more lines are too long
@@ -1 +1 @@
|
||||
bd-2um
|
||||
bd-lcb
|
||||
|
||||
146
AGENTS.md
146
AGENTS.md
@@ -17,153 +17,11 @@ 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.
|
||||
|
||||
## Beads Rust Workflow Integration
|
||||
|
||||
This project uses [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) for issue tracking. Issues are stored in `.beads/` and tracked in git.
|
||||
|
||||
### Essential Commands
|
||||
|
||||
```bash
|
||||
# View issues (launches TUI - NOT FOR AGENT USE, human only)
|
||||
bv
|
||||
|
||||
# CLI commands for agents (use --json for machine-readable output)
|
||||
br ready --json # Show issues ready to work (no blockers)
|
||||
br list --status=open --json # All open issues
|
||||
br show <id> --json # Full issue details with dependencies
|
||||
br create --title="..." --type=task --priority=2
|
||||
br update <id> --status=in_progress
|
||||
br close <id> --reason="Completed"
|
||||
br close <id1> <id2> # Close multiple issues at once
|
||||
br sync # Commit and push changes
|
||||
```
|
||||
|
||||
### Robot Mode (Agent-Optimized bv Commands)
|
||||
|
||||
Use `bv --robot-*` flags for structured JSON output optimized for AI agents:
|
||||
|
||||
```bash
|
||||
# Essential robot commands
|
||||
bv --robot-triage # THE MEGA-COMMAND: unified analysis, recommendations, health
|
||||
bv --robot-next # Single top recommendation (minimal output)
|
||||
bv --robot-plan # Dependency-respecting execution plan
|
||||
bv --robot-priority # Priority recommendations with reasoning
|
||||
bv --robot-insights # Deep graph analysis (PageRank, bottlenecks, etc.)
|
||||
|
||||
# File impact analysis (check before editing)
|
||||
bv --robot-impact <file> # Risk assessment for modifying files
|
||||
bv --robot-file-beads <path> # What beads have touched this file?
|
||||
bv --robot-file-hotspots # High-churn files (conflict zones)
|
||||
bv --robot-related <bead-id> # Find related beads
|
||||
|
||||
# Filtering options (work with most robot commands)
|
||||
bv --robot-triage --robot-by-label=backend
|
||||
bv --robot-priority --robot-min-confidence=0.7
|
||||
bv --robot-insights --label=api # Scope to label subgraph
|
||||
```
|
||||
|
||||
Run `bv -robot-help` for complete robot mode documentation.
|
||||
|
||||
### Workflow Pattern
|
||||
|
||||
1. **Start**: Run `br ready` to find actionable work
|
||||
2. **Claim**: Use `br update <id> --status=in_progress`
|
||||
3. **Work**: Implement the task
|
||||
4. **Complete**: Use `br close <id>`
|
||||
5. **Sync**: Always run `br sync` at session end
|
||||
|
||||
### Key Concepts
|
||||
|
||||
- **Dependencies**: Issues can block other issues. `br ready` shows only unblocked work.
|
||||
- **Priority**: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers, not words)
|
||||
- **Types**: task, bug, feature, epic, question, docs
|
||||
- **Blocking**: `br dep add <issue> <depends-on>` to add dependencies
|
||||
|
||||
### Session Protocol
|
||||
|
||||
**Before ending any session, run this checklist:**
|
||||
|
||||
```bash
|
||||
git status # Check what changed
|
||||
git add <files> # Stage code changes
|
||||
br sync # Commit beads changes
|
||||
git commit -m "..." # Commit code
|
||||
br sync # Commit any new beads changes
|
||||
git push # Push to remote
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
- Check `br ready` at session start to find available work
|
||||
- Update status as you work (in_progress → closed)
|
||||
- Create new issues with `br create` when you discover tasks
|
||||
- Use descriptive titles and set appropriate priority/type
|
||||
- Always `br sync` before ending session
|
||||
|
||||
<!-- end-br-agent-instructions -->
|
||||
|
||||
<!-- bv-agent-instructions-v1 -->
|
||||
|
||||
---
|
||||
|
||||
## Beads Workflow Integration
|
||||
## Third-Party Library Usage
|
||||
|
||||
This project uses [beads_viewer](https://github.com/Dicklesworthstone/beads_viewer) for issue tracking. Issues are stored in `.beads/` and tracked in git.
|
||||
|
||||
### Essential Commands
|
||||
|
||||
```bash
|
||||
# View issues (launches TUI - avoid in automated sessions)
|
||||
bv
|
||||
|
||||
# CLI commands for agents (use these instead)
|
||||
bd ready # Show issues ready to work (no blockers)
|
||||
bd list --status=open # All open issues
|
||||
bd show <id> # Full issue details with dependencies
|
||||
bd create --title="..." --type=task --priority=2
|
||||
bd update <id> --status=in_progress
|
||||
bd close <id> --reason="Completed"
|
||||
bd close <id1> <id2> # Close multiple issues at once
|
||||
bd sync # Commit and push changes
|
||||
```
|
||||
|
||||
### Workflow Pattern
|
||||
|
||||
1. **Start**: Run `bd ready` to find actionable work
|
||||
2. **Claim**: Use `bd update <id> --status=in_progress`
|
||||
3. **Work**: Implement the task
|
||||
4. **Complete**: Use `bd close <id>`
|
||||
5. **Sync**: Always run `bd sync` at session end
|
||||
|
||||
### Key Concepts
|
||||
|
||||
- **Dependencies**: Issues can block other issues. `bd ready` shows only unblocked work.
|
||||
- **Priority**: P0=critical, P1=high, P2=medium, P3=low, P4=backlog (use numbers, not words)
|
||||
- **Types**: task, bug, feature, epic, question, docs
|
||||
- **Blocking**: `bd dep add <issue> <depends-on>` to add dependencies
|
||||
|
||||
### Session Protocol
|
||||
|
||||
**Before ending any session, run this checklist:**
|
||||
|
||||
```bash
|
||||
git status # Check what changed
|
||||
git add <files> # Stage code changes
|
||||
bd sync # Commit beads changes
|
||||
git commit -m "..." # Commit code
|
||||
bd sync # Commit any new beads changes
|
||||
git push # Push to remote
|
||||
```
|
||||
|
||||
### Best Practices
|
||||
|
||||
- Check `bd ready` at session start to find available work
|
||||
- Update status as you work (in_progress → closed)
|
||||
- Create new issues with `bd create` when you discover tasks
|
||||
- Use descriptive titles and set appropriate priority/type
|
||||
- Always `bd sync` before ending session
|
||||
|
||||
<!-- end-bv-agent-instructions -->
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
2729
RUST_CLI_TOOLS_BEST_PRACTICES_GUIDE.md
Normal file
2729
RUST_CLI_TOOLS_BEST_PRACTICES_GUIDE.md
Normal file
File diff suppressed because it is too large
Load Diff
2659
docs/prd/checkpoint-3.md
Normal file
2659
docs/prd/checkpoint-3.md
Normal file
File diff suppressed because it is too large
Load Diff
239
docs/robot-mode-design.md
Normal file
239
docs/robot-mode-design.md
Normal file
@@ -0,0 +1,239 @@
|
||||
# Robot Mode Design
|
||||
|
||||
## Overview
|
||||
|
||||
Robot mode optimizes the `gi` CLI for AI agent consumption with structured JSON output, meaningful exit codes, and token-efficient responses.
|
||||
|
||||
## Activation
|
||||
|
||||
```bash
|
||||
# Explicit flag
|
||||
gi --robot list issues
|
||||
|
||||
# Auto-detection (when stdout is not a TTY)
|
||||
gi list issues | jq .
|
||||
|
||||
# Environment variable
|
||||
GI_ROBOT=1 gi list issues
|
||||
```
|
||||
|
||||
## Global Flags
|
||||
|
||||
| Flag | Description |
|
||||
|------|-------------|
|
||||
| `--robot` | Force JSON output, structured errors |
|
||||
| `--quiet` | Suppress progress/spinners (implied by --robot) |
|
||||
|
||||
## Exit Codes
|
||||
|
||||
| Code | ErrorCode | Meaning |
|
||||
|------|-----------|---------|
|
||||
| 0 | - | Success |
|
||||
| 1 | INTERNAL_ERROR | Unknown/internal error |
|
||||
| 2 | CONFIG_NOT_FOUND | Config file missing |
|
||||
| 3 | CONFIG_INVALID | Config file malformed |
|
||||
| 4 | TOKEN_NOT_SET | GitLab token not configured |
|
||||
| 5 | GITLAB_AUTH_FAILED | Authentication failed |
|
||||
| 6 | GITLAB_NOT_FOUND | Resource not found |
|
||||
| 7 | GITLAB_RATE_LIMITED | Rate limited |
|
||||
| 8 | GITLAB_NETWORK_ERROR | Network/connection error |
|
||||
| 9 | DB_LOCKED | Database locked by another process |
|
||||
| 10 | DB_ERROR | Database error |
|
||||
| 11 | MIGRATION_FAILED | Migration failed |
|
||||
| 12 | IO_ERROR | File I/O error |
|
||||
| 13 | TRANSFORM_ERROR | Data transformation error |
|
||||
|
||||
## Error Output Format
|
||||
|
||||
When `--robot` is active, errors are JSON on stderr:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": {
|
||||
"code": "CONFIG_NOT_FOUND",
|
||||
"message": "Config file not found at ~/.config/gi/config.toml",
|
||||
"suggestion": "Run 'gi init' to create configuration"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Success Output Format
|
||||
|
||||
All commands return consistent JSON structure:
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": { ... },
|
||||
"meta": {
|
||||
"count": 50,
|
||||
"total": 1234,
|
||||
"elapsed_ms": 45
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Command-Specific Output
|
||||
|
||||
### gi list issues --robot
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"issues": [
|
||||
{
|
||||
"iid": 123,
|
||||
"project": "group/project",
|
||||
"title": "Bug in login",
|
||||
"state": "opened",
|
||||
"author": "username",
|
||||
"assignees": ["user1"],
|
||||
"labels": ["bug", "priority::high"],
|
||||
"discussions": { "total": 5, "unresolved": 2 },
|
||||
"updated_at": "2024-01-15T10:30:00Z",
|
||||
"web_url": "https://..."
|
||||
}
|
||||
]
|
||||
},
|
||||
"meta": { "showing": 50, "total": 234 }
|
||||
}
|
||||
```
|
||||
|
||||
### gi show issue 123 --robot
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"issue": {
|
||||
"iid": 123,
|
||||
"project": "group/project",
|
||||
"title": "Bug in login",
|
||||
"description": "Full markdown...",
|
||||
"state": "opened",
|
||||
"author": "username",
|
||||
"created_at": "2024-01-10T08:00:00Z",
|
||||
"updated_at": "2024-01-15T10:30:00Z",
|
||||
"discussions": [
|
||||
{
|
||||
"id": "abc123",
|
||||
"resolved": false,
|
||||
"notes": [
|
||||
{
|
||||
"author": "user1",
|
||||
"body": "Comment text...",
|
||||
"created_at": "2024-01-11T09:00:00Z",
|
||||
"system": false
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### gi ingest --type issues --robot
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"resource_type": "issues",
|
||||
"projects": [
|
||||
{
|
||||
"path": "group/project",
|
||||
"issues_synced": 45,
|
||||
"discussions_synced": 123
|
||||
}
|
||||
],
|
||||
"totals": {
|
||||
"issues": 45,
|
||||
"discussions": 123
|
||||
}
|
||||
},
|
||||
"meta": { "elapsed_ms": 3400 }
|
||||
}
|
||||
```
|
||||
|
||||
### gi count issues --robot
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"entity": "issues",
|
||||
"count": 1234,
|
||||
"breakdown": {
|
||||
"opened": 456,
|
||||
"closed": 778
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### gi doctor --robot
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"success": true,
|
||||
"checks": {
|
||||
"config": { "status": "ok", "path": "~/.config/gi/config.toml" },
|
||||
"database": { "status": "ok", "version": 6 },
|
||||
"gitlab": { "status": "ok", "user": "username" },
|
||||
"projects": [
|
||||
{ "path": "group/project", "status": "ok" }
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### gi sync-status --robot
|
||||
|
||||
```json
|
||||
{
|
||||
"ok": true,
|
||||
"data": {
|
||||
"last_sync": {
|
||||
"status": "completed",
|
||||
"resource_type": "issues",
|
||||
"started_at": "2024-01-15T10:00:00Z",
|
||||
"completed_at": "2024-01-15T10:00:45Z",
|
||||
"duration_ms": 45000
|
||||
},
|
||||
"cursors": [
|
||||
{
|
||||
"project": "group/project",
|
||||
"resource_type": "issues",
|
||||
"cursor": "2024-01-15T10:00:00Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Implementation Plan
|
||||
|
||||
### Phase 1: Core Infrastructure
|
||||
1. Add `--robot` global flag to Cli struct
|
||||
2. Create `RobotOutput` trait for consistent JSON serialization
|
||||
3. Add exit code mapping from ErrorCode
|
||||
4. Implement TTY detection with `atty` crate
|
||||
|
||||
### Phase 2: Command Updates
|
||||
1. Update all commands to check robot mode
|
||||
2. Add JSON output variants for commands missing them (count, ingest, sync-status)
|
||||
3. Suppress progress bars in robot mode
|
||||
|
||||
### Phase 3: Error Handling
|
||||
1. Update main.rs error handler for robot mode
|
||||
2. Add suggestion field to GiError variants
|
||||
3. Emit structured JSON errors to stderr
|
||||
|
||||
### Phase 4: Documentation
|
||||
1. Update AGENTS.md with robot mode commands
|
||||
2. Add --robot examples to help text
|
||||
Reference in New Issue
Block a user