AGENTS.md - Gira Usage Guide for AI Agents¶

This guide provides comprehensive instructions for AI agents working with Gira, the Git-native project management tool.

🎯 What is Gira?¶

Gira is a Git-native project management tool that stores all project data as JSON files in .gira/, enabling version control for project management data and seamless AI collaboration.

🚀 Quick Start¶

Initial Setup¶

# Check if Gira is initialized
ls .gira/

# View project configuration
cat .gira/config.json

# View the board
gira board

Essential Commands¶

# View all tickets
gira ticket list

# Check ticket details
gira ticket show TICKET-ID

# Move ticket to in-progress
gira ticket move TICKET-ID "in progress"

# Add progress update
gira comment add TICKET-ID

📋 Core Workflows¶

1. Starting Work on a Ticket¶

# Find available tickets
gira ticket list --status todo

# Assign ticket to yourself
gira ticket update TICKET-ID --assignee me

# Move to in-progress
gira ticket move TICKET-ID "in progress"

# Add initial comment
gira comment add TICKET-ID --message "Starting work on this ticket"

2. During Development¶

# Update ticket description with progress
gira ticket update TICKET-ID --description "Implemented X, working on Y"

# If blocked
gira ticket move TICKET-ID blocked
gira comment add TICKET-ID --message "Blocked by: [reason]"

# Check related tickets
gira ticket list --epic EPIC-ID

3. Completing Work¶

# Move to review
gira ticket move TICKET-ID review

# Add completion summary
gira comment add TICKET-ID --message "Completed: [summary of changes]"

# After approval, move to done
gira ticket move TICKET-ID done

🔄 Ticket Lifecycle¶

Status Flow¶

todo → in progress → review → done
         ↓
      blocked

Status Descriptions¶

todo: Not started, available for work
in progress: Actively being worked on
blocked: Cannot proceed due to dependency
review: Work complete, awaiting review
done: Fully completed and approved

📝 Git Integration¶

Commit Message Format¶

# With Gira ticket
git commit -m "type(TICKET-ID): brief description

- Detailed change 1
- Detailed change 2

Gira: TICKET-ID"

# Without specific ticket
git commit -m "type: brief description

- Detailed changes

Relates-to: general context"

Commit Types¶

feat: New feature
fix: Bug fix
docs: Documentation changes
test: Test additions/changes
refactor: Code refactoring
style: Formatting changes
chore: Maintenance tasks

🔍 Finding and Filtering¶

Search Tickets¶

# By status
gira ticket list --status "in progress"

# By priority
gira ticket list --priority high

# By assignee
gira ticket list --assignee me

# Combine filters
gira ticket list --status todo --priority high --type bug

Code Integration¶

# Find tickets that modified files
gira ticket blame src/

# Check specific file
gira ticket blame src/main.py

# Get JSON output
gira ticket blame src/ --json

📊 Project Organization¶

Epics¶

# List all epics
gira epic list

# View epic details with tickets
gira epic show EPIC-001

# Create ticket in epic
gira ticket create "New feature" --epic EPIC-001

Sprints¶

# View current sprint
gira sprint current

# List all sprints
gira sprint list

# Show sprint details
gira sprint show SPRINT-001

💡 Best Practices¶

1. Always Update Status¶

Move tickets promptly when state changes
Don't leave tickets in "in progress" indefinitely
Use "blocked" status with explanation

2. Document Everything¶

Add comments for significant decisions
Update ticket descriptions with progress
Include context in commit messages

3. Check Before Acting¶

# Always check current state first
gira ticket show TICKET-ID

# Verify no one else is working on it
gira ticket list --status "in progress" --assignee all

Reference ticket IDs in commits
Use epics to group related tickets
Mention related tickets in comments

🛠️ Advanced Usage¶

Batch Operations¶

# Process multiple tickets
for ticket in TICKET-1 TICKET-2 TICKET-3; do
    gira ticket move "$ticket" "in progress"
done

# Export for analysis
gira export tickets --format json > tickets.json

Reporting¶

# Get project statistics
gira ticket list --format json | jq 'group_by(.status) | map({status: .[0].status, count: length})'

# Check velocity
gira sprint show SPRINT-001 --format json | jq '.completed_points'

🚨 Common Issues¶

Ticket Not Found¶

# List all tickets
gira ticket list

# Search by keyword
gira ticket list | grep -i "search term"

Understanding Workflow¶

# Check available statuses
gira board

# View workflow config
cat .gira/config.json | jq '.workflow'

Merge Conflicts in .gira/¶

# Tickets are stored as separate JSON files
# In case of conflicts, check both versions
git status
git diff .gira/board/

# Usually safe to keep both tickets
git add .gira/
git commit -m "chore: resolve gira merge conflict"

📚 Quick Reference¶

Most Used Commands¶

gira board                          # View kanban board
gira ticket list                    # List all tickets
gira ticket show ID                 # Show ticket details
gira ticket move ID STATUS          # Change status
gira ticket update ID --field VALUE # Update ticket
gira comment add ID                 # Add comment
gira epic list                      # List epics
gira sprint current                 # Current sprint

Useful Aliases¶

alias gb='gira board'
alias gt='gira ticket'
alias gtl='gira ticket list'
alias gtm='gira ticket move'
alias gts='gira ticket show'

This guide helps AI agents work effectively with Gira's Git-native project management system.