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¶

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

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

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

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

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

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

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

git commit -m "refactor: improve code organization

- Extract common functions
- Reduce code duplication
- Improve maintainability

Relates-to: general improvements"

Multiple Tickets:

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¶

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

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

Create a todo list for breaking down a Gira ticket
Reference the ticket ID in your todos
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:

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

# Mark as blocked
gira ticket move TICKET-ID blocked

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

# Search by keyword in titles
gira ticket list | grep -i "authentication"

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

Sprint Work¶

# View current sprint
gira sprint current

# List sprint tickets
gira sprint show SPRINT-ID

📊 Progress Tracking¶

Daily Updates¶

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

todo → in progress → review → done
Use blocked when waiting on dependencies
Add comments at each transition

🛠️ Best Practices for Claude¶

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

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