Claude Agent Guide for Gira

This guide provides Claude-specific best practices for working with the Gira CLI, particularly focusing on creating tickets with multi-line descriptions.

Overview

Claude has full shell capabilities and can execute complex bash constructs directly. This allows for elegant solutions using heredocs and other advanced shell features.

Creating Multi-line Descriptions

Preferred Method: Heredoc

Claude can reliably use heredoc syntax for creating rich, multi-line ticket descriptions:

gira ticket create "Feature: API Enhancement" --description "$(cat <<'EOF'
## Summary
Implement enhanced error handling for the REST API.

## Technical Details
- Add structured error responses
- Implement retry logic for transient failures
- Add comprehensive logging

## Code Example
```python
def handle_error(error):
    return {
        "status": "error",
        "message": str(error),
        "timestamp": datetime.utcnow()
    }

Acceptance Criteria

• All endpoints return consistent error format
• 95% test coverage for error paths
• Documentation updated EOF )" --type feature --priority high

  ### Why Heredoc Works for Claude
  
  1. **Direct Execution**: Claude executes commands in a full shell environment
  2. **Preserved Formatting**: All whitespace, line breaks, and special characters are preserved
  3. **No Escaping Needed**: Special characters like quotes, backticks, and variables don't need escaping
  4. **Readable**: The command structure is clear and maintainable
  
  ### Alternative Methods
  
  While heredoc is preferred, Claude can also use:
  
  #### Echo with -e Flag
  ```bash
  gira ticket create "Quick Task" \
    --description "$(echo -e "Line 1\nLine 2\n\nParagraph 2")" \
    --type task
  

Printf

gira ticket create "Formatted Task" \
  --description "$(printf "First: %s\nSecond: %s\n" "Value1" "Value2")" \
  --type task

Best Practices for Claude

1. Complex Ticket Templates

Create comprehensive tickets with structured content:

gira ticket create "Bug: Performance Regression" --description "$(cat <<'EOF'
## Bug Report

**Severity**: High
**Component**: API Gateway
**Version**: 2.3.1

## Description
API response times have increased by 300% after the latest deployment.

## Steps to Reproduce
1. Deploy version 2.3.1
2. Send GET request to `/api/v1/users`
3. Measure response time

## Expected Result
Response time < 100ms

## Actual Result
Response time > 300ms

## Investigation
```sql
-- Slow query identified:
SELECT * FROM users u
JOIN profiles p ON u.id = p.user_id
WHERE u.status = 'active'
-- Missing index on profiles.user_id

Proposed Fix

Add index on profiles.user_id column.

Testing

• Performance test in staging
• Load test with 1000 concurrent users
• Verify response times < 100ms EOF )" --type bug --priority high

  ### 2. Epic Creation with Detailed Scope
  
  ```bash
  gira epic create "Q4 Platform Modernization" --description "$(cat <<'EOF'
  # Platform Modernization Initiative
  
  ## Executive Summary
  Modernize our core platform to improve scalability, reduce operational costs, and enhance developer productivity.
  
  ## Objectives
  1. **Performance**: 10x improvement in response times
  2. **Scalability**: Support 1M concurrent users
  3. **Cost**: 50% reduction in infrastructure costs
  4. **Developer Experience**: 80% faster deployment cycles
  
  ## Technical Roadmap
  
  ### Phase 1: Architecture (4 weeks)
  - Microservices design
  - API gateway implementation
  - Service mesh evaluation
  
  ### Phase 2: Migration (8 weeks)
  - Database sharding
  - Service extraction
  - Legacy system decommission
  
  ### Phase 3: Optimization (4 weeks)
  - Performance tuning
  - Cost optimization
  - Monitoring enhancement
  
  ## Success Metrics
  
  | Metric | Current | Target | Measurement |
  |--------|---------|--------|-------------|
  | Response Time | 500ms | 50ms | p95 latency |
  | Availability | 99.5% | 99.99% | Monthly uptime |
  | Deploy Time | 2 hours | 15 min | CI/CD pipeline |
  | Cost/Request | $0.002 | $0.001 | AWS billing |
  
  ## Risks and Mitigations
  
  ### Technical Risks
  - **Data Migration**: Implement dual-write strategy
  - **Service Dependencies**: Use circuit breakers
  - **Performance Regression**: Continuous benchmarking
  
  ### Business Risks
  - **Customer Impact**: Phased rollout with fallback
  - **Timeline Slip**: Weekly progress reviews
  - **Budget Overrun**: Reserved instance planning
  
  ## Dependencies
  - [ ] Architecture review board approval
  - [ ] Security team sign-off
  - [ ] Budget allocation ($500K)
  - [ ] Team augmentation (3 senior engineers)
  
  ## Stakeholders
  - **Sponsor**: VP Engineering
  - **Technical Lead**: Principal Architect
  - **Project Manager**: PMO Director
  EOF
  )"
  

3. Dynamic Content Generation

Claude can generate ticket content programmatically:

# Generate a ticket with current system information
gira ticket create "System Health Check $(date +%Y-%m-%d)" --description "$(cat <<EOF
## Automated System Health Report

**Generated**: $(date)
**Hostname**: $(hostname)
**User**: $(whoami)

## System Resources
$(df -h | grep -E '^/dev/')

## Memory Usage
$(free -h)

## Recent Errors
$(tail -20 /var/log/syslog | grep -i error || echo "No recent errors")

## Running Services
$(systemctl list-units --type=service --state=running | head -10)

## Action Items
- [ ] Review disk usage if >80%
- [ ] Check memory pressure
- [ ] Investigate any errors found
EOF
)" --type task --priority medium

Special Characters and Edge Cases

Claude handles special characters gracefully with single-quoted heredocs:

gira ticket create "Handle Special Characters" --description "$(cat <<'EOF'
## Special Character Test

This description contains:
- Double quotes: "Hello, World!"
- Single quotes: 'It\'s working'
- Backticks: `command substitution`
- Variables: $HOME, ${USER}
- Backslashes: C:\Windows\System32
- Unicode: 🚀 Launch successful! ✅

None of these are interpreted or expanded.
EOF
)" --type task

Integration with Other Tools

Claude can seamlessly integrate Gira with other command-line tools:

# Create ticket from git log
gira ticket create "Review recent commits" --description "$(cat <<EOF
## Recent Commits to Review

$(git log --oneline -10)

## Changed Files
$(git diff --stat HEAD~10)

## Authors
$(git shortlog -sn HEAD~10..HEAD)
EOF
)" --type task

# Create ticket from test results
gira ticket create "Test Failures $(date +%Y-%m-%d)" --description "$(cat <<EOF
## Test Results

$(pytest --tb=short 2>&1 | tail -50)

## Coverage Report
$(coverage report | grep TOTAL)

## Failed Tests
$(pytest --lf --tb=no | grep FAILED || echo "No failures")
EOF
)" --type bug --priority high

Tips for Claude

1. Use Single-Quoted Heredocs: Prevents variable expansion with <<'EOF'
2. Combine with Command Substitution: Embed dynamic content with $(command)
3. Leverage Full Shell: Use pipes, conditionals, and loops within descriptions
4. No Cleanup Needed: Unlike temp file approaches, heredocs leave no artifacts

Conclusion

Claude's ability to execute complex shell constructs directly makes heredocs the ideal method for creating rich, multi-line ticket descriptions. This approach is: - Clean and readable - Requires no temporary files - Preserves all formatting - Handles all special characters - Integrates seamlessly with other shell commands