tracer: Instructions file for Codex

Tracer for AI Agents

This document guides AI agents (Claude, GPT, Cursor, etc.) on how to use Tracer effectively.

Quick Start

# Initialize tracer in your project
tracer init

# Create your first issue
tracer create "Implement user authentication" -p 1 -t feature

# See what's ready to work on
tracer ready --json

Core Workflow for AI Agents

1. Find Ready Work

At the start of any session, check for ready work:

# Get unblocked work in JSON format
tracer ready --json

# Filter by priority
tracer ready --priority 1 --json

# Limit results
tracer ready --limit 5 --json

2. Claim and Start Work

# Update issue to in_progress
tracer update <issue-id> --status in_progress --json

# Example:
tracer update bd-1 --status in_progress

3. Create Issues During Work

As you discover new work, file it immediately:

# Create a bug you found
tracer create "Fix edge case in validation" -t bug -p 0 --json

# Link it back to parent work with discovered-from
tracer dep add <new-issue-id> <parent-issue-id> --type discovered-from

4. Add Dependencies

When you realize work blocks other work:

# bd-2 is blocked by bd-1
tracer dep add bd-2 bd-1 --type blocks

# For parent-child relationships (epics)
tracer dep add bd-3 bd-1 --type parent-child

5. Complete Work

# Close the issue
tracer close <issue-id> --reason "Implemented and tested"

# Example with multiple issues
tracer close bd-1 bd-2 bd-3 --reason "All completed"

6. Check Status

# View issue details
tracer show <issue-id> --json

# See overall statistics
tracer stats --json

# Check what's blocked
tracer blocked --json

JSON Output Format

All commands support --json for programmatic parsing:

Ready Work Response

[
  {
    "id": "bd-1",
    "title": "Implement feature X",
    "status": "open",
    "priority": 1,
    "issue_type": "feature",
    "created_at": "2025-10-15T10:00:00Z",
    "updated_at": "2025-10-15T10:00:00Z"
  }
]