Skip to content

AI Agent Guide for Gira

This guide provides general best practices and workflow guidance for AI agents interacting with the Gira CLI. For agent-specific details on creating multi-line descriptions, please refer to the dedicated guides.

General Best Practices for AI Agents

  • Understand the Workflow: Familiarize yourself with Gira's ticket lifecycle (todo -> in progress -> review -> done) and use gira ticket move to update ticket statuses.
  • Use Gira Commands: Always interact with Gira data through the provided CLI commands (e.g., gira ticket show, gira epic list) rather than directly manipulating JSON files, to ensure data integrity and consistency.
  • Structured Output: Leverage --format json for machine-readable output when parsing command results.
  • Dry-Run First: For any state-modifying commands, use --dry-run if available to preview changes before execution.
  • Clear Commit Messages: Follow the project's commit message guidelines, including referencing ticket IDs.
  • Add Comments: Use gira comment add to provide detailed progress updates, technical decisions, or any relevant information on tickets.
  • Error Handling: Be prepared to handle errors gracefully. Parse JSON error output for structured error information.

Creating Multi-line Descriptions

When creating tickets or updating descriptions with multi-line content, it's crucial to preserve formatting and handle special characters correctly. The optimal method depends on your specific AI agent's execution environment.

For detailed, agent-specific guidance, please refer to:

Workflow Integration

  • Starting Work:
    1. Run gira board to identify available tickets.
    2. Move your assigned ticket to "in progress": gira ticket move <ID> in_progress.
    3. Review ticket details: gira ticket show <ID>.
  • During Implementation:
    1. Regularly update ticket descriptions and add comments with progress: gira ticket update <ID> --description "..." or gira comment add <ID> -c "...".
    2. Reference ticket IDs in all relevant Git commits.
  • Completing Work:
    1. Ensure all tests pass and code quality is met.
    2. Move ticket to "review": gira ticket move <ID> review.
    3. Add a final comment summarizing the work done.
    4. After human review/merge, move to "done": gira ticket move <ID> done.

See Also