# CLAUDE.md - Gira Usage Guide for Claude

This guide helps Claude AI agents understand how to use Gira for project management and ticket tracking.

## 🎯 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.

## 📋 Essential Gira Commands

### Viewing Project Status
```bash
# See the kanban board with all tickets
gira board

# List all tickets with status and priority
gira ticket list

# View epics and their progress
gira epic list

# Check current sprint status
gira sprint list
```

### Working with Tickets
```bash
# Move a ticket to in-progress when starting work
gira ticket move TICKET-ID "in progress"

# Update a ticket with progress notes
gira ticket update TICKET-ID --description "Implementation details..."

# Move completed ticket to review
gira ticket move TICKET-ID review

# Move reviewed ticket to done
gira ticket move TICKET-ID done

# Add comments for detailed progress tracking
gira comment add TICKET-ID
```

### Creating New Tickets
```bash
# Create a bug ticket
gira ticket create "Fix issue description" --type bug --priority high

# Create a feature ticket linked to an epic
gira ticket create "Add new feature" --type feature --epic EPIC-001

# Create a task ticket
gira ticket create "Update documentation" --type task --priority medium
```

## 🚀 Workflow Best Practices

### Starting Work on a Ticket
```bash
# 1. Check the board to see available tickets
gira board

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

# 3. View full ticket details
gira ticket show TICKET-ID

# 4. Begin implementation work
```

### During Development
```bash
# Update ticket with progress
gira ticket update TICKET-ID --description "Added new functionality, working on tests"

# Add detailed comments about implementation decisions
gira comment add TICKET-ID
# (This opens an editor - add detailed technical notes)
```

### Completing Work
```bash
# 1. Update ticket status
gira ticket move TICKET-ID review

# 2. Add final comment with completion summary
gira comment add TICKET-ID

# 3. After code review, move to done
gira ticket move TICKET-ID done
```

## 📝 Git Integration

### Commit Message Format

**With Gira Ticket:**
```bash
git commit -m "feat(TICKET-ID): implement feature description

- Add detailed implementation notes
- Include test coverage information
- Document any breaking changes

Gira: TICKET-ID"
```

**Without Gira Ticket (Fallback):**
```bash
git commit -m "refactor: improve code organization

- Extract common functions
- Reduce code duplication
- Improve maintainability

Relates-to: general improvements"
```

**Multiple Tickets:**
```bash
git commit -m "test(TICKET-1,TICKET-2): improve test coverage

- Add comprehensive unit tests
- Implement integration testing
- Increase coverage metrics

Gira: TICKET-1, TICKET-2"
```

## 🔍 Finding and Tracking Work

### Search Commands
```bash
# Filter tickets by status
gira ticket list --status "in progress"

# Filter by priority
gira ticket list --priority high

# Filter by type
gira ticket list --type bug

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

### Understanding Code Context
```bash
# Find tickets that modified a file
gira ticket blame src/main.py

# Find tickets for specific lines
gira ticket blame src/main.py -L 10,20

# Get JSON output for processing
gira ticket blame src/main.py --json
```

## 💡 Claude-Specific Tips

### Using TodoWrite with Gira
When working on complex tasks, you can use Claude's TodoWrite tool to track subtasks while linking them to Gira tickets:

1. Create a todo list for breaking down a Gira ticket
2. Reference the ticket ID in your todos
3. Update the Gira ticket as you complete todos

### Progress Documentation
Claude should be particularly detailed when using `gira comment add`:
- Document technical decisions
- Explain implementation approaches
- Note any challenges or blockers
- Reference related code changes

### Handling Multiple Tickets
When working on related tickets:
```bash
# View all tickets in an epic
gira epic show EPIC-001

# List tickets with dependencies
gira ticket show TICKET-ID  # Check the description for dependencies
```

## 🚨 Common Scenarios

### Blocked Ticket
```bash
# Mark as blocked
gira ticket move TICKET-ID blocked

# Add blocking reason
gira comment add TICKET-ID
# Explain what's blocking progress
```

### Finding Related Work
```bash
# Search by keyword in titles
gira ticket list | grep -i "authentication"

# View epic progress
gira epic list
gira epic show EPIC-001
```

### Sprint Work
```bash
# View current sprint
gira sprint current

# List sprint tickets
gira sprint show SPRINT-ID
```

## 📊 Progress Tracking

### Daily Updates
```bash
# Check your assigned tickets
gira ticket list --assignee me

# View in-progress work
gira ticket list --status "in progress"

# Update ticket progress
gira comment add TICKET-ID
```

### Ticket Lifecycle
1. `todo` → `in progress` → `review` → `done`
2. Use `blocked` when waiting on dependencies
3. Add comments at each transition

## 🛠️ Best Practices for Claude

1. **Always Check Current State**: Run `gira ticket show TICKET-ID` before starting work
2. **Document Thoroughly**: Use comments to explain your approach and decisions
3. **Update Regularly**: Move tickets through the workflow as you progress
4. **Reference in Commits**: Always include ticket IDs in commit messages
5. **Break Down Complex Work**: Create subtasks for large tickets

---

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