Issue Tracking with trx

Issue Tracking with trx

IMPORTANT: This project uses trx for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.

Why trx?

• Dependency-aware: Track blockers and relationships between issues
• Git-friendly: CRDT-based storage in .trx/ for version control
• Agent-optimized: JSON output, ready work detection, parent/child relationships
• Prevents duplicate tracking systems and confusion

Quick Start

Check for ready work:

trx ready --json

Create new issues:

trx create "Issue title" -t bug|feature|task -p 0-4 --json
trx create "Child issue" -t task -p 1 --parent trx-123 --json

Claim and update:

trx update trx-42 --status in_progress --json
trx update trx-42 -p 1 --json

Complete work:

trx close trx-42 --reason "Completed" --json

Manage dependencies:

trx dep add trx-42 trx-10       # trx-42 depends on trx-10
trx dep rm trx-42 trx-10        # remove dependency
trx dep tree --json              # show dependency tree

Issue Types

• bug - Something broken
• feature - New functionality
• task - Work item (tests, docs, refactoring)
• epic - Large feature with subtasks
• chore - Maintenance (dependencies, tooling)

Priorities

• 0 - Critical (security, data loss, broken builds)
• 1 - High (major features, important bugs)
• 2 - Medium (default, nice-to-have)
• 3 - Low (polish, optimization)
• 4 - Backlog (future ideas)

Workflow for AI Agents

1. Check ready work: trx ready shows unblocked issues
2. Claim your task: trx update <id> --status in_progress
3. Work on it: Implement, test, document
4. Discover new work? Create linked issue:
   • trx create "Found bug" -t bug -p 1 --parent <parent-id>
5. Complete: trx close <id> --reason "Done"
6. Sync: Run trx sync to commit .trx/ changes, or commit the .trx/ directory together with your code changes so issue state stays in sync with code state

Managing AI-Generated Planning Documents

AI assistants often create planning and design documents during development:

• PLAN.md, IMPLEMENTATION.md, ARCHITECTURE.md
• DESIGN.md, CODEBASE_SUMMARY.md, INTEGRATION_PLAN.md
• TESTING_GUIDE.md, TECHNICAL_DESIGN.md, and similar files

Best Practice: Use a dedicated directory for these ephemeral files

Recommended approach:

• Create a history/ directory in the project root
• Store ALL AI-generated planning/design docs in history/
• Keep the repository root clean and focused on permanent project files
• Only access history/ when explicitly asked to review past planning

Example .gitignore entry (optional):

# AI planning documents (ephemeral)
history/

Important Rules

• Use trx for ALL task tracking
• Always use --json flag for programmatic trx commands
• Link discovered work with --parent to connect related issues
• Check trx ready before asking "what should I work on?"
• Store AI planning docs in history/ directory
• Do NOT create markdown TODO lists
• Do NOT use external issue trackers
• Do NOT duplicate tracking systems
• Do NOT clutter repo root with planning documents