gitlore/AGENTS.md

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.

Beads Rust Workflow Integration

This project uses beads_viewer for issue tracking. Issues are stored in .beads/ and tracked in git.

Essential Commands

# 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:

# 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:

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

---

Beads Workflow Integration

This project uses beads_viewer for issue tracking. Issues are stored in .beads/ and tracked in git.

Essential Commands

# 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:

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